Merge pull request #46 from escoffier-labs/feat/security-finding-lifecycle

feat: add security finding lifecycle

Author: solomonneas

CHANGELOG.md

@@ -58,9 +58,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade security scan --import-findings` to route security findings into the local work import inbox for review.
 - `brigade security init` to write gitignored local defaults to `.brigade/security.toml`.
 - `brigade security fix` to create the local security artifact directory and refresh the managed `.gitignore` block.
+- `brigade security review`, `brigade security suppress`, and `brigade security unsuppress` for a local finding review lifecycle with required suppression reasons.
 - Security policy presets (`personal`, `public-repo`, `strict`), template scanning controls, stable finding fingerprints, and fingerprint suppressions.
 - `brigade security scan --output-dir <dir>` to write redacted `security-report.json` and `security-report.md` evidence bundles.
 - `brigade doctor` and `brigade work doctor` now report security config health, latest security evidence bundle status, and local security artifact ignore coverage.
+- `brigade doctor` and `brigade work doctor` now warn on stale security suppressions and suppressions missing reasons.
 - Security scan secret evidence is redacted before reports or work imports are written.
 - `ROADMAP.md` covering the daily-driver path, scanner-ready inbox, chat-surface scanners, memory-card decay refresh, and portable operator setup.
 - `brigade work note` to append timestamped checkpoints to the active work session without ending it.

README.md

@@ -207,6 +207,9 @@ brigade security fix
 brigade security scan --target .
 brigade security scan --target . --policy public-repo
 brigade security scan --target . --output-dir .brigade/security/latest
+brigade security review
+brigade security suppress <fingerprint> --reason "reviewed false positive"
+brigade security unsuppress <fingerprint>
 brigade security scan --target . --import-findings
 ```
 
