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

# Security Events

> Security-relevant events recorded in the audit database

## Overview

The governance server records security events in `audit_security_events`. Security events are anomalies that warrant investigation — they do not necessarily indicate a breach, but they indicate unexpected behavior that should be reviewed.

***

## Security event types

| Event type            | Severity | Description                                                             |
| --------------------- | -------- | ----------------------------------------------------------------------- |
| `replay_attempt`      | High     | A request was made with an `executionId` that was already consumed      |
| `signature_failure`   | Critical | An attestation signature failed verification                            |
| `invalid_policy`      | High     | A request referenced a policy bundle that failed signature verification |
| `rate_limit_exceeded` | Medium   | A client exceeded the rate limit on `/execute`                          |
| `unauthorized_access` | High     | A request was made with an invalid or missing API key                   |

***

## Querying security events

```typescript theme={null}
// All security events
const events = await client.audit.security({ limit: 100 });

// Events in a date range
const recentEvents = await client.audit.security({
  from: "2024-01-01T00:00:00Z",
  to:   "2024-01-31T23:59:59Z",
  limit: 500,
});

for (const event of events) {
  console.log(event.event_type);       // "replay_attempt"
  console.log(event.severity);         // "high"
  console.log(event.event_count);      // "3" (number of occurrences)
  console.log(event.last_occurrence);  // ISO timestamp
  console.log(event.first_occurrence); // ISO timestamp
}
```

***

## curl example

```bash theme={null}
curl "http://localhost:3000/audit/security?limit=50" \
  -H "Authorization: Bearer $PARMANA_API_KEY" | jq .
```

***

## Dashboard

The Security tab in the audit dashboard ([http://localhost:8081](http://localhost:8081)) shows security events grouped by type, with occurrence counts and timestamps.

***

## Responding to security events

**`replay_attempt`** — A client is submitting the same `executionId` more than once. Check whether this is a legitimate application retry (the application should use a new `executionId` on retry) or an attempted replay attack. Identify the source of the duplicate `executionId`.

**`signature_failure`** — An attestation failed verification. This is the most serious event. Immediately:

1. Identify which `executionId` and `execution_fingerprint` failed
2. Retrieve the full attestation and re-run verification independently
3. Determine whether the attestation was modified in transit or in storage
4. Do not authorize any business action that depends on this attestation

**`invalid_policy`** — A policy bundle failed signature verification. The bundle may have been modified after signing. Do not execute decisions against this bundle until it is recompiled and re-signed.

***

## Troubleshooting

**No security events appear despite expected replay attempts** — Verify `audit_db: true` in `/health`. Security events are only recorded when Postgres is connected. If Postgres is not connected, replay blocks still occur (Redis enforces them) but the events are not recorded.

**`event_count` is higher than expected** — The dashboard aggregates events by type. A count of 100 `replay_attempt` events may be a single client retrying 100 times. Investigate the `first_occurrence` and `last_occurrence` timestamps to determine the time range and frequency.