Audit trail

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:

const result = await kavach.authorize(agent.id, {
  action: 'read',
  resource: 'mcp:github:repos',
});

console.log(result.auditId); // "aud_3f8a..."

Querying logs

AuditEntry type

string

Unique entry identifier, prefixed aud_.

string

The agent that triggered the authorization check.

string

The user who owns the agent.

string

The action the agent attempted (e.g. read, write, delete).

string

The resource the action was attempted on.

Arguments passed to the tool at the time of the call.

'allowed' | 'denied' | 'rate_limited'

The outcome of the authorization check.

number

Time taken to evaluate the decision, in milliseconds.

number

Optional token usage from the agent’s LLM call, if provided.

Date

When the authorization check occurred.

Filtering

All filter fields are optional and combinable. Without filters, the query returns all entries up to the limit.

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,
});

string

Filter to a specific agent.

string

Filter to all agents owned by a user.

Date

Include entries on or after this timestamp.

Date

Include entries before this timestamp.

string[]

Filter to specific action names.

'allowed' | 'denied' | 'rate_limited'

Filter by outcome.

number

Maximum entries to return. Default is 1000.

number

Pagination offset.

Exporting logs

// 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

EU AI Act, Article 12. Record keeping

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.

NIST AI RMF. GOVERN 1.7 / MANAGE 4.2

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. CC6.1 through CC7.2

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, Annex A.8. Documentation of AI system behaviour

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

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

const denied = await kavach.audit.query({
  result: 'denied',
  since: new Date(new Date().setHours(0, 0, 0, 0)),
});

const countsByAgent = denied.reduce<Record<string, number>>((acc, entry) => {
  acc[entry.agentId] = (acc[entry.agentId] ?? 0) + 1;
  return acc;
}, {});

High-frequency agent detection

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

Compliance

Map audit data to EU AI Act, NIST, SOC 2, and ISO 42001.

REST API

Query audit logs via HTTP endpoints.

Admin dashboard

Visual audit log viewer with filters and export.

Identity

Authorization

Observability

Controls

How audit logging works

Querying logs

AuditEntry type

Filtering

Exporting logs

Compliance references

Usage patterns

Next steps

Compliance

REST API

Admin dashboard

​How audit logging works

​Querying logs

​AuditEntry type

​Filtering

​Exporting logs

​Compliance references

​Usage patterns

​Next steps

Compliance

REST API

Admin dashboard

How audit logging works

Querying logs

AuditEntry type

Filtering

Exporting logs

Compliance references

Usage patterns

Next steps