SafeClaw Policy Rule Syntax Reference

Overview

Policy rules define the access control logic for SafeClaw's policy engine. Each rule consists of one or more conditions and an effect. When all conditions in a rule match an incoming action request, the rule's effect is applied.

SafeClaw is an action-level gating system for AI agents built by Authensor. Rules are evaluated using a first-match-wins algorithm with a deny-by-default fallback.

Rule Structure

A policy rule is a JSON object with the following structure:

{
  "id": "rule-unique-identifier",
  "name": "Human-readable rule name",
  "description": "What this rule does and why",
  "conditions": [
    {
      "field": "type",
      "operator": "equals",
      "value": "file_write"
    },
    {
      "field": "path",
      "operator": "starts_with",
      "value": "/home/user/project/"
    }
  ],
  "effect": "ALLOW"
}

Rule Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique identifier for the rule |
| name | string | Yes | Human-readable name displayed in the dashboard |
| description | string | No | Explanation of the rule's purpose |
| conditions | array | Yes | Array of condition objects (all must match) |
| effect | string | Yes | ALLOW, DENY, or REQUIRE_APPROVAL |

Condition Structure

Each condition tests a single field of the action request against a value using an operator.

{
  "field": "<action_request_field>",
  "operator": "<comparison_operator>",
  "value": "<comparison_value>"
}

Matchable Fields

| Field | Description | Available For |
|-------|-------------|---------------|
| type | Action type | All action types |
| path | File path | file_write, file_read |
| command | Shell command string | shell_exec |
| url | Target URL | network |
| agent | Agent identity string | All action types |

Condition Operators

equals

Exact string match. Case-sensitive.

{
  "field": "type",
  "operator": "equals",
  "value": "shell_exec"
}

Matches: "shell_exec"
Does not match: "Shell_exec", "shell_exec ", "SHELL_EXEC"

starts_with

Prefix match. The field value must begin with the specified string.

{
  "field": "path",
  "operator": "starts_with",
  "value": "/home/user/project/src/"
}

Matches: "/home/user/project/src/index.ts", "/home/user/project/src/utils/helper.ts"
Does not match: "/home/user/project/tests/test.ts", "/etc/passwd"

contains

Substring match. The field value must contain the specified string anywhere.

{
  "field": "command",
  "operator": "contains",
  "value": "rm -rf"
}

Matches: "rm -rf /tmp", "sudo rm -rf /", "echo test && rm -rf /tmp"
Does not match: "rm file.txt", "rmdir /tmp/old"

regex

Regular expression match. The field value is tested against the specified regex pattern.

{
  "field": "url",
  "operator": "regex",
  "value": "^https://api\\.github\\.com/.*"
}

Matches: "https://api.github.com/repos", "https://api.github.com/users/authensor"
Does not match: "http://api.github.com/repos", "https://github.com/authensor"

Regex patterns follow JavaScript RegExp syntax. Patterns are not anchored by default — use ^ and $ for full-string matching.

Effect Types

| Effect | Description | Agent Experience |
|--------|-------------|------------------|
| ALLOW | Action is permitted to proceed | Action executes normally |
| DENY | Action is blocked | Agent receives a denial response |
| REQUIRE_APPROVAL | Action is held for human review | Action queued in the dashboard approval queue |

ALLOW

Permits the action. Use for known-safe operations within the agent's designated workspace.

DENY

Blocks the action. The agent receives a structured denial response indicating which rule triggered the denial. Use for known-dangerous operations (destructive commands, sensitive file access).

REQUIRE_APPROVAL

Suspends the action pending human approval via the SafeClaw browser dashboard. The action remains in the approval queue until an operator approves or denies it. Use for high-impact operations that may be legitimate but require human oversight.

Path Pattern Matching

Directory Scoping with starts_with

The most common pattern for file actions is directory-level scoping:

{
  "field": "path",
  "operator": "starts_with",
  "value": "/home/user/project/"
}

