Rule Syntax Reference
SigmaShake rules use a declarative DSL designed for readability and safety. Each rule defines a condition that matches tool calls and a decision to apply.
Basic structure
rule <rule_id> {
enabled true
priority <number>
severity <error|warning|info>
<DECISION> <target>
IF <condition>
MESSAGE "<text>"
[CONTEXT "<text>"]
[RUN "<command>"]
[WEBHOOK "<url>"]
}
Minimal example
rule no-rm-rf {
enabled true
DENY execution
IF command CONTAINS "rm -rf"
MESSAGE "Destructive command blocked."
}
Default values when omitted:
priority→50severity→warningenabled→true
Rule ID
Must be a valid identifier: letters, numbers, hyphens, underscores. Used in audit logs and API responses.
rule my-rule-123 { ... }
rule ts_write_safety { ... }
Decision types
| DSL Keyword | Runtime Decision | Behavior |
|---|---|---|
DENY | block | Reject the tool call |
ALLOW | allow | Permit explicitly (overrides lower-priority DENY) |
LOG | log | Allow but record in audit log |
SHADOW | shadow | Allow silently, log for monitoring |
ASK | ask | Pause execution, require human approval via dashboard |
FORCE | force | Refuse the original risky action and return a safe substitute or required safer path |
Not every rule has a decision. Ambient knowledge rules carry standing project context and never gate a tool call, so they omit the decision keyword entirely —
AMBIENTis a rule directive, not a seventh decision type. See Ambient knowledge rules below.
ASK decisions
Require a PROMPT field:
rule ask-before-reset {
enabled true
ASK execution
IF command CONTAINS "git reset --hard"
MESSAGE "Hard reset requires approval."
PROMPT "Allow git reset --hard?"
}
FORCE decisions
Require a SUBSTITUTE field:
rule force-exact-pins {
enabled true
FORCE execution
IF command REGEX "npm install\\s+\\S+@\\^"
MESSAGE "Use exact version pins."
SUBSTITUTE "npm install [email protected]"
}
CONTEXT — surface text to the AI
CONTEXT "<text>" is an optional directive that injects text into the AI's view when the rule matches. It is orthogonal to the decision — combinable with ALLOW, LOG, SHADOW, BLOCK (DENY), ASK, and FORCE.
Use it to drop a reminder, hint, or runbook link without blocking the tool call:
rule remind-elixir-tests {
enabled true
ALLOW execution
IF command CONTAINS "mix test"
MESSAGE "Heads up."
CONTEXT "OTP 28 hangs mix test on this box. Use `mix help test.<alias>` instead."
}
When the rule fires, Claude Code receives the text and prepends it to the tool result the model sees on the next turn — so the AI can adjust without the user having to intervene.
How it reaches the AI by decision
| Decision | Wire format |
|---|---|
ALLOW, LOG, SHADOW | Emitted as Claude Code hookSpecificOutput.additionalContext (PreToolUse). Tool runs; AI sees the context with the result. |
DENY (block) / FORCE | Appended to the stderr refusal message. Claude Code surfaces stderr to the model on exit-code 2; FORCE includes the safe substitute path. |
ASK | Emitted alongside permissionDecisionReason as additionalContext in the same hookSpecificOutput JSON — the user sees the reason in the approval dialog, the AI sees the context once the call resumes. |
When to use CONTEXT vs. MESSAGE
MESSAGEis for humans — shown in dashboards, audit logs, and the approval prompt.CONTEXTis for the AI — fed back into the model's reasoning loop so it changes its next action.
They are complementary; most rules will set both.
Constraints
- Empty strings are rejected at parse time (
CONTEXT ""→ parse error). - One
CONTEXTper rule; last write wins if duplicated. - Survives
auditandsoftruntime modes (it never enforces, so it never needs to be downgraded).
Ambient knowledge rules
An ambient rule carries always-on project knowledge instead of gating a tool call. It has no decision and no IF/OR conditions — it is never evaluated against tool calls. Instead, its MESSAGE + CONTEXT are surfaced to the agent at session start by ssg hook session-start. This is the SSG-native equivalent of an AI-agent memory file.
Mark a rule ambient with the standalone AMBIENT directive:
rule mem_otp28_mix_test_hang {
priority 80
severity warning
AMBIENT
MESSAGE "OTP 28 silently hangs `mix test` on this box."
CONTEXT "The erl_child_setup bug hangs the test wrapper on 64+ core machines. Verify changes with `mix compile` or `mix help test.<alias>` instead — the main agent runs `mix test` synchronously when asked."
}
Fields
| Field | Required | Purpose |
|---|---|---|
AMBIENT | yes | Marks the rule as a knowledge carrier. Takes no decision keyword. |
MESSAGE | yes | One-line headline. Shown in the session-start index. |
CONTEXT | yes | The knowledge body. Pulled on demand via ssg recall. |
priority | no | Higher = listed first at session start. Default 50. |
severity | no | Informational label only (error/warning/info). Default warning. |
An ambient rule takes no <DECISION>, no target, and no IF/AND/OR conditions — only the metadata above.
Session start and recall
At session start, ssg hook session-start emits a compact index of every ambient rule — one MESSAGE headline per entry, grouped by area — rather than dumping every CONTEXT body, keeping the injected context small.
Pull the full CONTEXT for any entry on demand:
ssg recall <keyword-or-id> # full MESSAGE + CONTEXT for matching entries
ssg recall # reprint the headline index
Ambient rule vs. CONTEXT on a gating rule
Both surface text to the AI, but at different times and for different reasons:
| Ambient rule | CONTEXT on a gating rule | |
|---|---|---|
| When | Session start, always | When the rule matches a tool call |
| Trigger | None — unconditional | The rule's IF conditions |
| Decision | None | ALLOW / LOG / DENY / ASK / FORCE / SHADOW |
| Use for | Standing project knowledge | A just-in-time hint tied to a specific action |
Where ambient rules live
By convention, ambient knowledge lives in mem_*.rules files under .sigmashake/rules/. The ambient flag is a file-level field — like RUN and WEBHOOK, it is not persisted to the rules database, and loadRulesFromFiles excludes ambient rules from the evaluator's active set so they never participate in tool-call decisions.
In the dashboard, ambient rules appear on the Rules page with a teal AMBIENT badge in place of the decision selector — a visual reminder that they carry no verdict.
Triggers (optional)
Any rule can include RUN and/or WEBHOOK lines that fire asynchronously when the rule matches. Triggers are fire-and-forget — failures log to stderr but never block eval output.
RUN — execute a script
rule block-and-notify {
enabled true
DENY execution
IF command CONTAINS "rm -rf"
MESSAGE "Destructive command blocked."
RUN "./scripts/on-block.sh"
}
The script receives a JSON payload on stdin:
{
"tool": "Bash",
"input": {"command": "rm -rf /"},
"rule_id": "block-and-notify",
"decision": "block",
"matched_pattern": "command CONTAINS \"rm -rf\""
}
WEBHOOK — send an HTTP POST
rule audit-network {
enabled true
LOG network
IF tool EQUALS "WebFetch"
MESSAGE "Network request logged."
WEBHOOK "https://hooks.slack.com/services/T00/B00/xxx"
}
The webhook receives the same JSON payload as the POST body (Content-Type: application/json). Timeout is 5 seconds.
Combining triggers with any decision
Triggers work with all decision types — DENY, ALLOW, LOG, SHADOW, ASK, FORCE. You can use both RUN and WEBHOOK on the same rule:
rule full-trigger {
enabled true
DENY execution
IF command CONTAINS "drop table"
MESSAGE "SQL drop blocked."
RUN "./scripts/alert.sh"
WEBHOOK "https://example.com/audit"
}
Targets
Targets determine which tool capability a rule applies to:
| Target | Matches tools with capability |
|---|---|
execution | Shell commands (Bash, terminal) |
read | File reading (Read, cat) |
write | File writing/editing (Write, Edit) |
edit | Edit only (subset of write) |
search | File/content search (Glob, Grep) |
agent | Sub-agent spawning (Agent) |
network | HTTP requests (WebFetch, WebSearch) |
any | All tools |
Conditions
Syntax
IF <field> [NOT] <operator> "<value>"
Fields
| Field | Resolves to |
|---|---|
command | input.command (Bash commands) |
path | input.file_path or input.path |
content | input.content or input.new_string |
tool | Tool name (e.g., "Bash", "Read") |
input.<key> | Any key in the tool input object |
Operators
| Operator | Description |
|---|---|
CONTAINS | Substring match |
EQUALS | Exact string match |
STARTS_WITH | Prefix match |
ENDS_WITH | Suffix match |
GLOB | Glob pattern (*, **, ?) |
REGEX | Regular expression |
WORD | Word-boundary match (no regex, O(n)) |
LINE_CONTAINS | Per-line substring, strips // comments |
LINE_REGEX | Per-line regex, strips // comments |
LENGTH_GT | UTF-8 byte length strictly greater than N |
LENGTH_LT | UTF-8 byte length strictly less than N |
TOKENS_GT | Estimated tokens (byte-length / 4) strictly greater than N |
TOKENS_LT | Estimated tokens (byte-length / 4) strictly less than N |
All operators support NOT for negation:
IF command NOT CONTAINS "echo"
AND / OR logic
Within a block, conditions are AND-ed. Use OR to start a new group:
rule block-secret-writes {
enabled true
DENY write
IF path ENDS_WITH ".env"
AND content CONTAINS "API_KEY"
OR path ENDS_WITH ".env.local"
AND content CONTAINS "SECRET"
MESSAGE "Cannot write secrets to env files."
}
This means: (path ends with .env AND content contains API_KEY) OR (path ends with .env.local AND content contains SECRET).
Priority
Higher priority rules are evaluated first. First match wins (short-circuit).
rule allow-echo {
enabled true
priority 100
ALLOW execution
IF command STARTS_WITH "echo"
MESSAGE "Echo commands are always allowed."
}
rule block-all-bash {
enabled true
priority 50
DENY execution
IF tool EQUALS "Bash"
MESSAGE "Bash commands require approval."
}
With priority 100 > 50, echo hello matches allow-echo first and is allowed.
Generic input fields
Access any key in the tool input object using input.<key>:
rule log-explore-agents {
enabled true
LOG agent
IF input.subagent_type EQUALS "Explore"
MESSAGE "Explore agent activity logged."
}
rule block-background-agents {
enabled true
DENY agent
IF input.run_in_background EQUALS "true"
AND input.subagent_type NOT EQUALS "general-purpose"
MESSAGE "Only general-purpose agents may run in background."
}
Non-string values are JSON-stringified before matching. Missing fields resolve to empty string (no match for positive conditions).
Enabling/disabling
rule temporarily-disabled {
enabled false
DENY execution
IF command CONTAINS "test"
MESSAGE "This rule is off."
}
Metadata directives
CATEGORY
CATEGORY <id> attaches a single security category identifier to a rule. Categories are used by the dashboard, the hub ATT&CK matrix, and the Sleep at Night feature (which verifies 10-category coverage). The value is free-form text; the recognized category identifiers are:
destructive-ops privilege-escalation code-execution
credential-access network-egress supply-chain
process-control version-control source-integrity
data-handling
rule guard-secrets {
enabled true
priority 90
severity error
CATEGORY credential-access
DENY write
IF path ENDS_WITH ".env"
MESSAGE "Credential file write blocked."
}
CATEGORY is optional. Rules without a CATEGORY are ungrouped in the dashboard's category view.
TAGS
TAGS <tag1>, <tag2>, ... attaches a comma-separated list of tags to a rule. Tags are arbitrary identifiers; they appear in the audit log, the dashboard rule table, and the hub search index. The ATT&CK integration uses tags of the form attack.t<technique> and attack.ta<tactic>.
Valid tag characters: letters, digits, and . _ : -. Each tag is validated at parse time.
rule guard-secrets {
enabled true
priority 90
severity error
CATEGORY credential-access
TAGS secrets, attack.t1552, attack.ta0006
DENY write
IF path ENDS_WITH ".env"
MESSAGE "Credential file write blocked."
}
Multiple TAGS lines in the same rule block are not supported; all tags must appear on a single line.
Scope hierarchy
Rules are loaded from multiple sources and merged at eval time. The sources, in precedence order (higher overrides lower):
| Scope | Location | Kind |
|---|---|---|
| session | ~/.sigmashake/policy/session/ | Temporary in-session overrides |
| project | .sigmashake/rules/ (working directory) | Per-project rules |
| profile | ~/.sigmashake/policy/profiles/ | Active built-in profile bundles |
| user-global | ~/.sigmashake/policy/user/ | Machine-wide user rules |
Within each scope, rules are sorted by priority descending before evaluation. Deduplication is by rule ID (first-seen wins); if a project rule and a user-global rule share the same ID, the project rule takes effect.
The merged, annotated effective rule set — including source_scope, source_kind, and profile_name — is visible via:
ssg policy list
ssg policy list --json # machine-readable, includes origin metadata
Version 2
Version 2 adds named data, data operators, and branches to one rule. A rule can use IF, ELSE IF, ELSE and END. A file without the version 2 header keeps the version 1 grammar. Its rules and its errors do not change.
Only the Go ssg reads version 2. The TypeScript parser rejects the header and prints Version 2 rules are read by the Go ssg only. Check this file with: ssg lint <file>. For each error code, see Rule Errors.
Header
Write the header on the first line that is not blank:
# version 2
A comment or another line above the header turns it off. The file then uses the version 1 grammar. # version 02 also reads as version 2. A version 2 file accepts the version 1 rule form, so a rule with one IF and no END works as before.
Named data
Declare each data block at file scope, above the first rule that uses it:
# version 2
domains owned { "sigmashake.com" }
set fetchers { "curl" "wget" }
prefixes scratch { "/home/user/ssd/tmp/" }
map tiers { "free" = "low" "pro" = "high" }
| Kind | Entries | Operator | Entry check |
|---|---|---|---|
set | Strings | IN | Non-empty, at most 512 bytes, no NUL byte. |
domains | Host names | HOST_IN | At least two labels. No *, no port, no IP address. Stored in lowercase with no trailing dot. |
prefixes | Absolute paths | UNDER | Absolute path. No * or ?. Not /. Stored cleaned, with no trailing slash. |
map | "key" = "value" pairs | MAP | Key checked as a set entry. Value at most 512 bytes. |
A name starts with a lowercase letter. It contains lowercase letters, digits and _ only. Declare each name once per file.
Data operators
IF input.url HOST_IN @owned
IF path UNDER @scratch
IF command IN @fetchers
IF input.tier MAP @tiers EQUALS "low"
field IN @setis true when the field equals an entry in the set.field HOST_IN @domainsis true only when the field holds at least onescheme://authorityURL and every URL host is a listed domain or a subdomain of one. For WebFetch, the field isinput.url.- The engine reads only
scheme://authoritytext. It does not see a scheme-less host, such ascurl sigmashake.comorgit@host:path. SoHOST_IN @badmisses those hosts.NOT HOST_IN @oktreats a scheme-less call as foreign, which is the safe direction. PairHOST_INwithSTARTS_WITH,CONTAINSorREGEXwhen scheme-less forms matter. - A URL is unreadable when its authority holds any byte other than a letter, a digit,
.,-or:. A user name (@),$, a backtick,\,%and[(an IPv6 literal) are such bytes. An IP address, a bad port, and an empty or invalid host also make the URL unreadable. - A quote that ends the host must close a quote that opened before the URL. A space or a shell operator must follow that quote. Otherwise the URL is unreadable, as in
"https://a.com"evil.io. - An unreadable URL is fail-secure. A
DENY,ASKorFORCEbranch matches it, whatever theNOT. AnALLOW,LOGorSHADOWbranch does not match it. field UNDER @prefixesneeds an absolute path. A relative path never matches. The path is cleaned first:..and.are resolved, and a trailing slash is removed. The prefix must match whole path segments, so/tmpxis not under/tmp. Symbolic links are not followed. The match is case-sensitive, except for Windows drive paths such asC:/Users, which are lowercased on both sides. A backslash counts as a slash. A prefix that cleans to/is refused.field MAP @map <OPERATOR> "value"looks up the field value as a key, then runs<OPERATOR>on the mapped value. A key that the map does not hold gives the empty string.<OPERATOR>is a version 1 content operator, such asEQUALS,STARTS_WITH,CONTAINSorREGEX. A data operator afterMAPfails withV2_MAP_OPERATOR_INVALID. This includesOWNED_EGRESSandOWNED_EGRESS_PIPE_SHELL.NOTworks as in version 1:NOT field IN @setandfield NOT IN @set.- The block kind must match the operator.
INneedsset,HOST_INneedsdomains,UNDERneedsprefixes, andMAPneedsmap. Otherwise the rule fails withV2_DATA_KIND_MISMATCH. - An
EXCEPTIONblock uses the version 1 expression grammar. It has no data operators.
Branches
rule <id> {
IF <condition>
<DECISION> [target]
MESSAGE "<text>"
ELSE IF <condition>
<DECISION> [target]
MESSAGE "<text>"
ELSE
<DECISION> [target]
MESSAGE "<text>"
END
}
- The first branch starts with
IF. Each later branch starts withELSE IF.ELSEis the last branch and takes no condition. - Each branch has one decision line. The target defaults to
any. - Each branch needs
MESSAGE. AnASKbranch needsPROMPT. AFORCEbranch needsSUBSTITUTE. - A rule with
ELSE IForELSEneedsENDbefore its closing}. - A rule with one
IFneeds noEND. Its decision line can also come above theIFline, as in version 1. With no decision line, it usesLOGonany. - A rule has at most 16 branches.
Semantics
- The branches are tried in order. The first branch whose condition holds decides.
- If the target of that branch does not cover the tool call, the rule does not apply. The later branches are not tried.
- If no branch holds, the rule does not apply. No branch allows the call by default.
- Priority works as in version 1. Across rules,
ALLOW,LOGandSHADOWbranches wait. Only aDENY,FORCEorASKof another rule beats them. ssg rule syncrefuses a version 2 file rule that has anALLOWorFORCEbranch. A version 1 file rule withALLOWis refused in the same way. Add these rules from the dashboard, or withssg allow.
Built-in owned domain
Every install treats sigmashake.com and its subdomains as an owned domain. The default is compiled into the binary. It is not a rules file. The TypeScript runtime has no built-in rows, and the dashboard Network tab does not show them.
The default covers these calls:
- Fetches with
curl,wgetorxh, and WebFetch, to HTTP or HTTPS URLs. - Pipes into
jq,head,tail,wc,grepandsort. cd DIR &&before a fetch.-oto/dev/nullor to a relative path.for V in LABELS; do <one fetch>; done. The loop variableVmust be one ofh,v,x,d,s,host,sub,label,name,svc,siteorapp.- A pipe into a shell or an interpreter, such as
sh. Onlycurlcan feed that pipe.wgetcannot.
Hosts that serve user content get reads only. These are 16 hosts, and each one includes all its subdomains: clip.sigmashake.com, vibe.sigmashake.com, hub.sigmashake.com, showcase.sigmashake.com, guild.sigmashake.com, only.sigmashake.com, promo.sigmashake.com, ads.sigmashake.com, support.sigmashake.com, hack.sigmashake.com, society.sigmashake.com, vcs.sigmashake.com, streamcord.sigmashake.com, yt-chat.sigmashake.com, discord.sigmashake.com and demo.sigmashake.com.
A write to one of these hosts still asks. A pipe into a shell from one of them still asks. A write to these hosts also asks for an owned rule that the dashboard Network tab adds.
Rules of other sources rank against the owned allow rules as follows. This applies to the built-in rules and to the owned rules that the dashboard Network tab adds.
- A
DENYorFORCErule always wins over an owned allow rule. The priority of theDENYorFORCErule does not matter. - An
ASKrule of your own wins over an owned allow rule when its priority is above the priority of the owned rule. - The plain owned allow rule has priority 70. An
ASKrule needs priority 71 or more to win over it. - The pipe-shell owned allow rule has priority 101. An
ASKrule needs priority 102 or more to win over it.
To turn the default off, set builtin_owned = false under [network]. Set it in ~/.sigmashake/config.toml or in the project .sigmashake/config.toml. Either file turns the default off. The values false, 0, off and no turn it off, in any case. With the default off, a fetch from sigmashake.com asks, as for any external host. The change takes effect at the next rules load: the next one-shot eval, or a daemon reload or restart. A DENY or FORCE rule still wins over the default.
Limits
| Limit | Value | Error when exceeded |
|---|---|---|
| Entries per data block | 4096 | V2_DATA_TOO_LARGE |
| Entry text in all data blocks of one file | 2 MiB | V2_DATA_TOO_LARGE |
| Bytes per entry | 512 | V2_DATA_BAD_ENTRY |
| Data blocks per file | 64 | V2_DATA_TOO_MANY_BLOCKS |
| Branches per rule | 16 | V2_TOO_MANY_BRANCHES |
| Levels of parentheses | 16 (version 1 allows 64) | V2_NESTING_TOO_DEEP |
| Groups and conditions in one file, shared by all its rules | 8192 groups and 65536 conditions | V2_TOO_COMPLEX |
| Referenced data in one file | 16 MiB. Each rule counts a copy of each data block that it uses. | V2_TOO_COMPLEX |
Performance
Named data compiles at load into hash tables. In the prototype benchmark of 2026-10-23, a version 2 data lookup took 127 to 365 ns with 4096 entries. The set lookup took 127 ns, the map lookup 161 ns, the prefixes lookup 330 ns, the domains lookup 336 ns, and HOST_IN with three branches 365 ns. Version 1 rules stay within 10% of the old engine. The worst case is +7.7%.
Example
This rule uses a data block, an IF branch, an ELSE IF branch and END:
# version 2
domains owned { "example.com" }
set fetchers { "curl" "wget" }
rule egress-example {
priority 70
IF input.url HOST_IN @owned
LOG
MESSAGE "Request to an owned domain"
ELSE IF command REGEX "^(curl|wget) "
ASK
MESSAGE "Fetch to a URL that is not owned"
PROMPT "Confirm the target URL before the request"
END
}
The fetchers set is not used by this rule. It shows the set syntax.
- A WebFetch call with
input.urlset tohttps://docs.example.com/matches the first branch. TheLOGdecision lets the call run and records the message. - A Bash call with
commandset tocurl https://other.test/does not match the first branch, becauseinput.urlis empty. It matches theELSE IFbranch, andssgasks for approval with the prompt text. - Any other call matches neither branch. The rule does not apply.
Migration
- A file without the header keeps its meaning. You do not need to change it.
- To move a file to version 2, add
# version 2as the first line of the file. Then runssg linton the file. - The new strict checks are errors in a version 2 file. They are warnings in a version 1 file.
- Upgrade every
ssgthat loads the file before you add the header. An olderssgrejects the file withUnsupported DSL version. - Do not add the header to a file that the TypeScript tools read. They reject it.
File naming convention
Follow the Sigma-style convention: {technology}_{capability}_{description}.rules
Examples:
ts_write_safety.rulesgit_exec_trunk_workflow.rulesbash_exec_destructive_ops.rulesagent_exec_oracle_redirect.rules