Skip to main content

Watchers

Watchers are standing rules over your estate. Each one describes a pattern and an action to take whenever the pattern matches, and they run continuously against the data in your organization's scope — so detections and hunts appear without anyone having to remember to look.

Open Watchers from the main navigation (Detect & automate › Watchers in the new navigation). The page has two tabs: Rules, the watchers themselves, and Health, where you test and measure them (see Watcher health).

Watchers and detections​

A watcher is the rule: the logic Huntbase runs over your data, such as a Sigma rule, a graph pattern or a threshold. Other tools call these "detection rules". When a watcher matches, it fires, and the firing generates a detection. Depending on the watcher's action, the detection starts a hunt, waits in Needs you to be judged, or goes into the daily digest.

The page's subtitle reads Your detection rules: …. Not sure what a word on this page means? What these words mean at the top explains Watcher, Shadow, Plane, Can it fire? and Armed in plain words. Terms with a dotted underline elsewhere in Huntbase (for example Huntbase Lake or the coverage words on a threat) show the same plain-word explanation when you hover them.

Three kinds of watcher​

Watchers differ in what they watch, and that decides what "it hasn't fired" tells you. Each one shows its kind — its plane — on its row:

PlaneFires whenNeeds
StreamPer event, seconds after it arrives.Telemetry of the kind the rule looks for.
GraphWhen your entity graph changes.Entities to have reached the graph.
CorrelationWhen a window closes over two or more earlier signals.Those precursor signals.
IntelWhen your telemetry, or newly arrived intel, matches an indicator from your threat intel feeds.Intel feeds your organization subscribes to. Part of Intelligence.

You don't need to think about the machinery, but the plane is half the answer to the only question anyone asks a rules page: why didn't this fire? A stream watcher only ever sees telemetry you actually ship. A graph watcher only sees what has reached the graph.

Off, Shadow, On​

Every watcher is in one of three states, set from the control on its row:

StateWhat happens
OffNot evaluated at all.
ShadowEvaluated and recorded to the daily digest. Never opens a hunt and never notifies anyone.
OnEvaluated, and takes its action when it matches. The confirmation says which action, for example "When it matches, it starts a hunt."

Shadow is the safe way to find out whether a rule is noisy. Put a watcher in Shadow, leave it for a few days, then look at its Activity — you learn what it would have done without anyone being paged for it.

A few watchers, mostly stream rules, are published as digest-only. They show Off and On · digest only, because Shadow would do the same thing as On: their On records matches to the daily digest, which is what Shadow does on other watchers, and never opens a hunt or notifies anyone. To make one act, set its action under When this fires, in the Response section of the watcher's Deploy tab.

While a watcher is in Shadow, When this fires shows the action it will take once it is On, and Who gets told says who will be told then. Choosing an action turns it On, and the panel says so before you pick.

Shadow keeps your action. If a watcher was On with Notify and you move it to Shadow, turning it On again (yourself or through its rollout) puts Notify back; it doesn't fall back to the rule's own action.

Quarantined watchers​

A watcher that fires far above its limit in an organization is quarantined there automatically. It shows a Quarantined badge, and its state control reads Shadow (quarantined) with On unavailable: it runs as Shadow, recording to the daily digest, and doesn't notify anyone or open hunts. You can still switch it Off.

The watcher's Deploy tab shows, under Response, why it was quarantined: how often it fired against its limit, how many matches were held, and when it will be released automatically, or Manual only. An organization administrator can select Release from quarantine, give a reason and confirm. A watcher quarantined in every organization at once can only be released by a Huntbase platform administrator.

When a watcher is quarantined, the organization's administrators get a notification. Review quarantine opens the watcher on its Deploy tab.

When this fires​

Open a watcher and go to its Deploy tab. Right under State, When this fires says what the watcher does when it matches and who is told:

ActionWhat happens
Start hunt and notifyScout opens a hunt, and the team is told it started. People in the organization also see the hunt in Needs you and their notifications.
NotifyRecords a detection and tells your alert channels. At High or Critical it waits in Needs you to judge; below High it waits in Activity › Insights. Nobody gets a personal alert by default.
Daily digestAdds the match to the daily digest. Nobody is told straight away. Shown for digest-only watchers.

A few graph watchers only Tag graph: they apply a graph tag so another watcher can build on it. That action is structural and can't be changed.

