Yellow JackBook a walkthrough
← All docs

Changelog

From CHANGELOG.md at v0.1.0 ·View the source on GitHub

All notable changes to Yellow Jack are recorded here. The format follows Keep a Changelog, and versions follow Semantic Versioning. docs/RELEASING.md says what a patch release may change and what each release publishes.

This is kept honest by test, not by intention: changelog_test.go fails if this file claims a version that has no tag behind it, fails if a tag exists with no section here, and fails if a package ecosystem the firewall gates goes unmentioned. 0.1.0 is the first release; nothing earlier was back-filled.

Unreleased

0.1.0 - 2026-10-25

The first public release. It publishes the gate, the control plane and the console as ghcr.io/flyyellowjack/yellowjack-{firewall,approval,console}:0.1.0, each built for linux/amd64 and linux/arm64 against Go’s certified FIPS 140-3 module; the Helm chart as oci://ghcr.io/flyyellowjack/charts/yellowjack at 0.1.0, pinned to those images by digest; and the yj CLI for five platforms, with a signed checksum list.

helm install yellowjack oci://ghcr.io/flyyellowjack/charts/yellowjack --version 0.1.0

On the version number: a 0.1.0 tag of an earlier build existed in this repository from 2026-09-27, but its images were never made public, so nobody outside could install it. This release replaces it.

What it does

  • A package firewall for five ecosystems: npm, PyPI, Maven, container images (OCI) and Go modules. Clients point at the gate with one registry line (.npmrc, pip.conf, settings.xml, a registry mirror, GOPROXY). Every package they fetch, transitive dependencies included, is served from your registry or refused with a reason and a next step.
  • Known-malware refusal, first and offline. A feed of published malicious packages (build it from OpenSSF Malicious Packages data with scripts/build-malware-feed.py) is checked before anything else and needs no network, so it keeps enforcing through an upstream outage or in an air gap. Advisories may name every version or one release.
  • A release cooldown. A release younger than FW_MIN_RELEASE_AGE_DAYS (14 days by default) is held back, and the client’s resolver is steered to the newest release old enough. It is on for npm, PyPI, Maven and Go modules; container images carry no trustworthy publish date, so it is not enforced for them.
  • Your own allow and block lists, by package (name@*), by one release, or by a version range on the allow list, re-read while the gate runs. An allow entry outranks a malware advisory by default (FW_ADMIN_OUTRANKS); every such pull is logged and audited.
  • Optional OpenSSF Scorecard scoring of each package’s source repository, from deps.dev or scanned on your own machines, with packages below a threshold held for a person to review. FW_SCORECARD_MODE=off runs the gate on the lists, the malware feed and the cooldown alone.
  • Refusing the bytes, not only the metadata. A lockfile install, a direct blob pull or a chosen file name fetches bytes without asking for metadata; those routes are judged too. Under FW_BYTE_GATE=enforce, a container layer the gate cannot tie to a release is refused.
  • npm build provenance. The Sigstore build-provenance attestation of each npm release is verified inside the gate and logged; FW_ATTESTATION_POLICY=require refuses a release without valid provenance.
  • Install-time code. An npm release that runs code at install can be refused or held for a person (FW_INSTALL_SCRIPT_POLICY, off by default).
  • People decide what scoring cannot. A quarantined release waits in the console’s Decisions queue. A person allows exactly the release that would install, or a scope of releases, and every ruling is recorded. Blocks can be posted to Slack or Microsoft Teams.
  • Report mode (FW_MODE=report): every verdict computed and logged, nothing refused.
  • The console: what the gate is doing, the approval queue, every refusal explained, the policy in force as text, gate health, a per-package lookup, request and download volumes, and the audit log. Sign-in with OIDC (tested with Keycloak) or a shared credential, with Admin and Read-only roles.
  • A decision record you can export (NDJSON): every verdict with the inputs that produced it, including the score, how old the score was, the threshold and a fingerprint of the policy in force, and the file and SHA-256 of the bytes each npm and PyPI install received.
  • yj dry-run: ask the gate what an npm install or pip install would be refused before it runs.
  • Deployment: a Helm chart with a high-availability layout for the gates, a Docker Compose stack, a reference deployment, and tested guides for Keycloak, Nexus Repository and Harbor. An optional Prometheus endpoint (FW_METRICS_LISTEN).
  • Opt-in usage data, off by default. Nothing is sent unless you set APPROVAL_USAGE_URL; the console shows the exact report before you turn it on.

Security

  • Every image is built against the certified FIPS 140-3 Go Cryptographic Module, with Go 1.26.10, and reports at startup whether FIPS mode is on.
  • Every base image is pinned by digest. Services run as a non-root user on a read-only root filesystem and need no writable host directory.
  • The vulnerability scan in CI runs on the same Go toolchain the images are built with, so a new standard-library advisory fails the build instead of passing unnoticed.
  • A credential written into FW_UPSTREAM is masked in the gate’s log.
  • See SECURITY.md for how to report a vulnerability, and docs/RELEASING.md for which releases get fixes.

Known limitations

Stated here rather than discovered later:

  • The approval service has no authentication of its own. Keep it off untrusted networks. The Helm chart’s NetworkPolicy (on by default) admits only the gate and console pods, and the Compose stack publishes it on loopback only.
  • Scorecard scores the source repository, not the published artifact, so a poisoned release of a healthy project is not caught by the score alone. The malware feed, the cooldown, provenance and the byte gate are the layers for that.
  • Enforcement is cooperative. A developer who removes the registry line is not gated. Closing that takes network egress rules (no direct route from build machines to the public registries); TLS interception is not part of this edition.
  • Build-provenance verification covers npm only.
  • Scanning on your own machines (FW_SCORECARD_MODE=local) runs with Docker Compose from this repository. The scheduler and scanner images are not published, and the Helm chart does not run local mode.
  • Editing the lists in the console needs a console image built with git. The published console shows the lists; you edit them in your list files.
  • OIDC sign-in is tested with Keycloak. Other providers are not yet measured.