Enforcement by package type

The Artifact Firewall enforces rules on nine package types: npm, PyPI, Maven, NuGet, Hex, Go, Conda, RPM and VS Code extensions. The Virtual Registry classifies each request and routes only those nine to the firewall, so a rule written against any other ecosystem matches nothing, whatever enable_firewall says.

Enforcement takes two forms, and most ecosystems use both:

  • Filtering a manifest. The response passes through the firewall, which evaluates every version it lists and rewrites the document before it reaches the client. This is what steers a client that asks for “the latest version” away from a version a rule objects to.
  • Authorizing a download. Before an artifact is served, the firewall evaluates that exact version, and a deny becomes a 403 that names the rule, or gives its reason. This is what stops a client that pins a version. An integrated Virtual Registry asks for the evaluation on each download, also one served from its cache.

The difference between deny and hide is the download: both keep a version away from a client resolving “latest”, and only deny blocks a request that names the version outright.

Only GET and HEAD requests are judged, apart from the VS Code Marketplace’s search. Anything else, such as the uploads of a mvn deploy, goes straight to the remote, so publishing a version that a rule denies is not refused, and the rule blocks only its download.

npm

The packument is filtered. Denied and hidden versions stay listed, and the latest dist-tag is re-pointed at the highest version no rule objects to, so a plain npm install resolves to that one. A client that pins a blocked version therefore gets an error saying it is blocked, rather than one saying the version does not exist.

Tarball downloads (/<package>/-/<package>-<version>.tgz) are authorized. A denied version returns 403, a hidden one is served.

Quarantine windows work here without further configuration, since the packument carries a publish time for every version.

PyPI

The simple index is filtered, in both its HTML form and its PEP 691 JSON form. A denied version’s files are removed from the index. A hidden version’s files are marked yanked with the rule’s reason, which is the mechanism PyPI itself uses for a withdrawn release: pip skips a yanked file unless the requirement pins that exact version.

Wheel and sdist downloads are authorized as well. A client that already holds the URL, out of a lock file or an index it cached earlier, is checked against the ruleset rather than served on the strength of what it read then. A denied version returns 403, a hidden one is served.

Quarantine windows on the JSON index use the publish times it carries. The HTML index carries none, so a lookup against the PyPI JSON API is needed, configured with pypi.api_url. Without it, quarantine is not applied to clients using the HTML index.

Maven

maven-metadata.xml is filtered, for releases and for snapshots. Denied and hidden versions are removed from the version list, so a build resolving a range or a LATEST never sees them.

Downloads of a .jar, .war, .aar or .zip below the version directory are authorized, and a denied version returns 403.

Two kinds of file stream through untouched whatever the verdict:

  • Descriptors, meaning .pom and Gradle’s .module. Maven reads the POM of every candidate version while resolving a conflict, including versions it then discards, so denying one would fail the whole resolve rather than the single artifact it describes. A build that pins a denied version reads the POM and is then blocked on the artifact.
  • Checksum and signature sidecars: .sha1, .md5, .sha256, .sha512 and .asc. A client has to be able to verify what it did download.

Quarantine windows need publish times, which Maven repositories do not carry in their metadata. They are looked up through Maven Central’s Solr endpoint, configured with maven.solr_url, falling back to a HEAD request against the POM when Solr answers nothing.

NuGet

The registration pages, the flat container index.json, the service index, and the query and autocomplete responses are all filtered. Denied and hidden versions are removed from the version lists.

.nupkg downloads are authorized, and a denied version returns 403.

Package IDs are matched in any case, as NuGet treats them, so a rule naming Newtonsoft.Json applies to a request for newtonsoft.json. The audit log records the purl lowercased.

Quarantine windows use the published timestamp on the registration catalog entry. The flat container index carries no timestamps, so a client resolving through it is not quarantined.

Hex

