git-pkgs proxy

Un proxy de mise en cache pour les registres de paquets. Accélère les téléchargements de paquets en mettant en cache les artefacts localement, réduisant l'utilisation de la bande passante et améliorant la fiabilité.

Délai de refroidissement des versions

La plupart des attaques de la chaîne d'approvisionnement reposent sur la rapidité : une version malveillante est publiée et consommée par des pipelines automatisés en quelques minutes, avant que quiconque ne s'en aperçoive. La fonctionnalité de délai de refroidissement ajoute une période de quarantaine aux versions nouvellement publiées. Lorsqu'elle est activée, le proxy retire les versions des réponses de métadonnées jusqu'à ce qu'elles aient dépassé un seuil configurable.

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 délai de refroidissement de 3 jours signifie que lorsque lodash publie la version 4.18.0, vos builds continuent d'utiliser 4.17.21 jusqu'à ce que 3 jours se soient écoulés. Si la nouvelle version s'avère compromise, vous n'avez jamais été exposé.

Ordre de résolution : override de paquet, puis override d'écosystème, puis valeur par défaut globale. Cela vous permet de définir une valeur par défaut conservatrice et de créer des exceptions pour les paquets où vous avez besoin de mises à jour plus rapides. Voir docs/configuration.md pour la référence complète de configuration.

Analyse des artefacts

Le refroidissement ne regarde que l'horodatage de publication d'une version — il n'inspecte jamais les octets réels. L'analyse des artefacts comble cette lacune : lorsqu'elle est activée, chaque artefact est mis en attente dans le stockage et analysé par un ou plusieurs services externes (trivy, ClamAV, Wiz, ou tout autre service respectant un petit contrat HTTP/JSON) avant d'être validé dans le cache et servi aux clients.

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]

Le proxy ne télécharge jamais les octets des artefacts vers un scanner. Chaque scanner est notifié avec les métadonnées du paquet ainsi qu'une URL signée à durée de vie limitée ; le scanner récupère lui-même les octets depuis le stockage propre du proxy. Les scanners s'exécutent simultanément, et le premier scanner en mode block à signaler un verdict de non-autorisation l'emporte immédiatement, annulant les autres. Voir docs/configuration.md pour la référence complète de configuration et le contrat HTTP des scanners.

Registres pris en charge

Registre	Langage/Plateforme	Cooldown	Terminé
npm	JavaScript	Oui	✓
Cargo	Rust	Oui	✓
RubyGems	Ruby	Oui	✓
Go proxy	Go		✓
Hex	Elixir	Oui*	✓
pub.dev	Dart	Oui	✓
PyPI	Python	Oui	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	Oui	✓
Composer	PHP	Oui	✓
Conan	C/C++		✓
Conda	Python/R	Oui	✓
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		✗

Le cooldown nécessite des horodatages de publication dans les métadonnées. Les registres sans « Oui » dans la colonne cooldown soit n'exposent pas d'horodatages, soit n'ont pas encore été configurés.

* Le cooldown Hex nécessite de désactiver la vérification de signature du registre (HEX_NO_VERIFY_REPO_ORIGIN=1) puisque le proxy réencode la charge utile protobuf.

Installation

brew install git-pkgs/git-pkgs/proxy

Ou téléchargez un binaire depuis la page des releases.

Helm

Installez le chart depuis GHCR, en définissant l'URL publique que les clients des gestionnaires de paquets utiliseront pour atteindre le proxy :

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

Le chart par défaut déploie un replica soutenu par un volume persistant de 10 GiB, utilisant SQLite et un stockage d'artefacts sur système de fichiers sous /data. Voir deploy/charts/proxy/values.yaml pour les options de configuration d'ingress, de base de données externe et de stockage objet.

Démarrage rapide

# 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

Le proxy est maintenant en cours d'exécution. Configurez vos gestionnaires de paquets pour l'utiliser.

OpenAPI (Swagger)

Ce dépôt utilise swaggo pour générer une spécification OpenAPI à partir des gestionnaires annotés.

Générer la spécification :

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

Les fichiers générés sont écrits dans docs/swagger/.

Lorsque le proxy est en cours d'exécution, récupérez la spécification en direct depuis :

http://localhost:8080/openapi.json

Ou remplacez http://localhost:8080 par votre URL de base configurée. Ce lien est également affiché sur le tableau de bord.

Configuration des gestionnaires de paquets

npm

Créez ou modifiez ~/.npmrc :

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

Ou définir par projet dans .npmrc :

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

Ou utilisez la variable d'environnement :

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

npm audit, pnpm audit, yarn npm audit et npm audit signatures fonctionnent à travers le proxy : les points de terminaison d'audit et de clé de signature sont transmis au registre amont configuré, avec l'authentification amont appliquée. Les avis proviennent donc de la base de données de l'amont, et non des données de vulnérabilité propres du proxy, et les versions retenues par le cooldown ne sont pas exclues du rapport.

Cargo

Créez ou modifiez ~/.cargo/config.toml :

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

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

Ou définissez-le par projet dans .cargo/config.toml à la racine de votre projet.

RubyGems / Bundler

Définissez la source de la gem dans votre Gemfile :

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

Ou configurer globalement :

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

Modules Go

Définissez la variable d'environnement GOPROXY :

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

Ou dans votre profil shell pour la persistance.

Homebrew

Faites pointer l'API JSON et le domaine des artefacts de Homebrew vers le proxy :

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

proxy v0.7.0