HomeDocumentationAPI Reference
Log In
API Reference

Whitelist alerting artifacts automatically

Create whitelist rules from alerting artifacts, and set the alerts those rules cover to pass.

The caller names the artifacts being accepted: individually in artifact_ids, by a result about them in result_ids, or as every artifact currently alerting on the hosts in host_sequence_ids (any combination of the three). A result ID is resolved to the artifact it is about and then treated exactly as if that artifact had been given in artifact_ids, which means the rule built from it covers every sandfly alerting on that artifact rather than only the sandfly whose result was named. One whitelist rule is created per distinct artifact: two artifacts that are the same thing at the chosen strictness -- the same process binary on two hosts, say -- share one rule. Each rule is written as ordinary expr rules over the artifact's properties. The properties are the ones the artifact's match hash is computed from: strictness picks the permissive set (a process's name and path, for example) or the moderate set (adding its binary hash and ownership).

Every rule created gets the host scope in whitelist_scope. With all_sandflies false a rule covers the sandflies currently alerting on the artifacts it was built from; with it true the rule covers every sandfly. Every existing result the new rules cover is changed to a whitelisted pass. Note that the source artifact's own host is not implicitly in scope: a host scope that leaves it out leaves its alert standing.

A source artifact that no rule can be built from is reported in skipped_artifacts with the reason, and the rest of the request proceeds. That covers an artifact that is not currently alerting, one superseded by a newer scan, one of a type with no whitelist properties (an operating system or an error, for instance), and one no sandfly is alerting on when all_sandflies is false. A request that ends up creating no rules -- hosts with nothing alerting on them, for instance -- succeeds with an empty whitelist_rules list.

Rules are not merged into existing whitelist rules, so whitelisting the same artifact twice creates two rules.

Body Params

The artifacts to whitelist, how far the rules should reach, and how strictly they should match.

source_artifacts
object
required

The artifacts being whitelisted. At least one of the three lists must be given; any combination may be.

whitelist_scope
object
required

How far the created rules reach. Every rule the request creates gets this host scope. The sandflies a rule covers are decided per rule.

string
enum
required

How strict of a match is required for the whitelist to apply. Permissive is a looser set of requirements (such as just the process name and file path), whereas moderate requires more properties to match (such as the actual hash of the process so replacement binaries or new versions won't match).

Allowed:
Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json