CloakClaw — Always-On Privacy Proxy#

Prerequisites#

bash

# Required
npm install -g cloakclaw

# Optional but recommended
brew install poppler       # Better PDF text extraction
ollama pull qwen2.5:7b     # AI-powered name/company detection

Verify: cloakclaw --version should return 0.1.2 or higher.

How It Works#

1. Detect: When user sends a document or sensitive text, auto-detect the document type
2. Cloak: Run the cloaking engine (regex + local LLM) to replace sensitive entities with realistic fakes
3. Send: Forward cloaked text to the cloud LLM for analysis
4. Decloak: When response arrives, reverse all replacements to restore originals
5. Deliver: Send the restored response to user with a privacy footer

Entity Types (24)#

CategoryTypesIdentityPeople, Companies, Passports, Drivers LicenseContactEmails, Phones, AddressesFinancialDollars, Percentages, Accounts, Banks, SSNsLegalCase Numbers, JurisdictionsTechIP Addresses, MAC Addresses, Passwords/Secrets, API Keys, URLsOtherCrypto Wallets, GPS Coordinates, VIN Numbers, Medical IDs, Dates

Profiles (6)#

• general — all 24 types (default for unknown documents)
• legal — contracts, NDAs, filings (10 types)
• financial — bank statements, P&L, investor docs (11 types)
• email — correspondence (10 types)
• code — .env files, configs, infra docs (9 types)
• medical — HIPAA-adjacent records (11 types)

Auto-Detection Rules#

Always cloak (document attached):

• PDF, TXT, MD, CSV, JSON, YAML, code files → auto-detect profile from content
• Legal keywords (agreement, contract, whereas, hereby) → legal profile
• Financial keywords (revenue, P&L, balance sheet, quarterly) → financial profile
• Code files (.env, .yaml, .json with secrets) → code profile
• Default for unrecognized → general profile

Always cloak (sensitive content in text):

• Contains SSN patterns (###-##-####)
• Contains dollar amounts > $1,000
• Contains multiple proper names + company names
• Contains IP addresses, API keys, or passwords
• User explicitly says "cloak", "private", "redact", or "protect"

Skip cloaking:

• Simple questions with no sensitive data
• User says "raw", "uncloak", "no cloak", or "cloakclaw off"

Execution Flow#

Step 1: Cloak the document#

bash

node scripts/cloak.js --profile <general|legal|financial|email|code|medical> --input /path/to/file

Output JSON:

json

{
  "sessionId": "a5cc1496-15b9-4b43-8506-3ea75dfe1304",
  "cloaked": "...cloaked text...",
  "entityCount": 20,
  "profile": "legal"
}

Or use the CLI directly:

bash

cloakclaw cloak document.pdf --profile legal -o cloaked.txt

Step 2: Send cloaked text to cloud LLM#

Use the cloaked text as the document content. The user's question stays unchanged — only the document data is cloaked.

Step 3: Decloak the response#

bash

node scripts/decloak.js --session <sessionId> --input /path/to/response.txt

Or CLI:

bash

cloakclaw decloak -s <sessionId> -f response.txt

Output: restored text with original entities.

Step 4: Deliver with privacy footer#

Append to the response:

text

🔒 CloakClaw: {entityCount} entities protected | Profile: {profile} | Session: {sessionId_short}

User Commands#

• cloakclaw off — disable auto-cloaking for this session
• cloakclaw on — re-enable auto-cloaking
• cloakclaw status — show current settings and recent sessions
• cloakclaw diff <sessionId> — show what was cloaked

Configuration#

Config at ~/.cloakclaw/config.yaml:

yaml

ollama:
  url: http://localhost:11434
  model: qwen2.5:7b

Recommended Models by RAM#

RAMModelQuality8GBqwen2.5:3bBasic (regex does most work)16GBqwen2.5:7bGood32GB+qwen2.5:32bVery good64GB+qwen2.5:72bExcellent

Security#

• AES-256-GCM encrypted mapping database
• Optional password protection ( cloakclaw password set)
• Auto-expiry: sessions purged after 7 days
• Zero telemetry, zero cloud dependency for cloaking
• All processing runs locally

⚠️ Disclaimer#

CloakClaw is NOT HIPAA, GDPR, SOC 2, PCI-DSS, or CCPA compliant. It is a best-effort privacy tool. Users are responsible for reviewing cloaked output before sharing.