git-pkgs proxy

Um proxy de cache para registros de pacotes. Acelera o download de pacotes ao armazenar artefatos em cache localmente, reduzindo o uso de largura de banda e melhorando a confiabilidade.

Cooldown de Versão

A maioria dos ataques à cadeia de suprimentos depende da velocidade: uma versão maliciosa é publicada e consumida por pipelines automatizados em questão de minutos, antes que alguém perceba. O recurso de cooldown adiciona um período de quarentena para versões recém-publicadas. Quando ativado, o proxy remove versões das respostas de metadados até que elas tenham ultrapassado um limite configurável de tempo.

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

Um cooldown de 3 dias significa que, quando o lodash publica a versão 4.18.0, as suas builds continuam a usar a 4.17.21 até passarem 3 dias. Se a nova versão se revelar comprometida, nunca esteve exposto.

Ordem de resolução: override do pacote, depois override do ecossistema, depois predefinição global. Isto permite-lhe definir uma predefinição conservadora e abrir exceções para pacotes onde precisa de atualizações mais rápidas. Consulte docs/configuration.md para a referência completa de configuração.

Análise de Artefactos

O cooldown apenas olha para o timestamp de publicação de uma versão — nunca inspeciona os bytes reais. A análise de artefactos fecha essa lacuna: quando ativada, cada artefacto é colocado em armazenamento temporário e analisado por um ou mais serviços externos (trivy, ClamAV, Wiz, ou qualquer outro que fale um pequeno contrato HTTP/JSON) antes de ser confirmado na cache e servido aos 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]

O proxy nunca envia os bytes dos artefatos para um scanner. Cada scanner é notificado com metadados do pacote mais uma URL assinada de curta duração; o scanner baixa os bytes por conta própria do armazenamento do próprio proxy. Os scanners são executados simultaneamente, e o primeiro scanner em modo block a reportar um veredito de não permitido vence imediatamente, cancelando os restantes. Consulte docs/configuration.md para a referência completa de configuração e o contrato HTTP do scanner.

Registries Suportados

Registry	Linguagem/Plataforma	Cooldown	Concluído
npm	JavaScript	Sim	✓
Cargo	Rust	Sim	✓
RubyGems	Ruby	Sim	✓
Go proxy	Go		✓
Hex	Elixir	Sim*	✓
pub.dev	Dart	Sim	✓
PyPI	Python	Sim	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	Sim	✓
Composer	PHP	Sim	✓
Conan	C/C++		✓
Conda	Python/R	Sim	✓
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	Qualquer		✓
Helm	Kubernetes		✓
Vagrant	Vagrant		✗

O cooldown requer timestamps de publicação nos metadados. Registries sem um "Sim" na coluna de cooldown ou não expõem timestamps ou ainda não foram configurados.

* O cooldown do Hex requer a desativação da verificação de assinatura do registry (HEX_NO_VERIFY_REPO_ORIGIN=1), uma vez que o proxy recodifica o payload protobuf.

Instalação

brew install git-pkgs/git-pkgs/proxy

Ou baixe um binário da página de releases.

Helm

Instale o chart a partir do GHCR, definindo a URL pública que os clientes de gerenciadores de pacotes usarão para acessar o proxy:

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

O chart padrão implanta uma réplica com um volume persistente de 10 GiB, usando SQLite e armazenamento de artefatos no sistema de arquivos em /data. Consulte deploy/charts/proxy/values.yaml para opções de configuração de ingress, banco de dados externo e armazenamento de objetos.

Início 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

O proxy está agora em execução. Configure os seus gestores de pacotes para o utilizar.

OpenAPI (Swagger)

Este repositório utiliza swaggo para gerar uma especificação OpenAPI a partir de handlers anotados.

Gerar a especificação:

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

Os arquivos gerados são gravados em docs/swagger/.

Quando o proxy está em execução, obtenha a especificação ao vivo em:

http://localhost:8080/openapi.json

Ou substitua http://localhost:8080 pela sua URL base configurada. Este link também é exibido no dashboard.

Configurando Gerenciadores de Pacotes

npm

Crie ou edite ~/.npmrc:

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

Ou defina por projeto em .npmrc:

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

Ou use a variável de ambiente:

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

npm audit, pnpm audit, yarn npm audit e npm audit signatures funcionam através do proxy: os endpoints de auditoria e de chave de assinatura são repassados para o registry upstream configurado, com autenticação upstream aplicada. Os avisos, portanto, vêm do banco de dados do upstream, não dos próprios dados de vulnerabilidade do proxy, e as versões retidas pelo cooldown não são excluídas do relatório.

Cargo

Crie ou edite ~/.cargo/config.toml:

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

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

Ou defina por projeto em .cargo/config.toml na raiz do seu projeto.

RubyGems / Bundler

Defina a origem da gem no seu Gemfile:

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

Ou configure globalmente:

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

Módulos Go

Defina a variável de ambiente GOPROXY:

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

Ou no seu perfil de shell para persistência.

Homebrew

Aponte a API JSON e o domínio de artefatos do Homebrew para o proxy:

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

O domínio de artefatos faz proxy de manifestos e blobs de bottles sob /v2/homebrew/core/. O roteamento do GHCR é limitado a esse repositório. Arquivos-fonte, downloads de aplicativos de cask, artefatos de taps personalizados e espelhos legados de bottles em arquivo simples usam as URLs de fallback normais do Homebrew. Mantenha o fallback habilitado deixando HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK sem definir.

Habilite cache_metadata ou defina PROXY_CACHE_METADATA=true para reter as respostas da API JSON do Homebrew para fallback offline. Blobs de bottles e seus manifestos OCI são armazenados em cache sem essa configuração.

proxy v0.7.0