# Vulnerability & Dependency Intelligence API — OSV.dev package vulnerability lookup, GitHub Advisory (GHSA) search, CVE/GHSA detail with CVSS and EPSS scores, CISA Known Exploited Vulnerabilities (KEV) catalog, and batch scanning

> All known vulnerabilities affecting a package (by name+ecosystem, optionally pinned to an installed version) OR a git commit — via OSV.dev. The dependency-audit core.
> ReefAPI engine `vuln-intel` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/vuln-intel/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /vuln-intel/v1/package_vulns — 1 credit
All known vulnerabilities affecting a package (by name+ecosystem, optionally pinned to an installed version) OR a git commit — via OSV.dev. The dependency-audit core.

**Parameters:**
- `package` (string, required) — Package name as published in its registry (npm 'lodash', PyPI 'django', Maven 'group:artifact' e.g. 'org.apache.logging.log4j:log4j-core', Go import path). Required unless you pass `commit` instead.
- `ecosystem` (enum, required) — Package ecosystem / registry. Case-insensitive; common aliases map (cargo->crates.io, pip/python->PyPI is via the 'pypi' key, composer->Packagist). Required with `package` (omit when querying by `commit`). [one of: alpine, android, bitnami, cargo, composer, crates.io, debian, githubactions, go, hex, maven, npm, nuget, packagist, pub, pypi, rubygems, swifturl, ubuntu]
- `version` (string, optional) — Exact installed version to test (e.g. '2.14.1', '4.17.15'). Omit to return ALL known vulnerabilities for the package across every version.
- `commit` (string, optional) — Git commit hash to query instead of package+version+ecosystem (OSV resolves which vulns affect that exact source revision).

**Returns:** package, ecosystem, version, vuln_count, severity_summary{by_severity:{critical,high,moderate,low,unknown}, highest_severity, total} (per-package rollup, no extra hop), vulnerabilities[] (id, aliases, cve_ids, summary, severity_label, cvss_vector/score, fixed_versions, affected[] ranges, references); meta.record_count = vuln_count, meta.highest_severity

**Example request body:**
```json
{
  "package": "org.apache.logging.log4j:log4j-core",
  "ecosystem": "Maven",
  "version": "2.14.1"
}
```

### POST /vuln-intel/v1/vuln_detail — 1 credit
Full detail for one vulnerability by OSV id, GHSA id, or CVE id. OSV is the base record; if it resolves to a GHSA the response is enriched with GitHub's numeric CVSS base score, EPSS exploitation probability, and CWEs.

**Parameters:**
- `id` (string, required) — A vulnerability id: OSV id (GHSA-…, PYSEC-…, GO-…, RUSTSEC-…) or a CVE (CVE-2021-44228). CVE ids are resolved via OSV's alias index. Case-insensitive.

**Returns:** vulnerability{} — normalized OSV record (id, aliases, cve_ids, summary, details, cvss_*, affected[], fixed_versions, references, exploit_references[] (PoC/exploit links from refs: exploit-db/packetstorm/metasploit)) plus ghsa{} enrichment (cvss_score, epss_percentage/percentile, cwes) when available

**Example request body:**
```json
{
  "id": "GHSA-jfh8-c2jp-5v3q"
}
```

### POST /vuln-intel/v1/advisory_search — 1 credit
Search the GitHub Advisory Database (GHSA) by ecosystem, severity, CVE, free text, type. Cursor-paginated (meta.next_cursor).

