API

Overview

VDB exposes an OSV-compatible vulnerability database plus AI-era signals (slopsquatting, MCP servers, model artifacts) as a public API. All responses are JSON, encoded as UTF-8.

Auth policy

Two endpoints answer without a key — the slop list and the package gate — on a per-address hourly quota, so the gate can be tried before anything is signed up for. Everything else needs a key, which is free and takes an email (an agent can request one — see below). Authenticated calls are metered per account, not per IP, so users behind a shared egress (an AI provider, office NAT, or campus network) don't rate-limit each other. Search-engine crawlers are never rate-limited.

Traffic limits / abuse defence

VDB ignores normal usage entirely and only catches bots / scraping / burst attacks. Real users almost never hit a cap; the moment traffic spikes past these numbers, it's almost always automation.

1) Identity — every data endpoint needs a key

There is no anonymous tier. Signup is free and takes an email; a key is currently unmetered beyond the abuse limits below. Site search was removed, so the API and the agent integration are the product surface.

2) Minute / hour / day windows

Metered traffic is capped per rolling minute, hour, and day against your account. An unauthenticated request never reaches the account meter: the slop list (60 reads an hour) and the package gate (20 checks an hour, 5 packages each) have their own per-address quota, and everything else is refused with 401 first — so the per-IP axis only guards what you can reach without a key: those two, plus sign-up, log-in and key request. The minute window catches bursts; real users (AI agents, CI bursts, regular devs) stay well below all three. Page reads and search-engine crawls are never metered.

Reference: real usage vs limits — An AI-agent coding session runs 5–10 calls/minute and 30–100/hour on average, well inside every cap. These are abuse limits, not a plan: an account is not billed or throttled for normal use. A full SBOM scan of 1000 packages is one call. A single host sustaining 5+ RPS for a full minute is what trips the minute window.

3) Block durations

Minute cap exceeded → 10 min block (burst defence). Hourly cap → 1h block. Daily cap → 24h block. Response: 429 with reason, axis, and expires_at in the body. Blocks apply only to metered calls — they never refuse page reads or crawls, and an IP block never affects an authenticated account on the same network.

4) The 429 tells the agent what to do

When the limit is hit the 429 body is machine-actionable: agent_action, reason, axis, signup_url and request_key_url, plus a human-readable message. A 401 from a missing or rejected key answers in the same spirit — agent_action, error, because, signup_url, request_key_url — so an AI agent can read it, ask the user for an email, POST it to /v1/auth/request-key, and keep going. The key is emailed; no dashboard visit needed.

5) Manual admin blocks

Admins can manually block an IP/account from /admin/blocks. Those rows are tagged reason=manual.

First call

The simplest call needs no key at all — paste it and see:

curl -X POST -H "Content-Type: application/json" \
  -d '{"packages":["pkg:npm/fast-jsonwebtoken","pkg:pypi/requests@2.19.0"]}' \
  https://vdb.ai.kr/v1/ai/check-packages

A keyless request checks up to 5 packages, 20 requests an hour per address, and says which ones it did not check. Everything else takes the key:

curl -H "Authorization: Bearer $VDB_API_KEY" \
  https://vdb.ai.kr/v1/vulns/GHSA-35jh-r3h4-6jhm

Get an API key

1. **By email (no password):** `POST /v1/auth/request-key` with `{"email":"you@example.com"}`. We email the key to that address — it's never returned in the response, so an AI agent calling on your behalf never sees the secret. This is the path the rate-limit 429 points agents to.
2. **With a password:** sign up with email + password; your first key is shown once and you manage keys from your account.
3. Created an account via email? Set a web-login password from the link in that email (or request a fresh one). Your key keeps working regardless.

Bearer header

Send the key in the Authorization header:

Authorization: Bearer vdb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl example:

curl -H "Authorization: Bearer vdb_xxxxx" \
  https://vdb.ai.kr/v1/auth/me

Manage / revoke keys

From /account you can:

• Mint a new key (with an optional name)
• List your keys (prefix · last-used timestamp)
• Revoke a specific key (effective immediately)

Same operations via API:

# new key
POST /v1/auth/keys/new
{ "name": "ci" }

# list
GET  /v1/auth/keys

# revoke
POST /v1/auth/keys/revoke
{ "key_id": "<uuid>" }

