Writing Your First Security Policy

You installed GuardClaw. You ran the security test. The detection engine is watching your agent. But right now it’s using the default rules. What if you need something different?

Maybe your agent needs to call a specific API that the default policy blocks. Maybe you want stricter controls on file system access. Maybe you need to allow one particular shell command while keeping everything else locked down.

That’s what policies are for.

GuardClaw policies are YAML files that define exactly what your agent can and can’t do. This post walks through how they work, what the defaults mean, and how to write your first custom policy.

How policies think

When your agent tries to do something — read a file, run a command, call an API — GuardClaw asks one question: is this action on the allow list?

If yes, it passes through. If no, it gets blocked. If the policy says “ask a human,” it pauses and waits for approval.

This is called deny-by-default. Nothing gets through unless you’ve said it’s okay. It’s the same principle behind fire doors in a building — everything is closed by default. You open specific doors for specific reasons.

The opposite approach — allow-by-default, where you list the things to block — is how most agent security works today. The problem is obvious: you have to predict every possible attack in advance. Miss one, and it gets through. GuardClaw inverts that.

The default policy

When you install GuardClaw, it ships with a default policy that balances security with usability. Here’s what it looks like conceptually:

• File system: Read access within the project directory. No writes to system files. No access outside the project boundary.
• Shell commands: Basic development commands allowed (git, npm, python, etc.). Dangerous patterns blocked (pipes to external URLs, encoded commands, process manipulation).
• Network: HTTPS allowed to known domains. No connections to private IP ranges. No unencrypted HTTP.
• MCP tools: Standard tool calls allowed. Blocked tool patterns (known dangerous MCP skills) rejected.

The defaults work for most development workflows. You won’t need to change them unless your agent needs access to something specific.

Creating a custom policy

Generate a starter policy file:

guardclaw init --target config

This creates a guardclaw.yaml file in your project. Open it in any text editor. The structure looks like this:

server:
  mode: http
  host: "127.0.0.1"
  port: 8082

storage:
  type: sqlite
  path: "./guardclaw.db"

executors:
  http:
    enabled: false
    allowed_domains: []
    require_https: true
    block_private_ips: true
  fs:
    enabled: false
    base_dir: ""
    allow_read: true
    allow_write: false
    allow_delete: false
  shell:
    enabled: false

Each section controls a different type of action your agent can take:

• executors.http controls network access. allowed_domains is the list of domains your agent can reach. If a domain isn’t on this list, the request gets blocked.
• executors.fs controls file system access. base_dir sets the boundary — your agent can’t access files outside this directory. allow_write and allow_delete are off by default.
• executors.shell controls shell command execution. Disabled by default. When enabled, commands still pass through the detection engine’s 1,000+ patterns.

Example: allowing a specific API

Say your agent needs to call your company’s internal API at api.yourcompany.com. In the default policy, this would be blocked because the domain isn’t on the allow list.

To allow it, update the http executor:

executors:
  http:
    enabled: true
    allowed_domains:
      - "api.yourcompany.com"
    require_https: true
    block_private_ips: true

Now your agent can reach api.yourcompany.com over HTTPS. Every other domain is still blocked. The require_https setting ensures no unencrypted traffic, and block_private_ips prevents the agent from reaching internal network addresses (a common server-side request forgery attack vector).

Example: restricting file access

If your agent should only work within a specific directory — say, the src/ folder of your project — set the file system boundary:

executors:
  fs:
    enabled: true
    base_dir: "/path/to/your/project/src"
    allow_read: true
    allow_write: true
    allow_delete: false

The agent can read and write files inside src/, but can’t delete anything and can’t access files outside that directory. If it tries to read ../../.env (a common path traversal attempt), GuardClaw blocks it.

The right way to adjust policies

Start strict. Watch the audit trail. Adjust based on what you see.

Here’s the pattern that works:

1. Start with defaults. Run your agent with GuardClaw’s default policy for a day or two.
2. Check the denials. Open your dashboard or run guardclaw sync and look at what got blocked.
3. Sort the denials. Some are legitimate threats GuardClaw caught. Some are legitimate actions your agent needs to do. The audit trail tells you which is which.
4. Allow what’s legitimate. For each denied action your agent actually needs, add it to your policy.
5. Keep the rest blocked. If you can’t explain why an action is needed, leave it denied.

This is the same process security teams use for firewall rules. You don’t start by opening everything and then trying to close the holes. You start closed and open only what’s needed.

Versioning your policies

Because policies are plain YAML files, you can version them with git just like your code. This gives you:

• History: who changed what, when, and why
• Review: policy changes go through pull requests, just like code changes
• Rollback: if a policy change breaks something, revert the commit

Store your guardclaw.yaml in your project repository. When you onboard a new team member, they get the same security policies as everyone else.

What to do next

After writing your first policy, run your agent with it and watch the audit trail. If you see denials you don’t expect, the trail tells you exactly which rule blocked which action. Adjust the policy and run again.

The next post covers setting up GuardClaw specifically for Claude Code — hooks, configuration, and what the integration looks like in practice.