security-gate

SECURITY-GATE

One command, one report, one verdict. SECURITY-GATE is the front door to SENTINEL: it fans out the three audit lenses, consolidates their findings, and returns a single gating decision a release pipeline (or a human) can act on.

---

Quick start

/security-gate            # full gate: PII + secrets + dependencies → SECURITY-REPORT.md
/security-gate quick      # working-tree PII + secrets only (skip history & deps) — fast pre-commit
/security-gate ./service  # gate a specific subproject

---

How it runs

Spawn the three audits in parallel (they share no state):

            ┌─ pii-audit         (personal data)   ─┐
/security-gate ─┼─ secret-scan       (credentials)    ─┼─▶ consolidate ─▶ verdict
            └─ dependency-audit  (supply chain)    ─┘

Each sub-skill returns its findings section in the shared SENTINEL finding format. SECURITY-GATE then:

1. Merges the three sections under one report.
2. Deduplicates overlaps (e.g. a connection string caught by both pii-audit and secret-scan → listed once, "confirmed by both").
3. Computes the overall verdict (below).
4. Writes SECURITY-REPORT.md.

---

Optional 4th lens — SAST via the Semgrep MCP

SENTINEL ships a semgrep MCP server (../../.mcp.json, package semgrep-mcp, run via uvx; approve it once with claude mcp list). When present it adds a static application security testing (SAST) lens through the mcp__semgrep__* tools — code-level vulnerability patterns (injection, unsafe deserialisation, path traversal, weak crypto, taint flows) that the SCA / secret / PII lenses do not cover. Scan the changed source, fold findings into the Supply Chain / Code section, and apply the same severity → verdict rule. It is optional and additive: if the server is not approved or uvx is unavailable, the gate runs its three core lenses and records SAST as a coverage gap (no silent PASS).

---

The verdict rule

Verdict	Condition	Meaning for the line
BLOCK	Any CRITICAL finding (live credential, real special-category PII, known-critical/high vuln, private key)	Do not ship. foundry's DELIVERY is halted; remediate and re-run.
REVIEW	No CRITICAL, but ≥1 HIGH or unresolved MEDIUM	Human decision required before ship. foundry surfaces it up the line (questions flow UP).
PASS	Only LOW/MINIMAL findings, all documented	Clear to ship. Report retained as evidence of diligence.

The verdict is the max severity across all three lenses — a clean PII scan does not offset a leaked key. A gate that cannot run a lens (missing tool) cannot return PASS for that lens; it returns REVIEW with the gap noted (no-silent-pass).

---

SECURITY-REPORT.md structure

# Security Gate Report — <project>
**Date:** YYYY-MM-DD   **Scope:** <scope>   **Verdict:** BLOCK | REVIEW | PASS

## Executive Summary
| Lens | Status | Highest risk | Coverage |
|------|--------|--------------|----------|
| Personal data (pii-audit)   | ✓/⚠/✗ | … | full/partial |
| Credentials (secret-scan)   | ✓/⚠/✗ | … | tree+history+artefacts |
| Supply chain (dependency-audit) | ✓/⚠/✗ | … | advisory-tool / static-only |

## Findings — Personal Data
## Findings — Credentials
## Findings — Supply Chain
## Remediation (prioritised: CRITICAL → HIGH → hygiene)
## Coverage & Gaps   (what was NOT scanned, and why — tools missing, scope limits)
## Appendix          (files/manifests scanned, exclusions applied)

---

Graceful degradation (the foundry contract)

SECURITY-GATE is what foundry calls only if SENTINEL is installed. Within SENTINEL, the gate itself degrades cleanly:

• A sub-skill whose external tool is missing (e.g. no pip-audit) runs its static checks and marks that lens partial coverage — never a false PASS.
• Foundry's side of the contract: if SENTINEL is absent entirely, foundry skips the gate, ships markdown, and notes "SECURITY gate skipped — install the sentinel plugin to enable." The decision to ship without a gate is always disclosed, never silent.

---

Chain-gap diagnostics (don't halt silently)

The gate walks a chain — pii-audit → secret-scan → dependency-audit (→ optional SAST). When a link cannot run (a sub-skill is unreachable, its required tool is absent, or a scope it needs is missing), the old failure mode was to halt or skip with no actionable guidance. Instead, detect the gap and emit a diagnostic the next operator can act on, in this exact shape:

missing: <which lens/tool — e.g. dependency-audit (pip-audit not on PATH)>
recent steps: <the chain links that DID run and their status — e.g. pii-audit ✓, secret-scan ✓>
to proceed: <the one command that closes the gap — e.g. `pip install pip-audit` then re-run /security-gate>

This is detect-and-report, never an auto-install (no network side-effects mid-audit — see the dependency-audit anti-patterns). The gap is already reflected in the verdict (a lens that cannot run cannot return PASS for that lens; the gate returns REVIEW with the gap noted), but the diagnostic turns a dead halt into a next action.

Log the gap to IN_PROGRESS.md (the conveyor's disaster-recovery artifact — the same ledger foundry's coverage-loop and phase work resume from) so a halted gate is recoverable across sessions and surfaces up the line. Append under a ## Security Gate — chain gap heading:

## Security Gate — chain gap
- **missing:** dependency-audit (pip-audit unavailable)
- **recent steps:** pii-audit ✓ · secret-scan ✓
- **to proceed:** install pip-audit, then re-run `/security-gate`
- **logged:** YYYY-MM-DD  (verdict held at REVIEW until closed)

This honours quality-first (../../knowledge/covenant.md): the gate is never weakened to make progress — a gap is disclosed and made actionable, not papered over.

---

When foundry invokes this

foundry's release path (before the DELIVERY station, after STORY) checks for SENTINEL and, if present, runs /security-gate. A BLOCK verdict halts DELIVERY (consistent with foundry's "a gate without a check is forbidden" rule); REVIEW is surfaced up the line for a human decision; PASS lets DELIVERY proceed with the report attached to the commit narrative.

---

Self-improvement covenant

SECURITY-GATE inherits the covenants of its three sub-skills. Additionally: every time a real issue ships past a PASS verdict, the verdict rule or a sub-skill pattern is tightened so the same class cannot pass again.

References

The gate carries no detection logic of its own — it composes the three sub-skills. See: ../pii-audit/SKILL.md, ../secret-scan/SKILL.md, ../dependency-audit/SKILL.md.

Product lifecycle (by capability)

SENTINEL owns the SECURE phase — the security gate, distinct from foundry's ASSURE quality gate that precedes it (quality ≠ security). When the gate returns a PASS verdict (no unresolved BLOCK/REVIEW), and the i2p plugin is installed, mark the SECURE phase done so the marketplace product lifecycle and the status line advance to PUBLISH:

/i2p-lifecycle done SECURE   # order-safe & idempotent — a no-op unless a lifecycle is running at SECURE

Degrades silently when i2p is absent. The canonical model is i2p/knowledge/product-lifecycle.md.