Vulnerability Proxy Endpoints

BatleHub proxies ecosystem-native vulnerability database protocols in addition to package downloads. This lets govulncheck, npm audit, dotnet list package --vulnerable, and composer audit work without direct internet access when BatleHub is your only outbound registry.

These endpoints are distinct from BatleHub's own SBOM vulnerability scanning ([vulnerability_scan]), which scans the contents of cached artifacts against OSV. See Adding a Vulnerability Scanner Source for that feature.

1. Go — govulncheck / Go Vulnerability Database

The Go Vulnerability Database (govulndb) is a separate protocol from the Go module proxy and requires its own set of endpoints. BatleHub proxies all three:

Endpoint	Method	Description
/proxy/{registry}/v1/index.json	GET	Vulnerability index (list of all known IDs)
/proxy/{registry}/v1/ID/{id}.json	GET	Full OSV record for a single vulnerability
/proxy/{registry}/v1/query	POST	Batch query — returns matching records for a set of modules

{id} must contain only alphanumeric characters, hyphens, and dots (e.g. GO-2023-1234, CVE-2024-12345). Any other character returns 400.

Configuration

The vuln DB upstream is controlled per-registry by the optional vuln_db_url field.

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

# Optional. Defaults to https://vuln.go.dev.
# Set to "" to disable the /v1/ endpoints for this registry.
# vuln_db_url = "https://vuln.go.dev"

vuln_db_url value	Behaviour
absent / null	Proxies to https://vuln.go.dev (default)
"https://…"	Proxies to the given URL
"" (empty string)	Disables the /v1/ endpoints; returns 404

Client setup

Point GONOSUMCHECK and GOVULNDB at BatleHub:

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

With authentication:

# Put the token in NETRC so govulncheck picks it up automatically.
echo "machine batlehub.example.com login user password <token>" >> ~/.netrc
chmod 600 ~/.netrc
export GOVULNDB="https://batlehub.example.com/proxy/go"

Or run govulncheck directly:

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

---

2. npm — npm audit

BatleHub proxies both npm audit modes:

Endpoint	Method	Description
/proxy/{registry}/-/npm/v1/security/advisories/bulk	POST	Bulk advisories — what npm audit sends by default
/proxy/{registry}/-/npm/v1/security/audits/quick	POST	Quick audit, for the lockfile-only scan

Both forward the request body to the configured upstream and relay the response as-is. You do not need to configure either path: they are the paths the npm CLI already uses, so npm audit finds them by pointing at the registry.

Two older paths are still answered, and should not be used

/-/npm/v1/audit/quick and /-/npm/v1/audit/bulk are deprecated aliases. They were never paths the npm CLI sends — earlier releases served only those, so npm audit against BatleHub received a 404 and reported nothing. They remain routed for any script that hard-coded them, and will be removed in a later release.

Audit answers are cached. A repeated audit is answered from the cache, and when the upstream advisory database is unreachable BatleHub serves the last answer it has rather than failing — so a CI pipeline running npm audit does not stop because npmjs.org is having an outage. The response carries X-BatleHub-Cache: hit | miss | stale, and stale means exactly that fallback happened. Set serve_stale = false on the registry if a stale advisory answer is worse for you than none.

The request body is part of the cache key, so two projects auditing different dependency sets never receive each other's answers.

Configuration

No extra config is needed. Audit requests are forwarded to the same upstream as package downloads (default https://registry.npmjs.org).

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

Client setup

Configure npm to use the BatleHub registry:

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

npm audit will then automatically route through BatleHub.

---

3. NuGet — dotnet list package --vulnerable

BatleHub exposes a VulnerabilitiesUrl/6.7.0 resource in the NuGet v3 service index and proxies the pages it references:

Endpoint	Method	Description
/proxy/{registry}/nuget/v3/vulnerabilities/index.json	GET	Vulnerability catalogue index
/proxy/{registry}/nuget/v3/vulnerabilities/page/{page}	GET	Individual catalogue page

The service index (GET /proxy/{registry}/nuget/v3/index.json) includes:

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

The dotnet CLI discovers this URL automatically from the service index.

Configuration

No extra config is needed. Vulnerability data is fetched from the NuGet upstream configured for the registry (default https://api.nuget.org). Since NuGet vulnerability data always originates from the NuGet gallery, the default covers all public NuGet feeds.

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

Client setup

Point your NuGet source at BatleHub in nuget.config:

<?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>

Then run:

dotnet list package --vulnerable

---

4. Composer — composer audit

BatleHub proxies the Packagist security advisory API used by composer audit:

Endpoint	Method	Description
/proxy/{registry}/api/security-advisories/	GET	Query advisories for a set of packages

The full query string (e.g. ?packages[]=vendor/pkg&packages[]=other/lib) is forwarded to the upstream Packagist unchanged.

Configuration

No extra config is needed. Requests are forwarded to the upstream configured for the registry (default https://packagist.org).

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

For a private Packagist mirror or Satis instance that exposes its own advisory endpoint:

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

Client setup

Add BatleHub as your Composer repository:

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

Then run:

composer audit

---

5. Ecosystems Without a Proxy-able Vuln API

Some ecosystems reach their vulnerability data out-of-band and do not require BatleHub to proxy anything:

Ecosystem	Tool	How it reaches vuln data	BatleHub action needed
Cargo / Rust	cargo audit	Clones rustsec/advisory-db from GitHub as a git repo	None — cargo audit bypasses the crate registry entirely
RubyGems	bundler-audit	Clones rubysec/advisory-database from GitHub	None — bundler-audit bypasses the gem server
PyPI	pip-audit	Queries https://api.osv.dev directly via the OSV API	None — configure pip-audit --index-url for packages; vuln data is separate
Maven	Depends on plugin	Most Maven security plugins query NVD or OSV directly	None

For Cargo and RubyGems in fully air-gapped environments you would need to mirror the advisory git repositories separately (e.g. via a local Gitea instance) and point the tools at that mirror — this is outside BatleHub's scope.