Who gets told lists the alert routing destinations for that action — your team Slack channel, team mailbox or webhook. It updates when routing changes, even if you changed it in another tab. If nothing is routed, it says so plainly:

  • Nobody will be notified for Notify, because without alert routing a detection only waits in Huntbase.
  • Nobody will be notified by Slack or email for Start hunt and notify, because people still see the hunt in Needs you and the bell.

If routing is set up but this kind of alert isn't ticked, it names the box to tick. Organization admins get a link to Settings › Alert routing; members are told to ask an admin. High and Critical watchers that would tell nobody are highlighted as a warning.

Hunt-action watchers run in one of three modes — Guided (Scout proposes each step and waits), Supervised (Scout runs but pauses at checkpoints), or Autonomous (Scout runs end to end and reports back).

Every watcher also carries a severity: Informational, Low, Medium, High or Critical. You can raise the floor for your organization so only matches at or above a chosen severity trigger the action.

Where a watcher runs​

A watcher's Deploy tab says where it runs, under Runs in, and what it does when it matches, under Response.

Coverage shows every watcher against every store.

Can it fire? — the readiness chip​

ChipMeaning
ArmedThe data this watcher needs is present, and the watcher is running.
Data ready · offThe data is present, but the watcher is Off, so it will not fire. Switch it to Shadow or On.
Needs dataIt cannot fire yet, and the chip says why — for example "No Process Activity (1007) events received by Huntbase in the last 24 h". This is the one to act on: add the missing source. Open the watcher to see what is missing, with a Send telemetry link (stream watchers) or a Connect a source link (graph and correlation watchers).
Ready on sample dataYour own data can't fire it yet, but your installed Example Corp sample data can. Connect a source to cover your own environment.
Check unavailableThe readiness check itself didn't answer just now. Usually temporary, and it says nothing about whether the watcher can fire.
Not applicableIntel watchers only. They fire on threat-intel events (a new report, or an indicator from your feeds or a watch list showing up in your data), not on telemetry, so there is no data to check.

Graph and correlation watchers read the entity graph, so only data that is sent to Huntbase counts: logs you send, or insights ingested from a connector. Connections Huntbase queries live (federated) don't count, because their data stays where it is and never reaches the graph. That is why a watcher can read Needs data in an organization with many connections, and its detail says so.

The last two look different on purpose. Needs data is a standing problem you own; Check unavailable means we couldn't look.

For stream watchers, the check counts two things: data Huntbase receives (the telemetry you ship with ingest keys), and stores where the watcher is deployed with a field mapping for its log source. A watcher whose events live only in Splunk is Armed once it runs on Splunk. A deployment that is still setting up, can't run, is failing or is paused doesn't count. Events that live only in a lake of your own, or in a store the watcher isn't deployed to, don't count either, so a watcher can show Needs data even when they hold matching events. To cover data kept in a SIEM or log store, deploy the watcher there from the Deploy tab.

Finding things in a large catalog​

The catalog runs to thousands of watchers, so the page is built for narrowing rather than scrolling.

  • Search matches a watcher's name, description or ATT&CK technique ID (T1059). It does not search the rule text.
  • Filters for state, severity and plane. Each option shows how many watchers are in that bucket, so the dropdowns double as navigation.
  • Group by state, severity, plane or ATT&CK tactic, with collapsible sections. A watcher covering several tactics appears under each of them.
  • Sort by severity, name or state.

The summary line above the list reports the totals for your search, not just what is currently on screen.

Watchers are enabled per organization​

A watcher's state belongs to one organization. The same watcher can be On for one and Off for another, and the controls on the page apply to the organization named at the top.

If you work across several organizations:

  • Use the organization picker at the top of the page to switch which one you are setting. The page's address includes it, so a link you share opens on the same one.
  • Open a watcher and use its Deployment tab to see its state in every organization you can see, and set each one from there.

Response settings — state, severity floor, action and hunt mode — are that organization's, not the rule's. Changing it doesn't affect anyone else.

The Deployment tab can also set every organization at once. When it does, each organization answers for itself: if one refuses — because the watcher isn't available to it, for example — that row says so and the others still apply. A row that can't run the watcher explains why underneath its name, rather than leaving you with a control that appears to work and a watcher that never fires.

What a watcher has done​

Open a watcher to see its Activity for the last 7, 14 or 30 days:

