git-pkgs proxy

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

Période de refroidissement des versions

La plupart des attaques sur la chaîne d'approvisionnement reposent sur la vitesse : 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 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.```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

A 3-day cooldown means that when `lodash` publishes version `4.18.0`, your builds keep using `4.17.21` until 3 days have passed. If the new release turns out to be compromised, you were never exposed.

Resolution order: package override, then ecosystem override, then global default. This lets you set a conservative default and carve out exceptions for packages where you need faster updates. See [docs/configuration.md](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md) for the full config reference.

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

Le cooldown nécessite des horodatages de publication dans les métadonnées. Les registres sans « Oui » dans la colonne cooldown n'exposent pas d'horodatages ou 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`) car le proxy ré-encode la charge utile protobuf.

## Installation```bash
brew install git-pkgs/git-pkgs/proxy

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

Démarrage rapide```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

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érez la spécification :```bash
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/

Or définissez-le par projet dans `.npmrc` :```
registry=http://localhost:8080/npm/

Ou utilisez une variable d’environnement :```bash npm_config_registry=http://localhost:8080/npm/ npm install

### Cargo

Créez ou modifiez `~/.cargo/config.toml` :```toml
[source.crates-io]
replace-with = "proxy"

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

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

RubyGems / Bundler

Définissez la source des gems dans votre Gemfile :```ruby source "http://localhost:8080/gem"

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

Or in your shell profile for persistence.

### Hex (Elixir)

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

Ou définissez la variable d'environnement :```bash export HEX_MIRROR=http://localhost:8080/hex

### pub.dev (Dart/Flutter)

Définissez la variable d'environnement PUB_HOSTED_URL :```bash
export PUB_HOSTED_URL=http://localhost:8080/pub

PyPI (pip)

Configurez pip pour utiliser le proxy :```bash pip install --index-url http://localhost:8080/pypi/simple/ package_name

Or définissez dans `~/.pip/pip.conf` :```ini
[global]
index-url = http://localhost:8080/pypi/simple/

Maven

Ajoutez à votre ~/.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

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

### NuGet

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

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

### Composer (PHP)

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

Or définir globalement :```bash composer config -g repositories.proxy composer http://localhost:8080/composer

### Conan (C/C++)

Ajoutez le proxy en tant que dépôt distant :```bash
conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter

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

Conda

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

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

Ou définir via la commande :```bash
conda config --add channels http://localhost:8080/conda/main

CRAN (R)

Définissez le dépôt dans R :```r options(repos = c(CRAN = "http://localhost:8080/cran"))

Or dans `~/.Rprofile` pour la persistance :```r
local({
  r <- getOption("repos")
  r["CRAN"] <- "http://localhost:8080/cran"
  options(repos = r)
})

Julia

Définissez le serveur Pkg avant de démarrer Julia :```bash export JULIA_PKG_SERVER=http://localhost:8080/julia

Ou à l'intérieur d'une session en cours :```julia
ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()

Docker / Registre de conteneurs

Configurez Docker pour utiliser le proxy comme miroir de registre dans /etc/docker/daemon.json :```json { "registry-mirrors": ["http://localhost:8080"] }

Alors redémarrez Docker :```bash
sudo systemctl restart docker

Ou tirez les images directement :```bash docker pull localhost:8080/library/nginx:latest

### Helm

Configurez chaque dépôt de chart HTTP avec un nom, puis ajoutez l'URL de proxy correspondante à Helm :```yaml
upstream:
  helm:
    bitnami: "https://charts.bitnami.com/bitnami"

I need the input content to translate. Please provide the chunk of Markdown content you'd like me to translate from English to French.```bash helm repo add bitnami http://localhost:8080/helm/bitnami helm repo update helm pull bitnami/nginx

Le proxy met en cache `index.yaml` en utilisant les paramètres normaux de cache de métadonnées et
met en cache les archives de charts après avoir vérifié leur empreinte SHA-256 à partir de l'index.

