Incidents

The Incidents screen lets you declare a security or safety incident, follow its timeline, change its status and its assignee, add notes, and run a response action (suspend an agent, disable a model or a provider, rotate a key) from the incident. Portal path: /security/incidents, menu Security and governance > Incidents. It is used by security officers and tenant administrators who lead the response, and by developers or agents who declare an incident.

What the screen shows

The screen (Incidents in portal/src/screens/security.tsx) shows one table, Incidents, read from GET /v1/incidents, newest first, 50 rows per request with a cursor.

Column	Content
Title	Title of the incident.
Severity	sev1 (highest) to sev4.
Status	open, investigating, contained, resolved, closed.
Category	Free category, other by default.
Assignee	Person in charge.
Created	Date of the declaration.

Filters above the table: Status and Severity (lists, all by default), then Filter. A click on a row opens a side panel loaded from GET /v1/incidents/{incident_id}: the timeline (creation, status and severity changes, notes, SIEM forwarding, actions) followed by the JSON of the incident with its actions. Empty table: "No incident", "Declare an incident to coordinate the response."

Actions

Button or action	What it does	API call	Roles
Declare incident (then Create)	Creates the incident with Title (3 to 300 characters), Severity (sev3 first in the list), Category, Resources, Assignee, Description; opens the timeline and forwards incident.created to the SIEM.	POST /v1/incidents	tenant_admin, security_officer, developer, agent
Filter	Applies the Status and Severity filters.	GET /v1/incidents (query status, severity)	Every user of the tenant
Row click or View details	Opens the timeline and the JSON of the incident.	GET /v1/incidents/{incident_id}	Every user of the tenant
Respond (row menu, then Respond)	Runs a response action: Action (suspend_agent, resume_agent, suspend_model, disable_provider, rotate_key), Target id, Reason. The result is shown in a side panel. An executed action moves an open or investigating incident to contained.	POST /v1/incidents/{incident_id}/actions	tenant_admin, security_officer
Change status (row menu, then Change status)	Changes Status, Assignee and adds a Note to the timeline; each change is forwarded to the SIEM as incident.updated.	PATCH /v1/incidents/{incident_id}	tenant_admin, security_officer
Refresh icon	Reads the list again.	GET /v1/incidents	Every user of the tenant

What each response action does on the server (execute_action in services/control-plane/src/eai/domains/incidents/__init__.py):

Action	Effect	Target id
suspend_agent, resume_agent	Kill switch of the agent registry.	Name or id of the agent.
suspend_model	Disables the model for the tenant.	Model id.
disable_provider	Disables the LLM provider.	Name or id of the provider.
rotate_key	Rotates an encryption key of the tenant (new version).	Name or id of the encryption key.

A model or a provider shared by the platform needs a platform administrator: without platform_admin, the action is recorded with the status pending and the reason requires_platform_admin.

Roles

The portal hides no button on this screen. The Control Plane checks the roles: declaring needs tenant_admin, security_officer, developer or agent; Respond and Change status need tenant_admin or security_officer (RESPONDERS); reading needs a tenant only. platform_admin passes every role check. Every write is audited (incident.create, incident.update, incident.action.<action>).

Typical tasks

Declare an incident and contain an agent

1. Declare it. A declared incident gives the response a timeline and an owner. Click Declare incident, fill Title, Severity (for example sev2), Assignee and Description, leave Resources empty, then Create. Expected result: the message Created and a new row with the status open. If it fails: validation_error (HTTP 422) on Resources (see Troubleshooting); forbidden means a missing role.
2. Suspend the agent. Suspension stops the agent without deleting it. Row menu > Respond, Action suspend_agent, Target id the name of the agent, Reason, then Respond. Expected result: a side panel with the action and the status executed. If it fails: unknown_action (HTTP 400) for an action outside the list; the status failed with an error code in the result means the agent was not found or refused the change.
3. Check the status and add a note. An executed action already moved the incident to contained; a note tells the other responders what was done. Row menu > Change status, keep Status contained, fill Note, then Change status. Expected result: the message Done, the status contained and the note in the timeline. If it fails: invalid_request (HTTP 400) for a status outside the five values.

Close an incident

1. Read the timeline. Every change and action is listed with its author. Click the row. Expected result: the timeline in the side panel. If it fails: not_found means the incident was removed or the identifier is wrong.
2. Resume what was suspended. A suspended agent stays suspended until resumed. Row menu > Respond, Action resume_agent. Expected result: the status executed in the result. If it fails: see the result panel for the error code.
3. Resolve, then close. Row menu > Change status, Status resolved (the resolution date is recorded), later closed. Expected result: the status of the row changes. If it fails: forbidden means your roles are neither tenant_admin nor security_officer.

Troubleshooting

Symptom	Cause	Fix
validation_error (HTTP 422) on Declare incident with resources	The form sends Resources as a list of texts; the API expects a list of objects.	Leave Resources empty, or declare the incident through the API with resource objects.
invalid_request (HTTP 400) with severity	A severity outside sev1 to sev4 (or critical, high, medium, low).	Choose a value from the list.
invalid_request with status and allowed	A status outside open, investigating, contained, resolved, closed.	Choose a value from the list.
unknown_action (HTTP 400)	The action is not one of the allowed actions.	Choose an action from the list.
invalid_request with target	Target id is empty.	Enter the name or the id of the target.
Result pending with requires_platform_admin	The model or provider belongs to the platform.	Ask a platform administrator to run the action.
forbidden (HTTP 403) with required_roles	Your roles do not allow this write.	Ask for one of the listed roles.
not_found with incident	Unknown incident identifier.	Refresh the table.

Related pages

• SOC and AI-SDR
• Kill Switch
• Encryption keys
• Agent registry
• Incident management brick
• Agent kill switch brick
• SOC runbook