Vigil Selectors

A Vigil selector is the JSON expression that says which alerts a policy rule or an alert resolution applies to. It is the vigil_selector field in the policy rules and alert resolutions API endpoints. The dashboard's rule editor builds one for you visually, but over the API you write it by hand.

A selector is an object whose keys are dotted field paths under finding., location., or artifact.:

{
  "finding.alertType": "criticalCVE",
  "finding.severity": { "$in": ["critical", "high"] },
  "artifact.type": "npm"
}

Top-level fields are implicitly AND-logic: for the selector to match, every field in the object must match.

Fields

Fields describe three families of facts. The values each field takes are the same ones the dashboard's rule editor offers. See Policies for the full value lists.

`location.*` — where the dependency was found

Field	Type	Notes
`location.repo`	string	Repository full name, e.g. `my-org/payments-api`
`location.repoLabel`	string	The repository label grouping several repositories
`location.manifest`	string	Repo-relative path of the manifest or lockfile, e.g. `services/api/package.json`

`artifact.*` — the package itself

Field	Type	Notes
`artifact.type`	string	Ecosystem: `npm`, `pypi`, `maven`, `gem`, `golang`, `nuget`, `cargo`, `composer`, `github`, `vscode`, `huggingface`
`artifact.name`	string	Package name without namespace, e.g. `express`
`artifact.namespace`	string	Namespace or scope, e.g. `@angular`; empty string for unscoped packages
`artifact.version`	string	e.g. `4.17.1` — exact, prefix, suffix, or substring; there are no version ranges
`artifact.published`	date	Publication date — `YYYY-MM-DD` or a relative window with `$before` / `$after`
`artifact.scores.overall`	number	Socket overall health score, `0`–`100`
`artifact.scores.license`	number	License score, `0`–`100`
`artifact.scores.maintenance`	number	Maintenance score, `0`–`100`
`artifact.scores.quality`	number	Quality score, `0`–`100`
`artifact.scores.vulnerability`	number	Vulnerability score, `0`–`100`
`artifact.scores.supplyChain`	number	Supply chain score, `0`–`100`

`finding.*` — what the alert says

Field	Type	Notes
`finding.alertType`	string	e.g. `criticalCVE`, `malware`, `installScripts`
`finding.category`	string	`supplyChainRisk`, `vulnerability`, `quality`, `maintenance`, `license`, `other`
`finding.severity`	string	`critical`, `high`, `medium`, `low`
`finding.priority`	string	Socket's composite priority: `critical`, `high`, `medium`, `low`
`finding.cvss`	number	CVSS base score, `0.0`–`10.0`
`finding.cveId`	string	e.g. `CVE-2024-29041`
`finding.ghsaId`	string	e.g. `GHSA-xvch-5gv4-984h`
`finding.reachability`	string	`reachable`, `maybe_reachable`, `unreachable`, `pending`, `missing_support`, `direct_dependency`, `undeterminable_reachability`, `unknown`, `error`
`finding.fixAvailable`	boolean	An upstream fixed version exists
`finding.hasKEV`	boolean	The CVE is in the CISA Known Exploited Vulnerabilities catalog
`finding.cvePatchStatus`	string	`patch_unavailable`, `patch_available`, `patch_applied` — Socket's patch, distinct from `fixAvailable`

Operators

A bare value means equality. For anything else, use an operator object:

Operator	Meaning
`$ne`	Not equal
`$in` / `$nin`	Matches any / none of a list
`$gt`, `$gte`, `$lt`, `$lte`	Numeric comparison
`$prefix`, `$suffix`, `$includes`	String starts with, ends with, contains
`$contains`	Array field contains the value
`$before`, `$after`	Date comparison; a date like `2026-01-31` (`YYYY-MM-DD`), or relative like `now-7d`, `now-2w`, `now-6m`, `now-1y` (lowercase units: `d`, `w`, `m`, `y`)
`$exists`	Whether the field is present at all

Combining Clauses

Nest selectors with $and, $or, and $not:

{
  "$and": [
    { "finding.category": "vulnerability" },
    { "finding.severity": { "$in": ["critical", "high"] } },
    { "$not": { "location.repo": "my-org/sandbox" } }
  ]
}

This is how the dashboard expresses exceptions: a rule with exceptions becomes a selector whose conditions are ANDed with $not of the exception clauses.

Absent Fields Fail Closed

If a fact is absent for an alert, any condition on that field fails — including negated ones. The common case is location.manifest: transitive dependencies often have no attributed manifest, so a location.manifest condition — even $ne or $nin — will not match those dependencies. Use manifest conditions to narrow, never for catch-alls.

Policies — the rules selectors power, and the value lists for each field.
Resolve Alerts — resolutions take the same selector as their scope.
Updating API Integrations — mapping older Socket API endpoints onto their replacements.

Fields

location.* — where the dependency was found

artifact.* — the package itself

finding.* — what the alert says