git-pkgs proxy

Un proxy con cache per i registri di pacchetti. Velocizza il download dei pacchetti memorizzando localmente gli artefatti, riducendo l'utilizzo della larghezza di banda e migliorando l'affidabilità.

Cooldown delle versioni

La maggior parte degli attacchi alla supply chain si basa sulla velocità: una versione malevola viene pubblicata e consumata dalle pipeline automatizzate in pochi minuti, prima che qualcuno se ne accorga. La funzionalità di cooldown aggiunge un periodo di quarantena alle versioni appena pubblicate. Quando è abilitata, il proxy rimuove le versioni dalle risposte dei metadati finché non hanno superato una soglia configurabile.

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

Un cooldown di 3 giorni significa che quando lodash pubblica la versione 4.18.0, le tue build continuano a usare 4.17.21 finché non sono trascorsi 3 giorni. Se la nuova release si rivela compromessa, non sei mai stato esposto.

Ordine di risoluzione: override del pacchetto, poi override dell'ecosistema, poi default globale. Questo ti permette di impostare un default conservativo e ritagliare eccezioni per i pacchetti in cui hai bisogno di aggiornamenti più rapidi. Vedi docs/configuration.md per il riferimento completo alla configurazione.

Scansione degli artefatti

Il cooldown guarda solo il timestamp di pubblicazione di una versione — non ispeziona mai i byte effettivi. La scansione degli artefatti colma questa lacuna: quando è abilitata, ogni artefatto viene messo in staging nello storage e scansionato da uno o più servizi esterni (trivy, ClamAV, Wiz o qualsiasi altro che parli un piccolo contratto HTTP/JSON) prima di essere committato nella cache e servito ai client.

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]

Il proxy non carica mai i byte degli artefatti su uno scanner. Ogni scanner viene notificato con i metadati del pacchetto più un URL firmato a breve scadenza; lo scanner scarica i byte direttamente dallo storage del proxy. Gli scanner vengono eseguiti in parallelo, e il primo scanner in modalità block che riporta un verdetto di non consentito vince immediatamente, annullando gli altri. Vedi docs/configuration.md per il riferimento completo della configurazione e il contratto HTTP dello scanner.

Registry supportati

Registry	Linguaggio/Piattaforma	Cooldown	Completato
npm	JavaScript	Sì	✓
Cargo	Rust	Sì	✓
RubyGems	Ruby	Sì	✓
Go proxy	Go		✓
Hex	Elixir	Sì*	✓
pub.dev	Dart	Sì	✓
PyPI	Python	Sì	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	Sì	✓
Composer	PHP	Sì	✓
Conan	C/C++		✓
Conda	Python/R	Sì	✓
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		✗

Il cooldown richiede timestamp di pubblicazione nei metadati. I registry senza un "Sì" nella colonna cooldown o non espongono i timestamp o non sono ancora stati configurati.

* Il cooldown di Hex richiede la disabilitazione della verifica della firma del registry (HEX_NO_VERIFY_REPO_ORIGIN=1) poiché il proxy ricodifica il payload protobuf.

Installazione

brew install git-pkgs/git-pkgs/proxy

Oppure scarica un binario dalla pagina delle release.

Helm

Installa il chart da GHCR, impostando l'URL pubblico che i client dei gestori di pacchetti utilizzeranno per raggiungere il proxy:

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

Il chart predefinito distribuisce una replica supportata da un volume persistente da 10 GiB, utilizzando SQLite e archiviazione di artefatti su filesystem sotto /data. Vedi deploy/charts/proxy/values.yaml per le opzioni di configurazione di ingress, database esterno e object-storage.

Avvio Rapido

# 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

Il proxy è ora in esecuzione. Configura i tuoi gestori di pacchetti per utilizzarlo.

OpenAPI (Swagger)

Questo repository utilizza swaggo per generare una specifica OpenAPI dagli handler annotati.

Genera la specifica:

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

I file generati vengono scritti in docs/swagger/.

Quando il proxy è in esecuzione, recupera la specifica live da:

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

Oppure sostituisci http://localhost:8080 con l'URL di base configurato. Questo link è mostrato anche nella dashboard.

Configurazione dei Package Manager

npm

Crea o modifica ~/.npmrc:

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

Oppure imposta per progetto in .npmrc:

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

Oppure utilizza una variabile d'ambiente:

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

npm audit, pnpm audit, yarn npm audit e npm audit signatures funzionano attraverso il proxy: gli endpoint di audit e delle chiavi di firma vengono inoltrati al registry upstream configurato, con l'autenticazione upstream applicata. Gli advisory provengono quindi dal database dell'upstream, non dai dati di vulnerabilità propri del proxy, e le versioni trattenute dal cooldown non sono escluse dal report.

Cargo

Crea o modifica ~/.cargo/config.toml:

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

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

Oppure imposta per progetto in .cargo/config.toml nella radice del tuo progetto.

RubyGems / Bundler

Imposta la sorgente della gem nel tuo Gemfile:

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

Oppure configurare globalmente:

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

Moduli Go

Imposta la variabile d'ambiente GOPROXY:

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

Oppure nel profilo della tua shell per la persistenza.

Homebrew

Punta l'API JSON e il dominio degli artefatti di Homebrew al proxy:

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

Il dominio degli artefatti fa da proxy per manifest e blob delle bottle sotto /v2/homebrew/core/. L'instradamento GHCR è limitato a quel repository. Gli archivi sorgente, i download delle applicazioni cask, gli artefatti dei tap personalizzati e i mirror legacy delle bottle in formato flat-file utilizzano gli URL di fallback normali di Homebrew. Mantieni abilitato il fallback lasciando HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK non impostato.