# How PAI Security Hook System Validates Commands Before Execution

> Discover how PAI's security hook system validates commands, using regex patterns to block dangerous operations before they execute and protecting your OS.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: how-to-guide
- Published: 2026-02-16

---

**PAI's `SecurityValidator` hook intercepts every tool request before execution, matches it against user-defined regex patterns in [`patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/patterns.yaml), and returns a block or allow decision to prevent dangerous operations from reaching the OS.**

The PAI (Personal AI Infrastructure) security hook system acts as a critical gatekeeper within the `danielmiessler/Personal_AI_Infrastructure` repository. When Claude requests a Bash command, file edit, write, or read operation, the system validates the payload against configurable security patterns before any external process spawns. This Pre-ToolUse architecture ensures that destructive or sensitive operations are caught at the application layer.

## Architecture of the PAI Security Hook System

The validation system centers on a TypeScript hook implementation that registers four specific tool matchers and resolves security rules from YAML configuration files.

### The Pre-ToolUse Hook Registration

The core validation logic lives in [`.claude/hooks/SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/.claude/hooks/SecurityValidator.hook.ts). During initialization, the Claude runtime registers this file as a **PreToolUse** hook for four specific matchers: **Bash**, **Edit**, **Write**, and **Read**. This registration ensures that every request targeting these tool types triggers the security validation pipeline before execution proceeds.

### Pattern Resolution and Loading

The hook implements a cascading file resolution strategy to locate security rules:

1. **Primary source**: [`skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml) (user-defined custom rules)
2. **Fallback source**: [`skills/PAI/PAISECURITYSYSTEM/patterns.example.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/PAISECURITYSYSTEM/patterns.example.yaml) (bundled default patterns)

If the user-specific file does not exist, the system automatically falls back to the example patterns bundled with the repository. Each entry in these YAML files contains a regular expression string describing disallowed commands, file paths, or content patterns.

## How the Security Validation Process Works

When a model requests a tool operation, the `SecurityValidator` executes a six-step validation pipeline:

**Step 1: Payload Stringification**

The incoming command payload is converted to a string representation suitable for regex matching.

**Step 2: Tool-Specific Matching**

The hook runs **four separate matchers**—one for each tool type. A Bash command is evaluated only by the Bash matcher, a file write only by the Write matcher, etc. This separation prevents cross-tool pattern leakage and improves performance.

**Step 3: Regex Pattern Testing**

The stringified payload is tested against every regex rule loaded from [`patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/patterns.yaml). The system checks for dangerous patterns such as `rm -rf /`, `.*password.*`, or `.*\.ssh/id_rsa$`.

**Step 4: Decision Rendering**

If any pattern matches, the hook returns a block decision:

```json
{
  "decision": "block",
  "reason": "Matched pattern: ^rm\\s+-rf\\s+.*$"
}

```

If no patterns match, the hook returns:

```json
{
  "decision": "allow"
}

```

**Step 5: Runtime Enforcement**

The Claude runtime respects this response and either aborts the operation (for blocks) or proceeds with execution (for allows).

**Step 6: Context Extension (Future)**

The architecture supports an `additionalContext` field for future versions, allowing the hook to inject warning messages that Claude can reason about before finalizing the block decision.

## Configuring Custom Security Patterns

Users define custom security rules by creating or editing the user-specific pattern file. The system uses standard YAML list syntax with regex strings:

```yaml

# ~/.claude/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml

# Block any use of curl to external URLs

- "^curl\\s+https?://.*$"

# Block attempts to read SSH private keys

- ".*\\.ssh/id_rsa$"

# Disallow git push to public repositories

- "^git\\s+push\\s+origin\\s+.*$"

```

After saving changes, the next tool request automatically validates against these updated patterns without requiring a restart.

## Testing the Security Hook Manually

Developers can validate the hook logic directly using the TypeScript runtime:

```bash

# Test a blocked command

bun ~/.claude/hooks/SecurityValidator.hook.ts <<EOF
{
  "type": "Bash",
  "command": "rm -rf /tmp/important"
}
EOF

```

Expected output for a blocked command:

```json
{
  "decision": "block",
  "reason": "Matched pattern: ^rm\\s+-rf\\s+.*$"
}

```

Testing an allowed command:

```bash
bun ~/.claude/hooks/SecurityValidator.hook.ts <<EOF
{
  "type": "Bash",
  "command": "echo hello"
}
EOF

```

Expected output:

```json
{
  "decision": "allow"
}

```

## Summary

- **PAI's security hook system** uses a Pre-ToolUse architecture to intercept commands before OS execution via [`SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SecurityValidator.hook.ts).
- **Four specialized matchers** handle Bash, Edit, Write, and Read operations independently, ensuring tool-specific validation.
- **Pattern resolution** cascades from user-defined [`skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml) to bundled example patterns.
- **Regex-based blocking** returns structured JSON decisions (`allow` or `block` with reason) that the Claude runtime enforces automatically.
- **Manual testing** is supported via direct TypeScript execution with `bun` for development and debugging.

## Frequently Asked Questions

### What happens when a command matches a security pattern in PAI?

When a command matches a security pattern, the [`SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SecurityValidator.hook.ts) returns a JSON object with `"decision": "block"` and a specific reason string indicating which regex pattern was matched. The Claude runtime receives this response and aborts the tool execution before any external process spawns, preventing the dangerous operation from reaching the operating system.

### Can I customize the security patterns in PAI?

Yes, you can customize security patterns by creating or editing [`skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml) in your PAI installation. This user-specific file takes precedence over the bundled [`patterns.example.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/patterns.example.yaml). You define custom rules as YAML list items containing regular expressions that match disallowed commands, file paths, or content patterns. Changes take effect immediately without requiring a restart.

### Which tool types does the PAI security hook monitor?

The PAI security hook monitors four specific tool types through dedicated matchers: **Bash** (shell commands), **Edit** (file modifications), **Write** (file creation/overwriting), and **Read** (file reading). Each tool type has its own matcher in [`SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SecurityValidator.hook.ts), ensuring that regex patterns are evaluated only against relevant command contexts rather than all tool requests indiscriminately.

### Where are the default security patterns stored in PAI?

The default security patterns are stored in [`skills/PAI/PAISECURITYSYSTEM/patterns.example.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/PAISECURITYSYSTEM/patterns.example.yaml) within the PAI repository structure. This file serves as a fallback when the user-specific [`skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml) does not exist. The example file contains bundled regex patterns for common dangerous operations, providing baseline protection immediately after installation.