Pour les charts stockés dans un registre OCI, configurez un upstream OCI nommé et ajoutez
le préfixe réservé `upstream/{name}` à la référence du chart :```yaml
upstream:
  oci:
    ghcr: "https://ghcr.io"

## Installation

To install `nuclei`, you need to install [Go](https://golang.org/dl/) first. Then, run the following command:

```bash
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

Usage

nuclei -h

This will display help for the tool. Here are all the switches it supports.

Usage:
  nuclei [flags]

Flags:
INPUT:
   -u, -target string[]          target URLs/hosts to scan
   -l, -list string              path to file containing a list of target URLs/hosts to scan (one per line)
   -eh, -exclude-hosts string[]  hosts to exclude from the scan (comma-separated)
   -resume string                resume scan using resume.cfg (clustering will be disabled)
   -sa, -scan-all-ips            scan all the IP's associated with dns record
   -iv, -ip-version string[]     IP version to scan either v4,v6 or mixed (comma-separated)
   -lfa, -list-file-allow        allow the list file to be used as a target
``````bash
helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http

Debian / APT

Configurez APT pour utiliser le proxy dans /etc/apt/sources.list.d/proxy.list :``` deb http://localhost:8080/debian stable main contrib

Remplacez vos entrées sources.list existantes, puis :```bash
sudo apt update

The upstream defaults to http://deb.debian.org/debian. To proxy a different APT repository (e.g. Ubuntu), set upstream.debian in the config file or PROXY_UPSTREAM_DEBIAN in the environment:```yaml upstream: debian: "http://archive.ubuntu.com/ubuntu"

### RPM / Yum / DNF

Configurez yum/dnf pour utiliser le proxy dans `/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

Alors :```bash sudo dnf clean all sudo dnf update

## Configuration

Le proxy peut être configuré via :

1. Les options de ligne de commande (priorité la plus élevée)
2. Les variables d'environnement
3. Le fichier de configuration (YAML ou JSON)

### Options de ligne de commande```
-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

Variables d'environnement```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

### Fichier de configuration```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"

Voir la référence de configuration pour chaque clé d’amont, variable d’environnement et URL par défaut.

Exécuter avec un fichier de configuration :```bash ./proxy -config /etc/proxy/config.yaml

### PostgreSQL

SQLite est la solution par défaut et fonctionne bien pour les déploiements à nœud unique. Pour les configurations multi-nœuds ou si vous préférez une base de données gérée, passez à Postgres :```yaml
database:
  driver: "postgres"
  url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"

Ou via des variables d’environnement :```bash PROXY_DATABASE_DRIVER=postgres PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable

Le proxy crée les tables automatiquement lors de la première exécution.

### Stockage S3

Le proxy peut stocker les artefacts en cache dans S3 ou tout service compatible S3 (MinIO, R2, etc.) au lieu du système de fichiers local.```yaml
storage:
  url: "s3://my-bucket-name?region=us-east-1"

Pour les services compatibles S3 comme MinIO :```yaml storage: url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"

Définissez les identifiants via les variables d’environnement AWS standard (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).

### Google Cloud Storage

Le proxy peut stocker les artefacts en cache dans un bucket GCS en utilisant le schéma d’URL `gs://`.```yaml
storage:
  url: "gs://my-bucket-name"

L'authentification utilise les identifiants par défaut de l'application, ce qui signifie qu'aucun identifiant ne doit être intégré dans la configuration ou l'environnement. Les sources prises en charge, dans l'ordre :

GKE Workload Identity — liez le compte de service Kubernetes exécutant le proxy à un compte de service Google disposant de roles/storage.objectAdmin sur le bucket. Le proxy utilisera automatiquement le jeton de la charge de travail.
Compte de service attaché sur GCE, Cloud Run, Cloud Functions, etc.
Variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pointant vers un fichier de clé JSON de compte de service.
gcloud auth application-default login pour le développement local.

Configuration de 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

#### Service direct (URL signées) avec Workload Identity

Lorsque `direct_serve: true` est activé, le proxy émet des redirections HTTP 302 vers des URL GCS présignées. Workload Identity ne fournit pas de clé privée, donc le backend GCS appelle l'[API IAM Credentials `signBlob`](https://docs.cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob). Accordez au compte de service le rôle token-creator sur lui-même :```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"

