Why an overlay, not a replacement. The thesis.

Part of the AI IR Overlay™ framework. See CONTENT_MAP.md for the full repository map.

The AI IR Overlay: Framework Overview

License: Apache 2.0 Latest release References: NIST · OWASP

Current release: v0.35.0 · 2026-07-09 · CHANGELOG

A practical incident-response baseline for AI agents in production. Adapt and critique freely.

Why an overlay, not a replacement

Traditional incident response (codified in NIST SP 800-61 r3, which superseded r2 in April 2025) was built around unauthorized access vectors: malware, exploits, credential theft, lateral movement. AI agents change the failure mode.

AI incidents often manifest through authorized channels:

When the actor is authorized, the question shifts from “who got in?” to “what could it touch, and what did it do?” Crucial evidence now lives in prompts, tool calls, retrieval traces, and configuration state. Not on endpoints.

What stays the same

The core mechanics of effective incident response remain unchanged:

AI doesn’t rewrite the rules of effective IR. It changes the map.

Scope

The AI IR Overlay operationalizes deployer obligations for AI systems in production. A deployer is the organization that uses an AI system in its own operations, under its own oversight (per EU AI Act Article 3). This framework is for the security team responding to incidents in agents the deployer’s organization runs.

Out of scope:

Vendor copilots that an organization deploys are in scope for the deployer (the customer side). The vendor’s provider obligations are not addressed here.

The Overlay model

The AI IR Overlay adds four agent-aware controls (the Minimum Viable Overlay, or MVO) on top of your existing IR program.

Note: The phases shown below align with NIST SP 800-61 r3 (April 2025), unpacked into seven operationally-distinct columns per MATRIX.md Section 1. NIST SP 800-61 r3 restructures incident response around NIST CSF 2.0 functions (Govern, Identify, Protect, Detect, Respond, Recover); see the AI IR Overlay to CSF 2.0 crosswalk at crosswalks/nist-csf-2.md for the function-level mapping.

┌───────────────────────────────────────────────────────────────────────┐
│        AI IR Overlay Response Flow (NIST SP 800-61 r3, unpacked)       │
│                                                                       │
│  Preparation → Detection → Triage → Containment → Evidence →           │
│                                       Recovery → Closure              │
└───────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────────┐
│              AI IR Overlay · MVO Controls (4)                          │
│                                                                       │
│  1. INVENTORY     · Agents · Identities · Tools · Write Targets        │
│  2. SAFE MODES    · Kill-Switch Ladder (M0–M5; 6 M3 + 2 M4 variants)   │
│  3. EVIDENCE      · Minimum AI Evidence Set (Types A–F)                │
│  4. CONTROLLED    · Staged, validated re-enablement                    │
│     RE-ENABLE                                                          │
└───────────────────────────────────────────────────────────────────────┘

For the full phase-by-control matrix view, see MATRIX.md Section 1.

Reading order

If you are responding to an AI agent incident right now, start with RESPONSE-START.md for the four-file navigation path that takes you from 3am page to a defensible 60-minute checkpoint.

New here? Start with QUICKSTART.md for the standard 30-day adoption path. For startups and small security teams (5 or fewer people, limited platform control), QUICKSTART-startup.md is the 4-week minimum-viable path targeting Maturity Level 2. For a worked end-to-end example, see examples/incident-walkthrough.md. For working code examples of the framework’s API contracts, see reference-impls/.

For the full conceptual reading order, items 1 through 8 are the core, items 9 through 15 are the working artifacts.