ReadingWhat it tells you
DetectionsHow many times it matched and acted.
SuppressedHow many further matches were folded into those. A dash means nothing measured it — not zero.
EntitiesHow many distinct hosts, accounts or assets it touched.
Hunts openedHow many hunts it started.
Daily barsThe shape of the volume: steady, or one bad Tuesday.

A Linked strip lists the hunts its recent firings opened, with each hunt's verdict, so you can see what the watcher led to without leaving it.

Beneath those, the recent detections list shows what each one produced and how much it suppressed. Select a detection's title to open what it produced: the finding, the hunt it started, or the event's own insight.

The address of an open watcher includes it (/watchers?watcher=<id>), so you can share a link that opens straight to that watcher.

Fired 64, suppressed 1,204 is a signal in its own right. A watcher suppressing ten times what it fires is working, and its tuning is wrong — a completely different problem from silence. The page says so when it sees it, and points you at Shadow rather than Off: moving a noisy rule to Shadow keeps its evidence coming while you narrow it.

What changed, and when​

Open a watcher's History tab to see every edit: the version number, who made it, when, and the note they left describing the change.

Selecting a version shows what it changed — its rule compared against the rule running now. Added lines are in today's rule; removed lines exist only in the version you selected. Long runs of unchanged lines are collapsed, and the page says how many it hid.

Two things you may see there:

  • Older pipeline on a version means it was compiled by an earlier version of Huntbase's rule engine. What it recorded about itself is history, not a promise about how it would compile today.
  • If you may tune a watcher but not read its rule, the history is still yours to see — the version list is shown, and the rule text says it isn't readable rather than appearing empty.

For a watcher you own, Restore as new version puts an earlier rule back. It is saved as a new version noting where it came from, not a rewind: the history stays complete, and the restore itself appears in it.

Recent detections on the Activity tab are labelled with the rule version that fired, so a change in volume can be traced to a change in the rule.

Check a watcher against your history​

Before turning a stream watcher on, you can run it over telemetry you already have. Open the watcher, and under Looks for use Check against history with a window of 1, 7, 14 or 30 days. You get the number of times it would have fired, how many distinct entities it touched, an expected daily rate, and sample matches. The check reads the Huntbase data lake and every lake of your own that is in federation, the same stores a KQL (Huntbase Lake) query reads.

Two things to read carefully:

  • If the number is shown with a ≥, the rule uses a construct the historical query can only approximate. The count is a floor — the real number is at least that, possibly higher.
  • Intel watchers match indicators from your feeds, so they can't be checked this way either. To look back over your data for an indicator, use Hunt last N days in Intelligence › Indicators.
  • Graph and correlation watchers cannot be checked this way, and the page says so rather than offering a button that does nothing. They are standing queries over live state; there is no history to replay.

Test a watcher on the test lake​

Your own history tells you how often a rule would fire. It can't tell you whether the rule catches the attack it was written for, unless that attack has happened to you. The test lake can: it holds public recordings of real attacks, plus baselines of normal activity.

On a watcher's Looks for tab, the backtest sits above the rule. Switch My telemetry to Test lake. In the watcher editor, Test on attack data beside the Sigma rule does the same and scrolls to it. A watcher that Needs data opens on the test lake, and its banner offers Test on attack data next to the link for sending the missing telemetry. The backtest then runs the rule, or the draft in the editor, over the attack recordings tagged with its ATT&CK techniques, plus the baselines for a false-positive count.

  1. Choose whether to Explain misses and to Include my recent telemetry.
  2. Click Run backtest.
  3. Read the counts: detected, missed, likely false positives and clean baselines, with the rule's quality verdict (Ready, Needs work, Noisy, or Not measured when the test didn't finish) and the result for each recording.
  4. For a missed recording, open Why it missed to see what the attack left in the logs and a draft rule built from it. Test this draft runs the draft the same way.

While a backtest runs it shows its progress and elapsed time, with Cancel. Open the full report shows the complete report. On the Tests tab, On attack data runs the same test-lake check under the watcher's own tests. Nothing here touches your telemetry, except Include my recent telemetry, which adds how often the rule would have fired on your own data to the quality check. See Test a watcher for what each result means.

Test a watcher​

Beta

Tests are part of Intelligence, which is still rolling out. When it isn't enabled for your organization, watchers have no Tests tab.

A watcher's tests are example events it must match and events it must not match. Running them passes each event through the same matching logic the live watcher uses, so you know the rule fires on what it should, and stays quiet on what it shouldn't, before it runs on your data.

