> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logging

> Configure the per-sandbox audit opt-out and understand what Declaw records for lifecycle and security events.

## What You'll Learn

* What Declaw's audit log actually captures (lifecycle + security events, not request/response bodies)
* How to opt a sandbox out of audit logging with `AuditConfig(enabled=False)`
* The retention window and why it is platform-wide

## Prerequisites

* Declaw instance running and `DECLAW_API_KEY` / `DECLAW_DOMAIN` set

```bash theme={null}
pip install declaw python-dotenv
```

## Code Walkthrough

<Note>This example is available in Python. TypeScript support coming soon.</Note>

### 1. The default: audit on

Declaw records a fixed set of lifecycle and security events for every
sandbox by default. You do not have to enable anything.

```python theme={null}
from declaw import Sandbox

sbx = Sandbox.create(template="base")
# Lifecycle + egress decisions for this sandbox are recorded
# to the platform's audit log automatically.
```

### 2. Opt out of audit logging

If a sandbox is handling sensitive workloads and you'd rather have no
record at all, pass `AuditConfig(enabled=False)` on the policy:

```python theme={null}
from declaw import Sandbox, SecurityPolicy, AuditConfig

sbx = Sandbox.create(
    template="base",
    security=SecurityPolicy(audit=AuditConfig(enabled=False)),
)
```

The `audit` field also accepts a plain boolean as a shorthand:

```python theme={null}
# Equivalent to AuditConfig(enabled=False)
sbx = Sandbox.create(
    template="base",
    security=SecurityPolicy(audit=False),
)
```

When `enabled=False`, the orchestrator drops gated events (network,
command, filesystem, snapshot, pty, security) for that sandbox at the
source — nothing is shipped to the collector for those categories. Only
lifecycle and admin events are still recorded.

| `AuditConfig` field | Default | Description                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------ |
| `enabled`           | `True`  | Whether events for this sandbox are recorded. Set to `False` to opt out. |

### 3. What the audit log captures

The audit log records a fixed set of events. These are emitted by the
orchestrator and node collector, not by the HTTP proxy:

* **Lifecycle** (always recorded) — `vm_created`, `vm_killed`, `vm_paused`,
  `vm_resumed`, plus their `_failed` counterparts.
* **Snapshot** (gated) — `vm_snapshot_started`, `vm_snapshot_completed`,
  `vm_snapshot_failed`, `vm_restore_started`, `vm_restored`,
  `vm_restore_failed`.
* **Network** (gated) — `egress_allowed` and `egress_blocked` decisions
  from the per-sandbox firewall (domain, destination IP/port, rule that fired).

Each event carries the sandbox id, node id, timestamp, event name,
category, and a JSON `detail` payload scoped to the event.

Request and response bodies are not written to the audit log. PII
redaction and prompt-injection scanning emit their own metrics; see
the PII and injection-defense cookbook pages for how to read those.

### 4. Retention

Audit events are retained for **7 days** platform-wide and then deleted
by a nightly cleanup job in the node collector. Retention is not
configurable per sandbox today — it is a single, predictable window for
all tenants.

### 5. Cleanup

```python theme={null}
sbx.kill()
```

## Expected Output

```
============================================================
Declaw Audit Logging Example
============================================================

--- Creating Sandbox with Audit Opt-Out ---
Sandbox created: sbx_abc123

Security policy applied:
  audit.enabled: False

Audit events for this sandbox are suppressed at the orchestrator.

--- Cleaning Up ---
Sandbox killed.

============================================================
Done!
============================================================
```