For a self-contained tabular reference (matrix view of the framework: phases, kill-switch ladder, evidence types, metrics, MVO controls, maturity levels, playbook index, standards crosswalk), see MATRIX.md.

  1. The Minimum Viable Overlay. The four controls in detail: framework/01-minimum-viable-overlay.md
  2. The Mental Model. Four sentences that govern every decision: framework/02-mental-model.md
  3. The Maturity Roadmap. Where your program is, and how to advance it: framework/03-maturity-roadmap.md
  4. Materiality and Disclosure. The convening protocol that decides which regulatory clock applies and when it starts: framework/04-materiality-and-disclosure.md. The canonical convening trigger (mode-based: M3+; condition-based: customer data, external recipients, financial actions, regulated data, customer-facing trust impact, public attention) referenced by every playbook that may convene the call.
  5. The Six Triage Questions. First-hour discipline: triage/six-questions.md. Printable card: triage/six-questions-card.md.
  6. Kill-Switch Modes. Containment ladder: kill-switches/overview.md
  7. Minimum Evidence Set. What to preserve, and in what order: evidence/minimum-evidence-set.md
  8. End-to-end worked example. A synthetic but specific incident response showing the framework operating as a coherent system (inventory → safe modes → evidence → materiality call → controlled re-enable → post-incident hardening): examples/incident-walkthrough.md. Read this after items 1-7 to see how the controls hand off to each other under operational pressure.
  9. Templates. templates/ai-bom.yaml (AI Bill of Materials for MVO-1 Inventory) · templates/agent-privilege-matrix.csv (tool-tier matrix for MVO-2 Mode M3)
  10. Crosswalks. crosswalks/nist-ai-rmf.md (NIST AI RMF 1.0) · crosswalks/nist-csf-2.md (NIST CSF 2.0 and SP 800-61 r3) · crosswalks/owasp-agentic-top-10.md (OWASP Agentic Top 10 2026)
  11. Playbooks. All twenty-four playbooks shipped (content gate complete), organized by the arc described in CONTENT_MAP.md:

More playbooks ship as MINOR releases. See CHANGELOG.md for the full release schedule.

  1. Schemas. Machine-readable contracts for CI validation: schemas/ai-bom.schema.json (AI-BOM validator) · schemas/privilege-matrix.schema.json (Privilege Matrix row validator) · schemas/credential-event.schema.json (PB07 credential-event log validator) · schemas/kill-switch-api.md (Mode M0 through M5 activation API contract) · schemas/evidence-export.spec.md (Type A through F evidence export script contract).

  2. Reference validator. scripts/validate.py (Python 3.10+, jsonschema, pyyaml). Validates AI-BOM YAML and Privilege Matrix CSV against the JSON Schemas; v0.26.0 adds maturity-target-conditional kill-switch validation plus operational-currency staleness checks for last_reviewed (7-day window) and kill_switches.mX.tested_at (90-day window). Run with --strict to escalate staleness to CI errors. A GitHub Action at .github/workflows/validate-templates.yml runs the validator on every pull request touching templates/, schemas/, or the script itself.

  3. Reference implementations. reference-impls/evidence_exporter/ is a Python CLI implementing the Evidence Export Script Contract for Types A through F with manifest discipline, integrity hashes, parallel-export, and telemetry events. reference-impls/kill_switch_demo/ demonstrates the Kill-Switch API contract with M0/M1/M2/M3/M4 against a synthetic agent tool registry, including separation-of-duties enforcement and the M3 scope parameter. Both are Python 3.10+ standard library only; both run end-to-end with no vendor accounts required.

  4. Framework Matrix. MATRIX.md: self-contained tabular reference for the framework at v0.33.0. Nine sections covering the response-phase matrix (Preparation through Closure), the kill-switch ladder with all six M3 variants, the Minimum Evidence Set with deep-dive pointers, the Six Metrics, the four MVO controls, the four maturity levels, the 24-playbook quick reference, the standards crosswalk summary, and a quick-read legend. Calibrated for board briefings, onboarding, auditor walkthroughs, and one-page references. Every cell traces to a specific file in the repo.

Provenance

The AI IR Overlay was developed through the AI IR Overlay LinkedIn newsletter series (Issues 1 through 24, 2025 to 2026), authored by Jacob Ideji, as a synthesis of NIST AI RMF 1.0, NIST CSF 2.0, NIST SP 800-61 r3, OWASP Top 10 for Agentic Applications 2026, EU AI Act deployer obligations, and the maintainer’s incident response and AI security experience. The framework has not yet been deployed in a documented production AI incident; adopters who use it in a real incident are encouraged to submit anonymized case studies via Discussions. Each newsletter issue maps to one playbook in the full framework. See CONTENT_MAP.md for the issue-to-file index.

Acronyms