Rules
The ready-made rules every source gets, and how to write your own: match a field, or count it over a window.
These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.
A rule reads each event a source sends and raises a finding when it matches. Ready-made rules are on for every source the moment it is connected. Custom rules add your own.
Ready-made rules
| Source | Rules | Guide |
|---|---|---|
| GitHub | Secret scanning alert, repository made public or deleted, branch protection or ruleset deleted, deploy key added, new organization owner | GitHub |
| AWS | Root user activity, CloudTrail stopped or changed, console sign in without MFA, repeated failed console sign ins, administrator policy attached, security group opened to the internet, S3 public access block removed, GuardDuty or Security Hub disabled, KMS key scheduled for deletion, access key or IAM user created | AWS |
| Okta, Auth0, your app | Possible credential stuffing, repeated failed sign ins for one account, administrator role granted, MFA turned off, API token created, sign in from a new country | Okta, Auth0, your app |
Switch a ready-made rule off for one source on that source’s page, for example the console sign in rule on an account where only automation signs in.
One finding, not a flood
A rule opens one finding per source and subject, such as the repository, the account, or the trail. A repeat of the same thing updates that finding’s last seen time and does not alert again. Once you resolve it, the next match opens a new one.
Custom rules
From Starter, in Settings, Integrations, Rules. A custom rule has:
| Part | What it is |
|---|---|
| Name | What the finding is called |
| Source | One source, or any |
| Severity | Critical, high, medium, or low |
| Conditions | All must match. Each is a path, a test, and a value |
| Threshold | Optional: only when the conditions match more than N times in M minutes |
A path is header.<Name> for a header or body.<dot.path> for a field, such as body.repository.visibility or body.detail.eventName. The tests:
| Test | Matches when |
|---|---|
eq | The value equals the text |
ne | The value does not equal the text |
contains | The value contains the text |
exists | The path is present |
in | The value is one of a comma separated list |
Examples
| Rule | Conditions | Threshold |
|---|---|---|
| Deploy outside working hours | header.X-GitHub-Event eq deployment | None |
| Lots of new Stripe disputes | body.type eq charge.dispute.created | More than 5 in 60 minutes |
| AWS console sign in from outside the office | body.detail.eventName eq ConsoleLogin, body.detail.sourceIPAddress ne 198.51.100.10 | None |
| Plan | Custom rules |
|---|---|
| Hobby | None |
| Starter | 10 |
| Pro | 50 |
| Business | Unlimited, within fair use |
Test a rule
Press Send a test event on a source to run a sample of its kind through every rule. Ready-made rules raise a test finding; custom rules show whether they would have matched.