Docs / Reference
security
The built-in agent workspace security scanner and evidence bundles.
Use this to scan an agent workspace for risky settings and unsafe tool setups, and to keep the evidence.
security is a built-in component with no external managed tool yet.
Commands
brigadestack security initwrites gitignored local defaults to.brigade/security.toml.brigadestack security configshows the local profile, enabled checks, severity threshold, output path, and suppressions in text mode. Include and exclude paths and enrichment settings appear only with--json.brigadestack security fixcreates.brigade/security/and refreshes the managed.gitignoreblock.brigadestack security scan --target .runs a read-only agent workspace security scan, with--fail-on <severity>to return nonzero at or above a severity and--include-templates/--no-include-templatesto toggle public template files in findings.brigadestack security scan --output-dir .brigade/security/latestwrites redacted report artifacts with stable finding ids, fingerprints, rule ids, severity, category, path, line, safe excerpt, and remediation hint.brigadestack security scan --import-findingswrites the local evidence bundle and turns unsuppressed findings into dedupedsecurity-scanwork imports with safe metadata.brigadestack security findingslists the latest reviewable findings, andbrigadestack security show <finding-id>inspects one finding.brigadestack security doctorreports config, evidence, suppression, and open-finding health in text or JSON.brigadestack security template-auditaudits public templates and docs for private values.brigadestack security diff --base <dir>compares two security reports for new, resolved, and persisting findings.brigadestack security sarifwrites SARIF for an existing report.brigadestack security closeoutwrites local security review closeout metadata and supports--reasonand--accept-risk.brigadestack security enrich --target .enriches an existing report and writes enrichment artifacts.brigadestack security reviewinspects the latest evidence bundle, including enrichment when present.brigadestack security suppress <finding-id-or-fingerprint> --reason "..."suppresses reviewed noise.brigadestack security unsuppress <finding-id-or-fingerprint>removes stale suppressions.
brigadestack security init
brigadestack security fix
brigadestack security scan --target .
brigadestack security scan --target . --policy public-repo
brigadestack security scan --target . --fail-on high
brigadestack security scan --target . --include-templates
brigadestack security scan --target . --output-dir .brigade/security/latest
brigadestack security config
brigadestack security doctor
brigadestack security findings
brigadestack security show <finding-id>
brigadestack security enrich --target .
brigadestack security suppress <finding-id-or-fingerprint> --reason "reviewed false positive"
brigadestack security unsuppress <finding-id-or-fingerprint>
brigadestack security scan --target . --import-findings
Config contract
The local .brigade/security.toml contract supports scan_profile values public-repo, internal-workspace, and local-only-audit, plus enabled_checks, include_paths, exclude_paths, severity_threshold, suppressions, and output_path. Scan state and raw evidence stay under .brigade/security/ and should remain gitignored. Public reports and work imports use redacted excerpts and safe detail fields, not raw secrets or private infrastructure values. The scanner never calls external SaaS scanners, runs network scans, stores secrets, starts a daemon, or remediates automatically.
Security config supports policy presets (personal, public-repo, ci, strict), fail_on, template scanning, fingerprint suppressions, and [enrichment] provider settings.
What the scanner covers
- secrets and private keys
- broad permissions and risky hooks
- package scripts, GitHub Actions, and Python dependency config
- prompt-injection style instructions
- pending handoff notes in writer inboxes, screened for prompt-injection signals as a dedicated
handoff-injectioncheck with ahandoff-inboxsurface (processed/andTEMPLATE.mdexcluded) - MCP configs, including remote transports, auto-approval, unpinned
npx, and shell metacharacters - MCP sensitive surfaces, including env values, broad file args, high-risk local commands, large server sets, and missing timeouts
Enrichment
Enrichment runs after the scan. The default local provider summarizes extracted indicators offline. The misp provider needs gitignored config and an API key environment variable.
brigadestack doctor and brigadestack work doctor report security config health, enrichment config health, stale suppressions and missing suppression reasons, latest evidence bundle status, and whether local security artifacts are ignored. Secret evidence is redacted before reports, artifacts, or imports are written.