Endpoints du proxy de vulnérabilités

En plus des téléchargements de paquets, BatleHub fait proxy des protocoles de bases de vulnérabilités propres à chaque écosystème. govulncheck, npm audit, dotnet list package --vulnerable et composer audit fonctionnent ainsi sans accès direct à Internet, quand BatleHub est votre seul registre sortant.

Ces endpoints sont distincts de l'analyse de vulnérabilités de BatleHub lui-même ([vulnerability_scan]), qui compare le contenu des artefacts en cache à OSV. Pour cette fonctionnalité, voir Adding a Vulnerability Scanner Source (en anglais).

1. Go — `govulncheck` / base de vulnérabilités Go

La base de vulnérabilités Go (govulndb) est un protocole distinct du proxy de modules Go et demande ses propres endpoints. BatleHub fait proxy des trois :

Endpoint	Méthode	Description
`/proxy/{registry}/v1/index.json`	GET	Index des vulnérabilités (liste de tous les identifiants connus)
`/proxy/{registry}/v1/ID/{id}.json`	GET	L'enregistrement OSV complet d'une vulnérabilité
`/proxy/{registry}/v1/query`	POST	Requête groupée — renvoie les enregistrements correspondant à un ensemble de modules

{id} ne peut contenir que des caractères alphanumériques, des tirets et des points (par exemple GO-2023-1234, CVE-2024-12345). Tout autre caractère donne un 400.

Configuration

L'amont de la base de vulnérabilités se règle registre par registre, par le champ facultatif vuln_db_url.

toml

[[registries]]
type = "goproxy"
name = "go"

# Facultatif. Vaut https://vuln.go.dev par défaut.
# Mettre "" pour désactiver les endpoints /v1/ de ce registre.
# vuln_db_url = "https://vuln.go.dev"

Valeur de `vuln_db_url`	Comportement
absente / `null`	Proxy vers `https://vuln.go.dev` (défaut)
`"https://…"`	Proxy vers l'URL donnée
`""` (chaîne vide)	Désactive les endpoints `/v1/` ; renvoie `404`

Mise en place côté client

Faites pointer GONOSUMCHECK et GOVULNDB vers BatleHub :

export GOPROXY="https://batlehub.example.com/proxy/go,direct"
export GONOSUMCHECK="*"
export GONOSUMDB="*"
export GOVULNDB="https://batlehub.example.com/proxy/go"

Avec authentification :

# Mettez le token dans NETRC pour que govulncheck le reprenne tout seul.
echo "machine batlehub.example.com login user password <token>" >> ~/.netrc
chmod 600 ~/.netrc
export GOVULNDB="https://batlehub.example.com/proxy/go"

Ou lancez govulncheck directement :

GOVULNDB="https://batlehub.example.com/proxy/go" govulncheck ./...

2. npm — `npm audit`

BatleHub fait proxy des deux modes d'audit de npm :

Endpoint	Méthode	Description
`/proxy/{registry}/-/npm/v1/security/advisories/bulk`	POST	Alertes groupées — ce que `npm audit` envoie par défaut
`/proxy/{registry}/-/npm/v1/security/audits/quick`	POST	Audit rapide, pour l'analyse du seul fichier de verrouillage

Les deux transmettent le corps de la requête à l'amont configuré et relaient la réponse telle quelle. Aucun de ces chemins n'est à configurer : ce sont ceux que la CLI npm emploie déjà, donc npm audit les trouve en pointant vers le registre.

Deux anciens chemins répondent encore, et sont à proscrire

/-/npm/v1/audit/quick et /-/npm/v1/audit/bulk sont des alias dépréciés. La CLI npm ne les a jamais envoyés — les premières versions ne servaient que ceux-là, de sorte qu'un npm audit contre BatleHub recevait un 404 et ne signalait rien. Ils restent routés pour les scripts qui les ont codés en dur, et disparaîtront dans une version ultérieure.

Les réponses d'audit sont mises en cache. Un audit répété est servi depuis le cache et, quand la base d'alertes amont est injoignable, BatleHub sert la dernière réponse qu'il a plutôt que d'échouer — un pipeline de CI qui lance npm audit ne s'arrête donc pas parce que npmjs.org est en panne. La réponse porte X-BatleHub-Cache: hit | miss | stale, et stale signifie exactement que ce repli a eu lieu. Mettez serve_stale = false sur le registre si une réponse d'audit périmée est pire pour vous que pas de réponse du tout.

Le corps de la requête fait partie de la clé de cache : deux projets qui auditent des jeux de dépendances différents ne reçoivent jamais la réponse de l'autre.

Configuration

Rien à configurer de plus. Les requêtes d'audit sont transmises au même amont que les téléchargements de paquets (par défaut https://registry.npmjs.org).

toml

[[registries]]
type = "npm"
name = "npm"
# upstreams = ["https://registry.npmjs.org"]  # défaut

Mise en place côté client

Configurez npm pour utiliser le registre BatleHub :

npm config set registry https://batlehub.example.com/proxy/npm/
npm config set //batlehub.example.com/proxy/npm/:_authToken "<token>"

