Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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 init writes gitignored local defaults to .brigade/security.toml.
  • brigadestack security config shows 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 fix creates .brigade/security/ and refreshes the managed .gitignore block.
  • 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-templates to toggle public template files in findings.
  • brigadestack 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.
  • brigadestack security scan --import-findings writes the local evidence bundle and turns unsuppressed findings into deduped security-scan work imports with safe metadata.
  • brigadestack security findings lists the latest reviewable findings, and brigadestack security show <finding-id> inspects one finding.
  • brigadestack security doctor reports config, evidence, suppression, and open-finding health in text or JSON.
  • brigadestack security template-audit audits public templates and docs for private values.
  • brigadestack security diff --base <dir> compares two security reports for new, resolved, and persisting findings.
  • brigadestack security sarif writes SARIF for an existing report.
  • brigadestack security closeout writes local security review closeout metadata and supports --reason and --accept-risk.
  • brigadestack security enrich --target . enriches an existing report and writes enrichment artifacts.
  • brigadestack security review inspects 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-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 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.