git-pkgs proxy

Un proxy con caché para registros de paquetes. Acelera las descargas de paquetes almacenando artefactos en caché localmente, lo que reduce el uso de ancho de banda y mejora la fiabilidad.

Enfriamiento de versiones

La mayoría de los ataques a la cadena de suministro dependen de la velocidad: una versión maliciosa se publica y es consumida por pipelines automatizados en cuestión de minutos, antes de que nadie lo note. La función de enfriamiento añade un periodo de cuarentena a las versiones recién publicadas. Cuando se activa, el proxy elimina las versiones de las respuestas de metadatos hasta que hayan superado un umbral 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 enfriamiento de 3 días significa que cuando lodash publica la versión 4.18.0, tus compilaciones siguen usando 4.17.21 hasta que hayan pasado 3 días. Si la nueva versión resulta estar comprometida, nunca estuviste expuesto.

Orden de resolución: anulación de paquete, luego anulación de ecosistema, luego valor predeterminado global. Esto te permite establecer un valor predeterminado conservador y crear excepciones para paquetes donde necesitas actualizaciones más rápidas. Consulta docs/configuration.md para la referencia completa de configuración.

Escaneo de artefactos

El enfriamiento solo examina la marca de tiempo de publicación de una versión — nunca inspecciona los bytes reales. El escaneo de artefactos cierra esa brecha: cuando está habilitado, cada artefacto se almacena en el almacenamiento y es escaneado por uno o más servicios externos (trivy, ClamAV, Wiz, o cualquier otra cosa que hable un pequeño contrato HTTP/JSON) antes de ser confirmado en la caché y servido a los clientes.

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]

El proxy nunca sube los bytes de los artefactos a un escáner. Cada escáner es notificado con metadatos del paquete más una URL firmada de corta duración; el escáner descarga los bytes por sí mismo desde el almacenamiento propio del proxy. Los escáneres se ejecutan de forma concurrente, y el primer escáner en modo block que reporte un veredicto de no permitido gana inmediatamente, cancelando el resto. Consulta docs/configuration.md para la referencia completa de configuración y el contrato HTTP del escáner.

Registros compatibles

Registro	Lenguaje/Plataforma	Enfriamiento	Completado
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		✗

El enfriamiento requiere marcas de tiempo de publicación en los metadatos. Los registros sin un "Sí" en la columna de enfriamiento o bien no exponen marcas de tiempo o aún no han sido integrados.

* El enfriamiento de Hex requiere deshabilitar la verificación de firma del registro (HEX_NO_VERIFY_REPO_ORIGIN=1) ya que el proxy recodifica la carga útil del protobuf.

Instalación

brew install git-pkgs/git-pkgs/proxy

O descarga un binario desde la página de releases.

Helm

Instala el chart desde GHCR, configurando la URL pública que los clientes de gestores de paquetes usarán para acceder al proxy:

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

El chart predeterminado despliega una réplica respaldada por un volumen persistente de 10 GiB, usando SQLite y almacenamiento de artefactos en el sistema de archivos bajo /data. Consulte deploy/charts/proxy/values.yaml para las opciones de configuración de ingress, base de datos externa y almacenamiento de objetos.

Inicio rápido

# 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

El proxy ahora está en ejecución. Configure sus gestores de paquetes para usarlo.

OpenAPI (Swagger)

Este repositorio utiliza swaggo para generar una especificación OpenAPI a partir de los manejadores anotados.

Genere la especificación:

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

Los archivos generados se escriben en docs/swagger/.

Cuando el proxy está en ejecución, obtén la especificación en vivo desde:

http://localhost:8080/openapi.json

O reemplaza http://localhost:8080 con tu URL base configurada. Este enlace también se muestra en el panel de control.

Configuración de gestores de paquetes

npm

Crea o edita ~/.npmrc:

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

O configurar por proyecto en .npmrc:

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

O utilice la variable de entorno:

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

npm audit, pnpm audit, yarn npm audit y npm audit signatures funcionan a través del proxy: los endpoints de auditoría y de claves de firma se pasan al registro upstream configurado, con la autenticación upstream aplicada. Los avisos por lo tanto provienen de la base de datos del upstream, no de los propios datos de vulnerabilidad del proxy, y las versiones retenidas por cooldown no se excluyen del informe.

Cargo

Cree o edite ~/.cargo/config.toml:

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

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

O configúralo por proyecto en .cargo/config.toml en la raíz de tu proyecto.

RubyGems / Bundler

Configura la fuente de gemas en tu Gemfile:

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

O configurar globalmente:

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

Módulos de Go

Establece la variable de entorno GOPROXY:

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

O en el perfil de tu shell para que sea persistente.

Homebrew

Apunta la API JSON y el dominio de artefactos de Homebrew al proxy:

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

proxy v0.7.0