git-pkgs proxy

Ein Caching-Proxy für Paketregistrierungen. Beschleunigt Paketdownloads durch lokales Caching von Artefakten, reduziert die Bandbreitennutzung und verbessert die Zuverlässigkeit.

Versions-Cooldown

Die meisten Supply-Chain-Angriffe setzen auf Geschwindigkeit: Eine bösartige Version wird veröffentlicht und innerhalb von Minuten von automatisierten Pipelines konsumiert, bevor es jemand bemerkt. Die Cooldown-Funktion fügt neu veröffentlichten Versionen eine Quarantänezeit hinzu. Wenn sie aktiviert ist, entfernt der Proxy Versionen aus Metadaten-Antworten, bis sie ein konfigurierbares Alter überschritten haben.

cooldown:
  default: "3d"              # hide versions published less than 3 days ago
  ecosystems:
    npm: "7d"                # npm gets a longer window
    cargo: "0"               # disable for cargo
  packages:
    "pkg:npm/lodash": "0"    # exempt trusted packages

Ein 3-Tage-Cooldown bedeutet, dass wenn lodash Version 4.18.0 veröffentlicht, deine Builds weiterhin 4.17.21 verwenden, bis 3 Tage vergangen sind. Wenn sich die neue Version als kompromittiert herausstellt, warst du nie exponiert.

Auflösungsreihenfolge: Paket-Override, dann Ökosystem-Override, dann globaler Standard. So kannst du einen konservativen Standard festlegen und Ausnahmen für Pakete schaffen, bei denen du schnellere Updates benötigst. Siehe docs/configuration.md für die vollständige Konfigurationsreferenz.

Artifact Scanning

Cooldown betrachtet nur den Veröffentlichungszeitstempel einer Version — es werden niemals die tatsächlichen Bytes inspiziert. Artifact Scanning schließt diese Lücke: Wenn aktiviert, wird jedes Artefakt in den Speicher überführt und von einem oder mehreren externen Diensten (trivy, ClamAV, Wiz oder allem anderen, das einen kleinen HTTP/JSON-Vertrag spricht) gescannt, bevor es in den Cache übernommen und an Clients ausgeliefert wird.

scanning:
  enabled: true
  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
  scanners:
    - name: clamav
      url: http://clamav-adapter:8080/scan
      mode: block             # a block verdict deletes the artifact and returns 403
    - name: trivy
      url: http://trivy-adapter:8081/scan
      mode: monitor            # findings are logged, never gate caching
      ecosystems: [npm, pypi]

Der Proxy lädt niemals Artefakt-Bytes zu einem Scanner hoch. Jeder Scanner wird mit Paket-Metadaten plus einer kurzlebigen signierten URL benachrichtigt; der Scanner lädt die Bytes selbst aus dem eigenen Speicher des Proxys. Scanner laufen gleichzeitig, und der erste block-Modus-Scanner, der ein Urteil „nicht erlaubt" meldet, gewinnt sofort und bricht die übrigen ab. Siehe docs/configuration.md für die vollständige Konfigurationsreferenz und den HTTP-Vertrag des Scanners.

Unterstützte Registries

Registry	Sprache/Plattform	Cooldown	Abgeschlossen
npm	JavaScript	Ja	✓
Cargo	Rust	Ja	✓
RubyGems	Ruby	Ja	✓
Go proxy	Go		✓
Hex	Elixir	Ja*	✓
pub.dev	Dart	Ja	✓
PyPI	Python	Ja	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	Ja	✓
Composer	PHP	Ja	✓
Conan	C/C++		✓
Conda	Python/R	Ja	✓
CRAN	R		✓
Julia	Julia		✓
Swift	Swift		✓
Container	Docker/OCI		✓
Homebrew	macOS/Linux		✓
Debian	Debian/Ubuntu		✓
RPM	RHEL/Fedora		✓
Alpine	Alpine Linux		✓
Arch	Arch Linux		✗
Chef	Chef		✗
Generic	Any		✓
Helm	Kubernetes		✓
Vagrant	Vagrant		✗

