Rules

A rule is a saved VFQL query with a cron schedule. Use a rule when you want a detection to run on its own, over new data, again and again. Use an ad-hoc query when you want to look at data once.

Each scheduled run reads only what arrived in the rule's source tables since the rule's last successful run. You do not write a time range in the query, and you cannot set one. The exact model, including why a rule's first run scans nothing, is in Scheduled rules read what changed.

Create a rule

1. Open Rules in the sidebar and click New Rule.
2. Under Basic Information, enter a Query Name. It is required. Add a Description if you like.
3. Turn on Enable rule if the rule should start running on its schedule. A new rule is off by default, and the form reads "Query is paused".
4. Under Query, write the VFQL. The editor checks the query as you type and marks errors in place.
5. Under Schedule, enter a Cron Expression, or click a preset such as Every hour (at minute 0) or Daily at 6:00 AM.
6. Optional: turn on Alert on matches under Alerting. See Alerts.
7. Click Create Rule. The app opens the new rule's page.

A rule that returns the accounts with repeated failed sign-ins in the new data:

SecurityEvents
| where Result == 'Fail'
| summarize failures = count() by Account
| where failures > 5

Through the API, see Create a rule.

Schedules

The schedule is a standard five-field cron expression: minute, hour, day of month, month, day of week.

• Times are UTC. "Daily at midnight" means midnight UTC.
• Each field accepts *, */n, a number, a range such as 1-5, or a comma list. The day of week runs from 0 to 7, where both 0 and 7 are Sunday.
• Vigilfield checks for due rules once a minute, so a run can start up to about a minute after its scheduled time.
• A rule never runs twice at once. While a run is in progress, the rule is not started again.
• Missed times are not replayed one by one. If a rule misses several scheduled times, for example while it was disabled, it runs once to catch up. That one run still reads everything that arrived since the last successful run.

The rule page

Click a rule's name to open its page. It shows:

• Enabled or Disabled, and the status of the last run.
• Total Runs, Successful and Failed counts.
• Coverage: "Covered through" an instant, which is the point up to which the rule has scanned all of its source tables. It reads "Nothing scanned yet" before the first successful run that advanced past a baseline. This is when data arrived in Vigilfield, not when the events in it happened. See What you can see.
• Query, read-only, and Schedule with the cron expression.
• Run History, newest first.

The Rules list also counts rules whose last run Failed, and you can filter it to Enabled or Disabled rules.

Run history and statuses

Every run has one of four statuses:

Run History shows each run as Success, Failed or Running, with its start time and duration.

• A failed run loses nothing. The rule's bookmarks stay where they were, so the next run reads the same data again, plus anything newer. There is nothing to re-run by hand.
• A run whose query fails raises a system alert, "Rule run failed", for your org admins. Later failures of the same rule add hits to that alert while it is open. See System alerts.
• A rule that keeps failing for more than seven days cannot recover. Its bookmark falls out of the table's retained history and every run is refused. The fix is to create the rule again, and the data in between is skipped. See When a pin outlives its versions, the run refuses.
• Run history is kept for six months.

Through the API, see List runs for a rule. Each run there also carries deltas: the exact window it read on each source table.

Result tables

Each run writes its rows to a result table. The result table keeps every row the run returned for seven days, including rows that did not become alerts. Each alert links to the result table of its latest run.

Edit, disable, duplicate and delete

• Edit opens the same form. Editing never resets a rule's bookmarks, so a changed query starts from where the old one stopped. See Edit a rule or Patch a rule in the API.
• Disable stops scheduled runs. Enable starts them again.
• Duplicate, in a rule card's menu, creates a copy named "(Copy)" with the same query, schedule, alerting and enabled state. The copy has scanned nothing: its first run pins a new baseline. See Duplicate a rule.
• Delete removes the rule and cannot be undone. The alerts it opened stay. After the rule is gone, only the org owner, or a team granted read access to all alerts, can see them.

Limits and gotchas

• A rule's first run scans nothing. It records a starting point for each source table. Data that arrived before the rule existed is out of scope; query it ad-hoc.
• Parameters need defaults. The rule form sends no parameter values, so every parameter the query declares with declare query_parameters needs a default. Through the API, you can supply values in query.parameters.
• asof cannot pin a rule's own source table. It still works on a join's right-hand side and inside an in (…) set. See Scheduled rules read what changed.
• A rule's name must not be blank.