git-pkgs proxy

Un proxy di caching per i registry di pacchetti. Accelera il download dei pacchetti memorizzando gli artefatti localmente, riducendo l'utilizzo della larghezza di banda e migliorando l'affidabilità.

Version Cooldown

La maggior parte degli attacchi alla supply chain si basa sulla velocità: una versione dannosa viene pubblicata e consumata dalle pipeline automatizzate nel giro di pochi minuti, prima che chiunque 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 superano una soglia configurabile.```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

Un periodo di raffreddamento 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 rivelasse compromessa, non saresti mai stato esposto.

Ordine di risoluzione: override del pacchetto, poi override dell'ecosistema, poi default globale. Questo ti consente di impostare un default conservativo e creare eccezioni per i pacchetti in cui hai bisogno di aggiornamenti più rapidi. Vedi [docs/configuration.md](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md) per il riferimento completo alla configurazione.

## 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 | | ✓ |
| Container | Docker/OCI | | ✓ |
| Debian | Debian/Ubuntu | | ✓ |
| RPM | RHEL/Fedora | | ✓ |
| Alpine | Alpine Linux | | ✗ |
| Arch | Arch Linux | | ✗ |
| Chef | Chef | | ✗ |
| Generic | Qualsiasi | | ✗ |
| Helm | Kubernetes | | ✗ |
| Swift | Swift | | ✗ |
| 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 collegati.

\* 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```bash
brew install git-pkgs/git-pkgs/proxy

Oppure scarica un binario dalla pagina delle release.

Avvio rapido```bash

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 dai handler annotati.

Genera la specifica:```bash
go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

Generated files are written to docs/swagger/.

When the proxy is running, fetch the live spec from:

http://localhost:8080/openapi.json

Or replace http://localhost:8080 with your configured base URL. This link is also shown on the dashboard.

Configuring Package Managers

npm

Create or edit ~/.npmrc:``` registry=http://localhost:8080/npm/

Or imposta per progetto in `.npmrc`:```
registry=http://localhost:8080/npm/

Oppure usa una variabile d'ambiente:```bash npm_config_registry=http://localhost:8080/npm/ npm install

### Cargo

Crea o modifica `~/.cargo/config.toml`:```toml
[source.crates-io]
replace-with = "proxy"

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

Or imposta per progetto in .cargo/config.toml nella root del tuo progetto.

RubyGems / Bundler

Imposta la sorgente delle gemme nel tuo Gemfile:```ruby source "http://localhost:8080/gem"

Or configurare globalmente:```bash
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:```bash export GOPROXY=http://localhost:8080/go,direct

Or nel tuo profilo di shell per la persistenza.

### Hex (Elixir)

Configura in `~/.hex/hex.config`:```erlang
{default_url, <<"http://localhost:8080/hex">>}.

Oppure imposta la variabile d'ambiente:```bash export HEX_MIRROR=http://localhost:8080/hex

### pub.dev (Dart/Flutter)

Imposta la variabile d'ambiente PUB_HOSTED_URL:```bash
export PUB_HOSTED_URL=http://localhost:8080/pub

PyPI (pip)

Configura pip per utilizzare il proxy:```bash pip install --index-url http://localhost:8080/pypi/simple/ package_name

Or imposta in `~/.pip/pip.conf`:```ini
[global]
index-url = http://localhost:8080/pypi/simple/

Maven

Aggiungi al tuo ~/.m2/settings.xml:```xml proxy central http://localhost:8080/maven/

The `/maven/` endpoint uses Maven Central as primary upstream and falls back to the Gradle Plugin Portal for Gradle plugin marker metadata and related artifacts when the primary upstream returns not found.

For Gradle plugin resolution via the same proxy endpoint:```kotlin
pluginManagement {
  repositories {
    maven(url = "http://localhost:8080/maven/")
  }
}

Gradle HTTP Build Cache

Configura in settings.gradle(.kts):```kotlin buildCache { local { enabled = false } remote { url = uri("http://localhost:8080/gradle/") push = true } }

### NuGet

Configura in `nuget.config`:```xml
<configuration>
  <packageSources>
    <clear />
    <add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
  </packageSources>
