Configuration and Policy

Configuration and Policy

Policy is how you tell the gate what "secure enough" means for your project. It is a single JSON file, versioned and signable, that the gate engine loads on every run. This page covers the schema, how to customize it, the exceptions file, and how to sign both.

Where it lives

The default policy is .mcp/policies/security-policy.json. Override the path with SECURITY_GATE_POLICY. Generate a starter with the generate_policy tool or by copying the shipped defaults/security-policy.json (schema v1.1.0).

Policy schema

Top-level keys:

Key	Purpose
name, version, description	Identity and documentation
required_checks	The baseline checks every run must include
environments	Per-environment overrides (dev / staging / prod)
requirements	Named security gates that must hold
artifacts_required	Artifacts that must be present (for example SBOM)
vulnerability_slas	Time limits to remediate by severity
exceptions	Rules governing how findings can be excepted

required_checks

The core checks, each with the severities that block:

"required_checks": {
  "secrets_scan":    { "severity_block": ["HIGH", "CRITICAL"] },
  "dependency_scan": { "severity_block": ["HIGH", "CRITICAL"] },
  "sast":            { "severity_block": ["HIGH", "CRITICAL"] },
  "iac_scan":        { "severity_block": ["HIGH", "CRITICAL"] }
}

environments

Each of dev, staging, and prod carries its own severity_block, required_scanners, required_checks, and vulnerability_slas. This lets you run a lenient bar in dev and a strict one in prod from one file. The gate resolves the active environment at load time.

requirements

Eight named gates express architectural guarantees:

Gate	Meaning
ZERO_TRUST	Zero-trust access posture
SECRET_MANAGER_ONLY	Secrets come from a manager, never hardcoded
TLS_13	TLS 1.3 required
CSP_NO_INLINE	Content Security Policy with no inline script
CSRF	CSRF protection present
SSRF	SSRF protection present
MOBILE_MASVS	Mobile meets MASVS
AI_BOUNDED_OUTPUTS	AI outputs are bounded and validated

vulnerability_slas

Remediation deadlines by severity and intel signal:

Severity / signal	SLA
CRITICAL	24h
HIGH	7d
MEDIUM	30d
LOW	90d
CISA_KEV	24h
HIGH_EPSS	48h

A finding past its SLA is escalated by the gate.

exceptions block

Governs how findings may be waived: require_ticket defaults to true, and approval_roles defaults to [SecurityLead, GRC, CTO].

Per-surface checklists for web, api, infra, mobile, ai, and payments also ship and are produced by the checklist tool.

Customizing policy

Edit the JSON directly, or start from generate_policy. Tighten by adding required scanners or requirements, widen by relaxing severity_block in dev. Keep prod strict. Commit the file so the bar is reviewed like any other code. If integrity is enabled, re-sign after every edit (see below).

The exceptions file

Exceptions time-box a known, accepted finding so it does not block while it is being addressed. Point the gate at the file with SECURITY_GATE_EXCEPTIONS. Each exception identifies the finding, the reason, the approver, the approval role, and an expiry.

Rules the engine enforces:

• No self-approval. The approver cannot be the author of the change the exception covers.
• 365-day maximum expiry. No exception may be open-ended; the longest allowed window is one year.
• Expired equals blocking. Once the expiry passes, the exception stops suppressing and the finding blocks again.

When signed exceptions are required (SECURITY_REQUIRE_SIGNED_EXCEPTIONS), an unsigned exceptions file will not suppress HIGH or above. The break-glass override is SECURITY_ALLOW_UNSIGNED_HIGH_SUPPRESSION. See Security and Hardening.

Signing policy and exceptions

Integrity signing uses HMAC. Set a key of at least 32 bytes in SECURITY_POLICY_HMAC_KEY, then sign:

security-mcp sign-policy

This writes a .hmac sidecar next to the policy (and exceptions) file. The gate verifies the sidecar on load. An unsigned or tampered policy is treated with a HIGH/CRITICAL severity floor, so a missing signature cannot quietly weaken your gate. Commit the .hmac sidecar alongside the file it signs.

See CI/CD Integration for wiring this into pipelines and Environment Variables for every related setting.