agent-threat-rules 2.1.5 → 3.0.5

package/spec/README.md

@@ -0,0 +1,279 @@
+# ATR Specification Index
+
+**ATR — Agent Threat Rules**
+**The open detection-rule standard for AI agent threats**
+
+> **STATUS: PROPOSED v1.0 — NOT YET RATIFIED**
+>
+> The specifications in this directory are **drafts for community comment**
+> in preparation for OASIS Open Project submission. They are NOT the current
+> operating contract of the ATR engine. The TypeScript production engine at
+> `npm:agent-threat-rules` continues to operate against the pre-spec-layer
+> behavior — these documents describe the target state, not the current state.
+>
+> **No integration interface has changed.** Existing ecosystem integrations
+> work unmodified. See `STANDARDIZATION-STATUS.md` at repo root for full
+> proposed-vs-ratified-vs-implemented status.
+
+**Status:** v1.0 — Draft for OASIS Open Project submission — NOT RATIFIED
+**License:** CC BY 4.0 (spec docs and schemas); CC0 (conformance corpus); MIT (reference implementations); CC BY 4.0 (rules)
+**Governance:** governance/CHARTER.md v2.0 (PROPOSED — TSC not yet formed)
+
+---
+
+## What ATR is, in one paragraph
+
+ATR is an open machine-readable detection-rule standard for AI agent
+threats. It is to AI agent security what Sigma is to SIEM detection,
+YARA is to malware signatures, and CVE/CWE is to software
+vulnerabilities. ATR rules are YAML files with declarative patterns
+that any conformant engine can load and evaluate. The standard is
+maintained by a 9-seat Technical Steering Committee (TSC) under
+fiscal sponsorship of Open Source Collective Inc. The corpus is
+licensed CC BY 4.0; reference implementations are MIT; conformance
+test artifacts are CC0.
+
+---
+
+## What this folder contains
+
+```
+spec/
+├── README.md                          ← you are here
+├── atr-schema.yaml                    ← (v0.1, existing) YAML rule schema
+├── compliance-metadata.md             ← (existing) rule compliance field reference
+├── stix-extension/                    ← (existing) STIX 2.1 extension bridge
+│
+├── ATR-SPEC-v1.md                     ← (existing, repo root) rule format spec
+├── atr-language-detection-v1.0.md     ← (new) deterministic language detection algorithm
+├── atr-event-v1.0.md                  ← (new) OTEL-compatible event format
+├── atr-profile-v1.0.md                ← (new) rule-set composition for tiered conformance
+├── atr-correlation-v1.0.md            ← (new) multi-event correlation rule format
+├── atr-method-v1.1.md                 ← (new) detection method extensions: signature/semantic/behavioral/trace
+├── mappings/                          ← (new 2026-05-28) ATR → external framework crosswalk documents
+│   ├── README.md                      ← mappings index
+│   └── atr-to-nist-csf-2.0.md         ← NIST CSF 2.0 (NIST IR 8596 Informative Reference draft)
+│
+├── category-registry/
+│   └── v1.0.yaml                      ← (new) versioned top-level category list
+│
+├── schema/                            ← (new) JSON Schemas
+│   ├── rule.schema.json               ← rule format JSON Schema
+│   ├── event.schema.json              ← event output JSON Schema
+│   ├── profile.schema.json            ← profile JSON Schema
+│   └── correlation.schema.json        ← correlation rule JSON Schema
+│
+└── conformance/                       ← (Phase 2) test corpus + expected-results.json
+```
+
+---
+
+## The four-layer standard
+
+ATR separates four concerns. This separation is the foundation of
+the standard's architecture per governance/CHARTER.md § Appendix A.
+
+| Layer | Lives in | Governance |
+|---|---|---|
+| **1. Specification** (the immutable contract — what conformant implementations must do) | `spec/` + repo-root `ATR-SPEC-v1.md` | TSC AEP process (Tier 3) |
+| **2. Reference implementation** (proves the spec is buildable) | `engines/typescript/` + `engines/python/` + `engines/go/` | Maintainer-led; tested against `spec/conformance/` |
+| **3. Production engines + integrations** (consumers of the spec) | `src/` (existing TypeScript engine), `integrations/{rampart,sigma,sentinel,splunk,opentelemetry}/` | Vendor-controlled; pass conformance to claim conformance |
+| **4. Conformance test corpus** (objective evidence anyone implements correctly) | `spec/conformance/` | TSC; signed with ed25519 key |
+
+---
+
+## How to read the spec
+
+If you are **implementing an ATR engine**, read in this order:
+
+1. `ATR-SPEC-v1.md` — rule format. Defines what a rule is and how
+   it evaluates.
+2. `spec/atr-schema.yaml` and `spec/schema/rule.schema.json` —
+   machine-readable rule schemas.
+3. `spec/atr-language-detection-v1.0.md` — the deterministic
+   algorithm your engine MUST implement for per-language conditions.
+4. `spec/atr-event-v1.0.md` and `spec/schema/event.schema.json` —
+   the event format your engine MUST emit when a rule fires.
+5. `spec/category-registry/v1.0.yaml` — categories your engine
+   recognises (and forward-compatibility for unknown categories).
+6. `spec/conformance/` (when published) — the test corpus your
+   engine MUST pass.
+7. `spec/atr-profile-v1.0.md` + `spec/atr-correlation-v1.0.md` —
+   RECOMMENDED for full conformance, optional for baseline.
+8. `spec/atr-method-v1.1.md` — OPTIONAL. Read only if your engine
+   implements detection methods beyond `pattern` (signature, semantic,
+   behavioral, or trace). v1.0 Pattern conformance does NOT require
+   this document.
+
+If you are **authoring rules**, read:
+
+1. `ATR-SPEC-v1.md` — rule fields and evaluation semantics
+2. `spec/atr-schema.yaml` — required and optional fields
+3. `spec/category-registry/v1.0.yaml` — pick a category
+4. `spec/atr-language-detection-v1.0.md` — only if writing
+   per-language conditions
+5. Existing rules in `rules/<category>/*.yaml` for patterns
+
+If you are **adopting ATR in your product**, read:
+
+1. `README.md` (repo root) — overview
+2. `governance/CHARTER.md` — governance model
+3. `spec/atr-profile-v1.0.md` — pick which profile your product
+   claims conformance to
+4. `spec/atr-event-v1.0.md` — your product's output integration
+5. `certification/program-guide.md` (when published) —
+   ATR-Certified™ program
+
+If you are **a regulator or standards-body reviewer**, read:
+
+1. `governance/CHARTER.md` — TSC structure, IPR, fiscal sponsorship
+2. `governance/STANDARD-THREAT-MODEL.md` — what attacks against
+   the standard itself we've designed for
+3. `spec/README.md` (this file) — index
+4. `ai-rmf-oscal-catalog` (separate repo) — NIST AI RMF mapping
+
+If you are **a sovereign authority** considering issuing rules in a
+sovereign sub-range:
+
+1. `governance/CHARTER.md` § 8 — sovereign sub-range governance
+2. `spec/atr-profile-v1.0.md` — sovereign profile examples
+3. `spec/schema/rule.schema.json` — `provenance.attestation_signature`
+   field
+
+---
+
+## Conformance levels
+
+A conformant ATR engine claim names what the engine can do. Three
+levels:
+
+**Level 1 — Baseline Conformance.** Engine implements:
+- Rule schema (`spec/schema/rule.schema.json`)
+- Event schema (`spec/schema/event.schema.json`)
+- Language detection (`spec/atr-language-detection-v1.0.md`)
+- Category registry forward-compat (`spec/category-registry/v1.0.yaml`)
+- Passes `spec/conformance/baseline/` corpus
+
+**Level 2 — Profile Conformance.** Adds:
+- Profile resolution (`spec/atr-profile-v1.0.md` and schema)
+- Multiple profile loading + isolated evaluation
+- Passes `spec/conformance/profiles/` corpus
+
+**Level 3 — Correlation Conformance.** Adds:
+- Correlation rule evaluation (`spec/atr-correlation-v1.0.md` and schema)
+- State management across events
+- Implements at least `temporal_sequence`, `count_threshold`, and
+  `chain_propagation` correlation types
+- Passes `spec/conformance/correlation/` corpus
+
+Engines may claim any subset of levels (e.g., L1+L3 without L2). The
+ATR-Certified™ program awards trust marks per level.
+
+---
+
+## Versioning policy
+
+The spec uses SemVer with the following rules:
+
+- **PATCH** (`1.0.x`): editorial changes, additional examples,
+  conformance corpus expansion. Engines MUST continue to pass.
+- **MINOR** (`1.x.0`): backward-compatible field additions (e.g.,
+  new optional rule field). Engines SHOULD adopt within 6 months.
+- **MAJOR** (`x.0.0`): breaking changes. Engines MUST adopt to
+  claim new-version conformance. Minimum 12-month deprecation
+  window for the prior major version.
+
+Each spec document declares its individual version (e.g.,
+`atr-event-v1.0.md`). The overall spec version is the lowest of
+all individual spec versions.
+
+Major-version bumps require ATR Enhancement Proposal (AEP) Tier 3
+vote per governance/CHARTER.md § 4.
+
+---
+
+## Status of each spec component (May 2026)
+
+| Component | Version | Status | Files |
+|---|---|---|---|
+| Rule format | v1.0 | existing-draft | `ATR-SPEC-v1.md`, `spec/atr-schema.yaml`, `spec/schema/rule.schema.json` |
+| Event format | v1.0 | draft (new May 2026) | `spec/atr-event-v1.0.md`, `spec/schema/event.schema.json` |
+| Profile format | v1.0 | draft (new May 2026) | `spec/atr-profile-v1.0.md`, `spec/schema/profile.schema.json` |
+| Correlation format | v1.0 | draft (new May 2026) | `spec/atr-correlation-v1.0.md`, `spec/schema/correlation.schema.json` |
+| Language detection algorithm | v1.0 | draft (new May 2026) | `spec/atr-language-detection-v1.0.md` |
+| Category registry | v1.0 | draft (new May 2026) | `spec/category-registry/v1.0.yaml` |
+| Conformance corpus | v1.0 | planned Phase 2 | `spec/conformance/` |
+
+---
+
+## How this spec evolves
+
+New spec components and changes to existing components go through
+the **ATR Enhancement Proposal (AEP)** process defined in
+governance/CHARTER.md § 5.
+
+AEP template at `rfc/TEMPLATE-AEP.md` (Phase 3 deliverable). Open
+AEPs are tracked in `rfc/`.
+
+Reported issues and bugs in the spec go through GitHub Issues with
+the `spec-bug` label, expedited as Tier 2 votes (simple majority of
+5 of 9 TSC).
+
+---
+
+## Cross-references to related specs
+
+- **Sigma** (SIEM detection rules): different domain (SIEM event
+  patterns vs AI-agent runtime patterns), but ATR's rule structure
+  draws explicitly on Sigma's design and the bidirectional Sigma ↔
+  ATR converter at `integrations/sigma/` (Phase 4 deliverable)
+  lets adopters cross-pollinate.
+- **STIX 2.1** (Structured Threat Information eXpression): ATR
+  publishes a STIX 2.1 extension at `spec/stix-extension/` so ATR
+  events flow into STIX-native CTI platforms.
+- **OSCAL** (NIST compliance): ATR events map to OSCAL `observation`
+  records per `spec/atr-event-v1.0.md` § OSCAL mapping. Companion
+  CC0 catalog at `Agent-Threat-Rule/ai-rmf-oscal-catalog`.
+- **MITRE ATLAS**: each ATR rule declares MITRE ATLAS technique
+  mappings in its `references.mitre_atlas` field. Current coverage
+  100 of 113 ATLAS techniques per `docs/MITRE-ATLAS-MAPPING.md`.
+- **OWASP Agentic Top 10**: each ATR rule declares OWASP Agentic
+  mappings in `references.owasp_agentic`. Full 10/10 category
+  coverage per `docs/OWASP-AGENTIC-MAPPING.md`.
+- **EU AI Act Article 50**: ATR events carry the evidence fields
+  required for Article 50 deployer obligations (signature, agent
+  identity, deployment-time provenance). See
+  `spec/atr-event-v1.0.md` § Required fields.
+- **C2PA** (Content Credentials): when a deepfake-related rule
+  fires on agent-generated media, the event includes a C2PA
+  manifest reference if available.
+
+---
+
+## Submission to standards bodies
+
+The spec is being prepared for:
+
+1. **OASIS Open Project (primary)** as adjacent to CoSAI. See
+   `panguard-outreach/2026-05-25-standardization-phase0/OASIS-APPROACH-MEMO.md`.
+   Target: Q3 2026 acceptance, Q1 2027 first Committee Specification.
+2. **NIST CAISI (citation target)**. See
+   `panguard-outreach/2026-05-25-standardization-phase0/NIST-CAISI-POSITION-PAPER.md`.
+   No formal submission window currently open; awaiting next RFI.
+3. **IETF (informational draft, transport / OTEL emission only)**
+   when reference implementations are stable.
+
+The spec is not yet submitted to any standards body; current state
+is "Draft v1.0, community-maintained at GitHub, transitioning to
+OASIS Open Project."
+
+---
+
+## Contact
+
+- Spec issues: GitHub Issues with label `spec-bug` or `spec-question`
+- Spec proposals: GitHub Pull Requests with AEP template
+- Maintainer: Adam Lin <adam@agentthreatrule.org>
+- Fiscal sponsor: Open Source Collective Inc. (501(c)(3),
+  EIN 81-1567737)
+- TSC (post-ratification): tsc@agentthreatrule.org (mailing list, public)

