56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
# AI Code Guard Policy Guide
|
|
> **Status:** Planned
|
|
> **Audience:** Policy authors, Security reviewers, CI owners
|
|
> **Related:** `docs/modules/scanner/operations/ai-code-guard.md`
|
|
|
|
This guide defines the Policy signals and matrix logic used to evaluate AI Code Guard evidence. The goal is deterministic, explainable pass/review/block outcomes with auditable overrides.
|
|
|
|
## 1) Policy goals
|
|
- Deterministic pass/review/block outcomes for the same inputs.
|
|
- Explainable results with short reasons and evidence links.
|
|
- Overrides allowed only with issue link and expiry.
|
|
|
|
## 2) Signals (proposed)
|
|
|
|
| Signal | Type | Notes |
|
|
| --- | --- | --- |
|
|
| `guard.ai.status` | string | `pass`, `review`, `block` from Scanner. |
|
|
| `guard.ai.hunk.count` | int | Count of changed hunks evaluated. |
|
|
| `guard.ai.secrets.new.count` | int | New secrets in this change. |
|
|
| `guard.ai.secrets.pre_existing.count` | int | Previously known secrets. |
|
|
| `guard.ai.unsafe.count` | int | Unsafe API findings. |
|
|
| `guard.ai.similarity.max` | number | Highest similarity score (0.0-1.0). |
|
|
| `guard.ai.similarity.denylist_hit` | bool | True when denylist threshold is exceeded. |
|
|
| `guard.ai.license.block.count` | int | Licenses in block list. |
|
|
| `guard.ai.license.review.count` | int | Licenses requiring review. |
|
|
| `guard.ai.override.active` | bool | Override is present and unexpired. |
|
|
| `guard.ai.override.expires_at` | string | UTC ISO-8601 timestamp. |
|
|
|
|
## 3) Policy matrix
|
|
|
|
Default matrix (policy pack example):
|
|
- Block if new secrets or denylist similarity exceed thresholds.
|
|
- Review if license review count > 0 or similarity above review threshold.
|
|
- Pass otherwise.
|
|
|
|
## 4) Example DSL snippet
|
|
|
|
```dsl
|
|
rule ai_code_guard_block priority 50 {
|
|
when guard.ai.secrets.new.count > 0 or guard.ai.similarity.denylist_hit == true
|
|
then status := "block"
|
|
because "AI code guard block criteria met";
|
|
}
|
|
```
|
|
|
|
## 5) Overrides
|
|
|
|
- Overrides require issue links and expiry.
|
|
- Review overrides require `SecurityReviewer` role; block overrides require `SecurityOwner`.
|
|
- Policy explain traces must include override metadata for audit.
|
|
|
|
## 6) Evidence and replay
|
|
|
|
- Policy explain exports include the guard evidence hash and rule version.
|
|
- Guard evidence is stored and signed for deterministic replay.
|