# 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:

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

Or set to `stdout` for local debugging:

```bash
export KV_INCIDENT_ENDPOINT=stdout
```

***

## Next steps

* [Dashboard Guide](/platform/dashboard.md) — navigate the dashboard
* [Reports](/platform/reports.md) — generate audit reports from incident data
* [Policies and Rules](/core-concepts/policies.md) — understand how violations are determined


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyvvu.com/platform/incidents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.