PIIcasso

PIIcasso is a PII analysis and security-workflow platform with a React web application, a Django REST API, and Node and Python command-line clients. Local CLI commands can detect and redact PII, score passwords, and generate candidate wordlists without contacting the API. Authenticated workflows use the backend for saved operations, AI-assisted generation, history, messaging, and risk data.

Use PIIcasso only with data and systems you own or are explicitly authorized to test. See Security and responsible use.

This README describes the repository and its supported configuration. It is not an uptime report or service-level guarantee.

Use the committed lockfiles with npm ci when working from source.

# Node.js CLI (requires Node >=24)
npm install --global piicasso

# Python CLI
pip install piicasso

Examples below use the Node CLI:

# Local operations: no account or network request
piicasso analyze "Email jane@example.com or call 9876543210"
piicasso redact "Email jane@example.com"
piicasso score "ExamplePassword42!" --profile username=jane birth_year=1990
piicasso wordgen --profile name=Jane birth_year=1990 --limit 20

# API-backed operations: authenticate first
piicasso login
piicasso submit --profile full_name="Jane Doe" birth_year=1990 current_city=Chennai --pattern-mode standard
piicasso history --limit 10
piicasso risk

submit accepts a structured profile, not a file. risk takes no target argument; it returns the authenticated user's current financial-risk snapshot. See the Node CLI documentation for the complete submit contract and the Python CLI documentation for that client's command surface.

The local engines are separate implementations. Do not assume byte-identical results between the browser, Node, and Python surfaces unless a specific parity test covers the behavior you depend on.

The React 19 and Vite 8 single-page application includes registration and authentication, user and security workflows, operation history, team features, an in-browser command interface, and role-gated administration.

The Django 5.2 and Django REST Framework backend provides JWT authentication, generation and analysis endpoints, history, messaging, teams, password-security workflows, analytics, and OpenAPI documentation. The production image starts the application through Daphne ASGI after applying migrations and ensuring the database-backed cache table exists.

• Piicasso/cli-node: Node.js 24+, Commander, Axios, and Chalk.
• Piicasso/cli-python: Python 3.9+, Click, Rich, Prompt Toolkit, and Requests.

Both clients combine local utilities with authenticated API calls, but their exact options and output formats can differ. Refer to each package's README.

Commands that expose a --json option can emit machine-readable output.

The Node CLI accepts one or more key=value pairs after --profile and validates them against its recognized profile-key set. --pattern-mode is one of:

• standard
• corporate
• leetspeak
• deep

The backend's committed OpenAPI schema documents the recognized submit fields and the same pattern-mode enum. A request must contain meaningful non-pattern PII; undeclared keys and profile values longer than 256 characters are rejected. A successful 201 response is a scored wordlist and metrics envelope, and --json prints the complete response.

Clone the repository and create the backend environment file:

git clone https://github.com/yokesh-kumar-M/Piicasso.git
cd Piicasso
cp Piicasso/backend/.env.example Piicasso/backend/.env

The example environment is production-oriented. For local work, review every value, set ENV=development, use development hosts/origins, and either remove the placeholder DATABASE_URL to use the local fallback or replace it with a real database URL. GOOGLE_CLIENT_ID and a valid FIELD_ENCRYPTION_KEY are required for backend startup.

Generate a Fernet key with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

cd Piicasso/backend
python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

python -m pip install -r requirements-dev.txt
python manage.py migrate
python manage.py runserver

The development API is available at http://localhost:8000/api/.

In another terminal:

cd Piicasso/frontend
cp .env.example .env.local
npm ci
npm run dev

The Vite development server is configured for http://localhost:3000.

# Node CLI
cd Piicasso/cli-node
npm ci
npm link
piicasso --version

# Python CLI, from the repository root
python -m pip install -e Piicasso/cli-python
piicasso --version

The repository intentionally contains two Compose files with different purposes.

Run this file from the repository root:

docker compose -f docker-compose.yml up --build

It uses Dockerfile.dev images and bind mounts for the Django development server and Vite development server. It also starts Redis and a Celery worker. Expected local ports are frontend 3000, backend 8000, and Redis 6379. It does not provision PostgreSQL; database behavior follows Piicasso/backend/.env.

Run the nested file explicitly:

docker compose -f Piicasso/docker-compose.yml up --build --detach

