Rules Reference

This page documents all 10 core HushSpec rules. For full normative semantics, see the core specification.

All rules share a common enabled field (boolean, default varies by rule). When enabled is false, the rule is inert and will not influence decisions. The rules object may contain up to ten named rule blocks. If rules is absent or empty, no rules are active.

1. forbidden_paths

Block access to sensitive filesystem paths using glob patterns. This is typically the first rule teams enable — it prevents agents from reading or writing credentials, SSH keys, cloud configuration, and other secrets stored on disk.

Semantics: A path is forbidden if and only if it matches at least one entry in patterns AND does not match any entry in exceptions. When patterns is empty, no paths are forbidden regardless of the enabled state.

Glob syntax: * matches any sequence within a path segment, ** matches any sequence of segments including separators, and ? matches any single character. Matching is case-sensitive on case-sensitive filesystems.

When to use: Nearly every policy should include this rule. Common patterns include blocking .env files, SSH keys, AWS/GCP credentials, and private key material. Use exceptions for safe variants like .env.example or .env.template.

rules:
  forbidden_paths:
    patterns:
      - "**/.ssh/**"
      - "**/.aws/**"
      - "**/.env"
      - "**/credentials*"
      - "**/*.pem"
    exceptions:
      - "**/.env.example"
      - "**/.env.template"

2. path_allowlist

Allowlist-based path access control. When enabled, only paths matching the allowlist are permitted for the specified operation type. This is the inverse of forbidden_paths — instead of blocking known-bad paths, it restricts the agent to known-good paths.

Semantics: When enabled, a file operation is allowed only if the target path matches at least one pattern in the corresponding array. If patch is empty, patch operations fall back to the write array. If the relevant array is empty and no fallback applies, all operations of that type are denied.

When to use: Use this rule in high-security environments where you want to confine an agent to a specific project directory. It is especially useful for sandboxed CI/CD pipelines or multi-tenant deployments where agents must not escape their workspace.

rules:
  path_allowlist:
    enabled: true
    read:
      - "/home/user/project/**"
      - "/usr/share/doc/**"
    write:
      - "/home/user/project/src/**"
      - "/home/user/project/tests/**"

3. egress

Network egress control by domain. This rule determines which external domains an agent is permitted to contact and which are blocked. It is critical for preventing data exfiltration and restricting agents to approved API endpoints.

Semantics: For a given target domain: (1) if it matches any entry in block, the decision is deny — block takes precedence over allow; (2) if it matches any entry in allow, the decision is allow; (3) otherwise, the default value applies.

Domain glob syntax: * matches any sequence of characters within a single domain label; ** matches across labels (e.g., **.example.com matches foo.bar.example.com). Port numbers are stripped before matching.

When to use: Production deployments should set default: "block" and explicitly allowlist required API endpoints. Development policies may use default: "allow" and only block known-bad domains. Always block domains associated with data exfiltration or unauthorized services.

rules:
  egress:
    allow:
      - "api.openai.com"
      - "*.anthropic.com"
      - "**.googleapis.com"
    block:
      - "**.pastebin.com"
      - "**.ngrok.io"
    default: "block"

4. secret_patterns

Detect secrets in content before it is written or transmitted. This rule scans output content against a set of named regular expressions and produces findings at configurable severity levels. It acts as a last line of defense against accidental credential leakage.

SecretPattern fields:

Severity levels:

• "critical" — Immediate deny. Used for high-confidence detections such as AWS access keys, private key material, or database connection strings with embedded passwords.
• "error" — Deny. Used for likely secrets such as generic API key patterns or bearer tokens.
• "warn" — Warning, requires confirmation. Used for lower-confidence patterns that may produce false positives, such as generic token-like strings.

Constraints: The name field must be unique within the patterns array — duplicate names cause document rejection. The pattern field must be a valid regular expression — invalid regexes cause document rejection (fail-closed). If the target path matches any skip_paths entry, scanning is bypassed.

When to use: Enable this rule in any policy where the agent can write files or send network requests. Start with patterns for your cloud provider's key formats, then add generic patterns for tokens and passwords.

rules:
  secret_patterns:
    patterns:
      - name: aws_access_key
        pattern: "AKIA[0-9A-Z]{16}"
        severity: critical
        description: "AWS access key ID"
      - name: private_key_header
        pattern: "-----BEGIN (RSA |EC )?PRIVATE KEY-----"
        severity: critical
        description: "PEM-encoded private key"
      - name: generic_api_key
        pattern: "(?i)(api[_-]?key|apikey)\\s*[=:]\\s*['\"]?[a-z0-9]{32,}"
        severity: error
      - name: generic_token
        pattern: "(?i)(token|secret|password)\\s*[=:]\\s*['\"]?[a-z0-9]{20,}"
        severity: warn
    skip_paths:
      - "**/test/fixtures/**"
      - "**/*.test.*"

5. patch_integrity

Validate the safety and reasonableness of patch/diff content. This rule limits patch size, enforces balance between additions and deletions, and blocks patches containing dangerous code patterns. It guards against large-scale code injection or mass deletion by a compromised agent.

Semantics: A patch is denied if any of the following conditions are met:

1. The number of added lines exceeds max_additions, OR
2. The number of deleted lines exceeds max_deletions, OR
3. Any line in the patch matches a forbidden_patterns entry, OR
4. require_balance is true AND the ratio of additions to deletions (or deletions to additions, whichever is larger) exceeds max_imbalance_ratio. When either count is zero and the other is nonzero and require_balance is true, the patch is denied.

Constraints: max_additions and max_deletions must be non-negative integers. max_imbalance_ratio must be a positive number (strictly greater than zero).