Auth API (signup/login/verify)

Wire-level endpoints for the lifecycle the web UI uses — documented so SDKs and CLI tools can talk to them directly. Email verification is mandatory at signup.

# Get a free key BY EMAIL — no password needed. The funnel the 429 points
# agents to. The key is emailed to the address; it is NEVER in the response.
# Generic 200 either way (anti-enumeration).
POST /v1/auth/request-key
{ "email": "you@example.com", "email_consent": true }

# Set a web-login password via the single-use link from that email.
POST /v1/auth/set-password
{ "token": "<from the email link>", "password": "..." }

# Sign up WITH a password — sends a verification email (mandatory).
POST /v1/auth/signup
{ "email": "you@example.com", "password": "...", "email_consent": true }

# The emailed link opens a page with a confirm button; the button calls this:
POST /v1/auth/verify  {"token": "<token>"}  # one-time; mints the first API key

# Resend the verification email (anti-enumeration: same 200 either way).
POST /v1/auth/resend-verification
{ "email": "you@example.com" }

# Log in → sets a web session cookie. Use Bearer + an API key for programmatic.
# A passwordless (email-funnel) account gets 403 password_not_set until it
# sets one via /v1/auth/set-password.
POST /v1/auth/login
{ "email": "you@example.com", "password": "..." }

# Which accounts share this IP? Read-only audit signal. Returns { ip_hash, binding }.
GET  /v1/auth/ip-binding

Metered per account, not per IP — authenticated calls are counted against the key (account), so users behind a shared egress (an AI provider, an office NAT) don't rate-limit each other. Two endpoints (/v1/ai/slopsquatting, /v1/ai/check-packages) answer without a key on a per-address hourly quota; every other data endpoint needs one, requested via /v1/auth/request-key. (The old 1:1 "IP binding + 7-day cooldown" enforcement collided with shared egress and is now off by default.)

Vulnerabilities

Single lookup

GET /v1/vulns/{id}

A VDB id, a GHSA id, or any alias the advisory carries (CVE ids included) works. Response is OSV 1.6 + vdb_signals extension.

Match by package (OSV-compatible)

POST /v1/query
{
  "package": { "purl": "pkg:npm/lodash" },
  "version": "4.17.20"
}

When a version is supplied in the field or purl, only advisories whose OSV ranges include that version are returned. Unparseable ranges remain visible rather than being hidden as safe.

Recently added

GET /v1/recent?limit=12

Search

GET /v1/search?q=lodash&limit=30

Search across id / alias / summary / details. Exact advisory IDs and package purls use indexed equality lookup; package-shaped queries return advisories for that exact affected package before any text fallback.

SBOM / dependency-file scan

Upload an SBOM, lockfile, or manifest — VDB auto-detects the format, parses it, and matches each component against the vulnerability DB. Every finding includes a Level 1 upgrade command and a Level 2 affected-functions list.

Request

Accepted formats — CycloneDX (JSON/XML), SPDX, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, requirements.txt, Pipfile.lock, pyproject.toml, uv.lock, poetry.lock, go.mod, go.sum, Cargo.lock, Gemfile.lock, composer.lock, and Excel/CSV with a name+version header. Format is detected from the filename first, then from content.

POST /v1/sbom/scan
Authorization: Bearer vdb_xxxxx     # required
Content-Type: multipart/form-data

file=@<filename>     # single file, max 20 MB

A key is required here — unlike the slop list and the package gate, an SBOM scan is not keyless. Without one you get a 401 carrying signup_url — a free key at /signup, or the passwordless email path at /v1/auth/request-key. A signed-up account is currently unmetered beyond abuse protection.

Auto-detected formats:

• CycloneDX (JSON/XML), SPDX 2.3+ JSON
• npm: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
• Python: requirements.txt, Pipfile.lock, pyproject.toml
• Go: go.mod, go.sum
• Rust: Cargo.lock · Ruby: Gemfile.lock · PHP: composer.lock
• Dart / Flutter: pubspec.yaml, pubspec.lock
• Excel (.xlsx) · CSV/TSV (auto-detected headers)

Example call

curl -H "Authorization: Bearer $VDB_API_KEY" \
     -F file=@package-lock.json \
     https://vdb.ai.kr/v1/sbom/scan

Response (200 OK)