</configuration>

Oppure usa la CLI:```bash dotnet nuget add source http://localhost:8080/nuget/v3/index.json -n proxy

### Composer (PHP)

Configura in `composer.json`:```json
{
    "repositories": [
        {
            "type": "composer",
            "url": "http://localhost:8080/composer"
        }
    ]
}

O impostare globalmente:```bash composer config -g repositories.proxy composer http://localhost:8080/composer

### Conan (C/C++)

Aggiungi il proxy come remote:```bash
conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter

Or configura in ~/.conan2/remotes.json.

Conda

Configura in ~/.condarc:```yaml channels:

http://localhost:8080/conda/main
http://localhost:8080/conda/conda-forge default_channels:
http://localhost:8080/conda/main

Oppure imposta tramite comando:```bash
conda config --add channels http://localhost:8080/conda/main

CRAN (R)

Imposta il repository in R:```r options(repos = c(CRAN = "http://localhost:8080/cran"))

Or in `~/.Rprofile` for persistence:```r
local({
  r <- getOption("repos")
  r["CRAN"] <- "http://localhost:8080/cran"
  options(repos = r)
})

Julia

Imposta il server Pkg prima di avviare Julia:```bash export JULIA_PKG_SERVER=http://localhost:8080/julia

Oppure all'interno di una sessione in esecuzione:```julia
ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()

Docker / Container Registry

Configura Docker per utilizzare il proxy come mirror del registry in /etc/docker/daemon.json:```json { "registry-mirrors": ["http://localhost:8080"] }

Allora riavvia Docker:```bash
sudo systemctl restart docker

Or pull images directly:

Or pull images directly:```bash docker pull localhost:8080/library/nginx:latest

### Helm

Configura ogni repository di chart HTTP con un nome, quindi aggiungi l'URL del proxy corrispondente a Helm:```yaml
upstream:
  helm:
    bitnami: "https://charts.bitnami.com/bitnami"

This is a translation task. The input chunk is empty (no content was provided after "INPUT:"). Since there is no text to translate, I will return an empty response, preserving the structure exactly as given.```bash helm repo add bitnami http://localhost:8080/helm/bitnami helm repo update helm pull bitnami/nginx

Il proxy memorizza nella cache `index.yaml` utilizzando le normali impostazioni della cache dei metadati e
memorizza nella cache gli archivi dei chart dopo aver verificato il digest SHA-256 dall'indice.

Per i chart archiviati in un registro OCI, configura un upstream OCI con nome e aggiungi
il prefisso riservato `upstream/{name}` al riferimento del chart:```yaml
upstream:
  oci:
    ghcr: "https://ghcr.io"

## 🛠️ Caratteristiche

- **Rilevamento in tempo reale**: Monitora continuamente le attività di rete per identificare potenziali minacce.
- **Analisi avanzata**: Utilizza algoritmi di apprendimento automatico per rilevare anomalie.
- **Report dettagliati**: Genera report completi sulle minacce rilevate.
- **Integrazione**: Si integra perfettamente con gli strumenti SIEM esistenti.
- **Open Source**: Completamente gratuito e personalizzabile.

## 📦 Installazione

```bash
git clone https://github.com/example/tool.git
cd tool
pip install -r requirements.txt

🚀 Utilizzo

python tool.py --interface eth0 --output report.html

📄 Documentazione

Per una documentazione completa, visitare la pagina wiki.

🤝 Contributi

I contributi sono benvenuti! Si prega di consultare le linee guida per i contributi.

📝 Licenza

Questo progetto è concesso in licenza sotto la MIT License.

helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http
```
### Debian / APT

Configura APT per utilizzare il proxy in `/etc/apt/sources.list.d/proxy.list`:```
deb http://localhost:8080/debian stable main contrib
```
Sostituisci le voci esistenti del tuo sources.list, quindi:```bash
sudo apt update
```
L'impostazione predefinita a monte è `http://deb.debian.org/debian`. Per fare da proxy a un repository APT diverso (ad es. Ubuntu), imposta `upstream.debian` nel file di configurazione o `PROXY_UPSTREAM_DEBIAN` nell'ambiente:```yaml
upstream:
  debian: "http://archive.ubuntu.com/ubuntu"
```
### RPM / Yum / DNF