Cooldown erfordert Veröffentlichungszeitstempel in den Metadaten. Registries ohne ein „Ja" in der Cooldown-Spalte stellen entweder keine Zeitstempel bereit oder wurden noch nicht angebunden.

* Hex-Cooldown erfordert das Deaktivieren der Registry-Signaturverifikation (HEX_NO_VERIFY_REPO_ORIGIN=1), da der Proxy die Protobuf-Nutzlast neu kodiert.

Installation

brew install git-pkgs/git-pkgs/proxy

Oder lade ein Binary von der Releases-Seite herunter.

Helm

Installiere das Chart von GHCR und lege die öffentliche URL fest, die Paketmanager-Clients verwenden werden, um den Proxy zu erreichen:

helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
  --set config.data.base_url=https://proxy.example.com

Das Standard-Chart stellt ein Replikat bereit, das auf einem 10 GiB persistenten Volume basiert, SQLite und Dateisystem-Artefaktspeicherung unter /data verwendet. Siehe deploy/charts/proxy/values.yaml für Ingress-, externe Datenbank- und Objektspeicher-Konfigurationsoptionen.

Schnellstart

# Build from source
go build -o proxy ./cmd/proxy

# Run with defaults (listens on :8080)
./proxy

# Run with custom settings
./proxy -listen :3000 -base-url https://proxy.example.com

Der Proxy läuft jetzt. Konfigurieren Sie Ihre Paketmanager so, dass sie ihn verwenden.

OpenAPI (Swagger)

Dieses Repository verwendet swaggo, um eine OpenAPI-Spezifikation aus annotierten Handlern zu generieren.

Generieren Sie die Spezifikation:

go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

Generierte Dateien werden in docs/swagger/ geschrieben.

Wenn der Proxy läuft, rufe die Live-Spezifikation ab von:

• http://localhost:8080/openapi.json

Oder ersetze http://localhost:8080 durch deine konfigurierte Basis-URL. Dieser Link wird auch im Dashboard angezeigt.

Paketmanager konfigurieren

npm

Erstelle oder bearbeite ~/.npmrc:

registry=http://localhost:8080/npm/

Oder pro Projekt in .npmrc festlegen:

registry=http://localhost:8080/npm/

Oder verwenden Sie eine Umgebungsvariable:

npm_config_registry=http://localhost:8080/npm/ npm install

npm audit, pnpm audit, yarn npm audit und npm audit signatures funktionieren über den Proxy: Die Audit- und Signing-Key-Endpunkte werden an die konfigurierte Upstream-Registry weitergeleitet, wobei die Upstream-Authentifizierung angewendet wird. Advisories stammen daher aus der Datenbank des Upstreams, nicht aus den eigenen Schwachstellen- daten des Proxys, und Versionen, die durch cooldown zurückgehalten werden, sind nicht vom Bericht ausgeschlossen.

Cargo

Erstellen oder bearbeiten Sie ~/.cargo/config.toml:

[source.crates-io]
replace-with = "proxy"

[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

Oder lege es pro Projekt in .cargo/config.toml im Projektstammverzeichnis fest.

RubyGems / Bundler

Lege die Gem-Quelle in deiner Gemfile fest:

source "http://localhost:8080/gem"

Global konfigurieren:

gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

Go-Module

Legen Sie die Umgebungsvariable GOPROXY fest:

export GOPROXY=http://localhost:8080/go,direct

Oder in deinem Shell-Profil für Persistenz.

Homebrew

Richte Homebrews JSON-API und Artefakt-Domain auf den Proxy aus:

export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080

Die Artefakt-Domain fungiert als Proxy für Manifeste und Bottle-Blobs unter /v2/homebrew/core/. Das GHCR-Routing ist auf dieses Repository beschränkt. Quellarchive, Cask-Anwendungsdownloads, benutzerdefinierte Tap-Artefakte und Legacy-Flat-File-Bottle-Mirrors verwenden Homebrews normale Fallback-URLs. Lassen Sie den Fallback aktiviert, indem Sie HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK nicht setzen.