audit-podclaw

name	Audit PodClaw
description	Comprehensive audit of PodClaw — the autonomous agent system (Claude Agent SDK, Python). Use when asked to audit, review, or assess PodClaw — covering agent security, sandbox isolation, tool restrictions, budget limits, bridge API, and fail-closed patterns.

Audit PodClaw

Systematic audit of podclaw/ — 9 autonomous agents on Claude Agent SDK with FastAPI bridge.

Prerequisites

• Read podclaw/README.md and podclaw/AGENTS.md for architecture
• Read podclaw/SECURITY.md for security model
• Read podclaw/SOUL.md for identity and constraints
• Read podclaw/config.py for budgets, tools, models, rate limits
• Read podclaw/bridge/api.py for the FastAPI bridge

Workflow

Phase 1: Agent Security Model

1. Fail-closed security hook:

   • Does a pre-tool-use hook exist that denies by default?
   • Is Bash access blocked for all agents? (per CLAUDE.md)
   • What tools are allowed per agent? (allowed_tools in config)
   • Is can_use_tool deny chain implemented?

2. Sandbox isolation:

   • Are agents running in sandboxed environments? (SandboxSettings)
   • Can agents access the filesystem outside their workspace?
   • Can agents access the network directly?
   • Can agents modify their own configuration?

3. Budget enforcement:

   • Is max_budget_usd set per agent?
   • What are the current budget limits?
   • Is there a global budget ceiling?
   • What happens when budget is exceeded? (graceful degradation or hard stop?)

4. Data boundaries:

   • Are [DATA] boundaries enforced for sensitive data?
   • Can agents access user PII directly?
   • Is there data classification (public, internal, sensitive, restricted)?

Phase 2: Agent Configuration

5. Agent inventory:

   • List all 9 agents with their roles
   • For each: model, budget, allowed tools, skill files
   • Verify each has a SKILL.md in podclaw/skills/<agent>/

6. Model selection:

   • Which Claude model does each agent use?
   • Are expensive models (Opus) limited to high-value tasks?
   • Is there model fallback on failure?

7. Rate limiting:

   • Are API calls rate-limited per agent?
   • Is there a global rate limit across all agents?
   • What happens on rate limit hit?

Phase 3: Bridge API Security

8. Authentication:

   • How does the bridge API authenticate requests?
   • Is it token-only? (per CLAUDE.md — needs OAuth/RBAC)
   • Is the token rotated? How is it stored?
   • Can the bridge be accessed from outside the Docker network?

9. Endpoint security:

   • List all bridge API endpoints
   • Which accept external input?
   • Is input validated and sanitized?
   • Are there any endpoints that trigger agent execution without auth?

10. Session management:

    • How are agent sessions managed? (session resume)
    • Is PreCompact transcript archiving working?
    • Can sessions be hijacked or replayed?

Phase 4: Tool & Skill Safety

11. Tool restrictions:

    • Are dangerous tools (file write, network access) restricted?
    • Is there a tool allowlist per agent?
    • Can agents install packages or modify dependencies?

12. Skill safety:

    • Do skills contain executable code?
    • Are skill files read-only for agents?
    • Can agents modify their own skills?

13. External service access:

    • Which external services can agents access? (Printful, fal.ai, Gemini, etc.)
    • Are API keys scoped per agent or shared?
    • Is there logging of external API calls?

Phase 5: Operational Resilience

14. Error handling & recovery:

    • What happens when an agent crashes?
    • Is there automatic retry with backoff?
    • Are failures logged and alerted?

15. Monitoring & observability:

    • Are agent actions logged? (decisions, tool calls, costs)
    • Is there a dashboard for agent activity?
    • Can suspicious agent behavior be detected?

Output Format

Generate AUDIT_PODCLAW_[DATE].md at workspace root with:

# PodClaw Audit — [DATE]

## Agent Inventory
| Agent | Model | Budget | Tools | Sandbox | Status |
|---|---|---|---|---|---|

## Summary
- Total checks: X
- PASS: X | WARN: X | FAIL: X | CRITICAL: X

## Critical Findings
[Security bypasses, missing sandboxing, uncontrolled access]

## Recommendations
[Priority-ordered — security first]