Configura yum/dnf per utilizzare il proxy in `/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
```
Then:```bash
sudo dnf clean all
sudo dnf update
```
## Configurazione

Il proxy può essere configurato tramite:

1. Flag da riga di comando (priorità più alta)
2. Variabili d'ambiente
3. File di configurazione (YAML o JSON)

### Flag da Riga di Comando```
-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
```
### Variabili d'ambiente```bash
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
```
### File di configurazione```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"

# Optional: version cooldown (see above)
cooldown:
  default: "3d"
```
Vedi il [riferimento alla configurazione](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md#upstream-registries) per ogni chiave upstream, variabile d'ambiente e URL predefinito.

Esegui con file di configurazione:```bash
./proxy -config /etc/proxy/config.yaml
```
### PostgreSQL

SQLite è il database predefinito e funziona bene per distribuzioni a singolo nodo. Per configurazioni multi-nodo o se preferisci un database gestito, passa a Postgres:```yaml
database:
  driver: "postgres"
  url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"
```
Oppure tramite variabili d'ambiente:```bash
PROXY_DATABASE_DRIVER=postgres
PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable
```
Il proxy crea le tabelle automaticamente al primo avvio.

### Archiviazione S3

Il proxy può memorizzare gli artefatti in cache in S3 o in qualsiasi servizio compatibile con S3 (MinIO, R2, ecc.) invece che nel filesystem locale.```yaml
storage:
  url: "s3://my-bucket-name?region=us-east-1"
```
Per i servizi compatibili con S3 come MinIO:```yaml
storage:
  url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"
```
Imposta le credenziali tramite le variabili d'ambiente AWS standard (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).

### Google Cloud Storage

Il proxy può archiviare gli artefatti memorizzati nella cache in un bucket GCS utilizzando lo schema URL `gs://`.```yaml
storage:
  url: "gs://my-bucket-name"
```
L'autenticazione utilizza [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials), il che significa che non è necessario incorporare credenziali nella configurazione o nell'ambiente. Le fonti supportate, in ordine:

- **GKE Workload Identity** — associa l'account di servizio Kubernetes che esegue il proxy a un account di servizio Google che dispone di `roles/storage.objectAdmin` sul bucket. Il proxy utilizzerà automaticamente il token del carico di lavoro.
- **Account di servizio associato** su GCE, Cloud Run, Cloud Functions, ecc.
- **Variabile d'ambiente `GOOGLE_APPLICATION_CREDENTIALS`** che punta a un file di chiave JSON dell'account di servizio.
- **`gcloud auth application-default login`** per lo sviluppo locale.

#### Configurazione di GKE Workload Identity```bash
# 1. Create a Google service account
gcloud iam service-accounts create git-pkgs-proxy \
  --project=PROJECT_ID

# 2. Grant it access to the bucket
gsutil iam ch \
  serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin \
  gs://my-bucket-name

# 3. Bind the Kubernetes service account to it
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]"

# 4. Annotate the Kubernetes service account
kubectl annotate serviceaccount KSA_NAME \
  --namespace=NAMESPACE \
  iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com
```
#### Direct serve (URL firmate) con Workload Identity

Quando `direct_serve: true` è abilitato, il proxy emette reindirizzamenti HTTP 302 verso URL GCS pre-firmati. Workload Identity non fornisce una chiave privata, quindi il backend GCS chiama l'[API `signBlob` di IAM Credentials](https://docs.cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob). Concedi all'account di servizio il ruolo token-creator su se stesso:```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"
```
## Comandi CLI

### serve (predefinito)

Avvia il server proxy. Questo è il comando predefinito se non ne viene specificato nessuno.```bash
proxy serve [flags]
proxy [flags]  # same as 'proxy serve'
```
### mirror

Pre-popola la cache da PURL, file SBOM o interi registry. Utile per garantire la disponibilità offline o per riscaldare la cache prima delle distribuzioni.```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]
```
Il comando mirror accetta gli stessi flag di storage e database di `serve`. Gli artefatti già in cache vengono saltati.

Un'API mirror è disponibile anche quando il server è in esecuzione:```bash
# Start a mirror job
curl -X POST http://localhost:8080/api/mirror \
  -H "Content-Type: application/json" \
  -d '{"purls": ["pkg:npm/[email protected]"]}'

