prempti-falco-rules

Prempti Falco Rules Author

Write custom Falco rules that govern what AI coding agents can do at runtime. These rules intercept tool calls (shell commands, file writes/reads, MCP calls) and enforce allow/deny/ask verdicts before execution.

Context: How This System Works

Prempti intercepts every tool call a coding agent makes. Each call becomes a Falco event with structured fields. Your rules evaluate these events and decide the verdict:

• deny — block the tool call entirely (the agent sees an explanation)
• ask — prompt the user for confirmation (they see your output message directly)
• allow — no tag needed; tool calls that match no deny/ask rule are allowed

The agent sees the verdict reason as: "Rule Name: <your output message> | For AI Agents: ... | correlation=<id>". For deny verdicts, the LLM reformulates this for the user. For ask verdicts, the user reads your output message directly in a permission prompt — so write it for a human audience.

Available Fields

Every tool call event exposes these fields for conditions and output:

Path fields come in raw/real pairs. Use real_* for policy matching (resolved, absolute). Use raw fields for display.

Rule Structure

Every rule needs these fields:

- rule: <Human-readable name>
  desc: >
    <What this rule does and why>
  condition: >
    <Boolean expression using fields above>
  output: >
    <LLM-friendly message starting with "Falco">
  priority: <CRITICAL|WARNING|NOTICE|DEBUG>
  source: coding_agent
  tags: [<verdict tag>]

Tags (verdict)

All Falco priorities are valid: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFORMATIONAL (or INFO), DEBUG.

