Respond to an Agent Incident
Who this is for: the Security analyst who handles an agent incident, working with an Admin for the steps that change configuration.
Purpose
This playbook takes an incident from the first alert to the evidence package. When you finish:
- The agent behind the alert is stopped, or released once you are satisfied it is safe.
- You know what the agent did, which policies and guardrails acted, and who was behind it.
- The alert is closed with a note, and the evidence is exported for review.
Guardrails, including alerts, posture and the Session investigator, carry a Preview tag in the console.
Architecture
Every agent request passes through the gateway, which records it, applies your policies and guardrails, and raises an alert when a guardrail acts. Turning an agent off takes effect at the gateway, on the agent's next request. For the request path, see Architecture: The Request Path.
Prerequisites
- Role: Security analyst, or a role with Guardrails: Manage and Agents: Toggle at All scope. For a summary of the role, see Get Started as a Security Analyst.
- An Admin you can reach, for the steps the Security analyst role doesn't include
- Guardrails turned on for your organization. See Turning Guardrails On.
The following table shows what each side does in an incident.
| Task | Security analyst | Admin |
|---|---|---|
| Triage, acknowledge and close alerts | Yes | Yes |
| Contain an agent, and turn any agent off and on | Yes | Yes |
| Read the Request Log, sessions, Session Watch findings, policy decisions and Session investigator decisions | Yes | Yes |
| Mark a paused session a false positive | Yes | Yes |
| Export guardrail evidence | Yes | Yes |
| Release a paused session before its time limit | No | Only as the agent's assigned supervisor, when pauses escalate to supervisors |
| Attach a Session Watch evaluator to a session | No | Yes |
| Change policies, guardrail settings, connectors or other settings | No | Yes |
Procedure
Complete these tasks in order. Each one is a summary, and links to the page with the detail.
Triage the Alert
Open Guardrails → Alerts. The page opens on Open alerts, with each alert's severity, status, summary, agent and session. Narrow the list with the Status and Severity filters.
- On the alert, click Ack, so others can see someone is on it.
- Note the agent and the session the alert names. The rest of this playbook starts from them.
See The Triage Queue.
Contain the Agent
If the agent may still be doing harm, stop it before you investigate. Containing is reversible.
- From the alert. Click Contain, and confirm Disable this agent and revoke its sessions?. The agent is turned off, and its live sessions are revoked.
- From the Agents page. Open Agents, find the agent, open its actions menu (⋮), and choose Turn off. Enter a Reason, which AgentPass records with your name, and click Turn off.
The gateway refuses the agent's next request. A request already in progress finishes. An agent you turn off stays off until a role that reaches all agents, such as Security analyst, Operator or Admin, turns it back on. The agent's supervisor can't turn it back on.
See Containing an Agent.
Investigate What Happened
Work outward from the alert. Each of these views is read-only for the Security analyst role.
| Question | Where to look |
|---|---|
| What did the agent send, and what came back? | Activity → Request log. Filter by supervisor, or search by session ID or source IP, and open a request to read its detail |
| What else did that session do? | In a request's detail, under Coding session, click See everything this session did. The session page shows every request and tool call in the session |
| Did an evaluator flag the session? | Activity → Session watch. Read the findings for the session, and what they touched |
| Which policies matched, and what did they decide? | Activity → Policy decisions. Open a decision to see who, what, why it matched and everything the request caused |
| Did the Session investigator pause, or would it have paused, the session? | Guardrails → Session investigator. Each decision shows the risk, severity, decision and confidence |
To attach an evaluator to a session that has none, ask an Admin. See Attaching an Evaluator to a Session.
See Request Log, Agent Session Forensics: Overview, Session Watch, Investigating a Policy Decision and The Session Investigator.
Resolve or Release
Decide what happens to the agent, the session and the alert.
- Release the agent. When you are satisfied it is safe, open its actions menu (⋮) on Agents, and choose Turn on.
- Keep it stopped. Leave it off, and tell its supervisor why. To take it out of use for good, ask an Admin or Operator to move it to the Retired stage.
- Close the alert. On Guardrails → Alerts, enter a Resolution note, and click Resolve, or False positive if the guardrail was wrong. The note is recorded with your decision.
When the Session investigator paused a session, a session-resume request waits on Approvals. If your address is on the SOC distribution list under Guardrails → Settings, the escalation reaches you by email too.
- The pause runs its time limit, 15 minutes by default. When it passes, your guardrail settings decide whether the session resumes or ends. Set the limit to fit how fast your team reviews.
- If the pause was a false positive, open the request, and click Mark false positive. The same signal on the same agent then doesn't pause a session again for seven days. The session itself still waits for its time limit.
- If the agent should stop, contain it or turn it off. The pause then no longer matters.
- When pauses escalate to supervisors instead of the SOC list, the agent's assigned supervisor can release the session early, signing with their passkey. The agent running the session can never release its own pause.
See Escalation and Signed Resume and Approvals in the Console.
Export the Evidence
- Open Guardrails → Posture, and click Export evidence.
- Choose the period that covers the incident. It defaults to the last 30 days.
- Click Export ⤓.
The download is a zip of guardrail decisions, alerts and Proving Ground runs over the period. Every export is audited. See Evidence Export.
Validate
Check the following:
- On Agents, the agent shows the status you decided on, Off or Active. An agent that is off shows who turned it off and when.
- On Guardrails → Alerts, the alert shows Resolved or False positive, with your name and note.
- On Approvals, no session-resume request for the session is still pending.
Logs and Audit Trail
AgentPass records each step of the incident: the alert and who closed it, the agent being turned off and on with the reason, each resume decision with the person who signed it, and each evidence export. Requests and policy decisions stay in the Request Log and on Activity → Policy decisions.
For long-term records, an Admin sends these events to your SIEM or to export files under Settings → Data management. See Data Management.
Related
- Alerts and Containment — alerts, containment and guardrail settings
- Pausing and Stopping a Session — what a pause does, and what the person running the agent sees
- Quick Start: Administering HYPR AgentPass — the Admin's side, including offboarding a person
- Permissions by Role — every permission each role holds