Rules engine guide

Rules define conditions that flag activity for investigation. Each rule has a detection expression, severity, status, and scoring metadata. A signal namespace identifies the records that its conditions read.

Start with the source

Source	Use it to inspect	Example field
Domain	Current domain analysis results	domain.classification.phishing
Email	Email Intelligence events linked to a monitored domain	email.sender_from_domain
Canary	Site Canary events for a monitored domain	canary.edge_outcome

Domain fields are available to Domain rules. Email and Canary rules require access to the corresponding feature.

Browse signals by namespace before writing a rule. Each reference supports field search and signal groups.

Create a rule

Open Monitoring → Rules and create a rule. Editing organization rules requires an administrator role. The builder starts on Detection, followed by General and Scoring.

1. Add conditions

Choose Domain, Email, or Canary with the namespace selector beside Add condition. The field picker shows only that group’s catalog, arranged by signal category, with local field names and types. Select a field, a compatible operator, and a value.

Use Add group to add another source or group related conditions. Each group has its own namespace selector. Combine conditions and groups with AND or OR. Switching a populated group to another namespace asks for confirmation before clearing fields that the new catalog does not contain.

For example, a Domain group can combine recent registration with a high phishing classification score:

domain.registration_metadata.registration_date.days_since:<=30 AND
domain.classification.phishing:>0.8

Generated expressions include the namespace prefix, except for the compatibility-only created_on field. Existing unqualified forms such as classification.phishing:>0.8 remain valid for Domain rules. Use created_on without a prefix; domain.created_on is not supported.

Email and Canary selections require access to Email Intelligence and Site Canaries, respectively. Locked selections identify the required feature.

2. Inspect matched results

The Matched results panel has separate Domain, Email, and Canary tabs. It filters organization records with the conditions for each source used in the rule. Valid changes refresh the preview; the refresh button runs it again.

Each tab shows up to ten example records. Email and Canary tab counts include all matches in the selected window; the Domain count covers the returned sample. Open a Domain card to inspect its lookup details, or review the Email and Canary event cards.

When the rule uses Email or Canary, Time window offers the last 24 hours, 7 days, 14 days, or 30 days. The default is seven days. This window also filters Domain lookup results in the preview. The execution window has different Domain semantics.

Preview sources separately

The tabs show each source’s matches across the organization. Records in different tabs can belong to different monitored domains. A populated preview does not establish that the complete mixed-namespace rule matches; runtime evaluation combines sources for the same monitored domain.

3. Describe, score, and save

In General, set a title that explains the detection, then add a description, tags, severity, and status.

Severity	Intended priority
Critical	Highest investigation priority
High	Prompt investigation
Medium	Review in the normal investigation queue
Low	Lower-priority activity
Informational	Context or baseline observations

Rule status

The available statuses are stable, experimental, deprecated, and unsupported. Status records a rule’s maturity or maintenance state. Severity and status are author-assigned metadata; they do not independently establish that a matched record is malicious.

In Scoring, set malware, phishing, and impersonation scores on the builder’s 0–100 scale and record known false positives, then save the rule. These scores are rule-author assessments used to prioritize results. They are separate from lookup classification fields such as domain.classification.phishing, which use a 0–1 scale.

Rules across namespaces

Use explicit field prefixes to make each source visible. Conditions within one namespace apply to the same record. Across namespaces, the engine evaluates each source independently and combines whether a match exists.

Require every source to match

domain.classification.phishing:>0.8 AND
email.sender_from_domain:example.com

The rule matches when an eligible Domain result passes the first condition and an Email event passes the second. Both are scoped to the same monitored domain. The matched Email event does not have to refer to the particular Domain result.

Accept any matching source

email.attachment_file_type:exe OR
canary.edge_outcome:unexpected

The rule matches when either source has a matching record.

Keep groups within a source

A source can contain its own nested logic:

(domain.classification.phishing:>0.8 OR domain.levenshtein_distance:<3) AND
(email.sender_from_domain:example.com AND email.direction:inbound)

Across sources, use a top-level AND (all sources) or OR (any source). A mixed-source nested group such as domain.permutation:example.com AND (email.direction:inbound OR canary.edge_outcome:unexpected) is rejected.

Negation can apply within one namespace. Negating a group that mixes namespaces is rejected. A field reference on the right-hand side, such as $email.sender_from_domain, must stay within the same namespace.

Understand the time window

Email and Canary evaluation reads persisted events within a default seven-day lookback. The saved execution setting accepts an integer from 1 to 30 days; the visual builder offers the four presets described above.

Domain conditions read eligible results from the current domain analysis. They do not search historical Domain results across the event lookback.

An explicit time condition can narrow the event window:

email.observed_on:>=now-1d AND
email.attachment_file_type:exe

A date predicate cannot retrieve events outside the configured lookback. Ingestion of an Email or Canary event does not itself imply an immediate rule run.

Read the result correctly

Open Monitoring → Alerts and expand a Rule row to inspect the aggregated result. The detail view includes the monitored domain, evaluated fields, rule expression, and exact execution window. Evidence separates Domain, Email, and Canary records into source tabs, with links to the rule and originating lookup.

The Events count reports recorded evidence references. A trailing + indicates that the retained sample was truncated. Evidence cards can be fewer than the recorded references if source records are no longer available. Email and Canary evidence require access to their corresponding features.

A rule alert represents the complete expression. Source tabs explain the evidence behind it; they are not separate alerts or proof of a record-to-record relationship. Email-only or Canary-only matches do not create a synthetic Domain result. Older Result rows can remain for lookup alerts that have no corresponding aggregated rule alert.

Focused examples

Combine page semantics with classification

domain.page_semantics.requests_wallet_recovery_secret:true AND
domain.classification.phishing:>0.8

Both conditions apply to one Domain result. The page-semantics condition can match any captured page in that result. Additional domain.page_semantics.* selectors can match different captured pages, so they do not establish a relationship within one page.

Match an exact public identifier

domain.identifiers:"google_tag_manager=GTM-ABC123"

The kind and value must match within one identifier object. A shared identifier can connect related sites; investigation must establish the significance of that relationship.

Inspect a recently observed attachment

email.observed_on:>=now-1d AND
email.attachment_size_bytes:>1000000 AND
_exists_:email.attachment_sha256

The conditions apply to one Email event. They do not combine fields from separate attachment or URL event rows.

Inspect an unexpected Canary observation

canary.edge_outcome:unexpected AND
canary.subdomain_depth:>2

Review the observed hostname, monitored domain, and request metadata with the event.

Manage rules

Global rules are maintained by Have I Been Squatted. Organization rules hold custom detection logic. Rule ownership is independent of signal namespace.

Use the rule list and detail views to review configuration and recent results. Organization administrators can edit, enable, disable, or delete custom rules.

Keep detections narrow enough to explain, record known false positives, and review alert evidence as source data changes.

Reference

Signals and namespaces Choose a data source, then find the fields needed for a rule.

Upsilon query syntax Operators, dates, arrays, field references, and execution differences.