falcosecurity/prempti/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 path policy matching (resolved, absolute). Use raw fields for display. For policies based on a file name, match tool.file_name or basename(tool.real_file_path) so both sensitive symlink aliases and sensitive canonical targets are covered.

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.real_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: