diff --git a/apps/web/src/content/docs/docs/guides/enterprise-governance.mdx b/apps/web/src/content/docs/docs/guides/enterprise-governance.mdx index 217a237c..663565fa 100644 --- a/apps/web/src/content/docs/docs/guides/enterprise-governance.mdx +++ b/apps/web/src/content/docs/docs/guides/enterprise-governance.mdx @@ -66,7 +66,7 @@ The full example, including comments, is in the agentv repo at - **`risk_tier`** — EU AI Act vocabulary (`prohibited | high | limited | minimal`). Other vocabularies (e.g. NIST 800-30) work too; pick one and stick with it. - **`controls`** — same string format as the eval-level `governance` schema - documented in [governance metadata]. That overlap is intentional: a + documented [below](#eval-level-governance). That overlap is intentional: a control declared on a system can be cross-referenced against the controls exercised by its evals. - **`last_reviewed`** — a date. Aggregators flag entries older than @@ -138,4 +138,53 @@ You don't have to rip out the manifest convention either. Most teams keep the Git-native artifact as the **canonical source** and the platform as the **operations surface**, syncing one direction. -[governance metadata]: ./agent-eval-layers/ +## Eval-level governance + +Individual eval suites can carry their own `governance:` block that records +which risks the suite exercises. The block is passed through verbatim to the +JSONL results file, making it queryable by downstream tools. + +### YAML shape + +```yaml +governance: + schema_version: "1.0" # optional — schema version + owasp_llm_top_10_2025: [LLM01] # OWASP LLM Top 10 v2025 IDs + owasp_agentic_top_10_2025: [T01, T06] # OWASP Agentic AI Top 10 v2025 IDs + mitre_atlas: [AML.T0051] # MITRE ATLAS technique IDs + controls: # -: strings + - NIST-AI-RMF-1.0:MEASURE-2.7 + - EU-AI-ACT-2024:Art.55 + risk_tier: high # EU AI Act tier: prohibited | high | limited | minimal + owner: security-team # owning team or person +``` + +All fields are optional. Blocks can appear at suite level (top-level `governance:` key, +merged into every test case) or on individual test cases under `metadata.governance`. +When both are present, arrays are concatenated and deduplicated; scalar fields on the +case win over the suite. + +### agentv-governance skill + +The `agentv-governance` Claude Code skill teaches an AI agent how to author and lint +`governance:` blocks. Load it alongside `agentv-eval-writer` when building red-team or +compliance suites: + +``` +/load agentv-governance +``` + +The skill operates in two modes: + +- **Authoring** — provides valid IDs from OWASP LLM, OWASP Agentic, MITRE ATLAS, and EU + AI Act, and validates your block before you commit. +- **Linting (CI)** — invoked from a GitHub Action, it lints each changed `*.eval.yaml` + against a set of vocabulary rules and returns a structured JSON violation report. + +### Compliance-lint GitHub Action + +`examples/governance/compliance-lint/` contains a ready-to-copy GitHub Action that runs +the agentv-governance skill on every pull request and fails the check if any governance +block contains unknown keys, malformed IDs, or invalid `risk_tier` values. See the +[README](https://github.com/EntityProcess/agentv/blob/main/examples/governance/compliance-lint/README.md) +in that directory for setup instructions. diff --git a/plugins/agentv-dev/skills/agentv-governance/SKILL.md b/plugins/agentv-dev/skills/agentv-governance/SKILL.md index bd32ece6..1b942c1f 100644 --- a/plugins/agentv-dev/skills/agentv-governance/SKILL.md +++ b/plugins/agentv-dev/skills/agentv-governance/SKILL.md @@ -57,7 +57,7 @@ The expected output format is: 1. Check which risks this eval exercises using the reference files above. 2. Pick IDs from the relevant frameworks (`owasp_llm_top_10_2025`, `mitre_atlas`, etc.). -3. Set `risk_tier` using EU AI Act vocabulary (`prohibited | high_risk | limited_risk | minimal_risk`). +3. Set `risk_tier` using EU AI Act vocabulary (`prohibited | high | limited | minimal`). 4. Add `controls` as `-:` strings (e.g. `EU-AI-ACT-2024:Art.55`). 5. Run the lint rules from `references/lint-rules.md` against your block before committing. 6. See `references/governance-yaml-shape.md` for complete examples copied from real suites. diff --git a/plugins/agentv-dev/skills/agentv-governance/references/eu-ai-act-risk-tiers.md b/plugins/agentv-dev/skills/agentv-governance/references/eu-ai-act-risk-tiers.md index a348a9d5..9d379376 100644 --- a/plugins/agentv-dev/skills/agentv-governance/references/eu-ai-act-risk-tiers.md +++ b/plugins/agentv-dev/skills/agentv-governance/references/eu-ai-act-risk-tiers.md @@ -10,9 +10,9 @@ Full text: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689 | Value | EU AI Act category | Key articles | Description | |-------|-------------------|-------------|-------------| | `prohibited` | Prohibited AI practices | Art. 5 | AI systems whose risks are deemed unacceptable — banned outright. Examples: social scoring by public authorities, real-time remote biometric surveillance in public spaces, AI that exploits vulnerabilities of specific groups. | -| `high_risk` | High-risk AI systems | Art. 6, Annex I–III | AI systems subject to mandatory conformity assessments, transparency, and human oversight. Examples: biometric identification, critical infrastructure, employment screening, access to education or essential services, law enforcement. | -| `limited_risk` | Limited-risk AI systems | Art. 50 | AI systems with transparency obligations only. Examples: chatbots must disclose they are AI; deep-fake generators must mark synthetic media. | -| `minimal_risk` | Minimal-risk AI systems | — | No mandatory obligations. Examples: spam filters, AI in video games. Voluntary codes of conduct encouraged. | +| `high` | High-risk AI systems | Art. 6, Annex I–III | AI systems subject to mandatory conformity assessments, transparency, and human oversight. Examples: biometric identification, critical infrastructure, employment screening, access to education or essential services, law enforcement. | +| `limited` | Limited-risk AI systems | Art. 50 | AI systems with transparency obligations only. Examples: chatbots must disclose they are AI; deep-fake generators must mark synthetic media. | +| `minimal` | Minimal-risk AI systems | — | No mandatory obligations. Examples: spam filters, AI in video games. Voluntary codes of conduct encouraged. | ## Usage notes @@ -20,9 +20,9 @@ Full text: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689 - The vocabulary is anchored to EU AI Act terminology. Some organizations use different risk scales (e.g. NIST SP 800-30 `low | moderate | high | very_high`). When mapping from another framework, choose the EU AI Act equivalent that best matches the impact. -- Combine `risk_tier: high_risk` with `controls` referencing EU AI Act articles: +- Combine `risk_tier: high` with `controls` referencing EU AI Act articles: ```yaml - risk_tier: high_risk + risk_tier: high controls: - EU-AI-ACT-2024:Art.55 - EU-AI-ACT-2024:Art.6 diff --git a/plugins/agentv-dev/skills/agentv-governance/references/governance-yaml-shape.md b/plugins/agentv-dev/skills/agentv-governance/references/governance-yaml-shape.md index 2faed6eb..8a7bf12c 100644 --- a/plugins/agentv-dev/skills/agentv-governance/references/governance-yaml-shape.md +++ b/plugins/agentv-dev/skills/agentv-governance/references/governance-yaml-shape.md @@ -9,7 +9,7 @@ governance: owasp_agentic_top_10_2025: [T01, T06] # string[], optional — OWASP Agentic AI Top 10 v2025 IDs mitre_atlas: [AML.T0051] # string[], optional — MITRE ATLAS technique IDs controls: [] # string[], optional — -: strings - risk_tier: high_risk # string, optional — EU AI Act tier (see eu-ai-act-risk-tiers.md) + risk_tier: high # string, optional — EU AI Act tier (see eu-ai-act-risk-tiers.md) owner: security-team # string, optional — owning team or person ``` @@ -44,7 +44,7 @@ governance: &gov # YAML anchor for reuse in per-case overrides controls: - NIST-AI-RMF-1.0:MEASURE-2.7 - EU-AI-ACT-2024:Art.55 - risk_tier: high_risk + risk_tier: high owner: security-team tests: @@ -85,7 +85,7 @@ governance: &gov controls: - NIST-AI-RMF-1.0:MEASURE-2.7 - EU-AI-ACT-2024:Art.55 - risk_tier: high_risk + risk_tier: high owner: security-team tests: @@ -114,7 +114,7 @@ governance: &gov controls: - NIST-AI-RMF-1.0:MEASURE-2.7 - EU-AI-ACT-2024:Art.55 - risk_tier: high_risk + risk_tier: high owner: security-team ``` diff --git a/plugins/agentv-dev/skills/agentv-governance/references/lint-rules.md b/plugins/agentv-dev/skills/agentv-governance/references/lint-rules.md index 0f7eb1ca..2cceda01 100644 --- a/plugins/agentv-dev/skills/agentv-governance/references/lint-rules.md +++ b/plugins/agentv-dev/skills/agentv-governance/references/lint-rules.md @@ -123,7 +123,7 @@ Examples of valid control IDs: ## Rule 6 — risk_tier_value **What:** `risk_tier`, when present, must be one of: -`prohibited`, `high_risk`, `limited_risk`, `minimal_risk` +`prohibited`, `high`, `limited`, `minimal` **On violation:** ```json @@ -131,16 +131,16 @@ Examples of valid control IDs: "rule": "risk_tier_value", "key": "risk_tier", "value": "", - "message": "Unknown risk_tier value ''. Allowed: prohibited, high_risk, limited_risk, minimal_risk.", + "message": "Unknown risk_tier value ''. Allowed: prohibited, high, limited, minimal.", "suggestion": "Use one of the EU AI Act risk tiers from references/eu-ai-act-risk-tiers.md." } ``` Common mistakes: -- `high` → `high_risk` -- `limited` → `limited_risk` -- `minimal` → `minimal_risk` -- `low` → `minimal_risk` (not an EU AI Act term) +- `high_risk` → `high` +- `limited_risk` → `limited` +- `minimal_risk` → `minimal` +- `low` → `minimal` (not an EU AI Act term) ---