Guide · Respond
How to investigate an AI agent incident
Agent incidents invert normal forensics. The action is usually well logged by the system that received it. What is missing is why the agent decided to do it — and that lives in artefacts and context nobody was recording.
before you start
- Whatever session, tool-call and artefact data you currently retain — find out now, not during an incident.
- The ability to freeze a machine's artefact state before anyone updates anything.
- A named owner for the AI surface in question.
Why the obvious approach does not work
In a conventional incident you know what code ran, because the code is versioned and deployed. With an agent, the behaviour is produced at runtime from a model, a context window and a set of artefacts — and only one of those three is typically under version control. So the question 'what was this agent operating under' has no default answer, which is why the first hour of an agent incident is so often spent discovering that the evidence does not exist.
There is a hard constraint to plan around: the model's reasoning is not recoverable. You cannot subpoena the decision. What you can reconstruct is the *inputs* — which artefacts were loaded, which tools were available, what content entered the context, what calls were made in what order. That reconstruction is usually enough to identify cause and, more importantly, scope. Chasing the reasoning is a dead end; chasing the inputs is tractable.
Scope is the real deliverable, and it is where these incidents differ most from ordinary ones. If the cause was a poisoned artefact, the blast radius is not one session — it is every session on every machine that loaded that artefact for as long as it was present. That is a very different containment problem from a single compromised host, and answering it requires placement data most organisations do not have.
The most common outcome of a first AI incident investigation is an honest 'we cannot determine this', and the most valuable output is the instrumentation list that comes out of it. Write down what you could not answer and why. That list is worth more than a speculative root cause, and it converts one bad week into the thing that makes the next investigation possible.
The procedure
Freeze artefact state before anyone touches it
Before remediation, before an update, before the developer 'just reinstalls it': snapshot the machine's artefact state — skills, rules files, hooks, MCP configuration, extension list — with hashes and timestamps. These files have no version history and no diff on update, so an update destroys your only copy of the evidence. This step is time-critical in a way the rest are not.
you now haveA hashed, timestamped snapshot of every artefact on the affected machine.
Establish what the agent actually did
Work from the receiving systems rather than the agent: repository history, cloud audit logs, database logs, API access logs, outbound network records. These are properly logged and are your reliable spine. Build a timestamped action sequence and note which actions were reversible and which were not. Resist theorising about cause until this timeline is complete.
you now haveA timestamped action timeline with an irreversibility flag on each entry.
Reconstruct what was in the context
Identify what the agent could have read before it acted: fetched URLs, files opened, tool results returned, retrieved documents, comments in the repository or ticket. You are looking for the injected instruction, and it is frequently in something innocuous — a code comment, an issue body, a page the agent fetched, a tool description. Note explicitly what you cannot recover, because those gaps are your instrumentation findings.
you now haveA candidate list of untrusted content that entered context, and a list of what is unrecoverable.
Identify every artefact that was loaded, with versions
From the snapshot, list the artefacts in play and try to establish what each contained *at the time*, not now. Read the instruction text looking for anything that would produce the observed behaviour. Because artefacts are unversioned by default this is often the hardest step, and where a registry with pinned versions turns days of archaeology into a lookup.
you now haveThe loaded artefact set with best-available version or content evidence.
Determine fleet scope, not session scope
If an artefact is implicated, ask immediately which other machines have it and since when. One session is the floor of the blast radius, not the ceiling. Without placement data you will be reduced to asking people, and you should record that as the finding it is — inability to scope is itself the most serious result an investigation can return.
you now haveA list of affected machines and a date range, or an explicit statement that scope is undeterminable.
Write the instrumentation gap list
Close by listing every question you could not answer and the data that would have answered it. Rank by how much each would have shortened this investigation. This is the output that changes anything: it turns an incident into a funded instrumentation plan, and it is far more defensible than a root cause you inferred.
you now haveA ranked instrumentation gap list, owned and dated, with the cost of each gap in this incident.
AI incident evidence checklist
Step 1 is time-critical — snapshot artefacts before remediation, because an update overwrites the only copy.
AI incident evidence checklist
INCIDENT: ____________ DETECTED: ____________ SURFACE: ____________
MACHINE(S): ____________ AGENT IDENTITY USED: ____________
*** COLLECT FIRST — DESTROYED BY REMEDIATION ***
[ ] Skills / rules / commands folder, hashed and timestamped
[ ] Hook definitions and lifecycle scripts
[ ] MCP server configuration, with version pins as installed
[ ] IDE / browser extension list with versions
[ ] Local agent settings and permission configuration
[ ] Shell history and agent session transcripts, if retained
ACTIONS TAKEN (from receiving systems — the reliable spine)
[ ] Repository history: commits, pushes, PRs, force-pushes
[ ] Cloud audit log for the agent identity
[ ] Database / application logs
[ ] Outbound network records for the window
[ ] Any customer-visible action (mail, tickets, payments)
[ ] Reversibility marked per action
CONTEXT INPUTS (the injection hunt)
[ ] URLs fetched during the session
[ ] Files read
[ ] Tool calls with arguments and returned content
[ ] Issue / PR / ticket comments in scope
[ ] Retrieved documents
[ ] MCP tool descriptions as they were at the time
[ ] UNRECOVERABLE — list explicitly: ______________________
CREDENTIALS
[ ] Identity the agent ran as, and its scopes at the time
[ ] Whether scopes exceeded task need
[ ] Rotation completed
FLEET SCOPE
[ ] Other machines holding the implicated artefact
[ ] Date range of presence
[ ] Sessions in that range
[ ] Or: SCOPE UNDETERMINABLE — record as a finding
OUTPUT
[ ] Action timeline
[ ] Probable cause, with confidence stated
[ ] Blast radius, or an honest statement that it is unknown
[ ] Ranked instrumentation gap listWhere this goes wrong
- Remediating before snapshotting
The instinct is to fix the machine. Artefacts have no version history, so reinstalling or updating destroys the only record of what was actually loaded. Snapshot first, always.
- Hunting for the model's reasoning
It is not recoverable and pursuing it burns the investigation. Reconstruct inputs — artefacts, context, tool calls — which is both tractable and sufficient for cause and scope.
- Scoping to the session
If an artefact was the cause, every machine that loaded it is in scope for as long as it was present. Session-scoped containment on an artefact-caused incident leaves the cause in place.
- Inventing a root cause to close the ticket
A speculative cause with no evidence is worse than 'undetermined, here is what we could not see'. The gap list is what gets instrumentation funded; a tidy fiction ends the conversation.
Doing this without us
The action timeline is fully achievable today — receiving systems log properly and that is your spine. The two questions that reliably go unanswered are which artefact versions were loaded in the session, and which other machines held them. Both require continuous recording that has to be in place before the incident, which is a deliberate reason to instrument now rather than after. Vincosha Ledger records artefact versions per session; Registry provides the placement data that turns session scope into fleet scope.
Frequently asked
- Can we recover what the model was thinking?
- No, and designing your process around that limit saves real time. You can reconstruct the inputs — artefacts, retrieved content, tool calls and their order — which is enough to establish probable cause and, critically, scope. The reasoning itself is not an available artefact.
- What is the single most valuable thing to instrument first?
- Tool calls with their arguments, tied to a session identifier. It gives you the agent's action sequence from the agent's side rather than piecing it together from every receiving system, and it is usually the cheapest of the gaps to close.
- How long should we retain agent session data?
- Long enough to cover your realistic detection lag, which for artefact-caused problems is months rather than days — a subtly weakened check does not announce itself. Balance against the fact that this data contains whatever the agent read, so it inherits the sensitivity of your most sensitive context.
- Is a poisoned artefact really more serious than a compromised machine?
- Usually, yes, because it is not host-scoped. One compromised machine is one blast radius; one poisoned artefact affects every machine that loaded it for as long as it was present, and it re-arrives through the same channel after you clean the host.
Sources
Checked on 2026-07-25. Where a vendor control is changing quickly this guide describes the mechanism rather than asserting a current state — verify against the vendor's own documentation, and tell us if we have drifted.