Scan gates
Scan gates are the Gatekeep-facing acceptance criteria within definition_of_done.scan_gates. They define which Gatekeep finding categories must pass, at what severity, and whether a failure blocks the PR or is advisory only. Scan gates are one part of the definition of done — not the entire contract.
devcontract.json format. They now live in their correct place: inside definition_of_done.scan_gates as the PR-time enforcement layer of the full DevContract.
Gate categories
| Category | What Gatekeep checks | Typical blocking severity |
|---|---|---|
secret |
Hardcoded secrets, API keys, passwords, tokens in source code. Runs detect-secrets and trufflehog patterns. | critical |
sast |
Static analysis security testing. Runs Semgrep and Bandit for Python. SQL injection, XSS, path traversal, and similar vulnerabilities. | high |
dependency |
Known CVEs in direct and transitive dependencies. Runs pip-audit (Python) and Snyk patterns. | critical |
iac |
Infrastructure-as-code misconfigurations. Runs Checkov against Terraform and CloudFormation templates. | high |
governance |
Governance policy violations: missing resource tags, unencrypted resources, public S3 buckets, IAM * permissions. | high |
license |
Dependency license compliance. Flags GPL, AGPL, and other copyleft licenses in commercial codebases. | high |
code_quality |
Code quality metrics: complexity, duplication, maintainability. Runs Ruff for Python. | medium |
quality |
Test coverage and test pass rate against the quality.test_coverage_min clause. |
high |
Severity levels
| Severity | Description |
|---|---|
critical | Confirmed vulnerability or exposure with immediate exploitation risk. e.g. hardcoded AWS credential, known RCE CVE. |
high | Significant security or quality issue likely to be exploitable or cause data loss. e.g. SQL injection vector, unencrypted S3 bucket. |
medium | Issue that reduces security posture but requires additional conditions to exploit. e.g. overly permissive IAM role, missing CSRF protection. |
low | Best practice deviation with limited direct security impact. e.g. missing security header, outdated but non-vulnerable dependency. |
info | Informational finding. No action required. Used for audit trail completeness. |
Thresholds
The threshold field in a scan gate controls how many findings at the specified severity are allowed before the gate fails. The default is 0 — fail on any finding at or above the specified severity.
| threshold value | Behaviour |
|---|---|
0 (default) | Zero tolerance. Any finding at the specified severity fails the gate. |
N | Up to N findings are permitted. The (N+1)th finding fails the gate. |
Use thresholds sparingly. A threshold above 0 documents a known technical debt acceptance. Use approved exceptions in the cost clause for similar compromises on infrastructure.
Blocking vs advisory
When blocking: true, a gate failure blocks the PR — the overall verdict becomes contract_breached. When blocking: false, the gate failure is recorded in the evidence bundle but the PR is not blocked. Use advisory gates for monitoring purposes before enforcing.
Recommended minimum gates
For any new project, start with these three blocking gates:
"scan_gates": [
{"category": "secret", "severity": "critical", "threshold": 0, "blocking": true},
{"category": "sast", "severity": "high", "threshold": 0, "blocking": true},
{"category": "dependency", "severity": "critical", "threshold": 0, "blocking": true}
]
Add iac and governance gates once you have Terraform/CloudFormation in your repository. Add license if you are building a commercial product.