The Hex package manifest cannot be filtered. It is a protobuf payload signed by the repository, and the client verifies that signature against a key in its repository configuration before trusting the contents, so any edit makes hex_core reject the response outright rather than fall back to the unedited one.

Enforcement is on the download instead. A tarball request (/tarballs/<name>-<version>.tar) is authorized and a denied version returns 403. A rule that denies a package as a whole, with no version, also blocks the manifest request, which fails the resolve before a version is chosen.

Documentation tarballs are not package content and are not routed through the firewall.

Go

Every GOPROXY resource except the module zip is buffered and evaluated, because resolving a module graph can ask for a .mod on its own without ever fetching the matching .info.

Only @v/list is rewritten, with denied and hidden versions dropped from the version list. The rest are evaluated but never altered in transit, so an allowed .mod or zip reaches the client byte for byte and GOSUMDB verification keeps working through the firewall.

Path Enforcement
@v/list Filtered. Denied and hidden versions are dropped from the list.
@latest Gated. Deny, hide and quarantine all return 404.
@v/<version>.info Gated. Deny returns 403, hide and quarantine return 404. The quarantine window is read from the response’s own Time field.
@v/<version>.mod Gated. Deny returns 403, hide returns 404. It carries no Time field, so quarantine is not checked.
@v/<version>.zip Authorized before the download starts. A denied version returns 403.
/sumdb/... Passed through. The checksum database is not a module resource.

A hide here answers a request that names the version, which it does nowhere else. The 404 is what the go command reads as “not found here”, leaving it to resolve from the filtered @v/list, so the version is absent rather than refused.

GOPROXY has to be a single entry

GOPROXY must name the firewall, or the Virtual Registry integrated with it, alone, with no ,direct and no second proxy after it.

The go command falls through to the next entry of a comma-separated GOPROXY whenever one answers 404 or 410. @latest returns 404 on a deny by design, so that the go command’s own “not found here” fallback sends it to @v/list, which is filtered to the versions no rule objects to. That fallback stays safe only while the firewall is the last word the go command gets. Append ,direct and a denied module is reachable again straight from its version control, past the rule that blocked it.

The requirement is what makes hide and quarantine work at all, not only deny. Both answer 404, and the go command cannot tell either apart from “not found here, try the next entry”. A .info or .mod deny returns 403 rather than 404 for the same reason, since a single denied version has no safe fallback target and has to be a dead end.

Conda

repodata.json is filtered, including its .zst and .gz variants. Denied and hidden versions are dropped from it, so a solver never picks one. A .conda or .tar.bz2 download is authorized, and a denied version returns 403.

Quarantine windows are not applied to conda packages.

Two repodata variants cannot be filtered and are answered 404 rather than passed through: .bz2, for which no re-encoder exists, and CEP-16 sharded repodata (repodata_shards.msgpack.zst and the per-shard files). Clients read the 404 as “variant not offered” and fall back to repodata.json.zst or plain repodata.json, both of which are filtered.

Repodata that cannot be parsed or re-encoded fails open. The upstream body is streamed through unfiltered and the error is logged, so a corrupt index does not take a whole channel down. A denied version in such an index is still blocked when a client tries to download it.

channeldata.json and notices.json stream through, since neither is used for solving.

The channel is carried in the purl namespace, so a rule reads pkg:conda/<channel>/<name>@<version>. An upstream that serves a channel at its root, such as https://conda.anaconda.org/<channel> configured as a remote, yields an empty namespace, and a rule meant to match every channel needs namespace: "*". Build strings such as py311h38be061_0 are not part of the coordinate, so denying a version denies every build of it.

A channel whose repodata sets a CEP-15 base_url pointing at another host moves the downloads off the firewall entirely. Filtering still governs what the solver can pick, but the per-download check is bypassed, so proxy such a channel with its base_url in mind.

Reading a conda-forge-scale index needs max_manifest_size raised above its 64 MiB default.

RPM

primary.xml is filtered, with denied and hidden versions dropped from the package list, and repomd.xml is filtered to match, since it carries the checksum of primary.xml. A .rpm download is authorized, and a denied version returns 403.