CLI Commands

serve (default)

Démarre le serveur proxy. Il s'agit de la commande par défaut si aucune n'est spécifiée.```bash proxy serve [flags] proxy [flags] # same as 'proxy serve'

### mirror

Pré-remplir le cache à partir de PURLs, de fichiers SBOM ou de registres entiers. Utile pour garantir la disponibilité hors ligne ou pour réchauffer le cache avant les déploiements.```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]

La commande mirror accepte les mêmes options de stockage et de base de données que serve. Les artefacts déjà mis en cache sont ignorés.

Une API de miroir est également disponible lorsque le serveur est en cours d'exécution :```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

Affiche les statistiques du cache sans exécuter le serveur.```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

Exemple de sortie :``` Cache Statistics

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

Packages by ecosystem: npm 32 cargo 13

Option 2: Install from source

git clone https://github.com/kitploit/kitploit.git
cd kitploit
pip install -r requirements.txt
python setup.py install

Usage

Basic usage

kitploit --help

Example

kitploit search nmap

License

This project is licensed under the MIT License - see the LICENSE file for details.

{
  "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"
}
```
#### Obtenir la version avec les vulnérabilités```bash
curl http://localhost:8080/api/package/npm/lodash/4.17.0
```
## Installation

```bash
# Clone the repository
git clone https://github.com/example/tool.git

# Navigate to the directory
cd tool

# Install dependencies
pip install -r requirements.txt
```

## Usage

To run the tool, use the following command:

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

### Options

| Option | Description |
|--------|-------------|
| `--target` | Specify the target domain or IP address |
| `--verbose` | Enable verbose output for detailed logging |
| `--output` | Save results to a specified file |

## Examples

Here are some common usage examples:

```bash
# Basic scan
python tool.py --target example.com

# Verbose mode with output file
python tool.py --target example.com --verbose --output results.txt
```

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/git-pkgs/proxy/blob/main/LICENSE) file for details.```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"
}
```
#### Vérifier les paquets obsolètes```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"}
    ]
  }'
```
## Installation

```bash
# Clone the repository
git clone https://github.com/example/repo.git

# Navigate to the directory
cd repo

# Install dependencies
pip install -r requirements.txt
```

## Usage

To run the tool, execute the following command:

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

This will scan the target and output the results in the terminal. For more options, run `python main.py --help`.

## Features

- Fast and efficient scanning
- Supports multiple protocols
- Easy to integrate with other tools

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/git-pkgs/proxy/blob/main/LICENSE) file for details.```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
    }
  ]
}
```
#### Recherche groupée de paquets```bash
curl -X POST http://localhost:8080/api/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "purls": [
      "pkg:npm/[email protected]",
      "pkg:pypi/[email protected]"
    ]
  }'
```
```
## 🛡️ **Fonctionnalités de sécurité**

- **Chiffrement de bout en bout** : Toutes les communications sont chiffrées à l'aide d'algorithmes cryptographiques de pointe.
- **Authentification multifacteur** : Prend en charge TOTP, WebAuthn et clés de sécurité matérielles.
- **Contrôle d'accès basé sur les rôles** : Contrôle granulaire des autorisations pour chaque utilisateur et rôle.
- **Journalisation d'audit** : Journalisation complète de toutes les actions sensibles à des fins de conformité et de forensique.
- **Détection d'intrusion** : Surveillance en temps réel des activités suspectes et des violations potentielles.
- **Mise à jour automatique** : Mises à jour de sécurité transparentes sans interruption de service.
``````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"
    }
  }
}
```
### Stats Response (HTTP endpoint)```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"
}
```
## Comment ça fonctionne

1. Le gestionnaire de paquets demande les métadonnées du paquet au proxy
2. Le proxy récupère les métadonnées en amont, réécrit les URL des artefacts pour pointer vers le proxy
3. Le gestionnaire de paquets demande l'artefact (tarball, crate, etc.)
4. Le proxy vérifie le cache local :
   - **Cache hit** : Servi depuis le stockage local
   - **Cache miss** : Récupéré en amont, stocké localement, servi au client
5. Les demandes ultérieures pour le même artefact sont servies depuis le cache```
┌─────────────┐     ┌─────────┐     ┌──────────┐
│   npm/cargo │────▶│  proxy  │────▶│ upstream │
│   client    │◀────│         │◀────│ registry │
└─────────────┘     └─────────┘     └──────────┘
                         │
                         ▼
                    ┌─────────┐
                    │  cache  │
                    │ storage │
                    └─────────┘