**Parameters:**
- `ecosystem` (enum, optional) — Filter advisories by GitHub ecosystem token (note GitHub's spelling: 'pip' for Python, 'rust' for crates, 'actions' for GitHub Actions). [one of: actions, composer, erlang, go, maven, npm, nuget, other, pip, pub, rubygems, rust, swift]
- `severity` (enum, optional) — Filter advisories by qualitative severity. [one of: low, medium, high, critical]
- `cve_id` (string, optional) — Return only the advisory(ies) for this exact CVE id.
- `query` (string, optional) — Free-text search across advisory summary/description.
- `type` (enum, optional) — Advisory review state. 'reviewed' (default) = GitHub-curated; 'malware' = malicious-package advisories. [one of: reviewed, unreviewed, malware]
- `sort` (enum, optional) — Sort field for the advisory list. [one of: published, updated]
- `direction` (enum, optional) — Sort direction. [one of: desc, asc]
- `per_page` (integer, optional, default 30) — Results per page (1-100, default 30). Larger values are clamped.
- `cursor` (string, optional) — Opaque pagination cursor for the next page of advisories — pass the value from meta.next_cursor. (GHSA paginates by cursor, not page number.)

**Returns:** advisories[] (ghsa_id, cve_id, summary, severity, cvss_score, cwes, vulnerabilities[] affected pkgs, references, published_at); meta has record_count, has_more, next_cursor, rate_limit_remaining

**Example request body:**
```json
{
  "ecosystem": "pip",
  "severity": "critical",
  "per_page": 5
}
```

### POST /vuln-intel/v1/kev_check — 1 credit
Is a CVE in the CISA Known-Exploited-Vulnerabilities catalog (actively exploited in the wild)? Returns the KEV entry when listed.

**Parameters:**
- `cve_id` (string, required) — The CVE id to look up in the CISA Known-Exploited-Vulnerabilities catalog. Case-insensitive.

**Returns:** cve_id, in_kev (bool), entry{} (vendor_project, product, vulnerability_name, date_added, due_date, required_action, known_ransomware_campaign_use) when listed; catalog_version, catalog_count

**Example request body:**
```json
{
  "cve_id": "CVE-2021-44228"
}
```

### POST /vuln-intel/v1/kev_list — 1 credit
Browse / filter the full CISA KEV catalog by vendor, product, or ransomware flag, with page pagination.

**Parameters:**
- `vendor` (string, optional) — Filter KEV entries by vendor/project (substring, case-insensitive).
- `product` (string, optional) — Filter KEV entries by product (substring, case-insensitive).
- `ransomware` (enum, optional) — Filter KEV entries by whether the CVE is known-used in ransomware campaigns (CISA's knownRansomwareCampaignUse field). [one of: Known, Unknown]
- `page` (integer, optional, default 1) — 1-based page number for the KEV list. Page forward with meta.next_page.
- `per_page` (integer, optional, default 30) — Results per page (1-100, default 30). Larger values are clamped.

**Returns:** entries[] (normalized KEV records), catalog_version, total (after filters), catalog_count (full); meta has record_count, page, per_page, has_more, next_page

**Example request body:**
```json
{
  "vendor": "Microsoft",
  "per_page": 5
}
```

### POST /vuln-intel/v1/exploits — 1 credit
Public exploit / PoC lookup for a CVE via the Exploit-DB (Offensive Security) database (keyless, CVE-indexed). Answers 'is there a weaponized public exploit?' — has_public_exploit + each entry's edb_id, type (remote/local/webapps/dos), platform, verified flag, date_published, and deep links (exploit_db_url + upstream source_url).

**Parameters:**
- `cve_id` (string, required) — The CVE id to look up in the Exploit-DB (Offensive Security) public exploit/PoC database. Case-insensitive. Returns every exploit row whose 'codes' column references this CVE.
- `verified_only` (boolean, optional, default false) — If true, return only Exploit-DB entries marked verified (reproduced by the Exploit-DB team). Default false = all entries.

**Returns:** cve_id, has_public_exploit (bool), exploit_count, exploits[] (edb_id, description, type, platform, author, date_published, verified, codes[], exploit_db_url, source_url); meta.has_public_exploit, meta.exploitdb_rows

**Example request body:**
```json
{
  "cve_id": "CVE-2021-44228"
}
```

### POST /vuln-intel/v1/batch — 1 credit
Bulk-scan up to 100 package/commit queries in one call (OSV querybatch), each hydrated to full vulnerability detail by default.

**Parameters:**
- `queries` (array, required) — Array of up to 100 query objects. Each is either {package, ecosystem, version?} or {commit}. Returns one result group per query (order preserved), each hydrated to full vulnerability detail.
- `hydrate` (boolean, optional, default true) — If true (default) each batch hit is expanded to the full normalized vulnerability via OSV /vulns/{id}. Set false for a faster id-only response (returns {id, modified} per hit).

**Returns:** results[] (one per input query, order preserved: query, vuln_count, vulnerabilities[]); meta.record_count = total vulns across all queries

**Example request body:**
```json
{
  "queries": [
    {
      "package": "lodash",
      "ecosystem": "npm",
      "version": "4.17.15"
    },
    {
      "package": "django",
      "ecosystem": "PyPI",
      "version": "3.0.0"
    }
  ]
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=vuln-intel
- Human docs page: https://reefapi.com/docs/vuln-intel
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt