> ## 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.

# Privilege analyzer

> Scan agent permissions with `kavach.analyzer` to surface over-privileged identities, unused scopes, wildcard risks, and stale agents across your deployment.

The privilege analyzer scans agent permissions to find over-privileged agents, unused permissions, and potential security issues.

## Usage

```ts theme={"system"}
const analysis = await kavach.analyzer.analyzeAgent(agentId);

console.log(analysis.overPrivileged);  // permissions broader than needed
console.log(analysis.unusedPermissions); // granted but never exercised
console.log(analysis.riskScore);       // 0-100 risk assessment
console.log(analysis.recommendations); // suggested permission changes
```

## Scan all agents

```ts theme={"system"}
const report = await kavach.analyzer.scanAll();

for (const finding of report.findings) {
  console.log(`${finding.agentId}: ${finding.type} - ${finding.description}`);
}
```

## Finding types

| Type                | Description                                         |
| ------------------- | --------------------------------------------------- |
| `over-privileged`   | Agent has broader permissions than its actual usage |
| `wildcard-risk`     | Agent uses `*` wildcard on sensitive resources      |
| `unused-permission` | Permission granted but never used in audit trail    |
| `stale-agent`       | Agent hasn't been used in 30+ days                  |
| `no-expiry`         | Agent has no expiration date set                    |
| `deep-delegation`   | Delegation chain depth exceeds recommended limit    |

## Configuration

```ts theme={"system"}
const kavach = await createKavach({
  analyzer: {
    unusedThresholdDays: 30,  // flag permissions unused for 30+ days
    maxRecommendedDepth: 3,   // flag delegation chains deeper than 3
    wildcardWarning: true,    // flag wildcard permissions
  },
});
```

<Warning>
  The analyzer reads from the audit trail. Enable `auditAll: true` in agent config for accurate unused-permission detection.
</Warning>