Anomaly detection

What anomaly detection does

KavachOS scans the audit log for behavioral patterns that suggest an agent is operating outside its intended scope. The most common signal is a cluster of denied calls that match privilege escalation patterns, an agent repeatedly attempting to access resources it was never granted. Anomaly detection is not a background process. You call scan() and get back a list of findings at that point in time. This keeps the system predictable: there are no background threads, no persistent state, and no surprise side effects.

Anomaly types

Type	Severity	Description
`privilege_escalation`	critical	Denied calls with reasons matching `INSUFFICIENT_PERMISSIONS`, `privilege`, or `escalation`.
`high_denial_rate`	warning	More than 20% of the agent’s recent calls were denied.
`rapid_fire`	warning	Call volume in the last hour exceeds a configurable threshold.
`unusual_resource_access`	info	The agent accessed a resource it has no explicit permission for, even if the call succeeded.
`off_hours_activity`	info	Calls outside the agent’s declared `timeWindow` constraint, if one is set.

scan() queries audit logs directly, it is not a background process and does not push alerts. Call it from a scheduled job, a webhook handler, or a dashboard endpoint.

Anomaly fields

string

The agent where the anomaly was detected.

'privilege_escalation' | 'high_denial_rate' | 'rapid_fire' | 'unusual_resource_access' | 'off_hours_activity'

Classification of the detected pattern.

'critical' | 'warning' | 'info'

How urgent the finding is.

string

Human-readable explanation of what was observed.

number

Number of matching events in the scanned window.

string

ISO timestamp of when the scan ran.

AuditEntry[]

The specific audit log entries that triggered this finding.

AnomalyConfig options

Date

Start of the window to scan. Defaults to 24 hours ago.

Date

End of the window to scan. Defaults to now.

number

Denial rate percentage above which high_denial_rate fires. Default is 20.

number

Calls per hour above which rapid_fire fires. Default is 100.

string

Scope the scan to a single agent. Omit to scan all agents.

Code examples

Scan a single agent for anomalies

const anomalies = await kavach.audit.query({
  agentId: 'agt_abc123',
  result: 'denied',
  since: new Date(Date.now() - 24 * 3_600_000),
});

// Check for privilege escalation pattern
const escalations = anomalies.filter((entry) => {
  const reason = entry.reason ?? '';
  return (
    reason.includes('INSUFFICIENT_PERMISSIONS') ||
    reason.toLowerCase().includes('privilege') ||
    reason.toLowerCase().includes('escalation')
  );
});

if (escalations.length > 0) {
  console.warn(`${escalations.length} escalation attempt(s) detected for agt_abc123`);
}

Get a denial-rate summary for all agents

const since = new Date(Date.now() - 24 * 3_600_000);

const logs = await kavach.audit.query({ since, limit: 5000 });

const byAgent: Record<string, { total: number; denied: number }> = {};

for (const entry of logs) {
  const bucket = (byAgent[entry.agentId] ??= { total: 0, denied: 0 });
  bucket.total++;
  if (entry.result === 'denied') bucket.denied++;
}

const highDenialAgents = Object.entries(byAgent)
  .filter(([, { total, denied }]) => total > 0 && denied / total > 0.2)
  .map(([agentId, { total, denied }]) => ({
    agentId,
    denialRate: (denied / total) * 100,
  }));

console.log('Agents with >20% denial rate:', highDenialAgents);

Act on critical findings

The most effective response to a privilege escalation detection is to pause the agent while you investigate:

const denied = await kavach.audit.query({
  agentId: 'agt_abc123',
  result: 'denied',
  since: new Date(Date.now() - 3_600_000),
});

const escalations = denied.filter((e) =>
  (e.reason ?? '').includes('INSUFFICIENT_PERMISSIONS'),
);

if (escalations.length >= 3) {
  await kavach.agent.revoke('agt_abc123');
  console.log('Agent revoked after repeated escalation attempts.');
}

agent.revoke() is permanent. If you want to temporarily suspend an agent and restore it later, create a new agent with the same configuration instead of revoking.

Use trust scores as the anomaly aggregate

The anomalyCount field on a trust score is a pre-computed count of privilege escalation attempts, updated each time computeScore runs. It is a cheaper signal than a full scan when you only need the count:

const score = await kavach.trust.computeScore('agt_abc123');

if (score.factors.anomalyCount > 0) {
  console.warn(
    `${score.factors.anomalyCount} anomalies detected. Last denial: ${score.factors.lastViolation}`,
  );
}

Next steps

Trust scoring

Translate anomaly counts into a graduated trust level.

Approval flows

Route flagged agents through human review before they act.

Audit trail

Query the raw log data that anomaly detection reads.

Identity

Authorization

Observability

Controls

Anomaly detection

What anomaly detection does

Anomaly types

Anomaly fields

AnomalyConfig options

Code examples

Scan a single agent for anomalies

Get a denial-rate summary for all agents

Act on critical findings

Use trust scores as the anomaly aggregate

Next steps

Trust scoring

Approval flows

Audit trail

​What anomaly detection does

​Anomaly types

​Anomaly fields

​AnomalyConfig options

​Code examples

​Scan a single agent for anomalies

​Get a denial-rate summary for all agents

​Act on critical findings

​Use trust scores as the anomaly aggregate

​Next steps

Trust scoring

Approval flows

Audit trail

What anomaly detection does

Anomaly types

Anomaly fields

AnomalyConfig options

Code examples

Scan a single agent for anomalies

Get a denial-rate summary for all agents

Act on critical findings

Use trust scores as the anomaly aggregate

Next steps