# Check job status
curl http://localhost:8080/api/mirror/mirror-1

# Cancel a running job
curl -X DELETE http://localhost:8080/api/mirror/mirror-1
```
### stats

Mostra le statistiche della cache senza avviare il server.```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
```
Esempio di output:```
Cache Statistics
================

Packages:   45
Versions:   128
Artifacts:  128
Total size: 892.4 MB
Total hits: 1547

Packages by ecosystem:
  npm        32
  cargo      13

Most popular packages:
   1. npm/lodash (342 hits, 24.7 KB)
   2. npm/react (198 hits, 89.3 KB)
   3. cargo/serde (156 hits, 234.1 KB)

Recently cached:
  npm/[email protected] (2024-01-15 14:32, 54.2 KB)
  cargo/[email protected] (2024-01-15 14:28, 412.8 KB)
```
## API Endpoints

### Protocolli del Registry

| Endpoint | Descrizione |
|----------|-------------|
| `GET /` | Dashboard (interfaccia web) |
| `GET /health` | Controllo di salute (JSON; HTTP 200 sano, 503 non sano) |
| `GET /stats` | Statistiche della cache (JSON) |
| `GET /metrics` | Metriche Prometheus |
| `GET /npm/*` | Protocollo del registry npm |
| `GET /cargo/*` | Protocollo dell'indice sparse di Cargo |
| `GET /gem/*` | Protocollo RubyGems |
| `GET /go/*` | Protocollo del proxy dei moduli Go |
| `GET /hex/*` | Protocollo Hex.pm |
| `GET /pub/*` | Protocollo pub.dev |
| `GET /pypi/*` | API semplice/JSON di PyPI |
| `GET /maven/*` | Protocollo del repository Maven |
| `GET /nuget/*` | API NuGet V3 |
| `GET /composer/*` | Protocollo Composer/Packagist |
| `GET /conan/*` | Protocollo Conan C/C++ |
| `GET /conda/*` | Protocollo Conda/Anaconda |
| `GET /cran/*` | Protocollo CRAN (R) |
| `GET /julia/*` | Protocollo del server Pkg di Julia |
| `GET /helm/{repository}/*` | Protocollo del repository di chart Helm HTTP |
| `GET /v2/*` | Protocollo del registry OCI/Docker |
| `GET /debian/*` | Protocollo del repository Debian/APT |
| `GET /rpm/*` | Protocollo del repository RPM/Yum |

### API Mirror

| Endpoint | Descrizione |
|----------|-------------|
| `POST /api/mirror` | Avvia un job di mirroring (corpo JSON con `purls`) |
| `GET /api/mirror/{id}` | Ottieni stato e avanzamento del job |
| `DELETE /api/mirror/{id}` | Annulla un job in esecuzione |

### API di Arricchimento

Il proxy fornisce endpoint REST per l'arricchimento dei metadati dei pacchetti, la scansione delle vulnerabilità e il rilevamento delle versioni obsolete.

| Endpoint | Descrizione |
|----------|-------------|
| `GET /api/package/{ecosystem}/{name}` | Ottieni i metadati del pacchetto |
| `GET /api/package/{ecosystem}/{name}/{version}` | Ottieni i metadati della versione con le vulnerabilità |
| `GET /api/vulns/{ecosystem}/{name}` | Ottieni tutte le vulnerabilità per un pacchetto |
| `GET /api/vulns/{ecosystem}/{name}/{version}` | Ottieni le vulnerabilità per una versione specifica |
| `POST /api/outdated` | Controlla più pacchetti per versioni obsolete |
| `POST /api/bulk` | Ricerca bulk dei metadati dei pacchetti |

#### Ottieni i Metadati del Pacchetto```bash
curl http://localhost:8080/api/package/npm/lodash
```
```
## 🛡️ **Sicurezza e Privacy**

- **Nessuna raccolta di dati**: Questo strumento non raccoglie, memorizza o trasmette alcun dato personale o di utilizzo.
- **Elaborazione locale**: Tutte le operazioni vengono eseguite localmente sul dispositivo dell'utente.
- **Trasparenza**: Il codice sorgente è completamente aperto e disponibile per la revisione.
- **Nessun tracker**: Nessun tracker di terze parti, cookie o meccanismi di analisi sono incorporati.
- **Minime autorizzazioni**: Lo strumento richiede solo le autorizzazioni strettamente necessarie per il suo funzionamento.
``````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"
}
```
#### Ottieni la Versione con Vulnerabilità```bash
curl http://localhost:8080/api/package/npm/lodash/4.17.0
```
```
## Installazione

Per installare **HackBrowserData**, è sufficiente eseguire:

```bash
go get -u github.com/moonD4rk/HackBrowserData
```

**Nota:** HackBrowserData utilizza il modulo `go-sqlite3`, che richiede `CGO_ENABLED=1` durante la compilazione. Se si preferisce una build statica, è possibile compilare con `CGO_ENABLED=0` e utilizzare il driver SQLite puro Go.

### Compilazione

```bash
# Compilazione normale
go build -o hack-browser-data

# Compilazione statica (senza CGO)
CGO_ENABLED=0 go build -o hack-browser-data
```

### Utilizzo

```bash
./hack-browser-data -b all -o results
```

Questo comando esporta i dati di tutti i browser supportati nella directory `results/`.
``````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"
}
```
#### Controlla i Pacchetti Obsoleti```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"}
    ]
  }'
```
## Installazione

```bash
# Clona il repository
git clone https://github.com/example/tool.git

# Entra nella directory
cd tool

# Installa le dipendenze
pip install -r requirements.txt
```

## Utilizzo

```bash
python tool.py --target example.com
```

## Opzioni

| Opzione | Descrizione |
|---------|-------------|
| `--target` | Specifica il dominio o l'IP di destinazione |
| `--verbose` | Abilita l'output dettagliato |
| `--output` | Salva i risultati in un file |

## Esempio

```bash
python tool.py --target example.com --verbose --output results.txt
```

## Licenza

Questo progetto è concesso in licenza sotto la [MIT License](https://github.com/git-pkgs/proxy/blob/main/LICENSE).```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
    }
  ]
}
```
#### Ricerca Bulk dei Pacchetti```bash
curl -X POST http://localhost:8080/api/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "purls": [
      "pkg:npm/[email protected]",
      "pkg:pypi/[email protected]"
    ]
  }'
```
```
## Installazione

### Requisiti

- Python 3.8 o superiore
- pip

### Passaggi

1. Clona il repository:
   ```bash
   git clone https://github.com/example/repo.git
   cd repo
   ```

2. Installa le dipendenze:
   ```bash
   pip install -r requirements.txt
   ```

3. Esegui lo strumento:
   ```bash
   python main.py --help
   ```

## Utilizzo

Dopo l'installazione, puoi iniziare a utilizzare lo strumento. Ecco alcuni comandi di base:

```bash
python main.py scan --target example.com
python main.py report --format json
```

Per ulteriori opzioni, consulta la documentazione ufficiale.
``````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"
    }
  }
}
```
### Risposta delle statistiche (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"
}
```
## Come Funziona

1. Il gestore dei pacchetti richiede i metadati del pacchetto al proxy
2. Il proxy recupera i metadati dall'upstream, riscrive gli URL degli artefatti per puntare al proxy
3. Il gestore dei pacchetti richiede l'artefatto (tarball, crate, ecc.)
4. Il proxy controlla la cache locale:
   - **Cache hit**: Serve dalla memoria locale
   - **Cache miss**: Recupera dall'upstream, salva localmente, serve al client
5. Le richieste successive per lo stesso artefatto vengono servite dalla cache```
┌─────────────┐     ┌─────────┐     ┌──────────┐
│   npm/cargo │────▶│  proxy  │────▶│ upstream │
│   client    │◀────│         │◀────│ registry │
└─────────────┘     └─────────┘     └──────────┘
                         │
                         ▼
                    ┌─────────┐
                    │  cache  │
                    │ storage │
                    └─────────┘
```
## Web Interface

Il proxy serve un'interfaccia web su `/ui`. Non è necessaria una build frontend separata: i template e gli asset sono incorporati nel binario. `GET /` reindirizza a `/ui/`. L'interfaccia è montata sotto il proprio prefisso, così un reverse proxy può applicare regole di accesso diverse rispetto agli endpoint dei pacchetti (ad esempio, richiedendo l'autenticazione per `PathPrefix(/ui)` mentre lascia `/npm`, `/pypi` ecc. aperti alle macchine di build).

- **Dashboard** (`/ui/`) -- statistiche della cache, pacchetti popolari, artefatti recentemente memorizzati nella cache e panoramica delle vulnerabilità.
- **Guida all'installazione** (`/ui/install`) -- istruzioni di configurazione per ecosistema, così non devi cercarle qui.
- **Browser dei pacchetti** (`/ui/packages`) -- sfoglia tutti i pacchetti in cache con filtro per ecosistema e ordinamento per hit, dimensione, nome o numero di vulnerabilità.
- **Ricerca** (`/ui/search?q=...`) -- cerca i pacchetti in cache per nome.
- **Dettaglio pacchetto** (`/ui/package/{ecosystem}/{name}`) -- metadati, licenza, vulnerabilità ed elenco delle versioni per un pacchetto. Puoi selezionare due versioni per confrontarle.
- **Dettaglio versione** (`/ui/package/{ecosystem}/{name}/{version}`) -- metadati per versione, hash di integrità, stato della cache dell'artefatto e conteggi degli hit.
- **Browser dei sorgenti** (`/ui/package/{ecosystem}/{name}/{version}/browse`) -- sfoglia i file all'interno degli archivi in cache con evidenziazione della sintassi per i file di testo e anteprime delle immagini.
- **Diff delle versioni** (`/ui/package/{ecosystem}/{name}/compare/{v1}...{v2}`) -- diff affiancato di due versioni in cache che mostra file aggiunti, rimossi e modificati.

## Monitoraggio

Il proxy espone metriche Prometheus su `GET /metrics`. Tutti i nomi delle metriche sono preceduti dal prefisso `proxy_`.

| Metrica | Tipo | Etichette | Descrizione |
|--------|------|--------|-------------|
| `proxy_requests_total` | contatore | `ecosystem`, `status` | Risposte del proxy per ecosistema di pacchetti e stato HTTP |
| `proxy_request_duration_seconds` | istogramma | `ecosystem`, `status` | Durata delle richieste del proxy |
| `proxy_cache_hits_total` | contatore | `ecosystem` | Hit della cache |
| `proxy_cache_misses_total` | contatore | `ecosystem` | Miss della cache |
| `proxy_cache_size_bytes` | gauge | | Dimensione totale degli artefatti in cache |
| `proxy_cached_artifacts_total` | gauge | | Numero di artefatti in cache |
| `proxy_upstream_fetch_duration_seconds` | istogramma | `ecosystem` | Tempo impiegato per il recupero dall'upstream |
| `proxy_upstream_errors_total` | contatore | `ecosystem`, `error_type` | Errori di recupero dall'upstream |
| `proxy_storage_operation_duration_seconds` | istogramma | `operation` | Latenza di lettura/scrittura dello storage |
| `proxy_storage_errors_total` | contatore | `operation` | Errori di lettura/scrittura dello storage |
| `proxy_active_requests` | gauge | | Richieste in corso |
| `proxy_health_probe_failures_total` | contatore | `step` | Errori del probe di salute dello storage per step non riuscito (`write`, `size`, `read`, `verify`, `delete`). |

La dimensione della cache e il conteggio degli artefatti vengono aggiornati ogni 60 secondi. Le metriche rimanenti vengono aggiornate a ogni richiesta.

### Health Check

`/health` restituisce un report JSON strutturato sullo stato di salute dei sottosistemi. HTTP 200 se tutti i controlli passano; 503 se uno qualsiasi fallisce.```json
{
  "status": "ok",
  "checks": {
    "database": {"status": "ok"},
    "storage":  {"status": "ok"}
  }
}
```
I controlli non riusciti includono un campo `"error"`. I guasti di storage includono anche un campo `"step"` che identifica quale fase della sonda è fallita (`write`, `size`, `read`, `verify`, `delete`). Quando il controllo del database fallisce, la voce di storage riporta `{"status": "skipped"}` così la risposta porta sempre lo stesso set di chiavi.

I risultati delle sonde di storage vengono memorizzati nella cache per `health.storage_probe_interval` (default 30s) per limitare il costo delle sonde sui backend remoti. Una sonda mantiene un mutex interno per un massimo di 10 secondi (il timeout fisso per sonda), quindi `/health` è pensato come una sonda Kubernetes **readiness** piuttosto che una sonda di liveness — un round-trip S3 lento dovrebbe togliere il pod dalla rotazione, non riavviarlo.

Configurazione di scrape per Prometheus:```yaml
scrape_configs:
  - job_name: git-pkgs-proxy
    static_configs:
      - targets: ["localhost:8080"]
```
## Production Deployment

### Servizio Systemd

Crea `/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
```
Abilita e avvia:```bash
sudo systemctl enable proxy
sudo systemctl start proxy
```
### Docker

Nel repository è incluso un Dockerfile. Per creare ed eseguire:```bash
docker build -t proxy .
docker run -p 8080:8080 -v proxy-data:/data proxy
```
Con 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
```
### Dietro un Reverse Proxy

Quando si esegue dietro nginx, Apache o un altro reverse proxy, imposta `base_url` sul tuo URL pubblico:```yaml
base_url: "https://proxy.example.com"
```
Se l'interfaccia utente viene raggiunta tramite un hostname diverso rispetto agli endpoint dei pacchetti — ad esempio, l'interfaccia esposta pubblicamente su un dominio mentre le macchine di build utilizzano un alias di rete Docker — imposta `ui_base_url` separatamente. `base_url` è l'URL utilizzato dai gestori di pacchetti e dalla riscrittura dei metadati; `ui_base_url` è l'URL pubblicizzato agli utenti che visitano l'interfaccia web (tag canonical/`og:url` e banner della guida all'installazione):```yaml
base_url: "http://pkg-proxy:8080"        # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui"  # public UI URL
```
Quando non impostato, `ui_base_url` assume come valore predefinito `base_url`.

> **Avvertenza:** il proxy serve l'interfaccia utente e gli endpoint dei pacchetti sullo stesso listener. Impostare `ui_base_url` modifica solo l'URL che l'interfaccia utente pubblicizza agli utenti; non impedisce che gli endpoint dei pacchetti rimangano raggiungibili sullo stesso hostname e porta. Quando si espone il proxy tramite un reverse proxy pubblico, limitare la rotta pubblica a `PathPrefix(/ui)` (o equivalente del proprio proxy), altrimenti `/npm`, `/pypi` e gli altri endpoint dei pacchetti restano esposti insieme all'interfaccia utente.

Esempio nginx, che limita l'host pubblico all'interfaccia utente lasciando gli endpoint dei pacchetti raggiungibili solo sul 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;
    }
}
```
Traefik esempio utilizzando `PathPrefix(/ui)` così che il router pubblico corrisponda solo al traffico dell'interfaccia utente:```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"
```
## Cache Management

Il proxy memorizza gli artefatti nella directory di storage configurata con questa struttura:```
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
```
Cache metadata è archiviato in SQLite (predefinito) o PostgreSQL. Per cancellare una cache locale:```bash
rm -rf ./cache/artifacts/*
rm ./cache/proxy.db
```
Il proxy ricreerà il database al prossimo avvio.

## Compilazione dal sorgente

Requisiti:

- Go (la versione del progetto è dichiarata in `go.mod`)```bash
git clone https://github.com/git-pkgs/proxy.git
cd proxy
go build -o proxy ./cmd/proxy
```
Esegui i test:```bash
go test ./...
```
## Licenza

GPL-3.0-or-later

proxy v0.7.0

Categorie