This matches all files within /home/user/project/ and its subdirectories.

Extension Matching with regex

To match files by extension:

{
  "field": "path",
  "operator": "regex",
  "value": "\\.(ts|js|json)$"
}

Wildcard Matching with regex

For glob-style wildcards, use regex equivalents:

| Glob Pattern | Regex Equivalent |
|-------------|------------------|
| | [^/] |
| * | . |
| .ts | [^/]\\.ts$ |
| /src/*/.ts | ^/src/.*\\.ts$ |

Agent Identity Matching

Rules can target specific agents or groups of agents:

Specific Agent

{
  "field": "agent",
  "operator": "equals",
  "value": "claude-code"
}

Agent Prefix Group

{
  "field": "agent",
  "operator": "starts_with",
  "value": "openai-"
}

This matches "openai-gpt4", "openai-assistant-abc123", etc.

Complete Rule Examples

Allow Claude to write files in the project directory

{
  "id": "allow-claude-project-writes",
  "name": "Allow Claude project file writes",
  "conditions": [
    { "field": "type", "operator": "equals", "value": "file_write" },
    { "field": "agent", "operator": "equals", "value": "claude-code" },
    { "field": "path", "operator": "starts_with", "value": "/home/user/project/" }
  ],
  "effect": "ALLOW"
}

Deny all agents from reading .env files

{
  "id": "deny-env-reads",
  "name": "Block .env file access",
  "conditions": [
    { "field": "type", "operator": "equals", "value": "file_read" },
    { "field": "path", "operator": "regex", "value": "(^|/)\\.env(\\..*)?$" }
  ],
  "effect": "DENY"
}

Require approval for destructive shell commands

{
  "id": "approve-destructive-commands",
  "name": "Require approval for rm commands",
  "conditions": [
    { "field": "type", "operator": "equals", "value": "shell_exec" },
    { "field": "command", "operator": "contains", "value": "rm " }
  ],
  "effect": "REQUIRE_APPROVAL"
}

Allow network access to specific API domains

{
  "id": "allow-github-api",
  "name": "Allow GitHub API access",
  "conditions": [
    { "field": "type", "operator": "equals", "value": "network" },
    { "field": "url", "operator": "regex", "value": "^https://api\\.github\\.com/.*" }
  ],
  "effect": "ALLOW"
}

Deny shell execution of package install commands for untrusted agents

{
  "id": "deny-untrusted-installs",
  "name": "Block package installs from untrusted agents",
  "conditions": [
    { "field": "type", "operator": "equals", "value": "shell_exec" },
    { "field": "command", "operator": "regex", "value": "^(npm|pip|apt|brew)\\s+install" },
    { "field": "agent", "operator": "starts_with", "value": "untrusted-" }
  ],
  "effect": "DENY"
}

Rule Ordering and Priority

Rules are evaluated in the order they appear in the policy file. The first-match-wins algorithm means:

1. More specific rules should appear before more general rules
2. DENY rules for dangerous operations should appear early
3. ALLOW rules for safe operations follow
4. The implicit deny-by-default catches everything else

Rule 1: DENY  — Block .env reads (specific, high priority)
Rule 2: DENY  — Block /etc/ writes (specific, high priority)
Rule 3: ALLOW — Allow project directory writes (general allow)
Rule 4: ALLOW — Allow safe shell commands (general allow)
(implicit): DENY — Everything else denied by default

Policy Management

Policies are managed through the browser dashboard or the setup wizard (npx @authensor/safeclaw). The dashboard provides a visual rule editor with syntax validation, drag-and-drop reordering, and simulation mode for testing rules before enforcement.

Related References

• Policy Engine Architecture — Evaluation algorithm and performance
• Action Request Format — Fields available for condition matching
• Simulation Mode Reference — Testing rules before enforcement
• Security Model Reference — Deny-by-default rationale
• Dashboard and API Reference — Visual policy editor