{
  "agent_action":        "REFUSE",     // REFUSE means: do not merge
  "because":             "1 critical, 5 high, 2 kev in the resolved tree — do not merge until these are pinned or removed",
  "sbom_format":         "package-lock.json",
  "components_total":    127,
  "components_matched":   14,
  "components_covered":   23,
  "components_unknown":  104,
  "coverage_ratio":      0.181,
  "summary": {
    "critical": 1, "high": 5, "medium": 8,
    "low": 0, "none": 0,
    "kev": 2, "slop": 0
  },
  "vulnerabilities": [
    {
      "id":              "GHSA-35jh-r3h4-6jhm",   // CVE-2021-23337
      "purl":            "pkg:npm/lodash",
      "version":         "4.17.20",
      "summary":         "Command Injection in lodash",
      "severity_bucket": "high",
      "severity_score":  7.2,
      "fixed_in":        ["4.17.21"],
      "kev":             false,         // CISA Known-Exploited list membership
      "epss":            0.00073,       // FIRST.org 30-day exploit probability (0..1)
      "slop_risk":       null,

      // ── Level 1 — copy-pasteable upgrade hint ──────────────
      "remediation": {
        "type":      "upgrade",
        "ecosystem": "npm",
        "name":      "lodash",
        "fixed":     "4.17.21",
        "command":   "npm install lodash@4.17.21",
        "manifest":  "\"lodash\": \"^4.17.21\"",
        "rationale": "Upgrade lodash to 4.17.21 or newer via npm."
      },

      // ── Level 2 — function-level impact ───────────────────
      "affected_functions": [
        { "path": null, "symbol": "template" },
        { "path": null, "symbol": "templateSettings" }
      ]
    }
  ]
}

Field reference

Recommended usage

To gate PRs in CI, block the merge when summary.critical + summary.high > 0 and quote each vulnerabilities[].remediation.command in the PR body. If affected_functions is non-empty, add a grep step that checks whether your code actually calls those symbols — that's the highest-accuracy filter.

Errors

• 400 — empty file / parse failure / malformed multipart payload.
• 413 — file larger than 20 MB.
• 401 — no key, or a key that is not valid. Sign up at /signup, or use the passwordless email-a-key path at /v1/auth/request-key: an AI agent can ask its human for an email and POST it there.

SBOM Watch — registered monitoring + email alerts (members only)

Where the scan is a snapshot, a watch is a subscription. Register an SBOM once; a worker re-checks its components against the vulnerability DB hourly and emails the account address only when a new advisory matches — severity, fixed versions, and the upgrade command included. Each (watch, vulnerability, package) triple is mailed exactly once, ever. All three endpoints require auth — there is no anonymous trial.

POST   /v1/sbom/watches            # register: multipart file= (+ optional name=, lang=ko|en)
GET    /v1/sbom/watches            # list your watches (+ notified_count)
DELETE /v1/sbom/watches/{id}       # delete — alerts stop immediately

curl -H "Authorization: Bearer $VDB_API_KEY" \
     -F file=@package-lock.json -F name=payment-api \
     https://vdb.ai.kr/v1/sbom/watches

• Limits: 5 watches per account, 20,000 components per file. Registering past the cap returns 409 + watch_limit_reached.
• Only the parsed package list (purl + version) is stored — never the original file. Re-register when your SBOM changes.
• Email language follows the lang field captured at registration (default ko); the web UI lives at /sbom-watch.

AI signals (4-pillar: packages · MCP · models · datasets)

0) Self-discovery manifest

Single JSON an AI tool can fetch once to learn every endpoint, decision policy, and the prompt-injection guardrail. Prompts only need to know this one URL.

GET https://vdb.ai.kr/v1/ai/manifest

Slopsquatting candidate list

GET /v1/ai/slopsquatting?ecosystem=npm&limit=50

Bulk check — packages, models, and datasets (DB + realtime registry)

POST /v1/ai/check-packages
{
  "packages": [
    "pkg:npm/%40babel/core@7.24.0",            // exact version (purl, %40 = @)
    "pkg:npm/express@^4.19.2",                 // semver range — server resolves
    "pkg:pypi/requests@>=2.0,<3.0",            // PEP 440 specifier — server resolves
    "pkg:pub/dio@5.4.0",                       // Dart / Flutter via pub.dev
    "pkg:huggingface/BAAI/bge-large-en-v1.5",  // AI model (Hugging Face)
    "pkg:data/squad",                          // training dataset
    "pkg:mcp/anthropic/filesystem"             // MCP server (trust + scopes)
  ],
  "probe_registry": true     // default. false → DB only (skip realtime probe).
}

