Policy Engine

YAML-based security policies with pattern matching on tool names and arguments.

Rule Anatomy

nameHuman-readable rule identifier

toolRegex matching tool name(s)

patternRegex matching the target field

match_onWhat to match: "tool_name" or "arguments.<field>"

decisionALLOW, DENY, or ESCALATE

reasonMessage returned to the agent on DENY/ESCALATE

Custom Policy Example

yaml

# my-policy.yaml
name: "production-api-guard"
version: "1.0"

rules:
  # Block all shell commands
  - name: no-shell
    tool: "run_command|execute_shell|bash"
    pattern: ".*"
    match_on: "tool_name"
    decision: DENY
    reason: "Shell access is disabled in production"

  # Allow read-only SQL, block mutations
  - name: sql-readonly
    tool: "execute_sql"
    pattern: "INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE"
    match_on: "arguments.query"
    decision: DENY
    reason: "Only SELECT queries are allowed"

  # Escalate file access outside safe directory
  - name: safe-directory
    tool: "read_file|write_file"
    pattern: "^(?!/app/data/)"
    match_on: "arguments.path"
    decision: ESCALATE
    reason: "File access outside /app/data/ requires approval"

  # Allow everything else
  - name: default-allow
    tool: ".*"
    pattern: ".*"
    match_on: "tool_name"
    decision: ALLOW

Policy CLI

bash

# Validate your custom policy
"code-keyword">$ "code-function">spidershield policy validate ./my-policy.yaml
✓ Policy "production-api-guard" is valid (4 rules)

# List built-in presets
"code-keyword">$ "code-function">spidershield policy list
  permissive  — Log only, no blocking
  balanced    — Block dangerous, escalate writes
  strict      — Deny by default, allowlist only

# Show preset rules
"code-keyword">$ "code-function">spidershield policy show balanced

Evaluation Order

Rules are evaluated top-to-bottom. The first matching rule wins.

1Each tool call is checked against rules in order
2First rule where both tool and pattern match is applied
3If no rule matches, the default decision is ALLOW
4DENY rules should come before ALLOW rules for safety

← CLI Reference Audit Logging →