khyari hamza
114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# Audit Logging
|
|
|
|
CleverAgents records security-relevant operations in an `audit_log` table
|
|
for compliance, post-hoc analysis, and diagnostics.
|
|
|
|
## Event Types
|
|
|
|
| Event Type | Trigger | Details Captured |
|
|
|---|---|---|
|
|
| `plan_applied` | `agents plan apply` | Plan ID, project, files changed, validation results |
|
|
| `plan_cancelled` | `agents plan cancel` | Plan ID, reason, resources released |
|
|
| `resource_modified` | Tool write during Execute | Resource ID, modification type, tool name |
|
|
| `correction_applied` | `agents plan correct` | Correction ID, original decision, mode, guidance |
|
|
| `config_changed` | `agents config set` | Key, old/new values (masked if secret) |
|
|
| `entity_deleted` | `agents <entity> delete` | Entity type, entity name, cascade effects |
|
|
| `session_created` | `agents session create` | Session ID, actor name |
|
|
|
|
## CLI Commands
|
|
|
|
### `agents audit list`
|
|
|
|
List audit entries with optional filters.
|
|
|
|
```bash
|
|
# List recent entries
|
|
agents audit list
|
|
|
|
# Filter by plan
|
|
agents audit list --plan 01HXYZ123
|
|
|
|
# Filter by project and time range
|
|
agents audit list --project myproject --since 2026-02-01T00:00:00
|
|
|
|
# Filter by event type with limit
|
|
agents audit list --type plan_applied --limit 10
|
|
```
|
|
|
|
### `agents audit show <id>`
|
|
|
|
Display a single entry with full metadata and JSON details.
|
|
|
|
```bash
|
|
agents audit show 42
|
|
```
|
|
|
|
### `agents audit prune`
|
|
|
|
Delete entries older than the retention period.
|
|
|
|
```bash
|
|
# Use configured retention (default: keep indefinitely)
|
|
agents audit prune --yes
|
|
|
|
# Override retention to 90 days
|
|
agents audit prune --days 90 --yes
|
|
```
|
|
|
|
### `agents audit count`
|
|
|
|
Display the total number of audit log entries.
|
|
|
|
```bash
|
|
agents audit count
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Setting | Environment Variable | Default | Description |
|
|
|---|---|---|---|
|
|
| `audit_retention_days` | `CLEVERAGENTS_AUDIT_RETENTION_DAYS` | `0` | Days to retain entries. `0` = keep indefinitely. |
|
|
|
|
## Database Schema
|
|
|
|
```sql
|
|
CREATE TABLE audit_log (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
event_type TEXT NOT NULL,
|
|
plan_id TEXT,
|
|
project_name TEXT,
|
|
actor_name TEXT,
|
|
user_identity TEXT,
|
|
details TEXT NOT NULL, -- JSON
|
|
created_at TEXT NOT NULL
|
|
);
|
|
|
|
CREATE INDEX idx_audit_event ON audit_log(event_type);
|
|
CREATE INDEX idx_audit_plan ON audit_log(plan_id) WHERE plan_id IS NOT NULL;
|
|
CREATE INDEX idx_audit_created ON audit_log(created_at);
|
|
```
|
|
|
|
## Retention Policy
|
|
|
|
By default, audit logs are retained indefinitely (`audit_retention_days=0`)
|
|
for compliance purposes. Use `agents audit prune` to manually remove old
|
|
entries, or set a non-zero retention to enable periodic pruning.
|
|
|
|
## Recording Events
|
|
|
|
The `AuditService.record()` method writes events:
|
|
|
|
```python
|
|
from cleveragents.application.services.audit_service import AuditService
|
|
from cleveragents.config.settings import get_settings
|
|
|
|
service = AuditService(settings=get_settings())
|
|
service.record(
|
|
event_type="plan_applied",
|
|
plan_id="01HXYZ123",
|
|
project_name="my-project",
|
|
actor_name="openai/gpt-4o",
|
|
details={"files_changed": 3, "validation_passed": True},
|
|
)
|
|
```
|