Open a watcher and select the Tests tab:

  • Run tests runs every test and shows Pass or Fail for each, with what actually happened, plus the rule version it ran against.
  • For your own watchers, Edit tests lets you add, change and remove tests and Save tests. Each test is a name, an expectation, and an event written as a JSON object of the data source's column names and values (for example process_cmd_line), not the Sigma field names such as CommandLine.
  • Tests for published watchers ship with the rule and are read-only.

The editor has a Tests section under Check against history. Run against draft runs the tests against the rule as you're writing it, before you save. When you edit an existing watcher, its saved tests are loaded so you can see whether your change breaks any of them, and any tests you add or change are saved with the rule when you select Save changes. A new test's event starts with the columns the rule reads. For a new watcher, the tests you add are saved with it when you select Create in Shadow. If saving them fails, the watcher is still created and you can add them again from its Tests tab.

A watcher's rollout needs both kinds of test. The rollout can't start until the watcher has a passing Must match test and a passing Must not match test. Until then it stays at Draft, in Shadow, however many days of Shadow its plan asks for. A test-lake run that detects every attack recording it runs on also counts. The editor's Tests section and the Deploy tab say what's still missing, and Add tests opens the Tests tab.

Open in Intelligence at the top of a watcher opens the same rule in Intelligence › Watcher health, with its precision, volume, promotion hint, an exact backtest and conversion to SIEM query languages.

Write your own watcher​

You can write your own stream watchers as Sigma rules. Click New watcher, or, in the new navigation, New › Watcher in the header from anywhere.

The editor is a loop rather than a text box:

  1. Write the rule. It compiles as you type. When editing, you can leave a short note saying what changed — it is kept with the version and shown in History.
  2. Read what it compiled to — which data surface it binds to and which fields it uses. If it wasn't accepted, the message says exactly why: an unmapped field, a construct that isn't supported, or that the rule belongs on a plane you don't author.
  3. Check the field list. It shows the fields the chosen surface actually provides. A rule referring to a field that isn't there saves happily and can never fire, so the editor shows you the difference up front.
  4. Backtest the draft over your own history, or over the test lake to see whether it catches recorded attacks, before it is saved.

Before you save, choose under When this fires what the watcher will do once it is On: Start hunt and notify or Notify, with who will be told (see When this fires). When you edit an existing watcher this is shown read-only; change it under Deploy in the watcher's panel.

A new watcher is created in Shadow. The confirmation says so and offers Turn on as a separate click — promoting a rule out of Shadow should be a decision you take after seeing it run. Once it is created, its panel opens so you can watch it.

You can also start a watcher from a hunt report: each watcher candidate in the report has Watch for this, which opens the editor with the report's Sigma rule filled in.

Your own watchers are marked Yours in the list, and you can edit or delete them. Graph and correlation patterns are written and published by Huntbase.

note

Some published watchers don't show their rule. Where that happens you can still tune the watcher for your organization, but not read or edit the pattern.

Where watcher output shows up​

  • Needs you — High and Critical detections from Notify watchers wait in the Inbox under Needs you, marked Raised by watcher …. A hunt a watcher starts shows there while it waits on a decision; otherwise it's under Updates.
  • Activity › Insights — detections raised by watchers appear as insights, graph and Sigma watchers alike, with the watcher's name. Set the Origin filter to Watcher, and combine it with Needs review to find the ones nobody has looked at. Some older Sigma detections show Origin Watcher without the watcher's name.
  • One name per firing — a Sigma watcher's detection and the hunt it starts are titled with the watcher's name, and the description names the Sigma rule's own title. Scout doesn't rename a hunt a watcher started.
  • Insight details — the insight's Linked strip names the watcher that raised it (click to open the watcher) and the hunts it led to, with their verdicts, and Seen in lists every store where the event was found. See Insights and One detection, many stores.
  • Hunts — a hunt started by a watcher shows where it came from in its header, for example Started from the detection and Watcher: the watcher's name, linked back to the watcher.
  • Notifications — watcher hunts, detections, tags and digest entries arrive as Hunt Alerts, and through your alert routing as set under When this fires. The daily digest's View digest link opens Activity › Insights filtered to Origin Watcher over the last 24 hours. See Notifications.
tip

Start a new watcher in Shadow, review its Activity for a few days, and promote it to On once you trust the signal.

Next steps​