This document tells you exactly what Brass reads, what it writes, and what (if anything) leaves your machine. If anything in this document is incorrect or out of date, that is a bug — please file an issue.

What Brass reads

Brass scans files inside the directory you point it at (the project root). For each file under that root, Brass:

Skips it if any path component is in the exclusion list (.git, __pycache__, node_modules, .venv, venv, build, dist, .brass, .next, .nuxt, .svelte-kit, prisma/generated, etc.).
Skips it if the resolved path falls outside the project root, even via a symlink.
Skips files larger than 1 MiB.
Reads the file content into memory.
Runs the relevant scanner suites (security, privacy, code quality, performance, secrets, content moderation).

Brass does not read files outside your project root.

What Brass writes

Brass creates a .brass/ directory inside the project root and writes:

ai_instructions.yaml — top-level summary
detailed_analysis.yaml — every finding, grouped by type
file_intelligence.yaml — findings collated per file
security_report.yaml — security-only view
statistics.yaml — aggregate metrics
privacy_analysis.yaml — present only when PII findings exist
brass.log — diagnostic log

The .brass/ directory is created with permissions 0700; YAML files are written with 0600 (POSIX). On Windows, Brass relies on filesystem ACLs.

Redaction in output

The privacy scanner exists to detect sensitive data; it would defeat the purpose to write the raw matched data into .brass/. Brass enforces this in two places:

At the source. The privacy scanner replaces the raw matched value with a masked version (e.g. 4111****1111), drops the surrounding context line, and clears the top-level code_snippet field for any privacy finding.
At the boundary. The YAML writer strips a known set of privacy-sensitive metadata keys (matched_text, code_snippet, context_line, raw_match, context) from any finding whose type is PRIVACY or whose detector is in the secret-leak allowlist (auth_pattern_analyzer, bandit) before serialization.

The hardcoded-credential detection path replaces literal values inside string quotes with <REDACTED> before persisting the line. The secret scanner records only the secret type and a short hash for de-duplication. The secret value itself is never written to disk by Brass.

What leaves your machine

Brass makes no outbound network calls by default.

The single optional network path is the package-hallucination check. When enabled, Brass takes each imported package name from your code and issues HTTPS GETs to the relevant registry to confirm it exists:

Python: https://pypi.org/pypi/<name>/json
JavaScript: https://registry.npmjs.org/<name>
Go: https://pkg.go.dev/<name>

This check is off by default and must be opted into per scan via --check-package-hallucination. Passing --offline overrides the opt-in back to off; that flag is the canonical way to assert "do not let anything leave my machine."

You should not enable the package-hallucination check on a project that imports private internal package names. Doing so would leak those names to the public registry.

There is no telemetry, error reporting, or auto-update check active by default in Brass. The optional telemetry framework, when enabled via brassai telemetry on, sends only anonymized usage counts (event type, finding-type distribution, CLI version, OS) and never includes source code, file paths, emails, or stack traces.

What Brass refuses to do

Brass refuses to follow symlinks pointing outside the project root, even if the symlink itself is inside the project. This prevents a hostile repo from steering a scan into ~/.aws/credentials or ~/.ssh/id_rsa.
Brass refuses to inherit user/system git config when invoking git, to prevent CVE-2022-24765-class repos from achieving code execution during the scan-time git health check.
Brass synthetic performance scripts (brassai scan --performance-full) run via python3 -I in a minimal env, and the script bodies are static templates — no metadata interpolation is permitted.

Reporting a privacy or security issue

Email brass@coppersuncreative.com with a description and reproduction steps. We treat unauthorized data egress, raw-PII serialization, and silent network calls as launch-blocking bugs and will respond within one business day.