What Does a BrassCoders Scan Output Look Like?
BrassCoders writes a small set of YAML files to .brass/ — a ranked AI instructions file, a full findings file, a per-file view, a security-only view, and aggregate statistics. Here's what each contains.
The Files in the .brass/ Directory
BrassCoders writes five YAML files to .brass/ after every scan, plus two more when they’re relevant: ai_instructions.yaml (short, severity-ranked findings for AI assistants), detailed_analysis.yaml (every finding, grouped by type), file_intelligence.yaml (findings collated per file, ranked by priority), security_report.yaml (security-only view), and statistics.yaml (aggregate counts and severity distribution). privacy_analysis.yaml appears when PII findings exist; operator_notes.yaml appears when there’s an operator-facing advisory.
Run brasscoders scan . and a .brass/ directory appears at your project root:
- ai_instructions.yaml — the primary output. Short, severity-ranked findings designed for pasting into Claude Code or Cursor. Contains title, severity, confidence, file_path, line_number, scanner, and a one-sentence description. This is what your AI assistant reads first.
- detailed_analysis.yaml — the full output. Every finding with extended context, evidence strings, and scanner metadata. Useful for deeper review or custom tooling.
- file_intelligence.yaml — the same findings collated per file and ranked by priority. Useful when you’re working through one file at a time rather than by severity.
- security_report.yaml — security findings only, separated for audit purposes. Useful if your security team wants a focused view without performance or code-quality findings.
- statistics.yaml — aggregate counts and severity distribution across the whole scan. The quick “how bad is it” summary.
- privacy_analysis.yaml (conditional) — a privacy-only view, written only when the scan actually finds PII.
- operator_notes.yaml (conditional) — operator-facing diagnostics, like a growing Pysa analysis cache or a version warning, not findings about your code.
What ai_instructions.yaml Contains
BrassCoders structures ai_instructions.yaml to be pasted directly into Claude Code or Cursor — each finding has a title, severity level (CRITICAL/HIGH/MEDIUM/LOW), confidence score, exact file path, line number, and a description written for an AI reviewer, not a human reader.
The YAML format (https://yaml.org/spec/1.2.2/) makes ai_instructions.yaml readable by any tool. The Paid plan adds an enrichment pass on top of the OSS core’s heuristic noise reduction, deduplicating against your project’s README, dependency manifest, and top-level structure. In one published case study, that took a scan from 2,470 raw findings to 217 after heuristic reduction to 22 after AI-enrichment dedup — the real ratio depends on codebase size and how much duplicate/overlapping signal the scanners produce.
The intended workflow: open Claude Code (https://docs.anthropic.com/en/docs/claude-code) or Cursor, paste the contents of ai_instructions.yaml into the context window, and ask the AI to triage the findings. The format is designed for that consumption pattern.
The .brass/ directory is safe to add to .gitignore — it’s generated output, not source. Re-run the scan whenever you want a fresh view.
Install BrassCoders with pip install brasscoders and run brasscoders scan . from your project root. The OSS core is free and Apache 2.0 licensed. BrassCoders Paid adds semantic noise reduction for $12/dev/month.
Frequently Asked Questions
What files does brasscoders scan create?
Five YAML files in .brass/ at your project root, every scan: ai_instructions.yaml (short, ranked findings for AI assistants), detailed_analysis.yaml (every finding, grouped by type), file_intelligence.yaml (findings collated per file, ranked by priority), security_report.yaml (security findings only, for audit purposes), and statistics.yaml (aggregate counts and severity distribution). Two more appear conditionally: privacy_analysis.yaml when PII findings exist, and operator_notes.yaml when there's an operator-facing advisory (e.g. cache size, version warnings).
Can I parse .brass/ai_instructions.yaml programmatically?
Yes — it's standard YAML. Any YAML library (PyYAML, ruamel.yaml in Python; js-yaml in Node.js) can parse it. Each finding is a YAML mapping with keys: title, severity, confidence, file_path, line_number, scanner, description.
Should I commit .brass/ to version control?
No — .brass/ is generated output and regenerates on every scan. Add it to .gitignore. Committing it adds churn without value; the scan output is only meaningful at the moment it was generated against the current source tree.
How is the Paid plan output different from the OSS core output?
The file structure is identical. The difference is volume: the OSS core produces findings after heuristic noise reduction; the Paid plan adds a semantic-dedup pass against your project signature on top of that. In one published case study, a scan went from 2,470 raw findings to 217 after heuristic reduction to 22 after AI-enrichment dedup — real numbers vary by codebase size.