# security-context-before

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FKherrisan%2Fsecurity-context-before&project-name=security-context-before&env=PROXY_API_KEY%2CDEEPSEEK_API_KEY&envDescription=Set%20a%20private%20proxy%20key%20and%20a%20DeepSeek%20API%20key%20before%20deploying.%20See%20the%20configuration%20section%20for%20optional%20GitHub%20and%20Upstash%20settings.&envLink=https%3A%2F%2Fgithub.com%2FKherrisan%2Fsecurity-context-before%23configuration)

[Security Context](https://securitycontext.dev) gives an agent the CVE and security-fix history of a program, so it can hunt with variant analysis and related strategies instead of starting from a blank tree. That is useful in production, but it breaks **recall evaluation on already-discovered bugs**: the agent is handed the answer key, so the score no longer measures unknown-vulnerability discovery. This proxy keeps the same SC tools while stripping CVEs and fixes that still apply at a requested snapshot, so a recall job can use SC as a historical map without leaking live ground truth.

Authenticated **remote MCP** proxy in front of Security Context. Repo queries take a snapshot `ref` (tag or commit). Responses keep only CVEs and fix fingerprints that already landed **before** that snapshot.

> **Deploy in one click:** the button opens Vercel's project import flow and asks for the two required secrets before building. After deployment, copy the generated `https://<project>.vercel.app/api/mcp` URL and configure it in your MCP client. The endpoint is private by default: every request must include the same `PROXY_API_KEY` that you entered in Vercel.

## Endpoint

After a Vercel deploy, use `https://<project>.vercel.app/api/mcp` (Streamable HTTP).

Auth (required):

```
Authorization: Bearer $PROXY_API_KEY
```

or `x-api-key: $PROXY_API_KEY`.

The proxy does not expose the upstream Security Context endpoint or the DeepSeek key to MCP clients. Keep the deployment URL and proxy key private.

## Tools

| Tool | Extra vs SC |
|---|---|
| `get_security_context` | required `ref` |
| `create_security_context` | required `ref` |
| `get_vulnerability_leads` | required `ref` |
| `get_vulnerability` | required `project` + `ref`; same-project live CVEs withheld |
| `search_vulnerabilities` | required `project` + `ref`; same-project live hits removed |

`ref` is a git tag (`7.0.1`) or commit SHA. `project` is the repo under test (`WordPress/WordPress` or `wordpress/wordpress`).

CVE search/get: if the record’s **Affected** product is this `project`, keep it only when the snapshot version is already past the CVE range (same rule as known_cves). Other products are returned unchanged.

## Filter

1. Resolve `ref` on GitHub (SHA, date, product version / `$wp_version`).
2. Fetch SC JSON for the repo **in parallel** with GitHub and the upstream MCP call.
3. Parse each CVE’s affected/fixed version via DeepSeek **Responses API**. Cache by CVE id.
4. Keep a CVE only if `snapshotVersion > affectedMax/fixedIn`.
5. Keep a fingerprint only if its fix `commit_date` is on or before the snapshot.

Unknown version ranges are **dropped** (no leak).

## Architecture

The request path is intentionally small: authenticate at the route boundary, validate the MCP tool input, resolve the requested GitHub snapshot, then filter upstream Security Context data before returning Markdown to the client.

```mermaid
flowchart LR
    Client[MCP client] -->|Bearer token or x-api-key| Auth[API-key guard]
    Auth --> Route[Next.js /api/mcp]
    Route --> Tools[MCP tools and Zod schemas]
    Tools --> Pipeline[Snapshot filter pipeline]
    Pipeline -->|commit, tag, version| GitHub[GitHub API]
    Pipeline -->|context, leads, CVEs| SC[Security Context]
    Pipeline -->|affected/fixed version parsing| DeepSeek[DeepSeek Responses API]
    Pipeline -.->|optional durable parse cache| Redis[Upstash Redis]
    Pipeline -->|filtered Markdown| Route
    Route --> Client
```

See the [standalone architecture diagram](docs/architecture.html) for the component-level view and the three filtering paths (`context`, `leads`, and `vulnerability search/get`).

## Deploy on Vercel

### Configuration

The deploy button requests the required values below. Add the optional values in Vercel's **Project Settings → Environment Variables** when needed.

| Variable | Required | Purpose |
| --- | --- | --- |
| `PROXY_API_KEY` | Yes | Shared secret required by every MCP request. Use a long, random value. |
| `DEEPSEEK_API_KEY` | Yes | DeepSeek Responses API key used to extract CVE affected/fixed versions. |
| `GITHUB_TOKEN` | Recommended | Raises GitHub API limits and is needed when resolving private repositories. |
| `DEEPSEEK_MODEL` | No | DeepSeek model name; defaults to `deepseek-flash`. |
| `DEEPSEEK_BASE_URL` | No | DeepSeek-compatible API base URL; defaults to `https://api.deepseek.com`. |
| `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` | No | Durable CVE parse cache across serverless invocations. In-memory caching is always enabled. |

The upstream endpoints can also be overridden for testing:
`SECURITYCONTEXT_MCP_URL` defaults to `https://securitycontext.dev/mcp` and
`SECURITYCONTEXT_JSON_BASE` defaults to `https://securitycontext.dev/r`.

The Vercel function is configured with a 60-second maximum duration in
[`vercel.json`](vercel.json). A full context or vulnerability search may make
several upstream calls, so use a durable cache for repeated production traffic.

### CLI deployment

```bash
cp .env.example .env.local
# set PROXY_API_KEY and DEEPSEEK_API_KEY; GITHUB_TOKEN is recommended
npx vercel
```

Vercel env: `PROXY_API_KEY`, `DEEPSEEK_API_KEY`, `DEEPSEEK_MODEL` (default `deepseek-flash`), `GITHUB_TOKEN`. Optional durable cache: `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN`.

### Connect an MCP client

Use the deployed URL as a Streamable HTTP MCP server and send the proxy key as a bearer token. For clients that use an `mcpServers` JSON configuration:

```json
{
  "mcpServers": {
    "security-context-before": {
      "type": "streamable-http",
      "url": "https://<project>.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <PROXY_API_KEY>"
      }
    }
  }
}
```

Local:

```bash
pnpm install
pnpm test
pnpm dev
```

MCP inspector: Streamable HTTP → `http://localhost:3210/api/mcp` with the bearer token.

## Vulseek

Point the org MCP server `securitycontext` URL at this `/api/mcp` and configure the proxy key. Send `ref` from the job tag (and `project` on search/get). The upstream SC tools do **not** have `ref` or `project`; orch/hunter tool schemas must include them when using this proxy.