How to Run Your First BrassCoders Scan on AI-Generated Python
Step-by-step: install BrassCoders, run the scan, read the .brass/ai_instructions.yaml output, and understand what to do with the findings.
brasscoders scan runs 12 static-analysis scanners against your project tree and writes the results to a single YAML file — .brass/ai_instructions.yaml — built for AI assistants to read.
Install BrassCoders from PyPI and point it at your project:
pip install brasscoders
brasscoders scan /path/to/your/projectZero configuration required. The scan runs locally — no account, no activation key — against your full source tree: Python and JavaScript/TypeScript files alike. When it finishes, the .brass/ directory appears at your project root. The OSS core makes zero outbound network calls; everything happens on your machine.
The resulting .brass/ai_instructions.yaml file groups findings by severity, CRITICAL down to LOW. Each entry names the scanner that flagged it — Bandit for Python security issues, or detect-secrets for credential patterns — along with the file path, line number, and a short remediation note. A scanner_metadata section records which of the 12 scanners ran and how many findings each produced. At the top sits a how_to_read_this_file block. It describes the field structure and orients your AI assistant before it reads a single finding.
Open the file in Claude Code or paste its contents into a Cursor chat. Each finding already names its source scanner, so the AI assistant knows the detection method before triage starts. The how_to_read_this_file header handles orientation — it describes each field and explains the severity tiers, so you get a triage conversation from the start. You don’t need to prompt for context.
For air-gapped machines or compliance-sensitive environments, add the --offline flag before scan: brasscoders --offline scan /path/to/your/project. The flag position matters — it must come before scan, not after. If the scan attempts any network call at runtime, it exits non-zero. That’s a process-level guarantee rather than a behavioral default.
The OSS core is Apache 2.0 licensed and installs with a single pip command. The .brass/ directory it creates is safe to add to .gitignore.
Frequently Asked Questions
What does brasscoders scan output?
brasscoders scan writes .brass/ai_instructions.yaml to your project root. The file groups findings by severity — CRITICAL down to LOW — with each entry listing the scanner that flagged it, the file path, the line number, and a short remediation note. A scanner_metadata section records which of the 12 scanners ran. The file opens with a how_to_read_this_file block that orients your AI assistant before it reads a single finding.
Do I need to configure anything before the first scan?
No. The OSS core requires zero configuration. Install with pip install brasscoders, point it at a directory, and it runs all 12 scanners with no setup steps. A .brassignore file is available if you want to suppress specific findings after reviewing the output.
Can I run BrassCoders offline?
Yes. The OSS core makes zero outbound network calls by default — every scanner runs locally against your source tree. For air-gapped environments or compliance requirements, brasscoders --offline scan . adds hard enforcement: the scan exits non-zero if any network call is attempted at runtime. The --offline flag goes before scan in the command.