audit notes work completed, test fixes work (95% done), new sprints, new data sources setup and configuration
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
> **Ownership:** Policy Guild • Platform Guild
|
||||
> **Services:** `StellaOps.Policy.Engine` (Minimal API + worker host)
|
||||
> **Data Stores:** PostgreSQL (`policy.*` schemas for packs, runs, exceptions, receipts), Object storage (explain bundles), optional queue
|
||||
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../aoc/aggregation-only-contract.md)
|
||||
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../aoc/aggregation-only-contract.md), [AI Code Guard policy](guides/ai-code-guard-policy.md)
|
||||
|
||||
This dossier describes the internal structure of the Policy Engine service delivered in Epic 2. It focuses on module boundaries, deterministic evaluation, orchestration, and integration contracts with Concelier, Excititor, SBOM Service, Authority, Scheduler, and Observability stacks.
|
||||
|
||||
|
||||
55
docs/modules/policy/guides/ai-code-guard-policy.md
Normal file
55
docs/modules/policy/guides/ai-code-guard-policy.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user