> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaegis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit trail

> Understand what the Aegis audit trail records, how to browse and filter events by date range, how to export records, and how long data is retained.

Every time your agent calls an MCP tool, Aegis writes an immutable record of that action to the audit trail. The record captures the tool called, the decision Aegis made, the outcome, how long the action took, and how severe the potential impact was. You cannot delete or modify these records, the audit trail is append-only by design.

## What the audit trail records

Each entry in the audit trail corresponds to one MCP tool call made during an agent session. The following fields are captured:

| Field            | Description                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| `agent_name`     | The name of the agent that initiated the action                                                  |
| `tool_name`      | The MCP tool that was called (e.g. `create_pull_request`, `push_files`)                          |
| `action_summary` | A plain-language description of what the agent attempted                                         |
| `decision`       | The policy outcome: `ALLOW`, `DENY`, `REWRITE`, or `REQUIRE_APPROVAL`                            |
| `target_repo`    | The GitHub repository the action targeted                                                        |
| `target_branch`  | The branch targeted, if applicable                                                               |
| `execution_time` | How long the action took to evaluate and execute, in milliseconds                                |
| `blast_radius`   | The assessed impact severity: **Low**, **Medium**, **High**, or **Critical**                     |
| `policy`         | The policy verdict, `pass` when all checks passed, or an enforced state when a policy intervened |
| `timestamp`      | When the action occurred                                                                         |
| `session_id`     | The session the action belonged to                                                               |

<Note>
  Audit records are immutable. Once written, they cannot be edited or deleted from the dashboard or via the API.
</Note>

## Browsing audit events

Open **Dashboard > Audit Trail** to view the full event log. Events are displayed in reverse chronological order, paginated at 50 records per page.

### Filtering by date range

Use the date range picker at the top of the page to narrow the log to a specific window. The picker defaults to the last 7 days. You can select any custom range.

### Expanding a row

Click any row in the table to expand it and view the full action summary and the raw tool arguments passed by the agent.

### Paginating through events

Use the **Prev** and **Next** buttons below the table to move between pages. Each page shows up to 50 events.

## Understanding blast radius

The `blast_radius` field gives you a quick signal of how impactful an action would have been if it had executed without any intervention:

<AccordionGroup>
  <Accordion title="Low">
    Read-only operations or small, scoped writes with minimal downstream effect.
  </Accordion>

  <Accordion title="Medium">
    Writes that affect a bounded set of files or resources in a non-critical path.
  </Accordion>

  <Accordion title="High">
    Writes that could affect production systems, shared infrastructure, or multiple repositories.
  </Accordion>

  <Accordion title="Critical">
    Actions with broad or irreversible impact, for example, force-pushing to a protected branch or modifying secrets.
  </Accordion>
</AccordionGroup>

## Exporting audit data

You can export the audit trail for a selected date range in two formats.

<Tabs>
  <Tab title="JSON export">
    Click **Export JSON** on the Audit Trail page to download all events within the current date range as a structured JSON file. The export includes metadata such as the export timestamp and total record count.

    The file is named `aegis-audit-YYYY-MM-DD.json` and contains the full event payload for each action.
  </Tab>

  <Tab title="PDF export">
    Aegis also supports exporting audit data as a PDF. The PDF contains the canonical JSON payload rendered in a fixed-width font, useful for sending to compliance teams or attaching to incident reports.
  </Tab>
</Tabs>

## Retention settings

You can configure how long audit records are kept in **Settings > Audit**. The available retention options are:

| Option      | Records kept for                                              |
| ----------- | ------------------------------------------------------------- |
| **90 days** | Rolling 90-day window; older records are purged automatically |
| **1 year**  | Rolling 12-month window                                       |
| **Forever** | Records are never automatically deleted                       |

<Warning>
  Switching from a longer retention period to a shorter one may result in older records being deleted. Review your retention setting before changing it.
</Warning>