Skip to main content

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 → 50
  • severity → warning
  • enabled → 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 KeywordRuntime DecisionBehavior
DENYblockReject the tool call
ALLOWallowPermit explicitly (overrides lower-priority DENY)
LOGlogAllow but record in audit log
SHADOWshadowAllow silently, log for monitoring
ASKaskPause execution, require human approval via dashboard
FORCEforceRefuse 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 — AMBIENT is 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​

DecisionWire format
ALLOW, LOG, SHADOWEmitted as Claude Code hookSpecificOutput.additionalContext (PreToolUse). Tool runs; AI sees the context with the result.
DENY (block) / FORCEAppended to the stderr refusal message. Claude Code surfaces stderr to the model on exit-code 2; FORCE includes the safe substitute path.
ASKEmitted 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​

  • MESSAGE is for humans — shown in dashboards, audit logs, and the approval prompt.
  • CONTEXT is 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 CONTEXT per rule; last write wins if duplicated.
  • Survives audit and soft runtime 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​

FieldRequiredPurpose
AMBIENTyesMarks the rule as a knowledge carrier. Takes no decision keyword.
MESSAGEyesOne-line headline. Shown in the session-start index.
CONTEXTyesThe knowledge body. Pulled on demand via ssg recall.
prioritynoHigher = listed first at session start. Default 50.
severitynoInformational 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 ruleCONTEXT on a gating rule
WhenSession start, alwaysWhen the rule matches a tool call
TriggerNone — unconditionalThe rule's IF conditions
DecisionNoneALLOW / LOG / DENY / ASK / FORCE / SHADOW
Use forStanding project knowledgeA 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:

TargetMatches tools with capability
executionShell commands (Bash, terminal)
readFile reading (Read, cat)
writeFile writing/editing (Write, Edit)
editEdit only (subset of write)
searchFile/content search (Glob, Grep)
agentSub-agent spawning (Agent)
networkHTTP requests (WebFetch, WebSearch)
anyAll tools

Conditions​

Syntax​

IF <field> [NOT] <operator> "<value>"

Fields​

FieldResolves to
commandinput.command (Bash commands)
pathinput.file_path or input.path
contentinput.content or input.new_string
toolTool name (e.g., "Bash", "Read")
input.<key>Any key in the tool input object

Operators​

OperatorDescription
CONTAINSSubstring match
EQUALSExact string match
STARTS_WITHPrefix match
ENDS_WITHSuffix match
GLOBGlob pattern (*, **, ?)
REGEXRegular expression
WORDWord-boundary match (no regex, O(n))
LINE_CONTAINSPer-line substring, strips // comments
LINE_REGEXPer-line regex, strips // comments
LENGTH_GTUTF-8 byte length strictly greater than N
LENGTH_LTUTF-8 byte length strictly less than N
TOKENS_GTEstimated tokens (byte-length / 4) strictly greater than N
TOKENS_LTEstimated 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):