When to use: The defaults (max_additions: 1000, max_deletions: 500, max_imbalance_ratio: 10.0) are reasonable for most agent workflows. Tighten these limits for security-sensitive codebases. Use forbidden_patterns to block injection of eval(), exec(), system(), or other dangerous constructs in patches.

rules:
  patch_integrity:
    max_additions: 500
    max_deletions: 200
    require_balance: true
    max_imbalance_ratio: 5.0
    forbidden_patterns:
      - "eval\\("
      - "exec\\("
      - "__import__\\("

6. shell_commands

Block dangerous shell commands before execution. This rule matches regex patterns against the complete command string, including arguments and pipes. It prevents agents from running destructive operations, downloading and executing remote code, or escalating privileges.

Semantics: A shell command is denied if any portion of the command string matches any forbidden_patterns entry. Matching is performed against the complete command string as provided to the engine, including arguments and pipes. Empty forbidden_patterns means no commands are blocked by this rule.

When to use: Enable this rule whenever agents have shell access. Common patterns to block include recursive force-delete (rm -rf /), piped downloads (curl | sh), permission escalation (chmod 777), and package installation with arbitrary sources.

rules:
  shell_commands:
    forbidden_patterns:
      - "rm\\s+-rf\\s+/"
      - "curl.*\\|.*sh"
      - "wget.*\\|.*bash"
      - "chmod\\s+777"
      - "sudo\\s+su"

7. tool_access

Control tool and MCP (Model Context Protocol) invocations. This rule provides fine-grained access control for agent tool calls, supporting allowlists, blocklists, confirmation requirements, and argument size limits. It is the primary mechanism for restricting what an agent can do.

Evaluation order:

1. If the tool name matches any entry in block, the decision is deny. Block takes precedence.
2. If require_confirmation is non-empty and the tool name matches, the decision is warn (requires confirmation).
3. If allow is non-empty and the tool name matches, the decision is allow.
4. If allow is non-empty and the tool name does NOT match, the decision is deny (allowlist mode).
5. Otherwise, the default value applies.

Tool names are matched as exact strings — glob or regex matching is not supported. If max_args_size is specified and the serialized argument payload exceeds this size, the invocation is denied regardless of other rules.

When to use: For agents with many available tools, use the blocklist approach with default: "allow" to block known-dangerous tools. For high-security environments, use the allowlist approach with default: "block" and explicitly list only approved tools. Use require_confirmation for operations like deployment and database writes that need human review.

rules:
  tool_access:
    block:
      - dangerous_tool
      - shell_exec
    require_confirmation:
      - deploy
      - database_write
      - send_email
    default: "allow"
    max_args_size: 65536

8. computer_use

Control computer use agent (CUA) actions in remote desktop and browser automation contexts. This rule governs what actions an autonomous agent can perform when operating a graphical desktop, browser, or remote session. It supports three distinct enforcement modes.

The three modes:

• "observe" — Log all actions but do not block. Decisions are allow with audit. Use this mode during initial rollout to understand what actions agents are performing before enforcing restrictions.
• "guardrail" — Block actions not in allowed_actions. Actions in the list are allowed; others are denied. Engines may apply heuristics or additional context to borderline cases. This is the recommended starting mode for production.
• "fail_closed" — Deny all actions unless explicitly listed in allowed_actions. No heuristic leniency — anything not explicitly listed is denied. Use this in high-security environments such as financial services or healthcare.

Action identifiers are engine-defined strings (e.g., "remote.session.connect", "input.inject", "clipboard.read"). The specification does not mandate a fixed set of action identifiers.

rules:
  computer_use:
    enabled: true
    mode: "guardrail"
    allowed_actions:
      - "remote.session.connect"
      - "clipboard.read"
      - "screenshot.capture"

9. remote_desktop_channels

Control side-channel capabilities in remote desktop sessions. This rule manages the data pathways available during remote desktop connections, preventing unauthorized data movement through clipboard sharing, file transfer, drive mapping, and other side channels.

Semantics: When enabled, each boolean field controls whether the corresponding side channel is permitted. A value of false means the channel must be blocked; a value of true means the channel is permitted. Engines that do not support a particular channel should ignore the corresponding field.

When to use: Enable this rule whenever agents interact with remote desktop sessions. The defaults are secure — only audio is permitted. Enable clipboard and file transfer only when the agent workflow specifically requires them. Drive mapping should remain disabled in most environments due to the risk of lateral data movement.

rules:
  remote_desktop_channels:
    enabled: true
    clipboard: false
    file_transfer: false
    audio: true
    drive_mapping: false

10. input_injection

Control input injection capabilities in computer use agent environments. This rule governs what types of simulated user input an agent can inject into a desktop or browser session, and optionally requires verification that injected input produced the expected effect.

Semantics: When enabled, only input injection types listed in allowed_types are permitted. If allowed_types is empty, all input injection is denied (fail-closed). Standard type identifiers include "keyboard", "mouse", and "touch", but engines may define additional types.

require_postcondition_probe: When set to true, the engine must verify that the injected input produced the expected effect before proceeding. For example, after injecting a keyboard shortcut to open a file dialog, the engine would verify that the dialog actually appeared. The mechanism for postcondition verification is engine-specific. This is a safety measure for critical workflows where incorrect input could cause damage.

When to use: Enable this rule when agents automate GUI interactions. Restrict allowed_types to only the input methods the agent needs. Enable require_postcondition_probe for workflows involving sensitive applications (e.g., financial trading platforms, admin consoles) where an incorrect click or keystroke could have significant consequences.

rules:
  input_injection:
    enabled: true
    allowed_types:
      - "keyboard"
      - "mouse"
    require_postcondition_probe: true