blacktent 0.1.0

Local-first secret scanner that redacts sensitive values before AI handoff.

BlackTent

An AI-safe firewall for your codebase. Detects secrets, redacts them deterministically, and produces a sanitized bundle you can hand to any AI tool without fear.

blacktent scan-file path/to/file.txt

---

Install

pip install blacktent

Requires Python 3.9+.

---

Usage

Scan a single file

blacktent scan-file path/to/file.txt
blacktent scan-file path/to/file.txt --out redacted.txt

Scan a directory

blacktent scan-dir .
blacktent scan-dir ./src --out-dir ./safe

Bundle for AI handoff

blacktent bundle .
blacktent bundle . --bundle-root ./ai-bundle

Creates a folder with redacted copies of every file that had findings, plus a manifest.json describing every redaction.

Patch (reapply redactions from manifest)

blacktent patch original.txt --out patched.txt

Replays the redactions from .blacktent/manifest.json onto the original file using SHA-256 validation. Safe and deterministic — no re-scanning.

Env diagnostics

blacktent env-check .

Reports which .env* files exist, which keys from .env.example are present or missing in the environment. Outputs safe JSON to .blacktent/env_report.json.

---

What it detects

Rule	Pattern
OPENAI_KEY	sk- followed by 20+ alphanumeric characters
GITHUB_TOKEN	ghp_ followed by 20+ alphanumeric characters
GENERIC_API_KEY	api_key = or token = assignments with 16+ char values
PASSWORD	password = assignments with quoted values

Redacted values use stable placeholders that encode the rule and an 8-character hash:

[REDACTED:OPENAI_KEY:88c422f1]

---

Output structure

Reports are written to .blacktent/ in your working directory:

.blacktent/
├── manifest.json      # all findings: file, span offsets, SHA-256, replacement
└── env_report.json    # env-check output

Bundles are written to blacktent.bundle/ (or --bundle-root):

blacktent.bundle/
├── files/             # redacted copies of files with findings
├── manifest.json      # same manifest, copied into bundle
└── README_AI.txt      # handoff note for the AI

---

What BlackTent will NOT do

• Read actual secret values
• Upload anything
• Modify your source files
• Guess env values
• Phone home

BlackTent is local, explicit, and reversible.

---

Status

MVP — stable core pipeline.

Planned next:

• blacktent doctor (full repo health check)
• .blacktentignore support
• CI-friendly exit codes and JSON output mode
• Pre-AI hooks

---

License

MIT