No key needed to try it. A keyless request is capped at 5 packages and 20 requests per hour per address, and the answer carries an anonymous block with what is left. Send more than 5 and the response adds a truncated block naming how many were not checked, and never answersPROCEED — a partial answer must not read as all-clear. A free key removes both caps.

Input auto-normalisation — if you send OSV-style purls (pkg:crates.io/..., pkg:rubygems/..., pkg:go/..., pkg:packagist/...) we translate them to purl-spec canonical types (cargo, gem, golang, composer) before matching. Response keeps your original in input and the normalised form in purl.

For each item: (1) slop / model / dataset DB lookup + (2) live npm · PyPI · crates · Go · Dart · Hugging Face probe, run in parallel. If either signal is suspicious, matched=true.

Supported ecosystems: npm, PyPI, crates.io, Go modules, pub.dev (Dart/Flutter), Hugging Face (models + datasets). The version slot accepts exact versions or ranges (^4.19.2, ~1.2, >=2.0,<3.0, 1.2.x, ||). Ranges are resolved server-side for npm and PyPI and the chosen concrete version is returned in resolved_version. AI-model and dataset entries get an extra model / dataset object on the response with weights_format, license, and PII signals.

{
  "agent_action": "REFUSE",     // worst verdict across the batch
  "results": [
    {
      "input":              "pkg:npm/express@^4.19.2",
      "purl":               "pkg:npm/express@^4.19.2",
      "version":            "4.21.2",           // what we evaluated against
      "requested_version":  "^4.19.2",          // raw caller input
      "resolved_version":   "4.21.2",           // null if range unresolvable
      "matched":            false,
      "risk":               "low",
      "agent_action":       "PROCEED",          // REFUSE | CONFIRM | PROCEED
      "because":            "no known advisory or slop signal",
      "flags":              [],
      "registry":           { "exists": true, "age_days": 482, "risk_hint": "low" },
      "vulnerabilities":    []
    },
    {
      "input":              "pkg:npm/this-name-does-not-exist@1.0.0",
      "purl":               "pkg:npm/this-name-does-not-exist@1.0.0",
      "matched":            true,
      "risk":               "not_found",
      "agent_action":       "REFUSE",
      "because":            "this name does not exist on the registry — likely hallucinated, and attackers register such names",
      "flags":              [],
      "registry": {
        "ecosystem": "npm",
        "name":      "this-name-does-not-exist",
        "exists":    false,
        "risk_hint": "not_found",
        "rationale": "Name does not exist on the npm registry — almost certainly an LLM hallucination. Attackers commonly squat hallucinated names; refuse without explicit user confirmation."
      }
    },
    {
      "input":        "pkg:npm/react-helper-v2@1.0.0",
      "risk":         "high",
      "agent_action": "REFUSE",
      "because":      "Registered only 3 day(s) ago — fresh-registered names that LLMs already recommend are a classic slopsquatting pattern.",
      "registry": {
        "exists":    true,
        "age_days":  3,
        "risk_hint": "high",
        "rationale": "Registered only 3 day(s) ago — fresh-registered names that LLMs already recommend are a classic slopsquatting pattern."
      }
    },
    {
      "input":        "pkg:mcp/anthropic/filesystem",
      "purl":         "pkg:mcp/anthropic/filesystem",
      "risk":         "medium",                             // ← scopes are orthogonal to risk
      "agent_action": "REFUSE",                             // scope check runs before severity
      "because":      "trust_tier=community with dangerous scope(s) exec, fs:write — unvetted publisher asking for privileged access",
      "mcp": {
        "trust_tier":  "community",                         // official / partner / community / unverified
        "scopes":      ["fs:read", "fs:write", "exec"],
        "risk_score":  62,
        "risk_notes":  "Holds fs:write + exec — capable of arbitrary code execution on the host.",
        "scope_drift": {                                    // populated only if changed within 90 days
          "added":      ["exec"],
          "removed":    [],
          "changed_at": "2026-05-18T09:32:00Z",
          "previous":   ["fs:read", "fs:write"]
        }
      }
    },
    {
      // Log4Shell — illustrates the KEV + EPSS exploit-evidence signals.
      // vulnerabilities[] entries carry the same kev / epss fields as
      // sbom-scan findings. Array is pre-sorted KEV → EPSS → CVSS so
      // vulnerabilities[0] is always the right one to surface.
      "input":        "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
      "purl":         "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
      "version":      "2.14.1",
      "matched":      true,
      "risk":         "high",
      "agent_action": "REFUSE",
      "because":      "GHSA-jfh8-c2jp-5v3q is in CISA KEV — confirmed exploitation in the wild; fixed in 2.15.0",
      "vulnerabilities": [
        {
          "id":              "GHSA-jfh8-c2jp-5v3q",
          "summary":         "Remote code injection in Log4j (Log4Shell)",
          "severity_bucket": "critical",
          "severity_score":  10.0,
          "fixed_in":        ["2.15.0"],
          "kev":             true,         // CISA-confirmed exploited
          "epss":            0.944         // 94.4% exploit probability (FIRST)
        }
      ]
    }
  ]
}