This topology builds the production frontend and backend images and adds a Celery worker, PostgreSQL, authenticated Redis, Prometheus, Grafana, Loki, and Grafana Alloy. Set the required POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, REDIS_PASSWORD, and GRAFANA_PASSWORD substitutions, and provide production secrets in Piicasso/backend/.env before starting it. The frontend is published on host port 80; the backend remains internal to the Compose network and is reached through the frontend proxy.

The backend container runs Piicasso/backend/start.sh, which collects shared static assets, applies migrations, creates the database cache table if needed, and then replaces the shell process with Daphne serving backend.asgi:application. The frontend production image serves its static Vite build through unprivileged Nginx and proxies HTTP and WebSocket traffic. Prometheus and Loki are private to the Compose network; Grafana is the published observability surface on port 3001.

Neither Compose file by itself proves that an external deployment is healthy; use the health endpoint and your deployment platform's monitoring.

Start from Piicasso/backend/.env.example and Piicasso/frontend/.env.example. Never commit populated environment files.

The backend OpenAPI snapshot is committed at Piicasso/backend/schema.yml. CI regenerates and validates the schema, then fails on drift. The current schema generation is warning-free and includes the recognized submit profile fields, pattern-mode enum, and typed success envelope.

The schema is the documented contract. The PII submission request is explicitly closed (additionalProperties: false), matching the server's unknown-field rejection.

After changing a view or serializer, regenerate the snapshot from the repository root:

task schema

# Frontend
npm ci --prefix Piicasso/frontend
npm test --prefix Piicasso/frontend
npm run lint --prefix Piicasso/frontend
npm run format:check --prefix Piicasso/frontend
npm run build --prefix Piicasso/frontend
npm run audit:production --prefix Piicasso/frontend

# Node CLI
npm ci --prefix Piicasso/cli-node
npm test --prefix Piicasso/cli-node

# Backend, after installing requirements-dev.txt in its virtual environment
python scripts/run_backend_tool.py manage.py test --verbosity=2
python scripts/run_backend_tool.py ruff check .
python scripts/run_backend_tool.py ruff format --check .

The root Taskfile.yml also provides setup, dev, test, lint, format, typecheck, and schema tasks.

• render.yaml defines the Docker-based backend deployment and health path.
• vercel.json defines frontend security headers, SPA routing, and the /api/ rewrite.
• Piicasso/docker-compose.yml is the production-style self-hosted stack.

Repository configuration includes hosted target URLs, but this README deliberately does not label them “live” or promise availability. Check the health endpoint and the relevant provider dashboard when operating a deployment.

Piicasso/
├── docker-compose.yml              # Local development stack
├── README.md
├── Taskfile.yml
├── UPGRADE_PLAN.md
├── render.yaml
├── vercel.json
└── Piicasso/
    ├── backend/                    # Django/DRF API and Daphne startup
    │   ├── backend/                # Settings, URLs, ASGI application
    │   ├── generator/              # Generation records and encrypted fields
    │   ├── operations/             # Logs, messages, notifications
    │   ├── password_security/      # Password analysis workflows
    │   ├── teams/                  # Team workflows
    │   ├── wordgen/                # API views, serializers, Gemini integration
    │   ├── schema.yml              # CI-enforced OpenAPI snapshot
    │   └── start.sh                # Migration/cache setup and Daphne startup
    ├── frontend/                   # React 19 and Vite 8 application
    ├── cli-node/                   # npm CLI
    ├── cli-python/                 # Python CLI
    ├── docker-compose.yml          # Production-style self-hosted stack
    ├── alloy/                      # Production log-collection configuration
    ├── grafana/                    # Provisioned dashboards and data sources
    └── prometheus/                 # Metrics configuration

1. Create a branch from the current default branch.
2. Install locked dependencies with npm ci and backend development dependencies with requirements-dev.txt.
3. Add or update tests for behavior changes.
4. Run the relevant checks from Quality checks.
5. If the API contract changed, regenerate schema.yml.
6. Open a pull request that explains behavior, migration, and security implications.

Pre-commit hooks are configured in .pre-commit-config.yaml. Install them with pre-commit install or use task setup.

• Report vulnerabilities privately through the repository's security-reporting channel; do not include real PII, tokens, or credentials in public issues.
• Treat generated wordlists and risk data as sensitive.
• Keep .env, CLI credential files, encryption keys, and database exports out of version control.
• Use the platform only for personal safety work or explicitly authorized security testing.

Licensed under the Apache License 2.0.