Allow and deny lists
How Package Firewall allow and deny entries match packages and versions, namespace entries for your own packages, and what an allow entry waives.
Each organization has one allow list and one deny list, curated on the Resolve Platform’s Curation tab at www.vulnes.is/resolve/package-firewall. They can also be written as a PackageList document and applied with vulnetix config apply.
Entry fields
| Field | Values | Notes |
|---|---|---|
listType |
allow, deny |
|
ecosystem |
an ecosystem ID | go, npm, maven, … |
packageName |
the name as the ecosystem’s requests carry it | npm @scope/name, Maven groupId:artifactId, Go module path, Terraform namespace/name, Julia package UUID |
version |
exact version or * |
default *, every version |
scope |
full, bad_actor |
bad_actor waives only the bad-actor block; it exists for entries migrated from the old exceptions table |
reason |
free text | shown in the audit trail |
isActive |
bool | an inactive entry is ignored |
One entry per (list, ecosystem, packageName, version).
Matching
- An exact-version entry wins over a
*entry for that version. - Versions match with or without a leading
v: an entry for1.2.3matches a Go request forv1.2.3. - A check with no version in hand (the whole-package gates, such as the bad-actor gate and the allowlist-only gate) matches only a
*entry, so allowingevil@1.2.3does not unblock all ofevil. - A package on both lists is blocked. The deny list is checked first, in every mode, including
warn.
Namespace entries
An allow entry whose package name ends in /* or :* covers every package under that prefix, at every version. Use it for packages your organization publishes.
| Ecosystem | Entry | Covers | Does not cover |
|---|---|---|---|
| Go | github.com/acme/* |
github.com/acme/tool, github.com/acme/tool/v2 |
github.com/acme-evil/tool |
| npm | @acme/* |
@acme/widget |
@acme-evil/widget |
| Maven | com.acme:* |
com.acme:core |
com.acme.evil:core |
| Rule | Error when broken |
|---|---|
* only as a final /* or :* |
packageName may contain * only as a final "/*" or ":*", for example github.com/acme/* or @acme/* |
| Allow list only | a namespace entry (ending in /* or :*) can only be on the allow list |
Version must be * |
a namespace entry covers every version of every package under it; leave version as * |
| A Go namespace needs a host and an owner | a Go namespace needs a host and an owner, for example github.com/acme/* |
- The prefix ends at a
/or:, so a look-alike namespace never matches. - An entry for the package itself wins over a namespace entry, and a longer namespace wins over a shorter one (
github.com/acme/tool/*beforegithub.com/acme/*). - Deny entries are exact names only, because the deny paths look packages up by exact name.
What an allow entry waives
| Block | Waived by a full allow entry |
|---|---|
| CVSS, EPSS and CESS thresholds | yes |
| KEV, weaponized, active, PoC | yes |
| Bad actor | yes, if the entry’s version is * |
| End of life | yes |
| Version lag | yes |
| Cooldown on Go | yes |
| Cooldown on other ecosystems | yes, if the entry covers every version: the package’s own * entry or a namespace entry. An entry for one exact version still waits out the window, because the metadata filter drops versions without reading per-version entries. |
allowlist_only refusal |
yes, that is its purpose |
| Exact-version malware record | no |
| Known-bad artifact digest | no |
| Inline malware scan verdict | no |
| Deny entry | no |
Conditional entries
An entry declared with the PackageList kind can carry a when: a CEL condition over the requested version. The entry then applies only to versions for which it is true. A conditional deny entry blocks only those versions, and a conditional allow entry waives only for them. Without when, the entry applies to every version it names.
apiVersion: vulnetix.com/v1
kind: PackageList
metadata:
name: reviewed
spec:
list: allow
entries:
- purl: pkg:pypi/requests@2.32.3
reason: CVSS on this release is a false positive for our use.
when: cvss < 9.0 && !kev
The variables are listed on the PackageList page, and the functions and limits on CEL rule expressions. In the firewall, the ones that carry a value are purl, ecosystem, name, version, malware, cvss, epss, cess, kev, eol, exploitMaturity, badActor and now.
A conditional entry is used only where the version’s signals are in hand. These skip it, as if it were not there:
- the whole-package gates, such as the bad-actor gate and the allowlist-only gate
- the cooldown and version-lag waivers, and the bad-actor waiver
- a deny entry for an exact version the Vulnesis API holds no signals for
A condition that fails to evaluate is logged and the entry does not apply: a deny entry does not block, and an allow entry does not waive.
Decisions in Guardian
Every firewall decision is also sent to Guardian, the Vulnesis SIEM, for organisations with Guardian active. It needs no token and does not count against the ingest cap. Decisions land in the product_events table with source package-firewall. See Vulnesis products.
Usage tracking
The proxy stamps lastUsedAt on an entry when live traffic matches it, at most once every 5 minutes per entry, and not during maintenance windows. Matched requests also carry X-Vulnetix-Firewall-List-Entry (the entry ID) and X-Vulnetix-Firewall-List-Version (the version the entry matched). The Resolve Platform uses lastUsedAt for the Flag an entry unused after review.