MCP scope_drift — populated only when permissions changed within the last 90 days. A non-empty added is a classic maintainer-takeover signal; require explicit user confirmation regardless of risk grade. If nothing drifted, the field is absent (not null).

KEV / EPSS — exploit-evidence signals. Every vulnerabilities[] entry carries kev (boolean — CISA Known Exploited listing) and epss (0..1 — FIRST 30-day exploit probability). kev=true or epss ≥ 0.5 means refuse regardless of severity bucket — catches the "low CVSS but already being exploited" case automatically. The array is pre-sorted KEV → EPSS → CVSS, so vulnerabilities[0] alone surfaces the top threat.

Recommended action per risk grade

MCP server registry

GET /v1/ai/mcp-servers
GET /v1/ai/mcp-servers/{id}     # id = "owner/name" OR "mcp:owner/name" OR "pkg:mcp/owner/name"

Prefer /v1/ai/check-packages for MCP lookups — same gate logic + scope_drift + trial counter in one response. Direct GET is for browsing/debugging. Unknown servers come back 200 with trust_tier: "unverified" + metadata.source: "not_in_registry" so agents don't have to special-case 404s.

The response object mirrors the mcp field on the check-packages response — trust_tier, scopes, risk_score, and scope_drift (when applicable).

The same capabilities are exposed as a native MCP server. The hosted endpoint offers seven tools (vdb_check_package, vdb_check_packages, vdb_scan_lockfile, vdb_lookup, vdb_search, vdb_check_mcp_server, vdb_list_slopsquatting); running the server locally adds three more that need your files (vdb_harden, vdb_harden_verify, vdb_vex) for ten in total. Connect from Claude Desktop / Cursor with either of the two forms below.

# Remote — no install:
{ "mcpServers": { "vdb": { "url": "https://vdb.ai.kr/mcp",
                           "headers": { "Authorization": "Bearer vdb_..." } } } }
# Claude Code:
claude mcp add --transport http vdb https://vdb.ai.kr/mcp --header "Authorization: Bearer $VDB_API_KEY"

# Local — via PyPI (also on Smithery + the official MCP registry):
{ "mcpServers": { "vdb": { "command": "uvx", "args": ["vdb-mcp"] } } }

Every tool needs a key. Hosted: send it as an Authorization: Bearer header (as above) or as the vdbApiToken session parameter. Local: the VDB_API_TOKEN env var. Without one, each tool answers agent_action: REFUSE with the URL to request a free key by email, so an agent can recover on its own.

No outbound DNS in your sandbox? Both the local MCP server and vdb harden fall back to the pinned address 144.202.127.83 when — and only when — name resolution fails. The TLS handshake still presents vdb.ai.kr and validates its certificate, so nothing is trusted by IP. Override with VDB_API_ADDR. For raw HTTP from a script: curl --resolve vdb.ai.kr:443:144.202.127.83 https://vdb.ai.kr/v1/version. vdb harden --doctor says which of network / key / service is at fault.