npm audit passera alors automatiquement par BatleHub.

3. NuGet — `dotnet list package --vulnerable`

BatleHub expose une ressource VulnerabilitiesUrl/6.7.0 dans l'index de services NuGet v3, et fait proxy des pages qu'elle référence :

Endpoint	Méthode	Description
`/proxy/{registry}/nuget/v3/vulnerabilities/index.json`	GET	Index du catalogue de vulnérabilités
`/proxy/{registry}/nuget/v3/vulnerabilities/page/{page}`	GET	Une page du catalogue

L'index de services (GET /proxy/{registry}/nuget/v3/index.json) contient :

json

{
  "@id": "https://batlehub.example.com/proxy/<registry>/nuget/v3/vulnerabilities/",
  "@type": "VulnerabilitiesUrl/6.7.0",
  "comment": "NuGet vulnerability database"
}

La CLI dotnet découvre cette URL automatiquement depuis l'index de services.

Configuration

Rien à configurer de plus. Les données de vulnérabilité sont récupérées depuis l'amont NuGet configuré pour le registre (par défaut https://api.nuget.org). Comme les données de vulnérabilité NuGet proviennent toujours de la galerie NuGet, le défaut couvre tous les flux NuGet publics.

toml

[[registries]]
type = "nuget"
name = "nuget"
# upstreams = ["https://api.nuget.org"]  # défaut

Mise en place côté client

Faites pointer votre source NuGet vers BatleHub dans nuget.config :

xml

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="batlehub" value="https://batlehub.example.com/proxy/nuget/nuget/v3/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <batlehub>
      <add key="Username" value="user" />
      <add key="ClearTextPassword" value="<token>" />
    </batlehub>
  </packageSourceCredentials>
</configuration>

Puis lancez :

dotnet list package --vulnerable

4. Composer — `composer audit`

BatleHub fait proxy de l'API d'alertes de sécurité de Packagist qu'utilise composer audit :

Endpoint	Méthode	Description
`/proxy/{registry}/api/security-advisories/`	GET	Interroger les alertes pour un ensemble de paquets

La chaîne de requête entière (par exemple ?packages[]=vendor/pkg&packages[]=other/lib) est transmise inchangée au Packagist amont.

Configuration

Rien à configurer de plus. Les requêtes sont transmises à l'amont configuré pour le registre (par défaut https://packagist.org).

toml

[[registries]]
type = "composer"
name = "packagist"
# upstreams = ["https://packagist.org"]  # défaut

Pour un miroir Packagist privé ou une instance Satis qui expose son propre endpoint d'alertes :

toml

[[registries]]
type = "composer"
name = "internal"
upstreams = ["https://satis.internal.example.com"]

Mise en place côté client

Ajoutez BatleHub comme dépôt Composer :

json

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://batlehub.example.com/proxy/packagist/"
    }
  ],
  "config": {
    "bearer": {
      "batlehub.example.com": "<token>"
    }
  }
}

Puis lancez :

composer audit

5. Les écosystèmes sans API de vulnérabilités proxifiable

Certains écosystèmes atteignent leurs données de vulnérabilité par un autre canal et n'ont besoin de rien de la part de BatleHub :

Écosystème	Outil	Comment il atteint les données	Action BatleHub nécessaire
Cargo / Rust	`cargo audit`	Clone `rustsec/advisory-db` depuis GitHub, comme dépôt git	Aucune — `cargo audit` contourne entièrement le registre de crates
RubyGems	`bundler-audit`	Clone `rubysec/advisory-database` depuis GitHub	Aucune — `bundler-audit` contourne le serveur de gems
PyPI	`pip-audit`	Interroge directement `https://api.osv.dev` par l'API OSV	Aucune — configurez `pip-audit --index-url` pour les paquets ; les données de vulnérabilité sont un canal distinct
Maven	Selon le plugin	La plupart des plugins de sécurité Maven interrogent directement NVD ou OSV	Aucune

Pour Cargo et RubyGems dans un environnement totalement coupé du réseau, il faudrait répliquer séparément les dépôts git d'alertes (via une instance Gitea locale, par exemple) et faire pointer les outils vers ce miroir — c'est hors du périmètre de BatleHub.

Endpoints du proxy de vulnérabilités ​

1. Go — govulncheck / base de vulnérabilités Go ​

Configuration ​

Mise en place côté client ​

2. npm — npm audit ​

Configuration ​

Mise en place côté client ​

3. NuGet — dotnet list package --vulnerable ​

Configuration ​

Mise en place côté client ​

4. Composer — composer audit ​

Configuration ​

Mise en place côté client ​

5. Les écosystèmes sans API de vulnérabilités proxifiable ​

Endpoints du proxy de vulnérabilités

1. Go — `govulncheck` / base de vulnérabilités Go

Configuration

Mise en place côté client

2. npm — `npm audit`

Configuration

Mise en place côté client

3. NuGet — `dotnet list package --vulnerable`

Configuration

Mise en place côté client

4. Composer — `composer audit`

Configuration

Mise en place côté client

5. Les écosystèmes sans API de vulnérabilités proxifiable