# security

`security` is a built-in station with no external managed tool yet.

## Commands

- `brigade security init` writes gitignored local defaults to `.brigade/security.toml`.
- `brigade security config` shows the local profile, enabled checks, severity threshold, output path, and suppressions in text mode; include/exclude paths and enrichment settings appear only with `--json`.
- `brigade security fix` creates `.brigade/security/` and refreshes the managed `.gitignore` block.
- `brigade 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-templates` to toggle public template files in findings.
- `brigade security scan --output-dir .brigade/security/latest` writes redacted report artifacts with stable finding ids, fingerprints, rule ids, severity, category, path, line, safe excerpt, and remediation hint.
- `brigade security scan --import-findings` writes the local evidence bundle and turns unsuppressed findings into deduped `security-scan` work imports with safe metadata.
- `brigade security findings` lists the latest reviewable findings, and `brigade security show <finding-id>` inspects one finding.
- `brigade security doctor` reports config, evidence, suppression, and open-finding health in text or JSON.
- `brigade security template-audit` audits public templates and docs for private values.
- `brigade security diff --base <dir>` compares two security reports for new, resolved, and persisting findings.
- `brigade security sarif` writes SARIF for an existing report.
- `brigade security closeout` writes local security review closeout metadata and supports `--reason` and `--accept-risk`.
- `brigade security enrich --target .` enriches an existing report and writes enrichment artifacts.
- `brigade security review` inspects the latest evidence bundle, including enrichment when present.
- `brigade security suppress <finding-id-or-fingerprint> --reason "..."` suppresses reviewed noise.
- `brigade security unsuppress <finding-id-or-fingerprint>` removes stale suppressions.

```bash
brigade security init
brigade security fix
brigade security scan --target .
brigade security scan --target . --policy public-repo
brigade security scan --target . --fail-on high
brigade security scan --target . --include-templates
brigade security scan --target . --output-dir .brigade/security/latest
brigade security config
brigade security doctor
brigade security findings
brigade security show <finding-id>
brigade security enrich --target .
brigade security suppress <finding-id-or-fingerprint> --reason "reviewed false positive"
brigade security unsuppress <finding-id-or-fingerprint>
brigade 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-injection` check with a `handoff-inbox` surface (`processed/` and `TEMPLATE.md` excluded)
- 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 is explicit and post-scan. The default `local` provider only summarizes extracted indicators offline. The `misp` provider is opt-in through gitignored config and an API key environment variable.

`brigade doctor` and `brigade 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.