Setup Debian Proxy with DevGuard Dependency Proxy

System packages are part of your supply chain too. In 2024, the backdoored xz-utils releases 5.6.0 and 5.6.1 (CVE-2024-3094) reached Debian testing and unstable before the backdoor was discovered, and every container image or server that ran apt-get upgrade against those suites pulled them in. Because base images and CI runners install system packages on every build, a single compromised .deb reaches a large part of your infrastructure within hours.

The DevGuard dependency proxy sits between apt and the Debian archive. It applies your package rules to the package lists apt downloads, so apt only sees versions that are allowed, and it checks every .deb download against the OSV dataset to block known malicious packages.

  • Registry URL: <your-devguard-url>/api/v1/dependency-proxy/<secret>/deb/debian
  • Security updates: <your-devguard-url>/api/v1/dependency-proxy/<secret>/deb/debian-security
  • Signing key: <your-devguard-url>/api/v1/dependency-proxy/<secret>/deb/debian/devguard-deb-keyring.asc

Replace <secret> with the dependency proxy secret of your organization, project or repository. The complete proxy URLs and the signing key download are shown in its Dependency Proxy Settings in DevGuard.

Supported suites

ArchiveSuites
debiantrixie, trixie-updates, bookworm, bookworm-updates
debian-securitytrixie-security, bookworm-security

Only the component main and the architectures amd64 and arm64 are supported. Requests for other suites answer 404 Not Found. Other distributions such as Ubuntu and third-party repositories are not supported.

Configuration

The proxy rewrites the package lists and signs them with its own key, one per dependency proxy secret. apt rejects the package lists unless it trusts this key, so install it first:

Since Debian 12, apt reads its package sources from /etc/apt/sources.list.d/debian.sources. Point both the main archive and the security archive at DevGuard and replace the Debian archive key with the proxy key:

Afterwards, the file looks like this:

Types: deb
URIs: https://<your-devguard-url>/api/v1/dependency-proxy/<secret>/deb/debian
Suites: trixie trixie-updates
Components: main
Signed-By: /etc/apt/keyrings/devguard.asc

Types: deb
URIs: https://<your-devguard-url>/api/v1/dependency-proxy/<secret>/deb/debian-security
Suites: trixie-security
Components: main
Signed-By: /etc/apt/keyrings/devguard.asc

Once set, all apt-get update, apt-get install and apt-get upgrade invocations go through DevGuard transparently.

In a Dockerfile, ADD downloads the key without needing curl in the image:

Warning

apt needs the ca-certificates package to connect to an https repository. Slim base images such as debian:trixie-slim do not include it, so install it from the default mirror first or use a DevGuard URL that your image already trusts.

Note

On startup, the proxy blocks all requests until the malicious package database is fully loaded. This initialization period prevents cache poisoning. See Cache Management for details.

How Debian packages are handled

apt does not ask the registry for the versions of a single package like npm or pip do. It downloads one signed package list per suite and picks the newest version from it. DevGuard therefore enforces your rules on the package list itself.

Release times

The Debian archive does not publish when a version was released. A DevGuard background job determines it once per hour for all supported suites and stores the result, so a proxy request never has to compute it:

  1. If a version was already in the archive 30 days ago according to snapshot.debian.org, its pkg.releasedAt is set to that point in time. It is at least 30 days old.
  2. Younger versions get the time they first appeared in the suite according to metasnap.debian.net.
  3. If neither source knows the version, pkg.releasedAt is the current time, so release age rules treat it as brand new.
Warning

Versions older than 30 days all count as exactly 30 days old. A minimum release age rule therefore only works reliably for durations up to 30 days (720h). A longer duration blocks almost every package.

Until the job has run for the first time after an installation, the proxy answers apt-get update with 503 Service Unavailable and a Retry-After header.

Rewriting the package list

On apt-get update, the proxy evaluates your rules for every package in the list. Debian packages are matched as debian/<package>, for example pkg.name == "debian/curl", and expose the suite as pkg.suite, for example pkg.suite.endsWith("-security").

If a version is not allowed, the proxy replaces it:

  1. All binary packages built from the same source package are replaced together, for example curl, libcurl4t64 and libcurl3t64-gnutls. Otherwise apt would mix versions that depend on each other exactly.
  2. The proxy looks for the newest older version of the same suite that all these packages are allowed in.
  3. The package entries are taken from the snapshot at which that version was published, and downloads are served from snapshot.debian.org through the proxy.
  4. If no allowed version exists, the packages are removed from the list and apt reports Unable to locate package or has no installation candidate.

Afterwards, the proxy signs the rewritten package list (InRelease, Release, Release.gpg) with the key you installed. apt verifies it as usual, so the package lists stay tamper-proof between the proxy and your machine.

The rewritten list is cached for 30 minutes per dependency proxy secret. Rule changes take effect after this time at the latest.

Malicious packages

Every .deb download is checked against the malicious package database. A blocked download answers 403 Forbidden and apt aborts the installation.

Custom registries

You can point the proxy at your own Debian mirror, for example a Nexus or Artifactory proxy repository:

The package list is then taken from your registry, while the release times still come from the official Debian archive. Packages that do not exist there, for example internal packages, have no known release time and get pkg.releasedAt set to the current time. A minimum release age rule blocks all of them. Add an allow rule for them, for example:

Replacement versions are still downloaded from snapshot.debian.org.

Testing

DevGuard ships a test package, fake-malicious-package, that is permanently flagged as malicious for all versions. The script below runs apt in a throwaway debian:trixie-slim container whose only package source is the DevGuard proxy, so your own system stays untouched:

fake-malicious-package does not exist in the Debian archive, so apt cannot request it. The proxy checks a download against the malicious package database before fetching it from upstream, so the curl request above proves the check without a real package.

Testing a package rule

Package rules are configured per repository and only apply to requests using the repository's proxy URL, which contains a secret. To verify them, temporarily deny every version of hello. The proxy removes it from the package list, so apt can no longer find it:

Note

The package list of a proxy secret is cached for 30 minutes. If you ran apt-get update against the same proxy URL shortly before changing the rule, the old list may still be served.

To see which packages were replaced with an older version, look for snapshot paths in the package list after apt-get update:

Further Reading

Have feedback? We want to hear from you!

Fields marked with * are required