When multiple rules match the same event, verdicts escalate: deny > ask > {allow | defer}. The lowest tier is the no-rule-match floor (default_action: allow by default, or defer to defer to the agent's own permission system) — deny/ask rules are unaffected by it.

Output Convention

The output: field is the message the coding agent (or user) sees. Write it as a clear, self-contained sentence:

• Start with "Falco" to attribute the verdict
• Use %field to interpolate resolved values (e.g., %tool.real_file_path)
• Do NOT include structured key=value pairs — those are handled automatically by append_output
• For deny rules: write for an LLM audience (it will rephrase for the user)
• For ask rules: write for a human audience (they read it directly in the permission prompt)

# Good:
output: >
  Falco blocked running sudo because elevated privileges are not permitted

# Bad (structured fields leak into user-facing message):
output: >
  Denied | cmd=%tool.input_command correlation=%correlation.id

Condition Language Quick Reference

Operators

Transformers

Transformers can be chained: basename(tolower(tool.file_path)).

Without val(), the right-hand side is a literal string, not a field reference.

Lists and Macros

Lists define reusable sets of values. Macros define reusable condition fragments.

- list: my_blocked_commands
  items: [rm, mkfs, dd, fdisk]

- macro: is_blocked_command
  condition: >
    tool.input_command startswith "rm -rf"
    or tool.input_command startswith "mkfs"

- rule: Deny dangerous commands
  condition: >
    tool.name = "Bash"
    and is_blocked_command
  ...

Override and Append

The override key modifies existing rules, macros, and lists across files — essential for customizing defaults without editing them:

# In rules/user/my_overrides.yaml:

# Add paths to the default sensitive_paths list
- list: sensitive_paths
  items: [/opt/secrets/]
  override:
    items: append

# Add conditions to the default is_sensitive_path macro
- macro: is_sensitive_path
  condition: or tool.real_file_path contains "/.vault/"
  override:
    condition: append

# Disable an existing rule
- rule: Monitor activity outside working directory
  enabled: false
  override:
    enabled: replace

# Change a rule's priority
- rule: Ask before writing outside working directory
  priority: CRITICAL
  override:
    priority: replace

# Append an extra condition to an existing rule
- rule: Deny writing to sensitive paths
  condition: and not tool.real_file_path startswith "/etc/my-app/"
  override:
    condition: append

Appendable fields: condition, output, desc, tags, exceptions. Replaceable fields: all appendable fields plus priority, enabled.

Where to Put Rules

The Prempti rule layout has three locations:

• Default rules: rules/default/coding_agents_rules.yaml — shipped with the project, overwritten on upgrade
• User rules: rules/user/*.yaml — preserved across upgrades, this is where custom rules belong
• Seen rule: rules/seen.yaml — DO NOT modify, required for verdict resolution

These paths exist in two contexts:

Important constraint on the installed system: Prempti's self-protection rules block Write/Edit on any path under the install prefix while the service is running, and deny every premptictl invocation. The agent cannot directly install or apply a rule on a running Prempti — the user must perform the manual install workflow described in Applying Rules to a Running Prempti.

In the project repo, drafting into rules/user/ is fine because those paths aren't under the install prefix.

Before writing a new rule, read rules/default/coding_agents_rules.yaml to check for overlaps. The default ruleset is organized into seven sections covering common AI-agent attack surfaces:

1. Working-directory boundary — monitor / ask on file access outside the session cwd
2. Sensitive paths — deny reads and writes to /etc/, ~/.ssh/, ~/.aws/, .env files, etc.
3. Sandbox disable — Claude Code / Codex / Gemini CLI sandbox-disable attempts (Write, Edit, and Bash variants)
4. Threats — credential access, destructive shell commands, pipe-to-shell, encoded payloads, curl/wget exfiltration, IMDS access, credential archives, SSH covert tunnels, cron persistence, history wipe, package publish, shell startup files, agent instruction files outside cwd, cross-agent auth file reads, MCP installs from untrusted hosts, MCP execution from temp dirs, credential glob patterns
5. MCP and skill content — MCP config poisoning (.mcp.json), slash-command and skill file injection (.claude/commands/, .claude/skills/), Claude Code subagent and plugin storage (.claude/agents/, .claude/plugins/), settings backups (.claude/backups/)
6. Persistence vectors — settings hooks, settings-level mcpServers, git hooks, package registry redirects, .env API base-URL overrides, AI API keys in env files
7. Self-protection — block agent attempts to disable Prempti: every premptictl invocation, platform service-stop alternatives (systemctl / launchctl / taskkill / pkill), writes under the install prefix, and writes to Claude Code config files (~/.claude/settings.json, policy-limits.json)

The file also exposes reusable lists (sensitive_paths, sensitive_file_names, shell_startup_files, agent_instruction_files, env_file_names, registry_config_files) and macros (is_sensitive_path, is_outside_cwd, is_claude_data_path, is_write_tool, contains_ioc_domain, cmd_contains_ioc_domain) that user rules can extend via override: append.

If the user's request overlaps with an existing rule, prefer extending it via override: append rather than creating a duplicate. If the new rule is more restrictive (e.g., deny where the default only asks), explain the interaction to the user.

Applying Rules to a Running Prempti

The agent cannot install or apply a rule on a running Prempti by itself. Two self-protection rules make this a user-driven operation:

• Deny writes under Prempti install prefix blocks Write/Edit on any path under ~/.prempti/ (or %LOCALAPPDATA%\prempti\ on Windows), including rules/user/.
• Deny premptictl invocation blocks every agent-invoked premptictl command — even read-only ones like status, health, logs.

This is by design: the agent is the threat model the rules defend against, so it cannot be trusted to author and load its own policy.

Workflow

1. Draft the rule to a path the agent can write to — typically the current working directory (./<rule-name>.yaml), the project repo's rules/user/ if the user is contributing back, or a scratch location like /tmp/<rule-name>.yaml. Do not attempt to write directly into ~/.prempti/rules/user/ — Prempti will deny it.
2. Validate the draft with Falco (see Validation). Validation works on any path; the rule does not need to be installed.
3. Hand the install steps to the user. The agent cannot run these — the user copies and runs them themselves. Substitute the actual draft path and a descriptive rule filename.

Linux / macOS

# 1. Stop Prempti — this unregisters the hook, so writes under ~/.prempti/ pass through
premptictl stop

# 2. Copy the validated rule into the user rules directory
cp <draft-path> ~/.prempti/rules/user/<rule-name>.yaml

# 3. Start Prempti — the new rule is loaded and the hook is re-registered
premptictl start

Windows (PowerShell)

# 1. Stop Prempti
premptictl stop

# 2. Copy the validated rule into the user rules directory
Copy-Item <draft-path> "$env:LOCALAPPDATA\prempti\rules\user\<rule-name>.yaml"

# 3. Start Prempti
premptictl start

4. Wait for the user to confirm premptictl start succeeded. The new rule is live only after start completes — between step 1 and step 3, Prempti's interception is off and tool calls pass through unmonitored, so the user knows this window exists.

Notes

• If the user prefers a single command, premptictl restart after the cp is equivalent to stop → re-add hook → start.
• Removing the rule later follows the same pattern: premptictl stop, rm ~/.prempti/rules/user/<name>.yaml, premptictl start.
• If the user is running Prempti in monitor mode (premptictl mode monitor), writes to the install prefix will still produce a deny alert in logs but tool calls succeed — the user can technically skip the stop/start, but the alert is noise and the canonical workflow above is preferred either way.

Validation

After writing a rule, always validate it with Falco. The validation step catches syntax errors, unknown fields, and malformed conditions before the rule goes live.

Finding the Falco binary

Check these locations in order. The "installed" locations are written by the platform packagers; the "development build" locations are produced by make falco-* and make download-falco-linux.

Linux / macOS

1. Installed binary (most common): ~/.prempti/bin/falco
2. System PATH: falco (if installed globally)
3. Development build: build/falco-*-<arch>/usr/bin/falco (Linux, downloaded) or build/falco-*-darwin-<arch>/falco (macOS, source)

Windows (PowerShell)

1. Installed binary: $env:LOCALAPPDATA\prempti\bin\falco.exe
2. System PATH: falco.exe (rare on Windows — PATH usually points to the installed bin dir via the post-install step)
3. Development build: build\falco-0.44.0-windows-<arch>\falco.exe (built via make falco-windows-x64 / falco-windows-arm64)

Running validation

Use the installed config so the plugin is loaded and all fields are recognized. Validate the draft file at whatever path it currently lives — validation does not require the rule to be installed under the Prempti prefix (and the agent cannot put it there until the user runs the manual install steps).

Linux / macOS

~/.prempti/bin/falco \
  -c ~/.prempti/config/falco.yaml \
  --disable-source syscall \
  -V <draft-path>      # e.g. ./my_rules.yaml or /tmp/my_rules.yaml

Windows (PowerShell)

& "$env:LOCALAPPDATA\prempti\bin\falco.exe" `
  -c "$env:LOCALAPPDATA\prempti\config\falco.yaml" `
  --disable-source syscall `
  -V <draft-path>

This validates:

• YAML syntax and rule structure
• Field names exist in the coding_agent source (catches typos like tool.command instead of tool.input_command)
• Condition expression syntax (operators, transformers, list/macro references)
• Output template field references

If validation passes, Falco exits 0. If it fails, the error message tells you exactly which rule and which field or expression has the problem.

Common Validation Errors

Warnings must also be fixed. If validation reports LOAD_UNUSED_MACRO or LOAD_UNUSED_LIST, remove the unused macro or list from the file. Do not ship rules with unused definitions.

If Falco is not available

If neither the installed binary nor a development build is found, validate manually:

• source: coding_agent is set
• Field names match the table above exactly
• val() is used for field-to-field comparisons
• Tags are one of coding_agent_deny, coding_agent_ask, or empty []
• Output starts with "Falco"

Flag to the user that the rule was not machine-validated.

Common Mistakes

Examples

Deny: block destructive shell commands

- rule: Deny destructive shell commands
  desc: >
    Blocks rm -rf, mkfs, dd, and other destructive commands that could
    cause irreversible damage to the filesystem.
  condition: >
    tool.name = "Bash"
    and (tool.input_command contains "rm -rf"
         or tool.input_command startswith "mkfs"
         or tool.input_command startswith "dd ")
  output: >
    Falco blocked a destructive command (%tool.input_command)
  priority: CRITICAL
  source: coding_agent
  tags: [coding_agent_deny]

Ask: confirm before running network commands

- rule: Ask before network commands
  desc: >
    Requires user confirmation before the agent runs curl, wget, or
    similar network tools that could exfiltrate data.
  condition: >
    tool.name = "Bash"
    and (tool.input_command startswith "curl "
         or tool.input_command startswith "wget "
         or tool.input_command contains "| curl"
         or tool.input_command contains "| wget")
  output: >
    Falco requires confirmation for a network command (%tool.input_command)
  priority: WARNING
  source: coding_agent
  tags: [coding_agent_ask]

Deny: prevent writing outside a project boundary

- list: allowed_write_prefixes
  items:
    - /home/user/myproject/

- rule: Deny writes outside project
  desc: >
    Restricts file writes to a specific project directory.
  condition: >
    tool.name in ("Write", "Edit")
    and tool.real_file_path != ""
    and not tool.real_file_path pmatch (allowed_write_prefixes)
  output: >
    Falco blocked writing to %tool.real_file_path because it is outside the allowed project directory
  priority: CRITICAL
  source: coding_agent
  tags: [coding_agent_deny]

Common Patterns

Match Bash commands by prefix (safer than contains — avoids matching substrings):

condition: tool.name = "Bash" and tool.input_command startswith "sudo "

Match files by name regardless of directory (use real_file_path so basename() works on Windows too):

condition: basename(tool.real_file_path) = "Dockerfile"

Match files inside the working directory (use val() for field comparison):

condition: tool.real_file_path startswith val(agent.real_cwd)

Match files by extension (use endswith):

condition: tool.real_file_path endswith ".key" or tool.real_file_path endswith ".pem"

Combine multiple tools:

condition: tool.name in ("Write", "Edit", "Read") and ...