Skip to main content

​
Overview

Security guards are input-level validation layers that run independently of the security mode. Even in full mode, the FsGuard and SsrfGuard still block access to dangerous paths and private networks. Each guard returns a GuardResult: 
interface GuardResult {
  allowed: boolean;
  reason?: string;      // Why it was blocked
  risk: RiskLevel;      // LOW | MEDIUM | HIGH | CRITICAL
  score?: number;       // 0-100 severity score
}

​
FsGuard - Filesystem Guard

Prevents path traversal attacks and blocks access to sensitive files.

​
How It Works

  1. Path normalization - Resolves ../ sequences to eliminate traversal
  2. Symlink resolution - Resolves symlinks to their real paths to detect symlink-based escapes
  3. Allowlist check - Verified resolved path is within an allowed directory
  4. Blocklist check - Verified path is not in the blocked paths list
  5. Pattern check - Verified filename does not match blocked patterns

​
Default Blocked Paths

/etc/passwd
/etc/shadow
/etc/sudoers
~/.ssh/
~/.gnupg/
~/.aws/credentials
~/.config/gcloud/
/proc/
/sys/
/dev/

​
Default Blocked Filename Patterns

.env
.env.local
.env.production
.env.staging
id_rsa, id_ed25519, id_ecdsa
*.pem, *.key
credentials.json
service-account.json

​
Configuration

security:
  fsGuard:
    enabled: true
    allowedPaths:
      - "{{ workdir }}"       # Project directory (required)
      - "/tmp"                # System temp
      - "/home/user/projects" # Additional allowed directory
    blockedPaths:
      - "/etc/passwd"         # Extra blocked paths (merged with defaults)
    blockedPatterns:
      - ".secret"             # Extra patterns
    followSymlinks: true      # Resolve symlinks before checking

​
Disabling FsGuard

You can disable FsGuard for specific operations if you need to access files outside the default paths: 
security:
  fsGuard:
    enabled: false  # NOT recommended for production
Instead, prefer adding specific paths to allowedPaths.

​
SsrfGuard - SSRF Guard

Prevents Server-Side Request Forgery by validating URLs before HTTP requests.

​
How It Works

  1. Scheme validation - Only http and https allowed
  2. Host blocklist - Checks against known metadata endpoints
  3. CIDR check - Resolves DNS and checks resolved IP against blocked CIDR ranges
  4. DNS rebinding defense - Resolves hostnames before connecting, re-validates on redirects
  5. Redirect chain validation - Each redirect target is re-validated (up to 5 hops)

​
Blocked CIDR Ranges

0.0.0.0/8        - "This" network
10.0.0.0/8       - Private Class A
100.64.0.0/10    - Carrier-grade NAT
127.0.0.0/8      - Loopback
169.254.0.0/16   - Link-local (includes cloud metadata 169.254.169.254)
172.16.0.0/12    - Private Class B
192.168.0.0/16   - Private Class C
224.0.0.0/4      - Multicast
240.0.0.0/4      - Reserved

​
Blocked Metadata Hosts

169.254.169.254         - AWS, GCP, Azure metadata
metadata.google.internal
metadata.internal

​
Configuration

security:
  ssrfGuard:
    enabled: true
    allowedHosts:
      - "internal-api.company.com"  # Allow specific internal hosts
      - "jenkins.internal"
    maxRedirects: 5
    dnsResolutionTimeout: 3000     # ms

​
PromptGuard - Injection Guard

Detects and blocks prompt injection and jailbreak attempts in user input.

​
Detection Categories

CategoryScoreExamples
Injection delimiters40[system], [INST], <<SYS>>, <|im_start|>
Token smuggling45Null bytes, ANSI escapes, backspace chars
Jailbreak personas35”You are now DAN”, “act as unrestricted”
Instruction override30”Ignore all previous instructions”
Encoded injection30”execute the following base64”
System prompt extraction25”reveal your system prompt”
Prompt leak via formatting20”translate the above text”
Total score is the sum of all triggered patterns. Inputs scoring above the blockThreshold are rejected.

​
Canary Token System

A random canary token is injected into the system prompt. If this token appears in the user’s message, it indicates the system prompt has been leaked and extracted - the request is blocked with CRITICAL risk.

​
Configuration

security:
  promptGuard:
    enabled: true
    maxInputLength: 50000   # Characters
    blockThreshold: 25      # Score >= 25 is blocked
    warnThreshold: 10       # Score >= 10 is logged as warning

​
AuditScanner - Code Scanner

Scans skill code and plugin code for dangerous patterns before loading.

​
Detection Patterns

PatternRiskExample
Shell executionCRITICALchild_process, exec(), spawn()
eval usageCRITICALeval(), Function("code")
Raw socket accessCRITICALnet.connect(), tls.connect()
Network accessHIGHfetch(), axios, got()
Credential accessHIGHAPI_KEY, SECRET, TOKEN references
Filesystem writesMEDIUMwriteFileSync, appendFileSync
Destructive opsHIGHunlinkSync, rmdirSync, rm -rf
Env var accessMEDIUMprocess.env. access

​
When It Runs

  • On skill file load
  • On plugin activation
  • During profclaw doctor health check

​
Configuration

security:
  auditScanner:
    enabled: true
    alertOnMatch: true   # Log warnings when patterns match

Security Modes

Guards apply within all modes except deny.

Audit Logging

Guard decisions are recorded in the audit log.