No PyPI either? Then uvx vdb-mcp cannot even start, and no fallback inside it helps. The whole CLI is also served as one stdlib-only file, built from the code this API is running: curl --resolve vdb.ai.kr:443:144.202.127.83 -O https://vdb.ai.kr/v1/harden/client.pyz, compare its SHA-256 with https://vdb.ai.kr/v1/harden/client.sha256, then python3 client.pyz --doctor or python3 client.pyz app.py --manifest uv.lock. Any Python ≥ 3.10, nothing to install, no key needed to fetch it.

AI model registry (Hugging Face)

GET /v1/ai/models                       # list / filter by provider, license
GET /v1/ai/models/{purl}                # purl = pkg:huggingface/owner/name

# example
curl https://vdb.ai.kr/v1/ai/models?provider=huggingface&limit=20
curl https://vdb.ai.kr/v1/ai/models/pkg:huggingface/BAAI/bge-large-en-v1.5

Model cards collected from Hugging Face and elsewhere. Exposes weights_format (pickle vs safetensors), license, sha256, download counts, risk_score, and risk_notes. Call before pulling a model to catch code-execution risk (pickle), license violations, or signature mismatches.

{
  "id":             "pkg:huggingface/BAAI/bge-large-en-v1.5",
  "display_name":   "BAAI/bge-large-en-v1.5",
  "provider":       "huggingface",
  "framework":      "pytorch",
  "license":        "mit",
  "weights_format": "safetensors",     // pickle | safetensors | gguf | …
  "sha256":         "…",
  "downloads":      1843201,
  "risk_score":     0.05,
  "risk_notes":     null,
  "metadata":       { /* raw HF model-card fields */ }
}

weights_format=="pickle" models execute arbitrary code on load (torch.load gadget chain). Prefer the safetensors variant when available. If license is non-commercial/research-only/other/null, review before commercial use.

Training-dataset registry

GET /v1/ai/datasets                     # list / filter by provider, license
GET /v1/ai/datasets/{purl}              # purl = pkg:data/name  or  pkg:data/owner/name

# example
curl https://vdb.ai.kr/v1/ai/datasets?provider=huggingface&limit=20
curl https://vdb.ai.kr/v1/ai/datasets/pkg:data/squad

Dataset cards from Hugging Face. Exposes file_formats, license, task, downloads, risk_score, and risk_notes (including PII flags). Check license and personal-information risk before fine-tuning on, redistributing, or commercialising a dataset.

{
  "id":            "pkg:data/squad",
  "display_name":  "rajpurkar/squad",
  "provider":      "huggingface",
  "task":          "question-answering",
  "file_formats":  "parquet,json",
  "license":       "cc-by-sa-4.0",
  "downloads":     412330,
  "risk_score":    0.10,
  "risk_notes":    null,                 // e.g. "pii:flagged" when HF tags include PII signals
  "description":   "Stanford Question Answering Dataset"
}

Reachability — hardening & VEX

These endpoints answer a question the rest of the API cannot: given your call sites, can attacker-controlled data reach a dangerous operation through your transitive dependencies — whether or not any CVE exists for it? Full explanation and limits → Worked example, start to finish →

Source code is never accepted. The ir field is an abstracted call-graph representation built on your machine — identifiers renamed, literals reduced to shapes, function bodies dropped. Produce it with vdb harden <path> --emit-ir (which makes no network call) or the vdb_harden MCP tool in local mode.

Decide risky dataflow

POST /v1/harden/analyze
{
  "ir":                { /* abstracted representation — see --emit-ir */ },
  "manifest":          "<contents of uv.lock / poetry.lock / requirements.txt / CycloneDX>",
  "manifest_filename": "uv.lock",
  "project":           "my-service"   // optional; new-path mail is one per project per day
}

{
  "paths": [
    {
      "path_id":         "P-8daff1f4-net_request",
      "sink":            "net_request",
      "sink_package":    "urllib3",
      "cve_independent": true,          // decided from the graph, not an advisory
      "confidence":      0.85,          // lowered by assumed hops and abstraction loss
      "hops":            [ /* package -> package -> sink */ ]
    }
  ],
  "hardenings": [
    {
      "path_id":    "P-8daff1f4-net_request",
      "code_patch": "def vdb_safe_url(value, allowed_hosts): ...",
      "agent_rule": { "rule": "harden-callsite", "require": ["scheme-allowlist", "host-allowlist", "block-internal-ranges"] },
      "residual_risk": { "undefended": [ /* what a boundary fix cannot cover */ ] }
    }
  ],
  "code_fingerprint": "sha256...", // binds later verification to this IR
  "analysis_complete": true,
  "summary_snapshot":  "sha256...", // invalidates cache when a summary changes
  "graph_svg":         "<svg ...>"  // rendered graph; graph_view remains machine-readable
}

