Rules detect behavior in normalized coding-agent activity. They are evaluated locally on each client and distributed through client groups.

Default rules

The Rules table includes the full built-in catalog alongside custom rules. Default rows are labeled Default and apply to all clients.

Deleting a default rule creates a disabled organization override; it does not modify the client binary. The row remains visible with a Disabled status so administrators can restore it later. Select the restore action to remove the override and reactivate the embedded default.

Custom rules are labeled Custom and can be assigned to selected groups. Deleting a custom rule permanently removes it.

Generate a rule with the assistant

1. Open Agents → Rules.
2. Select New rule.
3. Describe the behavior you want to detect in the rule generator terminal.
4. Select Generate YAML.
5. Review the generated YAML in the editor.
6. Ask follow-up questions to refine it, or edit the YAML directly.
7. Assign one or more client groups and select Validate and save.

For example:

Alert when an agent reads a .env file and then sends data to an external URL.
Make this high severity, but do not block it.

After the first response, the YAML editor appears above the terminal. Follow-up terminal instructions use the current YAML as context:

Limit this to events in production projects and change the window to 30 events.

The assistant is available only to organization owners. Generation is rate-limited and requires AI Gateway configuration on self-hosted deployments.

Edit YAML manually

Select Edit YAML manually to start from the default template without generating a rule. Every rule requires:

Field	Required	Description
id	Yes	Stable identifier using letters, numbers, dots, dashes, or underscores
version	Yes	Quoted version copied into alerts
enabled	Yes	Whether the rule is active; normally true
title	Yes	Human-readable alert title
description	Yes	Precise explanation of what matches and what the finding proves
severity	Yes	info, low, medium, high, or critical
tags	Yes	One or more categories, including relevant MITRE ATT&CK tags where applicable
expr	One of	CEL predicate evaluated against one event
sequence	One of	Ordered multi-event detection
enforce	No	Makes the rule eligible for blocking; defaults to false
deny_message	No	Message returned when an enforceable action is denied

Define exactly one of expr or sequence.

Single-event rules

Use expr when one event is enough to identify the behavior:

id: acme.secrets.env_read
version: "1.0"
enabled: true
title: Environment file read
description: Detects reads of environment files that commonly contain credentials.
severity: high
tags:
  - secrets
  - attack.t1552.001
expr: |-
  event.event_type == "file.read" &&
  event.file_path.matches("(^|/)\\.env$")

Useful fields include:

• event.event_type
• event.file_path
• event.command
• event.tool_name
• event.url
• event.content_preview
• event.project_path
• event.source_agent
• event.tags

Expressions support normal CEL operators and helpers such as ==, !=, &&, ||, contains(), startsWith(), endsWith(), and matches().

Sequence rules

Use sequence when events must occur in order:

id: acme.secrets.read_then_send
version: "1.0"
enabled: true
title: Secret read followed by external transfer
description: Detects an environment-file read followed by an outbound network indicator.
severity: critical
tags:
  - secrets
  - exfiltration
sequence:
  within_events: 30
  steps:
    - expr: |-
        event.event_type == "file.read" &&
        event.file_path.matches("(^|/)\\.env$")
    - expr: |-
        event.event_type == "network.indicator" &&
        event.url != ""

A sequence requires two to eight steps and at least one window:

• within — wall-clock duration such as 30m
• within_events — event-count window, up to 4096

Monitoring and enforcement

Rules are monitor-only unless both conditions are true:

1. The YAML contains enforce: true.
2. The endpoint hook was installed with enforcement enabled.

enforce: true
deny_message: Contact your security team before accessing this file.

Severity does not enable blocking. It only prioritizes the resulting alert.

Assign rules to groups

Use terminal commands to manage group assignments while editing:

/groups
/group add Production
/group remove Production
/group create New group

A client receives the union of rules assigned to all of its groups. Rule IDs are unique within an organization, so assigning one rule through multiple groups does not duplicate it.

Use /save to validate and save, /clear to reset the YAML, /close to close the panel, and /help to list commands.

Validation

Superagent validates the YAML structure and compiles every generated or edited rule with the same Numbat monitoring engine before accepting it. Compiler diagnostics are shown in the rule editor so unsupported fields, functions, and expressions can be fixed before saving.

Each endpoint validates downloaded rules again before activation. If a new catalog fails validation, the endpoint keeps its last known-good rules.

On self-hosted Node deployments, you can set AGENT_RULE_VALIDATOR_PATH to an executable Numbat v0.1.2 binary. When it is unset, the server downloads the pinned archive for macOS or Linux on arm64 or x64 during the first validation in each process, verifies the archive SHA-256 checksum, and keeps the validator only in that process's private temporary directory. Rule saves fail safely if the validator is unavailable.