```
## Interface Web

Le proxy sert une interface web sous `/ui`. Aucun build frontend séparé n'est nécessaire — les templates et les assets sont intégrés dans le binaire. `GET /` redirige vers `/ui/`. L'interface est montée sous son propre préfixe afin qu'un reverse proxy puisse lui appliquer des règles d'accès différentes de celles des endpoints de paquets (par exemple, exiger une authentification pour `PathPrefix(/ui)` tout en laissant `/npm`, `/pypi`, etc. ouverts aux machines de build).

- **Tableau de bord** (`/ui/`) — statistiques du cache, paquets populaires, artefacts récemment mis en cache et aperçu des vulnérabilités.
- **Guide d'installation** (`/ui/install`) — instructions de configuration par écosystème, pour ne pas avoir à les chercher ici.
- **Navigateur de paquets** (`/ui/packages`) — parcourez tous les paquets en cache avec filtrage par écosystème et tri par hits, taille, nom ou nombre de vulnérabilités.
- **Recherche** (`/ui/search?q=...`) — recherchez les paquets en cache par nom.
- **Détail du paquet** (`/ui/package/{ecosystem}/{name}`) — métadonnées, licence, vulnérabilités et liste des versions d'un paquet. Vous pouvez sélectionner deux versions pour les comparer.
- **Détail de version** (`/ui/package/{ecosystem}/{name}/{version}`) — métadonnées par version, hash d'intégrité, statut du cache d'artefact et compteurs de hits.
- **Navigateur de sources** (`/ui/package/{ecosystem}/{name}/{version}/browse`) — parcourez les fichiers dans les archives en cache avec coloration syntaxique pour les fichiers texte et aperçus d'images.
- **Diff de versions** (`/ui/package/{ecosystem}/{name}/compare/{v1}...{v2}`) — diff côte à côte de deux versions en cache montrant les fichiers ajoutés, supprimés et modifiés.

## Surveillance

Le proxy expose des métriques Prometheus sur `GET /metrics`. Tous les noms de métriques sont préfixés par `proxy_`.

| Métrique | Type | Labels | Description |
|--------|------|--------|-------------|
| `proxy_requests_total` | compteur | `ecosystem`, `status` | Réponses du proxy par écosystème de paquets et statut HTTP |
| `proxy_request_duration_seconds` | histogramme | `ecosystem`, `status` | Durée des requêtes du proxy |
| `proxy_cache_hits_total` | compteur | `ecosystem` | Hits du cache |
| `proxy_cache_misses_total` | compteur | `ecosystem` | Échecs du cache |
| `proxy_cache_size_bytes` | jauge | | Taille totale des artefacts en cache |
| `proxy_cached_artifacts_total` | jauge | | Nombre d'artefacts en cache |
| `proxy_upstream_fetch_duration_seconds` | histogramme | `ecosystem` | Temps passé à récupérer depuis l'amont |
| `proxy_upstream_errors_total` | compteur | `ecosystem`, `error_type` | Échecs de récupération amont |
| `proxy_storage_operation_duration_seconds` | histogramme | `operation` | Latence de lecture/écriture du stockage |
| `proxy_storage_errors_total` | compteur | `operation` | Échecs de lecture/écriture du stockage |
| `proxy_active_requests` | jauge | | Requêtes en cours |
| `proxy_health_probe_failures_total` | compteur | `step` | Échecs de sonde de santé du stockage par étape en échec (`write`, `size`, `read`, `verify`, `delete`). |

La taille du cache et le nombre d'artefacts sont actualisés toutes les 60 secondes. Les métriques restantes sont mises à jour à chaque requête.

### Contrôle de santé

`/health` renvoie un rapport JSON structuré de la santé des sous-systèmes. HTTP 200 si tous les contrôles réussissent ; 503 si l'un d'eux échoue.```json
{
  "status": "ok",
  "checks": {
    "database": {"status": "ok"},
    "storage":  {"status": "ok"}
  }
}
```
Failing checks include an `"error"` field. Storage failures also include a `"step"` field identifying which probe step failed (`write`, `size`, `read`, `verify`, `delete`). When the database check fails, the storage entry reports `{"status": "skipped"}` so the response always carries the same key set.

Storage probe results are cached for `health.storage_probe_interval` (default 30s) to bound the cost of probing remote backends. A probe holds an internal mutex for up to 10 seconds (the hardcoded per-probe timeout), so `/health` is intended as a Kubernetes **readiness** probe rather than a liveness probe — a slow S3 round-trip should pull the pod from rotation, not restart it.

Scrape config for Prometheus:```yaml
scrape_configs:
  - job_name: git-pkgs-proxy
    static_configs:
      - targets: ["localhost:8080"]
