> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Audit trail
> Immutable logging of every authorization decision, with filtering, export, and compliance references.
## How audit logging works
Every call to `kavach.authorize()` or `kavach.authorizeByToken()` writes an entry to the audit log, regardless of outcome. Allowed, denied, and rate-limited calls are all recorded. The log is append-only: entries are never updated or deleted.
`authorize()` returns an `auditId` linking the decision to its log entry:
```typescript theme={"system"}
const result = await kavach.authorize(agent.id, {
action: 'read',
resource: 'mcp:github:repos',
});
console.log(result.auditId); // "aud_3f8a..."
```
## Querying logs
### AuditEntry type
Unique entry identifier, prefixed aud\_.
The agent that triggered the authorization check.
The user who owns the agent.
The action the agent attempted (e.g. read, write, delete).
The resource the action was attempted on.
`}>Arguments passed to the tool at the time of the call.
The outcome of the authorization check.
Time taken to evaluate the decision, in milliseconds.
Optional token usage from the agent's LLM call, if provided.
When the authorization check occurred.
### Filtering
All filter fields are optional and combinable. Without filters, the query returns all entries up to the `limit`.
```typescript theme={"system"}
const logs = await kavach.audit.query({
agentId: 'agt_...',
userId: 'user-123',
result: 'denied',
since: new Date('2025-01-01'),
until: new Date('2025-02-01'),
actions: ['write', 'delete'],
limit: 100,
offset: 0,
});
```
Filter to a specific agent.
Filter to all agents owned by a user.
Include entries on or after this timestamp.
Include entries before this timestamp.
Filter to specific action names.
Filter by outcome.
Maximum entries to return. Default is 1000.
Pagination offset.
### Exporting logs
```typescript theme={"system"}
// JSON export
const json = await kavach.audit.export({ format: 'json' });
// CSV export, suitable for spreadsheets and compliance tools
const csv = await kavach.audit.export({ format: 'csv' });
// Export a specific time range
const q4 = await kavach.audit.export({
format: 'csv',
since: new Date('2024-10-01'),
until: new Date('2025-01-01'),
});
```
The CSV export includes a header row with field names matching the `AuditEntry` interface. Each row is one authorization decision.
Both `since` and `until` are optional on exports. Omitting both exports the entire log.
## Compliance references
Article 12 requires high-risk AI systems to log events automatically throughout the system lifecycle, including the period of activity and data used. KavachOS records every authorization decision with agent identity, resource, action, parameters, outcome, and timestamp.
The NIST AI Risk Management Framework calls for documented accountability mechanisms and the ability to trace AI actions to specific identities. The append-only audit trail links every decision to a named agent and user.
SOC 2 trust services criteria for logical access controls and system monitoring require evidence that access is granted only to authorized identities and that access events are logged. The `allowed`/`denied`/`rate_limited` result field satisfies CC6.1–CC6.3. The tamper-evident, append-only structure satisfies CC7.2.
ISO 42001 recommends documenting the behavior of AI systems in production. Exporting the audit log as JSON or CSV gives auditors a machine-readable record of every decision the system made.
## Usage patterns
**Monthly access report for a user**
```typescript theme={"system"}
const entries = await kavach.audit.query({
userId: 'user-123',
since: new Date('2025-03-01'),
until: new Date('2025-04-01'),
});
```
**Agents with repeated denials today**
```typescript theme={"system"}
const denied = await kavach.audit.query({
result: 'denied',
since: new Date(new Date().setHours(0, 0, 0, 0)),
});
const countsByAgent = denied.reduce>((acc, entry) => {
acc[entry.agentId] = (acc[entry.agentId] ?? 0) + 1;
return acc;
}, {});
```
**High-frequency agent detection**
```typescript theme={"system"}
const highActivity = await kavach.audit.query({
agentId: 'agt_...',
since: new Date(Date.now() - 3_600_000), // last hour
});
console.log(`${highActivity.length} calls in the last hour`);
```
A sudden spike in call volume from a single agent often indicates a runaway loop. Use `kavach.agent.revoke()` to suspend the agent while you investigate.
## Next steps
Map audit data to EU AI Act, NIST, SOC 2, and ISO 42001.
Query audit logs via HTTP endpoints.
Visual audit log viewer with filters and export.