The fix applies at your call site. VDB never asks you to patch, fork, or pin the dependency — you usually cannot fix someone else's package, and you can always fix your own boundary.

A path can also end in your own standard-library call — subprocess.run(cmd), eval(expr), pickle.loads(blob), zlib.decompress(data), urlopen(url). Those have a single hop and "sink_version": "stdlib". File paths and regular expressions in your own code are not examined.

Analysis runs on a separate worker pool with a time limit. If the pool is busy the request answers 503 with Retry-After; if one analysis runs past the limit, 504 — analyse a narrower path (a package or service directory) rather than the whole repository. The same applies to /v1/vex and /v1/harden/verify.

Verify the fix closed it

POST /v1/harden/verify
{ "ir": { /* representation AFTER your fix */ }, "manifest": "...", "path_id": "P-8daff1f4-net_request" }

The path id must come from this authenticated user's original analysis. The response binds the HMAC-signed canonical payload to both IR fingerprints, the dependency graph, required defenses, method, and timestamp. An incomplete re-analysis cannot turn an absent path into closure. Partial defense is not closure — a wrapper is credited only when its AST exactly matches the implementation VDB issued, so an edited one earns nothing (no-sanitizer-at-boundary) rather than partial credit, and a wrapper meant for another sink names every defense still required (sanitizer-incomplete:missing=…).

POST /v1/harden/evidence/verify       # public; no signing key disclosed
{
  "payload":      { /* evidence.payload returned above */ },
  "payload_hash": "...",
  "signature":    "..."
}

// response: { "valid": true, "hash_matches": true, "signature_matches": true }

A valid signature authenticates VDB's decision over the submitted abstract IR. It does not prove that the IR faithfully represents a deployed binary.

VEX — subtract what cannot be reached

POST /v1/vex
{
  "ir":                { /* whole SOURCE TREE, not one file */ },
  "manifest":          "...",
  "manifest_filename": "uv.lock",
  "findings":          [ /* rows straight from POST /v1/sbom/scan */ ]
}

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "statements": [
    {
      "vulnerability": { "name": "CVE-2026-1234" },
      "products":      [ { "@id": "pkg:pypi/urllib3@2.2.2" } ],
      "status":        "not_affected",
      "justification": "vulnerable_code_cannot_be_controlled_by_adversary"
    }
  ],
  "_vdb": {
    "counts":     { "not_affected": 26, "under_investigation": 10 },
    "share_url":  "https://vdb.ai.kr/vex/2dc91cf0...",
    "integrity":  { "algorithm": "HMAC-SHA256", "payload_hash": "...", "signature": "..." },
    "scope_note": "..."          // what the determinations rest on
  }
}

What it will not claim. Never affected: reaching a package is not reaching the function an advisory names. Never vulnerable_code_not_in_execute_path: the analysis follows tainted data, and a package called with your own constants is still executed. Nothing at all for an ecosystem the analysis did not cover. And no not_affected at all below two analyzed files — a determination is only as wide as the code behind it. Reachability comes from static per-package summaries, so a missed relation is a false negative: evidence for triage order, not proof of non-exploitability.

GET /v1/vex/{doc_id} fetches a stored document (no auth — it carries package names, versions, advisory ids and a file list, the same exposure as a published SBOM, and no source). The human-readable page is at /vex/{doc_id}.

Worked example

Eighteen lines of Flask, a requirements.txt, and the whole loop. Output copied from a real run, not written to look plausible.

$ vdb harden app.py --manifest requirements.txt

4 dataflow path(s) decided (independently of whether any CVE exists)

* net_request  confidence 0.8
   path  : requests@2.19.0 -> urllib3@1.23 -> urllib3@1.23
   sink  : urllib3@1.23 - urllib3.util.parse_url
   fix   : scheme-allowlist, host-allowlist, block-internal-ranges
   path_id : P-4927330b4da0-net_request

$ vdb harden app.py --manifest requirements.txt --verify P-4927330b4da0-net_request