A rule names a package as pkg:rpm/<name>@<version>-<release>, with no namespace. The epoch and the architecture are not part of the coordinate, so a rule covers every architecture of a build. Quarantine windows are not applied to RPM packages.

Rewriting repomd.xml invalidates the detached signature the repository publishes for it, so a client that verifies repository metadata rejects the filtered document. Such a client needs repo_gpgcheck=0. Per-package signature verification, gpgcheck=1, is unaffected and should stay on, since the packages themselves are never modified.

Where that trade is not acceptable, preserve_manifest keeps the upstream signature intact and gives up filtering. Downloads are still authorized, so a denied version is blocked when a client fetches it rather than kept out of the index it resolves from.

VS Code

VS Code reaches the Visual Studio Marketplace through two listings, which are both filtered: extensionquery, the POST behind the Extensions view and every search in it, and the per-extension latest endpoint, which VS Code reads to switch an extension to its pre-release version. In both, the download links are rewritten to point at the registry, and each VSIX download is authorized before it starts. The VSIX itself is passed through unmodified, so the signature VS Code checks it against stays valid. Icons, READMEs and the signature are fetched from the Marketplace’s CDN directly, and are never refused.

Unlike every other ecosystem, a deny leaves the extension listed. Its download returns 403, so the attempt is made and recorded in the audit log. Removing it from the listing would mean no attempt and nothing to record. VS Code reports the refused download as a VSIX that is not a valid zip file, End of central directory record signature not found, and shows the user nothing of the rule’s reason, so the audit log is the only place it appears.

hide removes the extension, or the version, from the listings, and the latest endpoint answers 404 for a hidden extension, as the Marketplace does for one that does not exist.

A version in its quarantine window is dropped from the listings and replaced with the newest version on the same track, release or pre-release, that is out of quarantine. Leaving it listed would make VS Code pick it and fail on the download. A download of a quarantined version is still refused. The Marketplace’s download URL carries no publish time, so the firewall stamps one onto each link it rewrites, which redirects.signing keeps a client from editing. With signing on, a download whose URL carries no stamp is refused, and recorded with block_reason: unsigned_url.

A rule names an extension as pkg:vscode-extension/<publisher>/<extension>@<version>, in lowercase. A rule on a version covers the builds for every platform.

Extension packs

An extension pack, such as ms-python.python, installs other extensions with it. VS Code installs a pack all or nothing, so the action on a member decides whether the pack installs:

Action on a member Result
hide The pack installs without the member.
Quarantine The pack installs with an older version of the member.
deny The member’s download fails, and VS Code uninstalls the pack. Members that installed before the failure are left behind.

To keep a member out of a pack, hide it. To block a pack, deny the pack itself, not a member.

Listing size

The Extensions view asks for the full version history of many extensions at once, and such a listing runs past 100 MiB decompressed. max_manifest_size has to be raised from its 64 MiB default, to about 256 MiB, or the firewall refuses the listing and the Extensions view stays empty. The firewall logs upstream manifest exceeds maximum size when it refuses one.

A standalone firewall

A standalone firewall serves the Marketplace from a registry whose remote_url is https://marketplace.visualstudio.com. VS Code has no registry flag. Point extensionsGallery.serviceUrl at the firewall’s /_apis/public/gallery, in the installation’s product.json or through the ExtensionGalleryServiceUrl device policy. In product.json, also clear extensionsGallery.resourceUrlTemplate: while it is set, VS Code builds download URLs from it and ignores the firewall’s rewritten ones.

The Extensions view only connects to a gallery over HTTPS. Over plain HTTP it reports Failed to fetch and the firewall sees no request, although code --install-extension works. Terminate TLS in front of the firewall, and set the registry’s base_url to the HTTPS URL.


®Varnish Software, Wallingatan 12, 111 60 Stockholm, Organization nr. 556805-6203