Security API

The security API manages profClaw’s permission system - controlling which tools agents can use, setting security modes, and retrieving the audit trail of all agent actions.

Security Modes

profClaw has five security levels for tool execution:

Mode	Description
`deny`	No tools allowed
`sandbox`	Only read-only tools
`allowlist`	Only explicitly allowed tools
`ask`	Prompt for approval before sensitive operations
`full`	All tools pre-approved (agentic mode default)

GET /api/security/policy

Get the current security policy configuration.

curl http://localhost:3000/api/security/policy --cookie "profclaw_session=<token>"

Response 200

{
  "defaultMode": "ask",
  "allowedTools": ["read_file", "web_fetch", "web_search"],
  "blockedTools": ["execute_command"],
  "requireApprovalFor": ["write_file", "run_tests", "git_commit"],
  "auditAll": true
}

PUT /api/security/policy

Update the security policy.

curl -X PUT http://localhost:3000/api/security/policy \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<admin-token>" \
  -d '{
    "defaultMode": "ask",
    "allowedTools": ["read_file", "web_fetch"],
    "requireApprovalFor": ["write_file", "git_commit"]
  }'

GET /api/security/audit

Retrieve the audit log of agent tool executions.

curl "http://localhost:3000/api/security/audit?limit=50&offset=0" \
  --cookie "profclaw_session=<token>"

Response 200

{
  "entries": [
    {
      "id": "audit_01",
      "timestamp": "2026-03-12T10:30:00Z",
      "conversationId": "conv_01",
      "taskId": "task_01",
      "tool": "write_file",
      "arguments": { "path": "src/auth.ts", "content": "..." },
      "result": "success",
      "userId": "usr_01",
      "approved": true,
      "approvalDecision": "allow-once"
    }
  ],
  "total": 420,
  "limit": 50,
  "offset": 0
}

Query parameters: limit, offset, tool, userId, conversationId, from, to

GET /api/security/audit/:id

Get a single audit entry with full argument and result details.

Tool Approval Queue

When securityMode is ask, tool calls requiring approval are queued until a user decision is made.

GET /api/security/approvals

List pending tool approvals.

{
  "approvals": [
    {
      "id": "approval_01",
      "conversationId": "conv_01",
      "toolName": "write_file",
      "params": { "path": "src/auth.ts" },
      "requestedAt": "2026-03-12T10:30:00Z",
      "securityLevel": "moderate"
    }
  ]
}

POST /api/security/approvals/:id

Submit an approval decision.

{ "decision": "allow-once" }

Decisions: allow-once | allow-always | deny allow-always adds the tool to the session allowlist so subsequent calls proceed without prompting.

Guard Configuration

Guards are pre-execution checks that block unsafe tool calls regardless of security mode:

GET /api/security/guards        # List active guards
PUT /api/security/guards/:name  # Enable/disable a guard

Built-in guards:

Guard	Blocks
`path-traversal`	Paths containing `../` or absolute paths outside workdir
`shell-injection`	Shell metacharacters in command arguments
`secret-exfiltration`	Reads of `.env`, credential files
`rate-limit`	Tool calls exceeding configured rate

Security Overview - Security modes, guards, and audit architecture
profclaw security - Manage security policies from the CLI
profclaw audit - View the audit log from the CLI
Tools Overview - Tool security levels and execution pipeline

API Overview

Authentication

Chat

Agents

Tasks

Memory

Integrations

System

Security Modes

GET /api/security/policy

PUT /api/security/policy

GET /api/security/audit

GET /api/security/audit/:id

Tool Approval Queue

GET /api/security/approvals

POST /api/security/approvals/:id

Guard Configuration

​Security Modes

​GET /api/security/policy

​PUT /api/security/policy

​GET /api/security/audit

​GET /api/security/audit/:id

​Tool Approval Queue

​GET /api/security/approvals

​POST /api/security/approvals/:id

​Guard Configuration

​Related

Security Modes

GET /api/security/policy

PUT /api/security/policy

GET /api/security/audit

GET /api/security/audit/:id

Tool Approval Queue

GET /api/security/approvals

POST /api/security/approvals/:id

Guard Configuration

Related