# CVE Watcher API and scopes

CVE Watcher is exposed through the ConnectRPC service
`bountyhub.cve.v1.CveWatcherService`. The Hub UI, the generated TypeScript SDK
(`cveWatcherClient`), and your own clients all call the same unary methods.

## Transport and authentication

- Protocol: [ConnectRPC](https://connectrpc.com/) over HTTPS.
- RPC path: `/<package>.<Service>/<Method>`, for example
`/bountyhub.cve.v1.CveWatcherService/ListCves`.
- Authentication: a session cookie (browser) or a Personal Access Token sent as
`Authorization: Bearer <token>`.
- Payloads: Connect JSON or protobuf. The examples below use JSON.

Create a PAT with the scopes in the table below — see
[Personal Access Token scopes](/developer/scopes) for the UI and scope
hierarchy.

## Methods and scopes

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Returns
    </th>
    
    <th>
      Required scope
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ListCves
      </code>
    </td>
    
    <td>
      A page of CVE feed entries
    </td>
    
    <td>
      <code>
        NotificationRo
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GetCve
      </code>
    </td>
    
    <td>
      One CVE feed entry
    </td>
    
    <td>
      <code>
        NotificationRo
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ListCveFacets
      </code>
    </td>
    
    <td>
      Distinct vendor and product values
    </td>
    
    <td>
      <code>
        NotificationRo
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ListCveWatcherNotificationChannels
      </code>
    </td>
    
    <td>
      Your channel assignments
    </td>
    
    <td>
      <code>
        IntegrationRo
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AssignCveWatcherNotificationChannel
      </code>
    </td>
    
    <td>
      The assignment id
    </td>
    
    <td>
      <code>
        IntegrationRw
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        UnassignCveWatcherNotificationChannel
      </code>
    </td>
    
    <td>
      Empty response
    </td>
    
    <td>
      <code>
        IntegrationRw
      </code>
    </td>
  </tr>
</tbody>
</table>

`NotificationRo` is the read side of the **Notifications** scope;
`IntegrationRo` / `IntegrationRw` are the **Integrations** scope. Write scopes
require their read counterpart.

## ListCves

```json
{
  "severities": ["CVE_SEVERITY_CRITICAL", "CVE_SEVERITY_HIGH"],
  "ransomwareOnly": true,
  "search": "tier:confirmed -product:windows",
  "pageSize": 50,
  "pageToken": ""
}
```

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        severities
      </code>
    </td>
    
    <td>
      <code>
        CveSeverity[]
      </code>
    </td>
    
    <td>
      Empty or omitted means all severities.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ransomwareOnly
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      Restrict to KEV entries with known ransomware use.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      The query language — see <a href="/cve-watcher/search">
        Search and filters
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pageSize
      </code>
    </td>
    
    <td>
      uint32
    </td>
    
    <td>
      Default 25, maximum 100.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pageToken
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Opaque cursor from the previous response.
    </td>
  </tr>
</tbody>
</table>

Results are ordered by CVE id descending. Pass `nextPageToken` from the
response as `pageToken` to continue; an empty token means the last page.

```bash
curl -sS https://api.bountyhub.com/bountyhub.cve.v1.CveWatcherService/ListCves \
  -H "Authorization: Bearer $BOUNTYHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "severities": ["CVE_SEVERITY_CRITICAL"],
    "search": "tier:confirmed",
    "pageSize": 25
  }'
```

The response contains `items` and `nextPageToken`:

```json
{
  "items": [
    {
      "cveId": "CVE-2024-3400",
      "kevAdded": "2024-04-12T00:00:00Z",
      "kevDue": "2024-05-03T00:00:00Z",
      "vendor": "Palo Alto Networks",
      "product": "PAN-OS",
      "shortDescription": "Command injection in GlobalProtect.",
      "ransomware": true,
      "cvssV3": 10.0,
      "severity": "CVE_SEVERITY_CRITICAL",
      "epss": 0.94,
      "exploitAvailable": true,
      "status": "CVE_STATUS_NOTIFIED",
      "publishedVersion": "2",
      "updated": true,
      "exploitTier": "confirmed",
      "userVisibleAt": "2024-04-12T00:00:00Z",
      "createdAt": "2024-04-12T00:00:00Z"
    }
  ],
  "nextPageToken": ""
}
```

`uint64` fields such as `publishedVersion` are strings in Connect JSON.

## CveItem fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        cveId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      CVE identifier.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kevAdded
      </code>
    </td>
    
    <td>
      timestamp
    </td>
    
    <td>
      Date CISA added the CVE to KEV. Empty for early exploit-sweep entries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kevDue
      </code>
    </td>
    
    <td>
      timestamp
    </td>
    
    <td>
      CISA remediation deadline.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vendor
      </code>
      
      , <code>
        product
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Normalized from KEV when present, otherwise NVD.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        shortDescription
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      One-line description.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ransomware
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      Known ransomware campaign use (KEV).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cvssV3
      </code>
    </td>
    
    <td>
      double
    </td>
    
    <td>
      CVSS v3 base score, 0.0 – 10.0.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        severity
      </code>
    </td>
    
    <td>
      enum
    </td>
    
    <td>
      <code>
        CVE_SEVERITY_CRITICAL
      </code>
      
      , <code>
        CVE_SEVERITY_HIGH
      </code>
      
      , <code>
        CVE_SEVERITY_MEDIUM
      </code>
      
      , <code>
        CVE_SEVERITY_LOW
      </code>
      
      , <code>
        CVE_SEVERITY_NONE
      </code>
      
      , or <code>
        CVE_SEVERITY_UNKNOWN
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        epss
      </code>
    </td>
    
    <td>
      double
    </td>
    
    <td>
      FIRST EPSS probability, 0.0 – 1.0.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exploitAvailable
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      NVD references public exploit code.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exploitTier
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Derived signal: <code>
        confirmed
      </code>
      
      , <code>
        likely
      </code>
      
      , <code>
        watch
      </code>
      
      , or <code>
        none
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      enum
    </td>
    
    <td>
      Pipeline position — see below.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        publishedVersion
      </code>
    </td>
    
    <td>
      uint64
    </td>
    
    <td>
      Published version. <code>
        0
      </code>
      
       means never published.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        updated
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      True when <code>
        publishedVersion > 1
      </code>
      
       (a re-announcement).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userVisibleAt
      </code>
    </td>
    
    <td>
      timestamp
    </td>
    
    <td>
      When the CVE entered every user's feed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createdAt
      </code>
    </td>
    
    <td>
      timestamp
    </td>
    
    <td>
      When the row was first ingested.
    </td>
  </tr>
</tbody>
</table>

### Status values

<table>
<thead>
  <tr>
    <th>
      Value
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        CVE_STATUS_INGESTED
      </code>
    </td>
    
    <td>
      Row exists but has not been announced. Early exploit-sweep rows stay here.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CVE_STATUS_PUBLIC_PUBLISHED
      </code>
    </td>
    
    <td>
      Public digest stage completed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CVE_STATUS_USER_VISIBLE
      </code>
    </td>
    
    <td>
      Visible in every user's in-app feed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CVE_STATUS_NOTIFIED
      </code>
    </td>
    
    <td>
      Paid push fan-out completed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CVE_STATUS_FAILED
      </code>
    </td>
    
    <td>
      Publication failed; the worker retries.
    </td>
  </tr>
</tbody>
</table>

## GetCve

```json
{ "cveId": "CVE-2024-3400" }
```

Returns `{ "item": CveItem }`, or `NOT_FOUND` when the CVE is not in the feed.

## ListCveFacets

Returns distinct, alphabetically sorted values for filter autocomplete:

```json
{
  "vendors": ["Apache Software Foundation", "Palo Alto Networks"],
  "products": ["HTTP Server", "PAN-OS"]
}
```

Up to 1,000 values are returned per list. Empty vendor or product values are
excluded.

## Manage push channels

Assignments are per user and limited to one channel per integration kind.
Assigning a channel of a kind that is already assigned replaces it.

```bash
# Assign a channel
curl -sS https://api.bountyhub.com/bountyhub.cve.v1.CveWatcherService/AssignCveWatcherNotificationChannel \
  -H "Authorization: Bearer $BOUNTYHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notificationChannelId":"<notification-channel-uuid>"}'

# List assignments
curl -sS https://api.bountyhub.com/bountyhub.cve.v1.CveWatcherService/ListCveWatcherNotificationChannels \
  -H "Authorization: Bearer $BOUNTYHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pageSize":100}'

# Remove an assignment by its assignment id
curl -sS https://api.bountyhub.com/bountyhub.cve.v1.CveWatcherService/UnassignCveWatcherNotificationChannel \
  -H "Authorization: Bearer $BOUNTYHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"<assignment-uuid>"}'
```

`ListCveWatcherNotificationChannels` returns `items` of
`CveWatcherNotificationChannelAssignment`:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      Assignment id, used to unassign.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notificationChannelId
      </code>
    </td>
    
    <td>
      The assigned notification channel.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        integrationKind
      </code>
    </td>
    
    <td>
      <code>
        bountyhub.integration.v1.IntegrationKind
      </code>
      
       as an int64, serialized as a string in JSON (Discord, Slack, Mail, Telegram, Webhook).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notificationChannelName
      </code>
    </td>
    
    <td>
      Channel name, for display.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        integrationName
      </code>
    </td>
    
    <td>
      Integration name, for display.
    </td>
  </tr>
</tbody>
</table>

Pagination: default 25, maximum 500, ordered by assignment id descending.

## Errors

<table>
<thead>
  <tr>
    <th>
      Connect code
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        UNAUTHENTICATED
      </code>
    </td>
    
    <td>
      Missing or invalid session cookie or PAT.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PERMISSION_DENIED
      </code>
    </td>
    
    <td>
      The PAT lacks the required scope.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FAILED_PRECONDITION
      </code>
    </td>
    
    <td>
      Assigning a channel on a free plan.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NOT_FOUND
      </code>
    </td>
    
    <td>
      Unknown CVE, or a notification channel you do not own.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INVALID_ARGUMENT
      </code>
    </td>
    
    <td>
      Malformed id or page token.
    </td>
  </tr>
</tbody>
</table>

## Related

- [CVE Watcher overview](/cve-watcher/overview) — sources, tiers, and versions.
- [Search and filters](/cve-watcher/search) — the `search` string.
- [Push notifications](/cve-watcher/notifications) — delivery and channel setup.
- [Personal Access Token scopes](/developer/scopes) — scope names and hierarchy.