Audit Log Schema — Network-AI

Network-AI writes a JSONL audit trail during permission management and swarm execution. This document describes every field and event type.

File Location

data/audit_log.jsonl

One JSON object per line. The file is append-only. Each entry is a complete, self-contained record — no dependencies between lines.

The CLI provides direct access without inspecting the file manually:

network-ai audit log            # print all entries (add --limit <n> to cap output)
network-ai audit tail           # live-stream new entries as they are appended
network-ai audit clear          # reset the log (irreversible)
network-ai --json audit log     # machine-readable output

Envelope (all events)

Every log entry uses the same outer structure:

{
  "timestamp": "2026-02-28T14:32:01.123456+00:00",
  "action":    "<event_type>",
  "details":   { ... }
}

Event Types

Per-Event details Schemas

permission_request

{
  "agent_id":      "data_analyst",
  "resource_type": "DATABASE",
  "justification": "Need customer order history for Q1 sales report",
  "scope":         "read"
}

permission_granted

{
  "token":         "grant_a1b2c3d4e5f67890abcdef1234567890ab",
  "agent_id":      "data_analyst",
  "resource_type": "DATABASE",
  "scope":         "read",
  "expires_at":    "2026-02-28T14:37:01.123456+00:00",
  "restrictions":  ["read-only", "no-schema-changes"],
  "granted_at":    "2026-02-28T14:32:01.123456+00:00"
}

permission_denied

{
  "agent_id":      "untrusted_bot",
  "resource_type": "PAYMENTS",
  "reason":        "Combined evaluation score (0.31) below threshold (0.5).",
  "scores": {
    "justification": 0.25,
    "trust":         0.40,
    "risk":          0.90,
    "weighted":      0.31
  }
}

permission_revoked

{
  "token":    "grant_a1b2c3d4e5f67890abcdef1234567890ab",
  "agent_id": "data_analyst",
  "reason":   "manual revocation"
}

ttl_cleanup

{
  "removed_tokens": ["grant_abc...", "grant_def..."],
  "count":          2
}

budget_initialized

{
  "ceiling": 5000,
  "unit":    "tokens"
}

handoff_allowed

{
  "from_agent": "orchestrator",
  "to_agent":   "implementer",
  "task":       "implement payment service",
  "budget_remaining": 4120
}

handoff_blocked

{
  "from_agent": "implementer",
  "to_agent":   "orchestrator",
  "reason":     "budget_exceeded",
  "budget_used": 5100,
  "budget_ceiling": 5000
}

safety_shutdown

{
  "reason":         "budget_ceiling_breached",
  "budget_used":    5100,
  "budget_ceiling": 5000,
  "agent":          "rogue_agent"
}

Scoring Reference

Permission decisions use a three-factor weighted score:

Approval threshold: 0.50. Requests below this are logged as permission_denied.

Node.js Layer (TypeScript package)

When using the network-ai npm package directly, the SecureAuditLogger class in security.ts produces HMAC-SHA256-signed entries with the same envelope format plus a signature field. This is separate from the Python script layer described above.

Retention & Privacy

• The log is append-only. There is no built-in rotation — implement log rotation at the infrastructure level (e.g. logrotate, S3 lifecycle policy).
• No PII is logged by default. Justification text is logged as-provided — avoid including PII in justification strings.
• No API keys, tokens in cleartext, or sensitive resource content are logged.