Skip to main content

​
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
pip install declaw python-dotenv

​
Code Walkthrough

This example is available in Python. TypeScript support coming soon.

​
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. 
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: 
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: 
# 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 fieldDefaultDescription
enabledTrueWhether 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

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!
============================================================