---
updatedAt: 2026-08-27T17:38:04.000Z
agentTools:
  projectIndex: https://docs.socket.dev/llms.txt
---

# 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](https://docs.socket.dev/reference/createorgalertpolicyrule) and [alert resolutions](https://docs.socket.dev/reference/createorgalertresolution) 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.`:

```json
{
  "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](https://docs.socket.dev/docs/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`:

```json
{
  "$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.

## Related Pages

* [Policies](https://docs.socket.dev/docs/policies) — the rules selectors power, and the value lists for each field.
* [Resolve Alerts](https://docs.socket.dev/docs/alert-resolutions) — resolutions take the same selector as their scope.
* [Updating API Integrations](https://docs.socket.dev/docs/updating-api-integrations) — mapping older Socket API endpoints onto their replacements.
* [Translating Alert Triage Payloads](https://docs.socket.dev/docs/translating-triage-payloads) — convert a triage write into a request that includes a selector.
* [Dry-Run Policy and Resolution Writes](https://docs.socket.dev/docs/dry-run-writes) — try a selector write without saving it.