Brass — noise filter for AI-generated code

Brass scans a codebase and produces a small set of structured intelligence files (.brass/*.yaml) designed to be read by Claude Code, Cursor, or any other AI coding assistant. The goal is to surface what matters — real security risks, PII leaks, performance pitfalls — and hide what doesn't, so the AI's review stops drowning useful signal in low-confidence noise.

Brass is a one-shot CLI: it scans, writes the YAML, and exits. There is no background daemon, no telemetry by default, and no outbound network calls unless you opt in.

What it produces

After brassai scan, you'll find these files in .brass/:

Output directory permissions are 0700; individual files are 0600. Brass scans private source code, so this is enforced rather than opt-in.

What it detects

Findings are de-duplicated and noise-filtered before they hit disk.

Supported languages

Brass is Python-first. The scanners that drive deepest analysis — Pysa (interprocedural taint), Bandit, Pylint, and the Brass-specific AI-coder anti-pattern detectors — are Python-only.

For JS-heavy applications that need deep taint analysis, Brass should be paired with a JS-specific SAST (CodeQL, etc.). The Brass team is tracking JS taint quality as a known pre-launch limitation.

Install

# Editable install for now (PyPI package will be `brass-ai-coders`).
pip install -e .

# Verify:
brassai --help

Brass requires Python 3.10+ and pulls in PyYAML, requests, bandit, pylint, radon, vulture, detect-secrets, and pyre-check as runtime dependencies. The requests library is only used when you explicitly opt into network checks (see --check-package-hallucination below). pyre-check is pinned to a narrow version window (>=0.9.25,<0.10) because the Pysa model file format has been unstable across minors; bumping requires a verification pass on the bundled model lines.

Python 3.10 is the minimum because the recommended Semgrep version (1.143.0+, for multicore parallelism — see below) is not available on PyPI for Python 3.9.

Optional: install Semgrep for additional pattern-based taint detection. Brass recommends version 1.143.0 or later, which enables multicore parallelism for ~3× faster scans on large repos:

pip install 'semgrep>=1.143.0'

Supported platforms

Why Windows native isn't supported:

• The interprocedural taint scanner (Pysa) is built on Meta's Pyre, which has no Windows support.
• fcntl.flock cache concurrency protection is Unix-only — Brass warns and proceeds unlocked on Windows.
• ProcessPoolExecutor batched Bandit/Pylint scanning was validated on fork (Linux/macOS); Windows spawn semantics are untested.

Bringing Windows native to supported status is weeks-to-months of work (replace or sandbox Pyre/Pysa; add a Windows flock alternative; spawn-safe ProcessPool rewrites). Not on the v1 roadmap.

For Docker users on Apple Silicon: pin --platform linux/amd64 so Pyre's bundled binary runs under Rosetta emulation. See docs/CI.md for the recipe.

Usage

# One-shot scan of the current directory.
brassai --offline scan

# Watch mode: re-run incrementally on file changes.
brassai --offline watch

# Show last analysis summary.
brassai status

# Print version and which components are available.
brassai version

First-scan note: typeshed bootstrap for Pysa

The interprocedural taint scanner (Pysa) needs Python's typeshed stubs to resolve stdlib calls. Brass doesn't bundle typeshed (~33 MB) and is offline-by-default, so on a fresh install Pysa skips with a clear "typeshed not found" status until you bootstrap it. The simplest path is the one-time autofetch flag:

# First scan only — let brass git-clone python/typeshed on demand.
BRASS_AUTOFETCH_TYPESHED=1 brassai --offline scan

This makes one outbound git clone call to GitHub the first time (no other network use; the rest of --offline semantics still hold). Subsequent scans reuse the cached typeshed at ~/.cache/brass/typeshed/ with no network access.

If your environment can't reach GitHub during scans, clone typeshed once into the cache location instead:

git clone --depth 1 https://github.com/python/typeshed ~/.cache/brass/typeshed

See docs/CACHE.md for the full typeshed-cache lifecycle.

Network policy

Brass is offline by default. The only outbound network surface is the package-hallucination check, which validates imported package names against PyPI / npm / pkg.go.dev. That check is disabled unless you pass --check-package-hallucination. Pass --offline to make absolutely sure nothing leaves your machine — it overrides the opt-in flag.

# Hard offline mode — nothing leaves your machine.
brassai --offline scan

# Opt in to the hallucination check (sends imported package names to public
# registries; do not use on closed-source code with private imports).
brassai scan --check-package-hallucination

Scan modes

brassai scan --fast       # Quick: code analysis only, no privacy/content
brassai scan --dev        # Source-only: skip tests/build artifacts
brassai scan --code       # Just bugs / security / quality
brassai scan --privacy    # Just PII detection
brassai scan --content    # Just content moderation

Performance and caching

Brass caches Pysa's call-graph state at ~/.cache/brass/pysa-state/ so repeat scans run 3–4× faster than cold. The cache is per-project, auto-invalidates on config drift, and is safe to delete at any time. See docs/CACHE.md for the full lifecycle (location, size profile, invalidation triggers, BRASS_PYSA_CACHE_ROOT env var, typeshed cache).

Running Brass in CI? See docs/CI.md for cache-mount recipes for GitHub Actions, GitLab CI, and CircleCI — without a cache mount, every CI run pays the full cold-scan cost.

Privacy & data handling

• Brass never sends your source code anywhere. The only outbound calls are the optional package-hallucination registry checks described above.
• The privacy scanner detects PII and writes findings to disk with the matched values redacted. Raw matched text is replaced with a masked form before serialization; raw context lines are dropped entirely.
• The secret scanner records the secret type and a short hash for de-duplication. The raw secret value is never persisted.
• See docs/PRIVACY_POLICY.md for the full disclosure.

Architecture

CLI ──► Scanners ──► IntelligenceRanker ──► YAMLOutputGeneratorV2 ──► .brass/*.yaml

Each scanner is single-purpose and returns List[Finding]. The ranker weights and orders. The output generator writes atomic, owner-only YAML. There is no background process, no scheduler, and no inter-scanner communication.

The Finding dataclass at src/brass/models/finding.py is the system's single contract; all builders, scanners, and the ranker depend on it but not on each other.

License

Apache 2.0. See LICENSE and NOTICE.