DOCSEARCHbyAlgolia
Submit Docs

CrabTrap Documentation

repository·main·Indexed 20 days ago

https://github.com/brexhq/crabtrap

An HTTP/HTTPS forward proxy providing security guardrails for AI agents. CrabTrap intercepts outbound requests and evaluates them against deterministic static rules and natural-language LLM-based policies to prevent SSRF, prompt injection, and unauthorized API access. It features MITM decryption via a custom CA, audit logging in PostgreSQL, and an admin Web UI for configuration and user management.

Tokens
20.7K
Snippets
61
Records
87
Agent score
71%

What's inside CrabTrap

  1. How the LLM Judge works

    main

    The LLM Judge provides automated evaluation of write requests against a policy prompt. It is designed to reduce reliance on human reviewers for well-understood workloads.

    Core Mechanics

    • Provider: Uses AWS Bedrock with Anthropic models.
    • Policy Management: Policies are stored in the llm_policies table as immutable, versioned records. Editing a policy always creates a new version.
    • User Assignment: Users can be assigned a specific policy via the llm_policy_id foreign key in the user row.

    Evaluation Modes

    ModeBehavior
    llm (default)The judge is invoked, and its decision (approve/deny) is applied directly to the request.
    passthroughAll requests are allowed through without being evaluated by the judge.

    Error Handling

    If the judge returns an error, the system follows a configurable fallback mode (set per deployment):

    • deny (Safe Default): The request is rejected with a 403 error.
    • passthrough: The request is allowed through.

    Data Handling & Privacy

    • No Redaction: The judge receives the full HTTP request verbatim (headers and body). This ensures the LLM has full context for accurate decisions. Security is managed via LLM provider agreements and network isolation rather than request sanitization.
    • Decompression: To ensure policies are evaluated against plaintext, the proxy decompresses request bodies using the Content-Encoding header. Supported encodings include gzip, x-gzip, deflate, and br (Brotli). If decompression fails or the encoding is unsupported, the original compressed body is passed to the judge.
    • Limits: Request bodies are buffered up to 10 MB for decompression. The judge consumes only the first 4 KB of the decompressed body text.

  2. How CrabTrap evaluates outbound requests

    main

    CrabTrap acts as a forward proxy between AI agents and the internet. The evaluation flow for every outbound request is as follows:

    1. Agent Connection: The agent connects via HTTP_PROXY and HTTPS_PROXY environment variables.
    2. TLS Termination: CrabTrap performs MITM (Man-in-the-Middle) decryption using a custom CA to inspect HTTPS traffic.
    3. Static Rules (Tier 1): The request is matched against deterministic URL pattern rules (prefix, exact, or glob). If a match is found, the decision (Allow/Deny) is immediate. Deny rules always take priority over allow rules.
    4. LLM Judge (Tier 2): If no static rule matches, the request is sent to an LLM judge. The judge evaluates the request against the agent's natural-language security policy.
      • Allowed: Request is forwarded.
      • Denied: Request is blocked with a 403 status and a reason.
    5. Audit Logging: Every request, decision, and response is recorded in PostgreSQL for auditing.

  3. CrabTrap Security and Limitations

    main

    Security Features

    • HTTPS Interception: Transparent MITM proxy with custom TLS certificate generation.
    • SSRF Protection: Blocks requests to private networks (RFC 1918, loopback, link-local, etc.) with DNS-rebinding prevention.
    • Prompt Injection Defense: Request payloads are JSON-encoded and policy content is JSON-escaped before LLM evaluation.
    • Rate Limiting: Per-IP token bucket rate limiter (default 50 req/s, burst 100).

    What CrabTrap Does NOT Do

    • Not an Inbound Firewall: It is a forward proxy for outbound-only traffic. It does not protect your services from inbound requests.
    • No Data Redaction: The proxy sees all request content (including Authorization and Cookie headers) in cleartext.
    • No Human-in-the-loop: Decisions are fully automated via static rules and the LLM judge; there is no manual approval queue.
    • No Response Filtering: Only outbound requests are evaluated. Upstream API responses are streamed back unexamined.
    • No WebSocket Inspection: Only the initial WebSocket upgrade request is evaluated; subsequent frames pass through uninspected.

  4. Configure LLM judge fallback behavior

    main

    When the LLM judge is unavailable, the gateway's behavior is determined by the llm_judge.fallback_mode configuration setting:

    • deny (default): Rejects the request.
    • passthrough: Allows the request to proceed through the proxy.

  5. Manage LLM Policies with the fork/publish model

    main

    CrabTrap provides per-user LLM policy management via internal/llmpolicy/pg_store.go. Policies are managed using a fork/publish model:

    • Forking: Create a new version of an existing policy to test changes.
    • Publishing: Make a forked version the active policy for the user.
    • Soft-delete: Policies can be removed without immediate hard deletion from the PostgreSQL store.

    Users can also use a Policy Agent (internal/builder/) which uses an agentic AI loop to help synthesize new policies.

  6. How Denial Alerting works in CrabTrap

    main

    CrabTrap provides summarized notifications to bot managers when their bots encounter denials. Instead of sending individual alerts for every denied request, CrabTrap buffers denials for a configurable window and uses an LLM to generate a concise summary. This prevents alert fatigue by grouping multiple denials into a single, context-rich notification.

    The lifecycle of an alert:

    1. A bot request is denied.
    2. The denial is added to a per-bot buffer.
    3. After the batch_window expires, the buffer is flushed.
    4. An LLM summarizes the buffered denials into a 2-3 sentence explanation.
    5. A single notification is sent to the bot's managers via their configured channels.

  7. Evaluate policies using the Evaluation System

    main

    The evaluation system (internal/eval/) allows you to measure the accuracy of your LLM policies. It works by:

    1. Replaying Audit Logs: Replaying historical AuditEntry records from the PostgreSQL-backed audit log.
    2. Policy Application: Running those entries against current policies.
    3. Result Tracking: Tracking results and statistics to determine how well the policy performs against real-world traffic.

    LLM response metadata is persisted in the llm_responses table for detailed analysis.

  8. How the Evaluation System works

    main

    The Evaluation System allows operators to replay historical audit_log entries through an LLM policy. This measures how closely an automated policy aligns with previous human decisions.

    Workflow

    1. Initiate Run: An operator starts an evaluation via POST /admin/evals, providing a policy_id and optional filters (e.g., date range, user).
    2. Asynchronous Processing: A worker pool fetches matching audit entries and submits them to the judge. The run status is tracked in the eval_runs table (pending, running, completed, failed).
    3. Result Storage: Results are written to the eval_results table, including the replay_decision (ALLOW / DENY / ERROR), the approved_by method (e.g., llm, llm-static-rule), and the judge's reason.
    4. Aggregation: Statistics such as agreed %, disagreed %, and errored % are computed by comparing the replay_decision against the original audit entry's decision.

    Ground-Truth Labeling

    To improve evaluation accuracy, admins can manually label audit entries as correct or incorrect. These labels are stored in the audit_labels table and persist across all evaluation runs, allowing for more sophisticated scoring.

  9. Understand the CrabTrap data model and storage

    main

    CrabTrap uses PostgreSQL for persistent storage of all core entities. The following table maps functional areas to their respective database tables:

    DataStoragePersistence
    Users & channelsPostgreSQL users, user_channelsYes
    Audit logPostgreSQL audit_logYes
    LLM policiesPostgreSQL llm_policiesYes
    Eval runs & resultsPostgreSQL eval_runs, eval_resultsYes
    LLM judge call metadataPostgreSQL llm_responsesYes
    Audit ground-truth labelsPostgreSQL audit_labelsYes

  10. Authorization rules for notification channels

    main

    Access to managing notification channels is governed by the following rules:

    • Managers: Can create, update, or delete notification channels for bots they specifically manage.
    • Admins: Have full permission to manage any notification channel across the system.
    • Constraint: To create a channel linked to a specific bot, the user must be a manager of that bot.

  11. Configure CrabTrap approval modes

    main

    CrabTrap operates in different modes that affect how requests are handled:

    • llm mode: The LLM judge evaluates the request and decides whether to approve or deny it. This adds latency (typically 1-5s).
    • passthrough mode: All requests are automatically approved and audit-logged. This is ideal for quick testing and has minimal latency (~100-200ms).

    To use passthrough mode, set approval.mode: passthrough in your configuration file.

  12. How CrabTrap's approval flow works

    main

    CrabTrap acts as a security mesh that intercepts all external API calls. Every request passes through an Approval Manager that decides whether to allow or deny the operation based on the following hierarchy:

    1. Static Rules: If a request matches a predefined static rule, it is immediately allowed or denied.
    2. LLM Policy Check: If no static rule matches, CrabTrap checks if the requesting user has an active LLM policy assigned.
      • Policy Assigned: The LLM judge is invoked, and its decision (approve/deny) is applied.
      • No Policy Assigned: The request is either denied or passed through, depending on your fallback_mode configuration.
      • Judge Error: If the LLM judge fails, the request is either denied or passed through, depending on your configuration.

    Note on Classification: For audit logging purposes, HTTP methods are classified as READ (GET, HEAD, OPTIONS) or WRITE (POST, PUT, PATCH, DELETE). This classification is used for logging and does not change the approval logic itself.