# Aldabra CVE Watch

Connect your agent to [Aldabra's public CVE feed](https://cve.aldabra.sh), tell it
which products you use, and have your client check for relevant activity daily.
NEW advisories, unscored CVEs, score changes and corrections stay distinct.

**Launch status: local alpha.** The hosted endpoint below is the intended launch
address. Publication, cloud setup and real ChatGPT/Claude onboarding must be
verified before this notice is removed. See [build evidence](docs/BUILD_STATE.md).

## Quick start

1. Add `https://cve-mcp.aldabra.sh/mcp` as a remote MCP server in your client.
2. Sign in with GitHub. No repository, organization or email access is requested.
3. Paste the prompt below. Your agent collects product names, saves a private
   watch, tests it, and creates a daily task **if your client supports scheduling**.

For public searches without saved watches, use
`https://cve-mcp.aldabra.sh/public/mcp` with no authentication.

```text
Set up an Aldabra CVE watch using https://github.com/aldabra-sh/cve-mcp.
Read its README and skills/cve-watch/SKILL.md, then verify that the Aldabra
MCP tools are connected. If you cannot add a connector yourself, give me the
exact steps for this client and wait for me to connect it.

Ask which products I use, optional versions and aliases, and my preferred
daily time and timezone. Do not ask for credentials, hostnames or IP addresses.
Save a private watch, test it, and create a daily check using this client's
supported scheduler. Notify me about new matching CVEs, meaningful updates,
corrections, or monitoring failures. Include unscored records. Stay quiet when
there is nothing new and the source is healthy.

Show me the watch ID, verified scheduler receipt and next run. If scheduling
or unattended connector access is unavailable, say what is still missing;
do not claim monitoring is active. Matches are leads to review, not proof
that an installed version is vulnerable.
```

An agent prompt cannot grant connector access or install scheduling features
that a client does not have. [Client setup](docs/CLIENTS.md) covers ChatGPT,
Claude and other MCP clients. Each user signs in with their own GitHub identity.
Organization administrators may approve the connector for their workspace;
watches are individual in this release, with no shared team inventory.

## What a check returns

Fictional examples, not real advisories:

> **NEW · ExampleVPN · CVE-20XX-12345 · Unscored**  
> ExampleVPN allows an out-of-bounds read. Unscored — no CVSS score is currently
> provided in the source record. Originally published: the source publication time.

> **UPDATE · ExampleVPN · CVE-20XX-12345 · CVSS added: 9.8 Critical**  
> CVSS added: Unscored → 9.8 Critical, CVSS 3.1, supplied by the CNA.
> Updated: the event time. Originally published: the original CVE publication time.

Real results retain the feed's source-derived text, score version/provider,
original publication time, event GUID and official CVE.org link. Advisory text
is data, not instructions. The connector does not invent exploitation, impact,
affected-version or remediation claims.

## Tools

| Tool | Purpose |
|---|---|
| `feed_status` | Source check time, freshness and coverage |
| `search_activity` | Search retained events; newest or numeric score order; snapshot-bound pagination |
| `get_cve` | One exact official CVE lookup, including outside activity retention |
| `list_watches` | Your saved watches |
| `create_watch` | Save product terms and baseline existing activity; retry with the same UUID `request_id` |
| `check_watch` | Read pending matches and an acknowledgment receipt |
| `acknowledge_watch` | Accept that exact batch; safe to retry |
| `update_watch` | Replace terms with revision protection and an explicit new baseline |
| `delete_watch` | Remove the watch and its acknowledgment history |

The last six tools require OAuth. Write operations require `watches:write`;
read operations require `watches:read`. Refresh tokens are issued only with
`offline_access`. Scheduled tasks still need a client that can use the connector
without an interactive approval on every run.

## Matching and coverage

- A product name or one of its explicit aliases matches a complete term/phrase
  in the feed's CVE ID, product, description or compact affected-version text.
  Multiple watched products are ORed. Search query words are ANDed.
- Stored versions are context only. There is no package ecosystem resolver,
  CPE database, semantic version range engine, infrastructure scanner or enrichment.
- Matching CVE identities stay associated with a watch so a later correction can
  still be returned when the correction no longer names the product.
- Initial creation baselines existing matching activity. A read does not advance
  the watch. The client acknowledges consumed batches with a signed receipt.
  Acknowledgment proves client acceptance, **not notification delivery**. Retries
  can repeat unacknowledged results; clients should deduplicate on event GUID.
- NEW and UPDATE use different durable GUIDs. Repeated imports do not create
  events. Scoring-provider, version and scenario changes remain explicitly labelled.
- Source coverage is read from the live manifest: initially 7 days of backfill,
  30 days of activity, and score/correction tracking for known CVEs for 90 days
  after publication. This is not a complete 90-day or all-time catalog.
- Updates represent differences observed between upstream polls. Intermediate
  revisions can be combined. Affected-version-only metadata edits are not an UPDATE
  trigger in the feed. Term matching can miss ambiguous or omitted product names.
- A missed interval beyond retained history returns `coverage_gap`, never “all clear.”
  A stale source or outage leaves watch progress unchanged. Exact-ID lookup does
  not expand watch coverage.
- Limits: 20 watches per account, 20 products per watch, 5 aliases per product,
  40 results per batch. Follow `has_more`; capacity errors are explicit.

## Privacy

Supply product names and optional versions. Do not submit secrets, hostnames,
IP addresses, customer identities, private repositories or lockfiles.
The service stores a GitHub numeric ID, watch definition and accepted event IDs
in private D1, and OAuth connection records in private KV. It discards the GitHub
access token after sign-in and makes no calls to an AI model. Delete watches with
`delete_watch`; disconnect the connector and remove its scheduled task separately.
See [operator privacy and recovery notes](docs/OPERATIONS.md).

## Development

Node 22+:

```sh
npm ci
npm run check
npx wrangler d1 migrations apply aldabra-cve-watches --local
npm run dev
```

The local default is `http://localhost:8787`. Public MCP reads work without
credentials. Full OAuth requires a configured HTTPS origin and GitHub OAuth app;
the integration tests exercise the complete protocol with synthetic identities
and real local KV/D1. No production auth bypass is included.

One Worker serves Streamable HTTP MCP and OAuth; D1 stores watches; KV stores
OAuth state. The existing cloud feed ingestion and its 30-minute timer remain
independent. The client owns its daily schedule. There is no production dependency
on the development computer. See [deployment](docs/DEPLOYMENT.md).

## Source and license

Source data: [CVE Program / CVEProject/cvelistV5](https://github.com/CVEProject/cvelistV5),
presented through Aldabra's public feed. Returned data includes the upstream
license notice. CVE data retains its own terms; see the notices returned with
tool results. New connector source is under the [MIT license](LICENSE).