ScopeLocationKind
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.

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" }
KindEntriesOperatorEntry check
setStringsINNon-empty, at most 512 bytes, no NUL byte.
domainsHost namesHOST_INAt least two labels. No *, no port, no IP address. Stored in lowercase with no trailing dot.
prefixesAbsolute pathsUNDERAbsolute path. No * or ?. Not /. Stored cleaned, with no trailing slash.
map"key" = "value" pairsMAPKey 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 @set is true when the field equals an entry in the set.
  • field HOST_IN @domains is true only when the field holds at least one scheme://authority URL and every URL host is a listed domain or a subdomain of one. For WebFetch, the field is input.url.
  • The engine reads only scheme://authority text. It does not see a scheme-less host, such as curl sigmashake.com or git@host:path. So HOST_IN @bad misses those hosts. NOT HOST_IN @ok treats a scheme-less call as foreign, which is the safe direction. Pair HOST_IN with STARTS_WITH, CONTAINS or REGEX when 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, ASK or FORCE branch matches it, whatever the NOT. An ALLOW, LOG or SHADOW branch does not match it.
  • field UNDER @prefixes needs 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 /tmpx is not under /tmp. Symbolic links are not followed. The match is case-sensitive, except for Windows drive paths such as C:/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 as EQUALS, STARTS_WITH, CONTAINS or REGEX. A data operator after MAP fails with V2_MAP_OPERATOR_INVALID. This includes OWNED_EGRESS and OWNED_EGRESS_PIPE_SHELL.
  • NOT works as in version 1: NOT field IN @set and field NOT IN @set.
  • The block kind must match the operator. IN needs set, HOST_IN needs domains, UNDER needs prefixes, and MAP needs map. Otherwise the rule fails with V2_DATA_KIND_MISMATCH.
  • An EXCEPTION block 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 with ELSE IF. ELSE is the last branch and takes no condition.
  • Each branch has one decision line. The target defaults to any.
  • Each branch needs MESSAGE. An ASK branch needs PROMPT. A FORCE branch needs SUBSTITUTE.
  • A rule with ELSE IF or ELSE needs END before its closing }.
  • A rule with one IF needs no END. Its decision line can also come above the IF line, as in version 1. With no decision line, it uses LOG on any.
  • A rule has at most 16 branches.

Semantics​

  1. The branches are tried in order. The first branch whose condition holds decides.
  2. If the target of that branch does not cover the tool call, the rule does not apply. The later branches are not tried.
  3. If no branch holds, the rule does not apply. No branch allows the call by default.
  4. Priority works as in version 1. Across rules, ALLOW, LOG and SHADOW branches wait. Only a DENY, FORCE or ASK of another rule beats them.
  5. ssg rule sync refuses a version 2 file rule that has an ALLOW or FORCE branch. A version 1 file rule with ALLOW is refused in the same way. Add these rules from the dashboard, or with ssg 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, wget or xh, and WebFetch, to HTTP or HTTPS URLs.
  • Pipes into jq, head, tail, wc, grep and sort.
  • cd DIR && before a fetch.
  • -o to /dev/null or to a relative path.
  • for V in LABELS; do <one fetch>; done. The loop variable V must be one of h, v, x, d, s, host, sub, label, name, svc, site or app.
  • A pipe into a shell or an interpreter, such as sh. Only curl can feed that pipe. wget cannot.

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 DENY or FORCE rule always wins over an owned allow rule. The priority of the DENY or FORCE rule does not matter.
  • An ASK rule 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 ASK rule needs priority 71 or more to win over it.
  • The pipe-shell owned allow rule has priority 101. An ASK rule 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​

LimitValueError when exceeded
Entries per data block4096V2_DATA_TOO_LARGE
Entry text in all data blocks of one file2 MiBV2_DATA_TOO_LARGE
Bytes per entry512V2_DATA_BAD_ENTRY
Data blocks per file64V2_DATA_TOO_MANY_BLOCKS
Branches per rule16V2_TOO_MANY_BRANCHES
Levels of parentheses16 (version 1 allows 64)V2_NESTING_TOO_DEEP
Groups and conditions in one file, shared by all its rules8192 groups and 65536 conditionsV2_TOO_COMPLEX
Referenced data in one file16 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.url set to https://docs.example.com/ matches the first branch. The LOG decision lets the call run and records the message.
  • A Bash call with command set to curl https://other.test/ does not match the first branch, because input.url is empty. It matches the ELSE IF branch, and ssg asks 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 2 as the first line of the file. Then run ssg lint on the file.
  • The new strict checks are errors in a version 2 file. They are warnings in a version 1 file.
  • Upgrade every ssg that loads the file before you add the header. An older ssg rejects the file with Unsupported 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.rules
  • git_exec_trunk_workflow.rules
  • bash_exec_destructive_ops.rules
  • agent_exec_oracle_redirect.rules