path P-4927330b4da0-net_request -> CLOSED (sanitizer-applied:block-internal-ranges,host-allowlist,scheme-allowlist)
  graph hash : 8e25c9dd6228dd7c...
  signature  : 541aee2e69f232e02d7cc4a7...

The risk lands in urllib3, a package nobody wrote down, and a call in the same file using a literal URL produces nothing at all. The full walk-through, including what leaves your machine →

Bug reports (auth required)

POST /v1/bug-reports
Authorization: Bearer vdb_xxxxx
Content-Type: application/json

{
  "title":       "Search result ordering looks off",
  "description": "Repro: ... / Expected: ... / Actual: ...",
  "category":    "ui"
}

Categories: ui · data · api · suggestion · other

GET /v1/bug-reports/me     # list my reports

Meta / changelog

Lightweight public endpoints so external dashboards can pull build info, headline counts, /changelog entries, or the 30-day collection activity without scraping HTML. No auth required.

GET /v1/version                          # build + commit info
GET /v1/stats                            # headline counts (vulns, mcp, …)
GET /v1/changelog?limit=200              # curated + auto-milestone entries
GET /v1/activity/recent                  # 30-day sanitised collection activity (day × source)
GET /v1/blog/{slug}/comments             # public; author shown as the first 2 chars of the email
POST /v1/blog/{slug}/comments            # signed-in key; { "body": "..." } (1–4000 chars, 10/day)
GET /v1/blog/posts                       # published console posts (hand-written pages are not listed)
GET /v1/blog/posts/{slug}                # one published post, body as Markdown
GET /v1/harden/mail/off?u=&s=            # signed stop link from risk-path mail: shows a button
POST /v1/harden/mail/off?u=&s=           # turns that mail off (also RFC 8058 one-click)

Admin (is_admin required)

All admin endpoints require Authorization: Bearer plus is_admin=true on that user.

GET   /v1/admin/users
PATCH /v1/admin/users/{id}                # { "is_admin": true }
GET   /v1/admin/bug-reports[?status_filter=open]
PATCH /v1/admin/bug-reports/{id}          # status / triage_note
GET   /v1/admin/disclosures[?status_filter=received]
GET   /v1/admin/disclosures/{id}          # PoC included
PATCH /v1/admin/disclosures/{id}          # status / internal_notes / vuln_id
GET   /v1/admin/traffic?hours=24[&source=user|internal|anon]
GET   /v1/admin/collector-runs
GET   /v1/admin/collector-health          # 24h health + watermarks + DB counts
GET   /v1/admin/anon-insights             # funnel + cohort retention + conversion
POST  /v1/admin/changelog                 # { date, tag, title_ko, title_en, body_ko, body_en, visibility? }
DELETE /v1/admin/blog/comments/{id}       # soft delete; hidden from the post
GET   /v1/admin/blog/posts                # drafts included
GET   /v1/admin/blog/posts/{slug}
PUT   /v1/admin/blog/posts/{slug}         # { title, description, body_md, tags[], status: draft|published }
DELETE /v1/admin/blog/posts/{slug}
GET   /v1/admin/blog/syndication          # where each post was republished
PUT   /v1/admin/blog/syndication/{slug}/{platform}  # devto|dzone|medium; { status, url, notes }

Swagger UI

Interactive — call and test endpoints directly from the browser. Everything is grouped by tag (vulnerabilities, sbom, ai-signals, auth, bug-reports, disclosures, admin, meta).

Open Swagger UI →

ReDoc

Open ReDoc →

OpenAPI 3.1 JSON

curl https://vdb.ai.kr/openapi.json > vdb-openapi.json

Editor extension — VS Code & Cursor

Prefer not to call the API by hand? The official **VDB** extension wraps this same POST /v1/ai/check-packages endpoint and surfaces the results inline as you edit. Open or save a package.json, requirements.txt, Cargo.toml, go.mod, pubspec.yaml, or an MCP config and risky dependencies are underlined right in the editor — slopsquatting as errors, known CVEs with a one-click upgrade to a safe version.

It also generates a CycloneDX SBOM from your workspace and scans it in one step, and checks the npm/PyPI package behind each MCP server. Works in VS Code, Cursor, Windsurf, and VSCodium (via Open VSX). Only package names and versions are sent — never your source.

Install from the Marketplace

Error responses

Errors always look like:

{ "detail": "<message>" }