Imported from Lercas/prowl (AGENTS.md). Install upstream with npx skills add Lercas/prowl. Copyright stays with the author.

Prowl for AI agents

Prowl is a secret scanner with a layered runtime pipeline: L1 regex/checksum/entropy candidate detection → optional L2 ML false-positive filtering (--ml) → optional post-detection live verification (--verify). This guide is how an autonomous agent drives it.

MCP (preferred)

Prowl is an MCP server — register it once and call scans as tools:

claude mcp add prowl -- prowl mcp

Tools (each returns the JSON findings envelope as text):

prowl_domain refuses unless authorized: true — set it only for a target you are authorized to test (a bug-bounty scope, your own asset, an engagement). The same attestation gates the CLI's --authorized.

CLI (direct / scripting)

prowl scan ./src --ml --format json          # local tree, ML-denoised
prowl scan incident.pdf deployment.eml       # PDF text layers + decoded MIME attachments
prowl scan screenshots/ scan.pdf --ocr       # local VLM OCR for images + image-only PDF pages
prowl repo https://github.com/org/repo --verify
prowl cicd github:org/repo --ml --format json
prowl domain example.com --authorized --recon --ml --format json
prowl mobile app.apk --ml --format json
prowl image registry/img:tag --format json   # container image layers
prowl bucket s3://bucket/prefix --format json

Key flags: --format json|sarif|pretty, --ml (L2 candidate filter), --verify (post-detection provider validation), --show-secrets (raw values for authorized triage; default is redacted), --verified-only (keep only provider-confirmed live findings), --ocr (local image/PDF OCR), --max-size N (bytes), --fail-on SEV.

Output

JSON envelope: {"findings": [...], "truncated": bool, ...}. Each finding:

{ "type": "aws-access-key-id", "severity": "high", "path": "...", "line": 12,
  "redacted": "AKIA****WJX42K",        // full value when --show-secrets
  "verified": true,                     // true=LIVE, false=dead, null/absent=not checked
  "confidence": 0.9, "fingerprint": "..." }

Read verified first: true = a live, exploitable secret (the only kind worth a bug-bounty report); false = dead/rotated; null = generic type with no verifier, judge by type/confidence.

Decision guide

• Want only real leaks? add --ml --verify; for a noisy web/mobile target add --verified-only.
• --verify hits the live provider (validates the key). Fine for triage; never mass-exercise a key.
• Generic findings (generic_password, generic_high_entropy) are low-confidence and never verified — treat as candidates, not confirmed secrets. Typed findings (aws/stripe/google/jwt) are the signal.
• OCR is opt-in. --ocr sends PNG/JPEG/WebP and PDF pages without a text layer to the local OpenAI-compatible endpoint at 127.0.0.1:8080. A remote endpoint requires --ocr-allow-remote plus HTTPS because documents can contain the very secrets being scanned.
• prowl_domain / prowl_mobile surface different things: web = source maps + bundles; mobile = resources.arsc + dex strings + google-services.json (often richer). Run both for full coverage.