package/spec/atr-correlation-v1.0.md

@@ -0,0 +1,281 @@
+# ATR Correlation Rule Format v1.0
+
+> **STATUS: PROPOSED v1.0 — NOT YET RATIFIED.** This specification describes
+> a target correlation format for community comment. No correlation rules
+> have shipped to the canonical corpus yet. See `STANDARDIZATION-STATUS.md`
+> for full status.
+
+**Status:** Draft for AEP-004 ratification — NOT RATIFIED
+**Date:** 2026-05-25
+**License:** CC BY 4.0
+**Required by (on ratification):** Detection of multi-step agent attacks (A2A chains, memory-poisoning persistence, delegated authority abuse)
+
+---
+
+## Purpose
+
+A single agent action rarely constitutes an attack. The attack lives
+in the **chain**:
+
+- Agent A receives an indirect prompt injection from a retrieved
+  document (event 1).
+- Agent A calls tool X with the injected parameters (event 2).
+- Tool X delegates to Agent B via A2A (event 3).
+- Agent B writes a persistence payload to its memory store (event 4).
+- Three sessions later, Agent B exfiltrates the user's context to a
+  remote URL pulled from memory (event 5).
+
+A single-event rule fires on event 1 (prompt injection class), event
+2 (tool poisoning), event 4 (memory write), and event 5 (context
+exfiltration) **independently**, with no connection between them.
+The defender sees four unrelated alerts and may dismiss each as
+low-severity noise.
+
+A correlation rule joins these events into one detection. The output
+is a single, high-confidence event that names the attack chain and
+points to every constituent event.
+
+This spec defines the correlation rule format. It is modelled on
+Sigma's correlation rule specification but adds AI-agent-specific
+join keys (agent.id, session.id, agent.delegation_chain).
+
+---
+
+## Correlation JSON Schema reference
+
+Machine-readable schema: `spec/schema/correlation.schema.json`.
+
+This Markdown document is normative; JSON Schema must match.
+
+---
+
+## Required fields
+
+```yaml
+correlation:
+  schema_version: "1.0"
+  id: "ATR-COR-2026-00001"                    # correlation rule ID, separate range from atomic rules
+  title: "A2A delegated authority abuse chain"
+  description: >
+    Detects the multi-agent attack pattern: indirect prompt injection
+    upstream → delegated tool call → memory poisoning downstream →
+    exfiltration in subsequent session.
+  status: "draft"
+  severity: "critical"
+  author: "ATR Maintainer"
+  date: "2026-05-25"
+  license: "CC-BY-4.0"
+  references:
+    owasp_agentic: ["ASI03", "ASI04", "ASI09"]
+    mitre_atlas: ["AML.T0048", "AML.T0024"]
+
+source_rules:
+  - alias: "injection"
+    rule_id: "ATR-2026-00012"                 # indirect prompt injection
+  - alias: "tool_call"
+    rule_id_pattern: "ATR-2026-001*"          # tool-poisoning class
+  - alias: "memory_write"
+    rule_id_pattern: "ATR-2026-003*"          # memory write
+  - alias: "exfil"
+    rule_id_pattern: "ATR-2026-006*"          # context exfiltration
+
+correlation_logic:
+  type: "temporal_sequence"                   # see § Correlation types below
+  sequence:
+    - alias: "injection"
+    - alias: "tool_call"
+    - alias: "memory_write"
+    - alias: "exfil"
+  join_keys:
+    - "agent.id"                              # all events must share agent.id
+    - "session.id"                            # OR be linked across sessions via memory.store_id
+  window:
+    type: "session_chain"                     # see § Time windows below
+    max_session_count: 5                      # exfil may occur up to 5 sessions later
+    max_wall_time: "30d"                      # but no longer than 30 days
+
+response:
+  severity_uplift: "critical"                 # final correlation severity
+  actions: ["alert", "snapshot", "quarantine"]
+  message_template: >
+    [ATR-COR-2026-00001] Multi-agent attack chain detected. Indirect
+    injection at event {injection.event_id} → tool call at
+    {tool_call.event_id} → memory poisoning at
+    {memory_write.event_id} → exfiltration at {exfil.event_id}.
+    Recommend immediate session quarantine plus memory store audit.
+```
+
+---
+
+## Correlation types
+
+### `temporal_sequence`
+
+Events must occur in declared order on the timeline. Events between
+the named ones are allowed (and ignored). The match fires when the
+final event in the sequence is observed.
+
+### `temporal_unordered`
+
+All named events must occur within the window, but order is not
+constrained.
+
+### `count_threshold`
+
+A single source-rule fires N or more times within the window. Useful
+for brute-force / repeated-attempt detection ("agent attempted
+forbidden tool call ≥ 5 times in 1 hour").
+
+### `value_overlap`
+
+Two or more source rules fire AND share a common value in a named
+field (e.g., both fire on the same `agent.id` and the same
+`tool.target_jurisdiction`).
+
+### `chain_propagation`
+
+Events form a graph: event A produces upstream_chain reference
+pointing to event B. Useful for A2A delegated-authority chains where
+each link in the chain explicitly references the prior.
+
+Engines MUST implement at least `temporal_sequence`, `count_threshold`,
+and `chain_propagation` to claim correlation conformance. The other
+two are RECOMMENDED.
+
+---
+
+## Join keys
+
+Correlation requires join keys — fields whose equality across events
+ties them into one chain. Standard join keys:
+
+| Key | Source field | Use |
+|---|---|---|
+| `agent.id` | event.agent.id | Same agent across events |
+| `session.id` | event.session.id | Same session |
+| `agent.delegation_chain[*].agent_id` | A2A chain | Cross-agent |
+| `memory.store_id` | memory write events | Same memory store |
+| `tool.target_jurisdiction` | tool call events | Cross-event geographic correlation |
+| `evidence.upstream_chain[*]` | event chain | Explicit upstream linkage |
+
+Correlation rules MAY define custom join keys via XPath-like syntax
+into the event JSON. Engines MUST implement standard keys; custom
+keys are best-effort.
+
+---
+
+## Time windows
+
+| Window type | Description |
+|---|---|
+| `wall_time` | Events must occur within N seconds / minutes / hours. Format: `"5m"`, `"24h"`. |
+| `session_chain` | Events may span N consecutive sessions, with max wall time. |
+| `chain_depth` | Events linked via `evidence.upstream_chain` up to N hops. |
+| `unbounded` | No window (use sparingly; primarily for static-analysis chains where time is irrelevant). |
+
+---
+
+## False-positive considerations
+
+Correlation rules have a multiplicative FP risk: P(FP) = P(FP_r1) ×
+P(FP_r2) × ... × P(FP_rN), assuming independence. This makes
+correlation rules ROBUSTLY HIGH PRECISION when the constituent
+rules are individually high-precision.
+
+But correlation also has a multiplicative complexity: the engine
+maintains state across events, with bounded memory. Specification:
+
+- Engines MUST set a per-correlation-rule maximum state size. If
+  exceeded, oldest pending matches are evicted.
+- Engines MUST emit a `correlation_state_evicted` event when
+  eviction occurs (so audit chains know about lost detections).
+- Engines MAY share state across correlation rules (e.g., index of
+  events by `agent.id`) for efficiency.
+
+---
+
+## ID numbering
+
+Correlation rules use a distinct ID range:
+
+- Atomic rules: `ATR-YYYY-NNNNN`
+- Correlation rules: `ATR-COR-YYYY-NNNNN`
+
+This prevents ID collision and lets downstream consumers easily
+filter correlation events. The Numbering Authority issues both
+ranges; correlation rules pass the same TSC review process.
+
+---
+
+## Conformance gate
+
+A correlation rule's CI gate has an additional check beyond the
+atomic-rule gate:
+
+- Engine MUST be able to load the rule (parse + validate).
+- Engine MUST evaluate the correlation against a fixture event
+  stream included in the rule's `test_cases.true_positive_streams`.
+- Engine MUST NOT fire on `test_cases.true_negative_streams`.
+
+Fixture event streams are JSON Lines files in
+`tests/correlation-streams/<rule-id>/`.
+
+---
+
+## Example fixture stream (positive case for ATR-COR-2026-00001)
+
+```jsonl
+{"@timestamp":"2026-05-25T10:00:00Z","atr.event_id":"01927e2d-7b32-7c41-9e84-0001","atr.rule_id":"ATR-2026-00012","agent.id":"agt-abc","session.id":"sess-1","atr.matched_field":"agent_output","atr.category":"prompt-injection"}
+{"@timestamp":"2026-05-25T10:00:30Z","atr.event_id":"01927e2d-7b32-7c41-9e84-0002","atr.rule_id":"ATR-2026-00115","agent.id":"agt-abc","session.id":"sess-1","atr.matched_field":"tool_call","atr.category":"tool-poisoning"}
+{"@timestamp":"2026-05-25T10:01:00Z","atr.event_id":"01927e2d-7b32-7c41-9e84-0003","atr.rule_id":"ATR-2026-00345","agent.id":"agt-abc","session.id":"sess-1","atr.matched_field":"memory_write","atr.category":"context-exfiltration","memory.store_id":"mem-xyz"}
+{"@timestamp":"2026-05-27T14:32:00Z","atr.event_id":"01927e2d-7b32-7c41-9e84-0004","atr.rule_id":"ATR-2026-00610","agent.id":"agt-abc","session.id":"sess-22","atr.matched_field":"agent_output","atr.category":"context-exfiltration"}
+```
+
+Engine MUST emit one correlation event after consuming all four
+above, referencing all four event IDs in `evidence.upstream_chain`
+of the output event.
+
+---
+
+## Example fixture stream (negative case)
+
+Same as above but with different `agent.id` values across events.
+Engine MUST NOT correlate (join key mismatch).
+
+---
+
+## Performance bounds
+
+Correlation evaluation must remain bounded:
+
+- **Memory:** O(N events × M correlation rules × K state per rule).
+  Engines MUST evict oldest state when memory budget exceeded.
+- **CPU per event:** O(M correlation rules), with O(1) state update
+  per rule on average. Catastrophic-backtracking is forbidden in
+  correlation logic.
+- **Latency:** Correlation evaluation MUST NOT block atomic-rule
+  emission. Atomic events emit immediately; correlation events
+  emit on chain completion.
+
+These bounds are guidelines; specific deployment SLAs (e.g., <100ms
+p99 per event) belong to the engine's deployment specification, not
+the spec.
+
+---
+
+## Versioning
+
+Same versioning as atomic rules: SemVer with PATCH for backward-
+compatible additions, MINOR for spec-relevant changes, MAJOR for
+breaking changes. v1.0 is the initial release.
+
+---
+
+## References
+
+- Sigma Correlation Rules Specification: https://github.com/SigmaHQ/sigma-specification/blob/main/specification/sigma-correlation-rules-specification.md
+- Sigma rule design lessons: https://sigmahq.io/docs/guide/about.html
+- A2A delegation patterns: https://datatracker.ietf.org/doc/draft-ni-a2a-ai-agent-security-requirements/
+- SpAIware (memory-poisoning persistence): https://www.sciencedirect.com/science/article/abs/pii/S0167739X25002894
+- ATR Event Format Spec v1.0: spec/atr-event-v1.0.md
+- ATR Rule Format Spec v1.0: ATR-SPEC-v1.md