From fd3aed0b70c2531001999e497d787c048bfe498b Mon Sep 17 00:00:00 2001 From: Andrew Nesbitt Date: Fri, 4 Sep 2026 14:12:24 +0100 Subject: [PATCH 1/4] Update proxy and manifests docs to current release proxy: add Helm/APK/Swift/Homebrew/generic registries, artifact scanning, ECR auth, GCS/Azure storage, JSONL access log, docker and Helm chart install. manifests: add chef, helm, ips, opam, vagrant to ecosystems. --- content/docs/modules/manifests.md | 2 +- content/docs/tools/proxy.md | 28 +++++++++++++++++++++++++--- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/content/docs/modules/manifests.md b/content/docs/modules/manifests.md index 24b2a68..ca387bc 100644 --- a/content/docs/modules/manifests.md +++ b/content/docs/modules/manifests.md @@ -25,7 +25,7 @@ for _, dep := range result.Dependencies { ## Supported ecosystems -alpine, arch, asdf, bazel, bower, brew, cargo, carthage, clojars, cocoapods, composer, conan, conda, cpan, cran, crystal, deno, docker, dub, elm, gem, git, github-actions, golang, guix, hackage, haxelib, hex, julia, lean, luarocks, maven, nimble, nix, npm, nuget, pre-commit, pub, pypi, rpm, swift, vcpkg. +alpine, arch, asdf, bazel, bower, brew, cargo, carthage, chef, clojars, cocoapods, composer, conan, conda, cpan, cran, crystal, deno, docker, dub, elm, gem, git, github-actions, golang, guix, hackage, haxelib, helm, hex, ips, julia, lean, luarocks, maven, nimble, nix, npm, nuget, opam, pre-commit, pub, pypi, rpm, swift, vagrant, vcpkg. ## Types diff --git a/content/docs/tools/proxy.md b/content/docs/tools/proxy.md index 8defc7c..82330e1 100644 --- a/content/docs/tools/proxy.md +++ b/content/docs/tools/proxy.md @@ -24,15 +24,33 @@ cooldown: When enabled the proxy strips versions from metadata responses until they've aged past the threshold. Resolution order is package PURL, then ecosystem, then global default. The implementation is the [cooldown](../modules/cooldown/) module. +## Artifact scanning + +Cooldown gates on age; scanning gates on content. When enabled, each artifact is staged, handed to one or more external scanners over a small HTTP contract, and only committed to the cache if none of the `block`-mode scanners reject it. + +```yaml +scanning: + enabled: true + scanners: + - name: clamav + url: http://clamav-adapter:8080/scan + mode: block + - name: trivy + url: http://trivy-adapter:8081/scan + mode: monitor +``` + +Scanners receive package metadata and a short-lived signed URL, then pull the bytes themselves; the proxy never uploads artifact content to a scanner. + ## Supported registries -npm, Cargo, RubyGems, Go modules, Hex, pub.dev, PyPI, Maven, Gradle build cache, NuGet, Composer, Conan, Conda, CRAN, Julia, OCI/Docker, Debian/APT, RPM. Cooldown is available wherever the upstream metadata exposes publish timestamps. +npm, Cargo, RubyGems, Go modules, Hex, pub.dev, PyPI, Maven, Gradle build cache, NuGet, Composer, Conan, Conda, CRAN, Julia, Swift, Helm, Homebrew, OCI/Docker, Alpine APK, Debian/APT, RPM, and a generic HTTP-download endpoint for GitHub release assets and tools like mise or aqua. Cooldown is available wherever the upstream metadata exposes publish timestamps. OCI upstreams can use static credentials or ECR's 12-hour tokens with automatic refresh. ## What else it does -The root URL serves a dashboard with cache stats, a package browser, archive source viewer, and version diff. `proxy mirror` pre-populates the cache from PURLs or an SBOM. `/metrics` exposes Prometheus counters. `/api/package`, `/api/vulns`, `/api/outdated`, and `/api/bulk` provide a JSON enrichment API over the same data git-pkgs uses. +The root URL serves a dashboard with cache stats, a package browser, archive source viewer, and version diff. `proxy mirror` pre-populates the cache from PURLs or an SBOM. `/metrics` exposes Prometheus counters and `/health` reports upstream circuit-breaker state. `/api/package`, `/api/vulns`, `/api/outdated`, and `/api/bulk` provide a JSON enrichment API over the same data git-pkgs uses. `access_log.path` writes one JSONL line per request. -Storage is local filesystem by default, S3 or any S3-compatible service via `storage.url`. Metadata lives in SQLite by default or Postgres for multi-node setups. +Storage is local filesystem by default; `storage.url` accepts `s3://` (or any S3-compatible endpoint), `gs://`, or `azblob://`. Metadata lives in SQLite by default or Postgres for multi-node setups. ## Installation @@ -40,6 +58,10 @@ Storage is local filesystem by default, S3 or any S3-compatible service via `sto brew install git-pkgs/git-pkgs/proxy # or go install github.com/git-pkgs/proxy/cmd/proxy@latest +# or +docker run -p 8080:8080 ghcr.io/git-pkgs/proxy:latest +# or +helm install proxy oci://ghcr.io/git-pkgs/charts/proxy ``` [View on GitHub](https://github.com/git-pkgs/proxy) From 8fdbb3d4a85e2db29138d712383363348ef7be1f Mon Sep 17 00:00:00 2001 From: Andrew Nesbitt Date: Fri, 4 Sep 2026 14:14:31 +0100 Subject: [PATCH 2/4] Use Homebrew core formulae for proxy, brief, forge git-pkgs-proxy, git-pkgs-brief, and git-pkgs-forge are in homebrew-core; the tap is no longer needed for these. --- content/docs/modules/forge.md | 2 +- content/docs/tools/brief.md | 2 +- content/docs/tools/proxy.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/modules/forge.md b/content/docs/modules/forge.md index 1016892..ea9f067 100644 --- a/content/docs/modules/forge.md +++ b/content/docs/modules/forge.md @@ -91,7 +91,7 @@ go get github.com/git-pkgs/forge ``` ```bash -brew install git-pkgs/git-pkgs/forge +brew install git-pkgs-forge # or go install github.com/git-pkgs/forge/cmd/forge@latest ``` diff --git a/content/docs/tools/brief.md b/content/docs/tools/brief.md index 2e188c6..9b99ed7 100644 --- a/content/docs/tools/brief.md +++ b/content/docs/tools/brief.md @@ -72,7 +72,7 @@ r, _ := detect.New(knowledgeBase, "/path/to/project").Run() ## Installation ```bash -brew install git-pkgs/git-pkgs/brief +brew install git-pkgs-brief # or go install github.com/git-pkgs/brief/cmd/brief@latest ``` diff --git a/content/docs/tools/proxy.md b/content/docs/tools/proxy.md index 82330e1..522d0c8 100644 --- a/content/docs/tools/proxy.md +++ b/content/docs/tools/proxy.md @@ -5,7 +5,7 @@ title: proxy A caching proxy for package registries. Speeds up installs by caching artifacts locally, and can hide newly published versions until they've aged past a configurable cooldown so automated pipelines aren't first in line for a malicious release. ```bash -brew install git-pkgs/git-pkgs/proxy +brew install git-pkgs-proxy proxy -listen :8080 ``` @@ -55,7 +55,7 @@ Storage is local filesystem by default; `storage.url` accepts `s3://` (or any S3 ## Installation ```bash -brew install git-pkgs/git-pkgs/proxy +brew install git-pkgs-proxy # or go install github.com/git-pkgs/proxy/cmd/proxy@latest # or From e943d6d3386fe78d73b23f006a4dce97920867c9 Mon Sep 17 00:00:00 2001 From: Andrew Nesbitt Date: Fri, 4 Sep 2026 14:16:00 +0100 Subject: [PATCH 3/4] Add tap trust step to pin install instructions --- content/docs/tools/pin.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/tools/pin.md b/content/docs/tools/pin.md index 91f4c12..33bafbf 100644 --- a/content/docs/tools/pin.md +++ b/content/docs/tools/pin.md @@ -57,7 +57,9 @@ The `assets` sub-package is the runtime helper a Go web app uses to consume the ## Installation ```bash -brew install git-pkgs/git-pkgs/pin +brew tap git-pkgs/git-pkgs +brew trust --tap git-pkgs/git-pkgs +brew install pin # or go install github.com/git-pkgs/pin/cmd/pin@latest ``` From 8c97a15a63c703097d1c4ad482fdab5569f5d152 Mon Sep 17 00:00:00 2001 From: Andrew Nesbitt Date: Fri, 4 Sep 2026 14:21:26 +0100 Subject: [PATCH 4/4] Fix release download URLs and record hugo theme module Release assets are versioned (git-pkgs_X.Y.Z_linux_amd64.tar.gz), so releases/latest/download with a fixed filename 404s. Resolve the version from the API first for manual installs, and use git-pkgs/actions/setup for the GitHub Actions examples. go.mod/go.sum: record the hextra theme module hugo requires. --- content/docs/ci-cd.md | 10 ++++++---- content/docs/licenses.md | 11 +++++------ content/docs/sbom.md | 11 +++++------ go.mod | 2 ++ go.sum | 2 ++ 5 files changed, 20 insertions(+), 16 deletions(-) diff --git a/content/docs/ci-cd.md b/content/docs/ci-cd.md index d18cc8b..146ef77 100644 --- a/content/docs/ci-cd.md +++ b/content/docs/ci-cd.md @@ -16,7 +16,7 @@ Installs git-pkgs and initializes the database. The other actions expect this to ```yaml - uses: git-pkgs/actions/setup@v1 with: - version: "0.1.9" # optional, defaults to latest + version: "0.19.0" # optional, defaults to latest ``` ### Dependency diff @@ -74,7 +74,7 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: fetch-depth: 0 @@ -100,7 +100,8 @@ If you need more control or use a different CI system, you can install git-pkgs ```yaml - name: Install git-pkgs run: | - curl -sfL https://github.com/git-pkgs/git-pkgs/releases/latest/download/git-pkgs_0.1.9_linux_amd64.tar.gz \ + v=$(curl -sfL https://api.github.com/repos/git-pkgs/git-pkgs/releases/latest | jq -r .tag_name | sed 's/^v//') + curl -sfL "https://github.com/git-pkgs/git-pkgs/releases/download/v${v}/git-pkgs_${v}_linux_amd64.tar.gz" \ | tar xz -C /usr/local/bin git-pkgs - name: Initialize database @@ -132,7 +133,8 @@ If you maintain [notes](/docs/notes) with a `policy` namespace marking packages dependency-diff: stage: test script: - - curl -sfL https://github.com/git-pkgs/git-pkgs/releases/latest/download/git-pkgs_0.1.9_linux_amd64.tar.gz + - v=$(curl -sfL https://api.github.com/repos/git-pkgs/git-pkgs/releases/latest | jq -r .tag_name | sed 's/^v//') + - curl -sfL "https://github.com/git-pkgs/git-pkgs/releases/download/v${v}/git-pkgs_${v}_linux_amd64.tar.gz" | tar xz -C /usr/local/bin git-pkgs - git-pkgs init - git-pkgs diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD diff --git a/content/docs/licenses.md b/content/docs/licenses.md index 14734d1..b367157 100644 --- a/content/docs/licenses.md +++ b/content/docs/licenses.md @@ -38,15 +38,14 @@ jobs: licenses: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 + with: + fetch-depth: 0 - - name: Install git-pkgs - run: | - curl -sL https://github.com/git-pkgs/git-pkgs/releases/latest/download/git-pkgs-linux-amd64 -o git-pkgs - chmod +x git-pkgs + - uses: git-pkgs/actions/setup@v1 - name: Check licenses - run: ./git-pkgs licenses --allow=MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC + run: git-pkgs licenses --allow=MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC ``` ## Options diff --git a/content/docs/sbom.md b/content/docs/sbom.md index c6ef4da..4bd1fac 100644 --- a/content/docs/sbom.md +++ b/content/docs/sbom.md @@ -41,15 +41,14 @@ jobs: sbom: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 + with: + fetch-depth: 0 - - name: Install git-pkgs - run: | - curl -sL https://github.com/git-pkgs/git-pkgs/releases/latest/download/git-pkgs-linux-amd64 -o git-pkgs - chmod +x git-pkgs + - uses: git-pkgs/actions/setup@v1 - name: Generate SBOM - run: ./git-pkgs sbom --name=${{ github.repository }} > sbom.json + run: git-pkgs sbom --name=${{ github.repository }} > sbom.json - name: Upload to release uses: softprops/action-gh-release@v1 diff --git a/go.mod b/go.mod index ed36345..c4e8356 100644 --- a/go.mod +++ b/go.mod @@ -3,3 +3,5 @@ module github.com/git-pkgs/website go 1.26 toolchain go1.26.7 + +require github.com/imfing/hextra v0.12.3 // indirect diff --git a/go.sum b/go.sum index e69de29..afa8680 100644 --- a/go.sum +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/imfing/hextra v0.12.3 h1:DZHY2rUWYteyzjlHi9r4n7Bb5e2Q+6LXe4C1Dqn0ZjM= +github.com/imfing/hextra v0.12.3/go.mod h1:vi+yhpq8YPp/aghvJlNKVnJKcPJ/VyAEcfC1BSV9ARo=