```
## Production Deployment

### Service Systemd

Créez `/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
```
Enable and start :```bash
sudo systemctl enable proxy
sudo systemctl start proxy
```
### Docker

Un Dockerfile est inclus dans le dépôt. Construisez et exécutez :```bash
docker build -t proxy .
docker run -p 8080:8080 -v proxy-data:/data proxy
```
Avec Postgres et 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
```
### Derrière un proxy inverse

Lorsque vous exécutez derrière nginx, Apache ou un autre proxy inverse, définissez `base_url` sur votre URL publique :```yaml
base_url: "https://proxy.example.com"
```
Si l'interface est accessible via un nom d'hôte différent de celui des points de terminaison du package — par exemple, l'interface exposée publiquement sur un domaine tandis que les machines de build utilisent un alias réseau Docker — définissez `ui_base_url` séparément. `base_url` est l'URL utilisée par les gestionnaires de packages et la réécriture des métadonnées ; `ui_base_url` est l'URL annoncée aux humains visitant l'interface web (balises canoniques/`og:url` et bannière du guide d'installation) :```yaml
base_url: "http://pkg-proxy:8080"        # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui"  # public UI URL
```
Lorsque non défini, `ui_base_url` prend par défaut la valeur de `base_url`.

> **Avertissement :** le proxy sert l'interface utilisateur et les points de terminaison de paquets sur le même écouteur. Définir `ui_base_url` ne modifie que l'URL que l'interface utilisateur annonce aux humains ; cela n'empêche pas les points de terminaison de paquets d'être accessibles sur le même nom d'hôte et le même port. Lorsque vous placez un reverse proxy public devant le proxy, restreignez la route publique à `PathPrefix(/ui)` (ou l'équivalent de votre proxy), sinon `/npm`, `/pypi` et les autres points de terminaison de paquets restent exposés aux côtés de l'interface utilisateur.

Exemple nginx, restreignant l'hôte public à l'interface utilisateur tout en laissant les points de terminaison de paquets accessibles uniquement sur l'écouteur interne :```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 example using `PathPrefix(/ui)` so the public router only matches UI traffic:```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"
```
## Gestion du cache

Le proxy stocke les artefacts dans le répertoire de stockage configuré avec cette structure :```
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 is stored in SQLite (default) or PostgreSQL. To clear a local cache:```bash
rm -rf ./cache/artifacts/*
rm ./cache/proxy.db
```
Le proxy recréera la base de données au prochain démarrage.

## Compilation à partir des sources

Prérequis :

- Go (la version du projet est déclarée dans `go.mod`)```bash
git clone https://github.com/git-pkgs/proxy.git
cd proxy
go build -o proxy ./cmd/proxy
```
Exécutez les tests :```bash
go test ./...
```
## Licence

GPL-3.0-ou-ultérieure

Lire plus

proxy v0.7.0

Catégories