@@ -291,7 +294,7 @@ brigade add guard    # content-guard
 brigade add tokens   # tokenjuice
 ```
 
-`security` is a built-in station with no external managed tool yet. Run `brigade security scan --target .` for a read-only agent workspace security report, add `--output-dir .brigade/security/latest` to write redacted `security-report.json` and `security-report.md` artifacts, or add `--import-findings` to turn findings into local `brigade work import` review items. The scanner covers secrets, permissions, hooks, supply-chain patterns, prompt-injection patterns, and MCP configs including remote transports, auto-approval, unpinned `npx`, shell metacharacters, secret-looking env values, sensitive and broad file args, high-risk local commands, large server sets, and missing timeouts. `brigade doctor` and `brigade work doctor` report security config health, latest evidence bundle status, and whether local security artifacts are ignored. `brigade security fix` applies the narrow safe hygiene fix for that local state: it creates `.brigade/security/` and refreshes the managed `.gitignore` block. Secret evidence is redacted before reports, artifacts, or imports are written. Use `brigade security init` to write gitignored local defaults to `.brigade/security.toml`; it supports policy presets (`personal`, `public-repo`, `strict`), `fail_on`, template scanning, and fingerprint suppressions for reviewed findings.
+`security` is a built-in station with no external managed tool yet. Run `brigade security scan --target .` for a read-only agent workspace security report, add `--output-dir .brigade/security/latest` to write redacted `security-report.json` and `security-report.md` artifacts, or add `--import-findings` to turn findings into local `brigade work import` review items. Run `brigade security review` to inspect the latest evidence bundle, `brigade security suppress <fingerprint> --reason "..."` to suppress reviewed noise with a required reason, and `brigade security unsuppress <fingerprint>` to remove stale suppressions. The scanner covers secrets, permissions, hooks, supply-chain patterns, prompt-injection patterns, and MCP configs including remote transports, auto-approval, unpinned `npx`, shell metacharacters, secret-looking env values, sensitive and broad file args, high-risk local commands, large server sets, and missing timeouts. `brigade doctor` and `brigade work doctor` report security config health, stale suppressions, missing suppression reasons, latest evidence bundle status, and whether local security artifacts are ignored. `brigade security fix` applies the narrow safe hygiene fix for that local state: it creates `.brigade/security/` and refreshes the managed `.gitignore` block. Secret evidence is redacted before reports, artifacts, or imports are written. Use `brigade security init` to write gitignored local defaults to `.brigade/security.toml`; it supports policy presets (`personal`, `public-repo`, `strict`), `fail_on`, template scanning, and fingerprint suppressions for reviewed findings.
 
 The current managed tools:
 

ROADMAP.md

@@ -65,7 +65,16 @@ Brigade-specific additions:
 - Produce Memory Handoffs for durable security findings while keeping raw secret evidence redacted.
 - Add policy packs for personal dogfooding, public-repo release checks, CI gates, and strict enterprise workspaces. Status: started with `personal`, `public-repo`, and `strict`.
 - Include dependency and package-manager hardening checks for agent plugin ecosystems, MCP packages, skills, and local tool wrappers.
-- Track false-positive taxonomy, runtime-confidence rules, suppressions, and regression fixtures as first-class project artifacts.
+- Track false-positive taxonomy, runtime-confidence rules, suppressions, and regression fixtures as first-class project artifacts. Status: started with `brigade security review`, reasoned suppressions, unsuppress, and stale-suppression doctor warnings.
+
+## Later Phase: Issue And TDD Work Loop
+
+Goal: make Brigade support a narrow issue lifecycle for daily work: pick one task, define acceptance, test first when practical, implement, review, refactor, and close.
+
+- Add task templates for vertical-slice work, bugfix work, and RED/GREEN/REFACTOR loops.
+- Let `brigade work run` consume structured acceptance criteria from the local task ledger or a GitHub issue mirror.
+- Keep repo-shareable workflow rules separate from gitignored personal/global preferences.
+- Add doctor checks for missing acceptance criteria or stale active issue context.
 
 First build slice:
 

src/brigade/cli.py

@@ -394,6 +394,17 @@ def _build_parser() -> argparse.ArgumentParser:
     p_security_fix = security_sub.add_parser("fix", help="Apply safe local security hygiene fixes.")
     p_security_fix.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
     p_security_fix.add_argument("--dry-run", action="store_true", help="Show changes without writing files.")
+    p_security_review = security_sub.add_parser("review", help="Review the latest local security evidence bundle.")
+    p_security_review.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to review.")
+    p_security_review.add_argument("--output-dir", type=Path, default=None, help="Security evidence bundle directory.")
+    p_security_review.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_security_suppress = security_sub.add_parser("suppress", help="Suppress a reviewed security finding fingerprint.")
+    p_security_suppress.add_argument("fingerprint", help="Finding fingerprint to suppress.")
+    p_security_suppress.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
+    p_security_suppress.add_argument("--reason", required=True, help="Required suppression reason.")
+    p_security_unsuppress = security_sub.add_parser("unsuppress", help="Remove a security finding suppression.")
+    p_security_unsuppress.add_argument("fingerprint", help="Finding fingerprint to unsuppress.")
+    p_security_unsuppress.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
     p_security_scan = security_sub.add_parser("scan", help="Run a read-only agent workspace security scan.")
     p_security_scan.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to scan.")
     p_security_scan.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
@@ -796,6 +807,12 @@ def main(argv=None) -> int:
             return security_cmd.init(target=args.target, force=args.force)
         if args.security_command == "fix":
             return security_cmd.fix(target=args.target, dry_run=args.dry_run)
+        if args.security_command == "review":
+            return security_cmd.review(target=args.target, output_dir=args.output_dir, json_output=args.json)
+        if args.security_command == "suppress":
+            return security_cmd.suppress(target=args.target, fingerprint=args.fingerprint, reason=args.reason)
+        if args.security_command == "unsuppress":
+            return security_cmd.unsuppress(target=args.target, fingerprint=args.fingerprint)
         if args.security_command == "scan":
             return security_cmd.scan(
                 target=args.target,

src/brigade/doctor.py

@@ -87,16 +87,36 @@ def security_station_checks(ctx: DoctorContext) -> List[CheckResult]:
 
     results: List[CheckResult] = [(OK, "security: built-in scanner", "available")]
     config = security_cmd.config_path(ctx.target)
+    config_valid = True
     if config.is_file():
         try:
             loaded = security_cmd.load_config(ctx.target)
         except ValueError as exc:
+            config_valid = False
             results.append((FAIL, "security: config", f"invalid {config}: {exc}"))
         else:
             results.append((OK, "security: config", f"{config} (policy={loaded.policy if loaded else 'personal'})"))
     else:
         results.append((WARN, "security: config", f"missing at {config}; run `brigade security init --target .`"))
 
+    if config_valid:
+        try:
+            suppression_health = security_cmd.suppression_health(ctx.target)
+        except ValueError as exc:
+            results.append((FAIL, "security: suppressions", f"invalid: {exc}"))
+        else:
+            suppression_count = suppression_health["suppression_count"]
+            stale = suppression_health["stale"]
+            missing_reasons = suppression_health["missing_reasons"]
+            if stale:
+                preview = ", ".join(stale[:5])
+                results.append((WARN, "security: stale suppressions", f"{len(stale)} no longer match current findings: {preview}"))
+            if missing_reasons:
+                preview = ", ".join(missing_reasons[:5])
+                results.append((WARN, "security: suppression reasons", f"{len(missing_reasons)} missing reason: {preview}"))
+            if not stale and not missing_reasons:
+                results.append((OK, "security: suppressions", f"{suppression_count} configured"))
+
     artifacts_dir = security_cmd.default_artifacts_dir(ctx.target)
     bundle = security_cmd.inspect_evidence_bundle(artifacts_dir)
     if bundle.get("ready"):