Incident Management

What you'll learn: How incidents are created, the incident lifecycle, and how to triage and resolve them.

---

What is an incident?

An incident is a policy violation record. When the engine evaluates a step and a policy returns warn or block, an incident is created and sent to the platform (if the incident webhook is configured).

Incidents provide the compliance audit trail — they record what was violated, when, by which agent, and in which task.

Incident lifecycle

open  →  active  →  resolved
                 →  ignored

Status	Meaning
open	Newly created. No human has reviewed it.
active	Acknowledged by a team member. Under investigation or remediation.
resolved	The violation has been addressed — code fixed, policy adjusted, or root cause mitigated.
ignored	Reviewed and determined to be a false positive or acceptable risk.

Incident data

Each incident includes:

Field	Description
agent_id	The agent that triggered the violation.
scope	step_execution or agent_registration.
task_id	The task in which the violation occurred (for step violations).
step_name	The step that was evaluated.
step_type	The behaviour type.
action	warn or block.
risk_score	The aggregate risk score (0.0 to 1.0).
violations	List of violated policies with name, severity, and details.
timestamp	When the violation occurred.

Dashboard workflow

1. Navigate to Incidents in the sidebar.

2. Filter by status, agent, severity, or time range.

3. Click an incident to see full details.

4. Use the action buttons:

   • Resolve — mark as addressed.

   • Ignore — mark as false positive.

   • Reactivate — reopen a resolved or ignored incident.

API endpoints

Method	Path	Description
GET	/api/v1/incidents	List incidents (filterable).
GET	/api/v1/incidents/{id}	Get incident details.
PUT	/api/v1/incidents/{id}/resolve	Resolve incident.
PUT	/api/v1/incidents/{id}/ignore	Ignore incident.
PUT	/api/v1/incidents/{id}/reactivate	Reactivate incident.

Incidents are never deleted — they form part of the immutable audit trail.

Configuring the incident webhook

By default, the engine does not send incidents to the platform. To enable:

export KV_INCIDENT_ENDPOINT=https://platform.kyvvu.com/api/v1/incidents

Or set to stdout for local debugging:

export KV_INCIDENT_ENDPOINT=stdout

---

Next steps

• Dashboard Guide — navigate the dashboard

• Reports — generate audit reports from incident data

• Policies and Rules — understand how violations are determined