# VulnRap — Guide for AI Agents

## Behaviour changes (newest first)

- **2026-10-26:** `POST /api/reports` and `POST /api/reports/check` now say how much of the text was read: `analysedChars` (at most 50,000) and `truncated` (true when the text was longer than 50,000 characters after cleaning, or longer than 250,000 characters as received). Before, a long text was cut without any sign in the response, and this manual said the first 250,000 characters were analyzed.
- **2026-10-22:** `POST /api/reports` and `POST /api/reports/check` answer HTTP 400 with `code: "too_short"` when the text is under 20 characters (before, a two-character report got a verdict). A GET on `/api/reports/check` answers 405 with `Allow: POST`. A request body that is not valid JSON says so.
- **2026-10-21:** no API change. The web page now shows plainer words for the labels (for example "Weak evidence" for `HIGH RISK`); the identifiers the API returns are unchanged. See "Labels" below.
- **2026-10-20:** with `aiOpinion=true`, `aiOpinion.similar` shows how similar public bounty-program reports (a fixed reference set of 1,085, vectors and an accepted label only) were decided, plus the AI score combined with that. It does not change the triage label. It adds one embedding call and one lookup (about 0.2 s) and nothing is stored.
- **2026-10-20:** every check result carries an `outcomeTicket` (numbers only, valid 30 days). `POST /api/outcomes {ticket, outcome}` (MCP `record_check_outcome`) records what happened to a report you only checked, so VulnRap can measure itself against real outcomes; no text, id or address is stored; rate limited. `aiLabel=false` (MCP `aiLabel: false`) shows the AI opinion without letting it change the triage record: no label change and no questions added (suggestions are still listed in `aiInfluence`). Only an explicit false-like value (`false`, `0`, `off`, `no`) switches it off. `POST /api/reports/check?view=summary` returns a compact result (about a tenth the size). `GET /api/capabilities` lists every optional behaviour, its default per surface, what data leaves and its limits. MCP `check_report` and `submit_report` declare an `outputSchema` and return `structuredContent`.
- **2026-10-19:** every JSON error has a stable `code` and, when waiting helps, `retryAfterSeconds`; routes behind the exact limiter return `RateLimit-*` headers; `/llms.txt`, `/openapi.json` and `/.well-known/mcp.json` exist.
- **2026-10-19:** the web form is private by default.
- **2026-10-18:** with `aiOpinion=true`, the AI opinion can move the triage label between `STANDARD_TRIAGE` and `CHALLENGE_REPORTER`; the `aiInfluence` object records what it did.

> **You are an AI agent (autonomous coding agent, security copilot, triage bot, research agent, or
> similar) and a vulnerability report just landed in your inbox. Read this file first.** It tells
> you everything you need to integrate with VulnRap so the human you work for gets a real, scored,
> reviewer-grounded second opinion on every report — and so the platform learns from how well it
> did on each one.

VulnRap is a free, anonymous, no-account-required service that scores vulnerability reports for
**slop** (low-effort, AI-generated, copy-paste, hand-wavy, fabricated) vs. **substance** (real
evidence, working PoC, reproducible impact). It is run by REMEDiSSecurity for the public good; the
codebase is open source. The point of this file is to make it trivial for _your_ system to share
reports for a second opinion and to feed your verdict back into the platform so it gets better
over time.

If you're a coding agent working **inside** the VulnRap repository, see the engineering README
(`README.md`); this file is for agents using VulnRap as a **service**.

---

## TL;DR — the 30-second integration

1. **Check every inbound vulnerability report with `POST https://vulnrap.com/api/reports/check`**
   as soon as you receive it: it scores the report and stores nothing. Use `POST /api/reports`
   only when your user wants a recorded copy. Reports are private by default (only fingerprints
   and scores are kept, never the text). Never set `showInFeed=true` unless the person you act
   for has explicitly asked to publish that report: published reports are redacted, but
   redaction is pattern based and cannot be undone by anyone but the holder of the delete token.
2. **Read the `slopScore` (0–100, higher = sloppier), `qualityScore` (0–100, higher = better),
   and `validityScore` (0–100, higher = more substance)** from the response. Surface those — plus
   a verify link you build yourself as `https://vulnrap.com/verify/{id}` — alongside your own
   assessment to the human.
3. **After the human (or you) acts on the report, send one feedback call** to
   `POST /api/feedback` with `reportId` (integer), `rating` (1–5), `helpful` (bool), and a
   one-line `comment` describing what actually happened ("real RCE, paid bounty" / "fabricated,
   closed"). This is how VulnRap calibrates itself — please don't skip it.

That's the whole loop. The rest of this file is the details.

---

## What VulnRap actually does

When you submit a vulnerability report, VulnRap runs three engines on it:

| Engine                        | What it measures                                                                                                          | What it returns                                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Slop detector**             | Copy-paste, AI boilerplate, hand-wavy phrasing, missing PoC, overconfident vibes                                          | `slopScore` 0–100 (higher = sloppier), plus `slopTier` and human-readable `feedback[]`                                                                                                 |
| **Quality / validity scorer** | Reproducible steps, working PoC, concrete impact, strong-evidence "gold signals", claim specificity, internal consistency | `qualityScore` 0–100, `validityScore` 0–100, plus a structured `substance` object with `pocValidity` / `claimSpecificity` / `domainCoherence` / `coherenceScore` when LLM analysis ran |
| **Section hashing**           | SHA-256 of normalized sections; finds reports that recycle the same PoC, intro, or impact text across submissions         | `sectionHashes`, `sectionMatches[]`, `similarityMatches[]`                                                                                                                             |

You also get back an integer `id` (use it to build `/verify/{id}` and `/results/{id}` URLs
yourself), a `redactedText` payload, an `evidence[]` array of specific signals the rule engine
flagged with their weights, and (when LLM analysis runs) `llmSlopScore` / `llmFeedback` /
`llmBreakdown` so you can explain _why_ the score is what it is.

The lightweight `GET /api/reports/{id}/verify` endpoint additionally returns a short
human-readable `reportCode` (e.g. `VR-7K3M`) and a server-built `verifyUrl` if you want a clean
shareable handle without constructing the URL yourself.

---

## Recommended defaults for AI agents

These are the defaults VulnRap is tuned for. Use them unless your user has a specific reason to
opt out — and if they do, document why in your own logs.

| Setting                              | Default                         | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showInFeed`                         | `"false"` (API default)         | Private unless set. Publish only on explicit request. A published report shows redacted text and scores, never reporter identity, and stays unlisted for 10 minutes (reachable by its link and deletable with its token, but not in the feed, comparisons or duplicate matching) before it is listed.                                                                                                                                                                                                                                                                                                                                                                  |
| `contentMode`                        | `"full"`                        | Stores the redacted text so the substance/slop engines can give a complete diagnostic. `"similarity_only"` stores hashes only and skips most of the diagnostics.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `skipLlm`                            | `"false"`                       | LLM-backed analysis is currently off on vulnrap.com, so this setting changes nothing today. Leave it at its default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `skipRedaction`                      | `"false"`                       | Stored reports are always redacted. The flag is ignored for stored submissions, so there is no opt-out. Don't rely on it for routine traffic.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `file` vs. `rawText` vs. `reportUrl` | Pick whichever you already have | All three are first-class. PDFs are extracted server-side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Feedback after every report**      | **Yes**                         | It is how we see where the scoring helps and where it misses. One short feedback call per report is enough.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `aiOpinion`                          | `"false"` (opt in)              | Optional AI second opinion on `POST /api/reports/check` and `POST /api/reports`: the redacted text (first 9,000 characters) is assessed by Cloudflare Workers AI and you get an advisory score, the model's category and confidence, and every answer behind it. Ask your user first. It never changes any score, but it can move the triage label between `STANDARD_TRIAGE` and `CHALLENGE_REPORTER` (AI score 80 or more relaxes a challenge; under 20 tightens standard triage); the response's `aiInfluence` field records whether it did, why, and the measured basis. When used on a submission, only the model's numbers (never text) are kept with the report. |

For anything confidential (customer NDA, embargoed CVE) use `check` or a private submission:
the text is never stored. You still get a `slopScore` and a match count.

---

## API basics

- **Base URL:** `https://vulnrap.com/api`
- **Auth:** None for the endpoints below. No account, no API key, no OAuth.
- **Content type:** `multipart/form-data` for submission, `application/json` for feedback.
- **Rate limits:** Per IP, per minute: 10 submissions (`POST /api/reports`), about 20 checks (`POST /api/reports/check`, edge-enforced, approximate), 6 batch requests, 30 MCP calls (`POST /mcp`). Cached public endpoints (feed, stats, status) are not limited. Over the limit you get HTTP 429 with a `Retry-After` header. Routes behind the exact limiter (submit, batch, MCP) also return `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` on every response so you can pace yourself. **Errors:** every JSON error is `{"error": "message", "code": "rate_limited", "retryAfterSeconds": 60}`; branch on `code` (never on the message), and wait `retryAfterSeconds` when present. Codes: `invalid_request`, `too_short`, `unauthorized`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `payload_too_large`, `unsupported_media_type`, `unprocessable`, `rate_limited`, `daily_limit_reached`, `capacity_reached`, `internal_error`, `bad_gateway`, `unavailable`, `timeout`.
  If you're operating at scale, reach out (`remedisllc@gmail.com`) and we'll work something out
  rather than have you get throttled.
- **OpenAPI spec:** `https://vulnrap.com/openapi.yaml` (also at
  [`lib/api-spec/openapi.yaml`](https://github.com/REMEDiSSecurity/VulnRap.Com/blob/main/lib/api-spec/openapi.yaml)
  in the repo). It describes the whole API surface; reviewer-only and some
  secondary areas in it are not served by the current deployment, so rely on the
  endpoints documented in this file. There is no Swagger UI.
- **Discovery:** `https://vulnrap.com/llms.txt` (index), `/llms-full.txt` (this file), `/openapi.json` and
  `/openapi.yaml`, and the MCP server card at `/.well-known/mcp.json`.
- **MCP server:** `https://vulnrap.com/mcp` (streamable HTTP, JSON-RPC 2.0, no key, stateless).
  Tools: `check_report` (score without storing), `submit_report`, `lookup_report`,
  `find_by_hash`, `list_recent_reports`, `record_outcome`, `record_check_outcome`, `get_outcomes_summary`,
  `get_stats`, `get_status`. Each calls the endpoint of the same name above, so the same
  limits apply. `check_report` and `submit_report` take an optional boolean `aiOpinion`
  (default false; ask your user first) that returns the condensed `aiOpinion` and
  `aiInfluence` objects, including any specific questions for the reporter in
  `triage.challengeQuestions`. Claude Code: `claude mcp add --transport http vulnrap https://vulnrap.com/mcp`.
- **Human-readable API guide:** `https://vulnrap.com/developers`

---

## Step 1 — Submit a report for analysis

There are three ways to submit, pick whichever you already have. They are mutually exclusive
within a single request: send either `file`, or `rawText`, or `reportUrl`.

The examples below are private, which is the default (only fingerprints and scores are kept, never
the text). Add `-F "showInFeed=true"` only when the person you act for asked to publish the report.

```bash
# A) Upload a file (multipart field name MUST be "file")
curl -X POST https://vulnrap.com/api/reports \
  -F "file=@./inbound-report.md;type=text/markdown" \
  -F "contentMode=full"

# B) Submit raw text inline (multipart string field; up to 5 MB accepted, a text over 250,000 characters is cut, and only the first 50,000 characters are analyzed; the response says so: `truncated` and `analysedChars`)
curl -X POST https://vulnrap.com/api/reports \
  -F "rawText=$(cat ./inbound-report.md)" \
  -F "contentMode=full"

# C) Point at a public URL (allowlisted hosts only — see below)
curl -X POST https://vulnrap.com/api/reports \
  -F "reportUrl=https://gist.github.com/octocat/abc123def456" \
  -F "contentMode=full"
```

**`reportUrl` allowlist (as of writing):** `raw.githubusercontent.com`, `github.com` (blob URLs
are auto-rewritten to raw), `gist.githubusercontent.com`, `gist.github.com`, `gitlab.com`,
`pastebin.com`, `dpaste.org`, `hastebin.com`, `paste.debian.net`, `bpa.st`. Other hosts (e.g.
HackerOne, Bugcrowd) are rejected; download the report yourself and pass it via `file` or
`rawText`. Maximum fetched size is 5 MB; timeout is 15 s. The current allowlist is the source
of truth — check `ALLOWED_URL_HOSTS` in `artifacts/api-server/src/routes/reports.ts` if a host
you need is missing.

Response (truncated, real field names):

```json
{
  "id": 12345,
  "deleteToken": "8f1a4c…",
  "contentHash": "sha256:…",
  "contentMode": "full",
  "slopScore": 82,
  "slopTier": "high_slop",
  "qualityScore": 19,
  "validityScore": 14,
  "confidence": 0.86,
  "authenticityScore": 78,
  "evidence": [ { "type": "vague_impact", "weight": 12, "description": "…" } ],
  "humanIndicators": [ … ],
  "sectionHashes": { "summary": "…", "poc": "…" },
  "sectionMatches": [ { "sectionTitle": "poc", "matchedReportId": 11987, "similarity": 1.0 } ],
  "similarityMatches": [ { "reportId": 11987, "similarity": 0.93, "matchType": "near_dup" } ],
  "redactedText": "…",
  "feedback": [ "Missing concrete reproduction steps…" ],
  "llmSlopScore": 79,
  "llmFeedback": [ … ],
  "llmBreakdown": { "claimSpecificity": 8, "evidenceQuality": 6, "verdict": "LIKELY_FABRICATED" },
  "substance": { "pocValidity": 5, "claimSpecificity": 8, "domainCoherence": 30, "substanceScore": 14, "coherenceScore": 22 },
  "vulnrap": { "compositeScore": 18, "label": "noise", "engines": [ … ] },
  "createdAt": "2026-04-30T03:14:15.926Z"
}
```

**Save `id` and `deleteToken`.** The `id` is what you pass to Step 3 (feedback). The
`deleteToken` is the _only_ credential that can ever delete this report — there's no admin
override, store it.

To build the public verify URL for the human, use `https://vulnrap.com/verify/{id}`. To get the
short human-readable handle (`VR-…`), call `GET /api/reports/{id}/verify` and read its
`reportCode` field.

## Step 2 — Retrieve / re-fetch the analysis

```bash
# Full analysis (idempotent, cached)
curl https://vulnrap.com/api/reports/{id}

# Lightweight verification badge (good for embeds / chat replies)
curl https://vulnrap.com/api/reports/{id}/verify

# Markdown export ready to paste into a Jira / ServiceNow / ticket comment
curl https://vulnrap.com/api/reports/{id}/triage-report
```

The `/triage-report` endpoint is purpose-built for agents: it returns a clean Markdown summary
including the scores, the gold-signal bonus breakdown, and the section-hash matches. Pasting it
into the ticket is usually the right move.

## Step 3 — Send feedback so VulnRap can learn

This is the single most important step for the long-term health of the platform. Run it after
the human has triaged the report (real, dup, fabricated, won't-fix, paid bounty, etc.).

Feedback is gated by a tiny proof-of-work challenge to keep spam out. The challenge endpoint
returns a `nonce`, a `prefix`, and a `difficulty` (number of leading hex zeros required); your
client finds any string `solution` such that
`sha256(prefix + nonce + solution)` starts with `"0".repeat(difficulty)`. At the current
difficulty of 4, brute-force completes in well under a second from a normal CPU.

Reference solver — Node.js (no dependencies, ~50 lines including the POST):

```js
import { createHash } from "node:crypto";

async function submitFeedback({ reportId, rating, helpful, comment }) {
  // 1. Fetch the challenge
  const ch = await fetch("https://vulnrap.com/api/feedback/challenge").then(
    (r) => r.json(),
  );
  // ch = { challengeId, nonce, difficulty, prefix, expiresAt }

  // 2. Solve the proof-of-work
  const target = "0".repeat(ch.difficulty);
  let solution = 0;
  while (true) {
    const candidate = solution.toString(16);
    const hash = createHash("sha256")
      .update(ch.prefix + ch.nonce + candidate)
      .digest("hex");
    if (hash.startsWith(target)) break;
    solution++;
  }

  // 3. Submit
  const res = await fetch("https://vulnrap.com/api/feedback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      challengeId: ch.challengeId,
      challengeSolution: solution.toString(16),
      reportId, // integer from Step 1
      rating, // 1–5
      helpful, // boolean
      comment, // ≤ 1000 chars
    }),
  });
  return res.json();
}

await submitFeedback({
  reportId: 12345,
  rating: 5,
  helpful: true,
  comment: "Real RCE in product X. PoC reproduced on first try. Bounty paid.",
});
```

Reference solver — Python (no dependencies):

```python
import hashlib, json, urllib.request

def submit_feedback(report_id, rating, helpful, comment):
    ch = json.loads(urllib.request.urlopen("https://vulnrap.com/api/feedback/challenge").read())
    target = "0" * ch["difficulty"]
    solution = 0
    while True:
        cand = format(solution, "x")
        h = hashlib.sha256((ch["prefix"] + ch["nonce"] + cand).encode()).hexdigest()
        if h.startswith(target):
            break
        solution += 1
    body = json.dumps({
        "challengeId": ch["challengeId"],
        "challengeSolution": format(solution, "x"),
        "reportId": report_id,
        "rating": rating,
        "helpful": helpful,
        "comment": comment,
    }).encode()
    req = urllib.request.Request(
        "https://vulnrap.com/api/feedback",
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    return json.loads(urllib.request.urlopen(req).read())
```

Each challenge is single-use, expires after 5 minutes, and is rate-limited per IP. If you get a
403 with "Invalid solution", recompute against the latest `nonce`/`prefix` from a fresh
`/feedback/challenge` call.

**What to put in `comment`:** one short, factual sentence about _what actually happened_ with this
report. "Fabricated — function doesn't exist in the codebase." "Real but already known (dup of
CVE-2024-1234)." "Real, novel, paid $500." This is the ground-truth label VulnRap uses to recompute
its scoring weights, so don't editorialize and don't skip it.

`rating` (1–5) and `helpful` (bool) are about whether _VulnRap's analysis_ helped you, not about
the report itself. A fabricated report that VulnRap correctly flagged with `slopScore: 90` is a
5/5, helpful=true.

---

## How to present VulnRap's verdict to the human

A good agent integration shows, at minimum:

- The `slopScore` and `substanceScore` (with the color thresholds: green <30, amber 30–69, red ≥70 for slop; inverted for substance).
- The `matchCount` if > 0, plus a link to `/compare/{id}/{matchId}` so the human can see the duplication.
- The `verifyUrl` so the human (or anyone they forward the ticket to) can click through and see the public badge.
- Your _own_ assessment alongside it. VulnRap is a second opinion, not an oracle.

Don't auto-close tickets purely on `slopScore`. Use it as a strong signal, not a verdict.

**Labels.** The values the API returns are stable identifiers; match on them, not on the words the web page shows. The page says what each means in plain language: triage actions `PRIORITIZE` (read first), `STANDARD_TRIAGE` (normal queue), `CHALLENGE_REPORTER` (ask the reporter), `MANUAL_REVIEW` (needs a person), `AUTO_CLOSE` (confirm before closing); composite bands `STRONG`, `PROMISING`, `REASONABLE`, `NEEDS REVIEW`, `HIGH RISK`, `LIKELY INVALID` (strong to very weak evidence, from the heuristic engines, a reading aid); slop tiers `Clean`, `Likely Human`, `Questionable`, `Likely Slop`, `Slop` (few to strong AI signs). None of these is a verdict on whether a program will accept the report.

---

## Privacy, content modes, and what gets stored

- **PII redaction** runs in the browser/API before any text touches the database. Emails, phone
  numbers, IPs, common token formats, and a long denylist of secret patterns are scrubbed.
- **`contentMode=full`** stores the redacted text so the diagnostics page can show the human
  _why_ a section scored the way it did. This is the default and what we recommend.
- **`contentMode=similarity_only`** stores per-section SHA-256 hashes only. Use this if the
  report contents are sensitive (NDA, embargoed CVE, customer data your scrubber missed).
  You'll still get a slop/substance score and a match count, but the diagnostics block will be
  thin.
- **`showInFeed=false`** removes the report from the public Recent Reports feed and the
  `/reports` explorer. It's still in the database (so `/api/reports/{id}` still works for you
  via the `id` you got back), just not publicly listed.
- **Deletion:** the `deleteToken` returned at submission time is the only credential that can
  delete the report. There is no admin override; if you lose the token, the report is permanent.
  Store it.

Read the full policy at [`/privacy`](https://vulnrap.com/privacy).

---

## What not to do

- **Don't strip the redaction step** by setting `skipRedaction=true` for routine traffic. It's
  there to protect _your user's_ secrets, not just VulnRap.
- **Don't submit the same report on a tight loop** to "watch the score change." The score is
  deterministic per submission; resubmitting the same content just spends rate limit and
  pollutes the duplicate-detection signal for everyone else.
- **Don't claim VulnRap "validated" a report** when all you got back was a low slop score. A low
  slop score means the report doesn't _look_ like AI slop — it does not mean the vulnerability
  is real. Always run the actual reproduction.
- **Don't drop the feedback step** because "the report wasn't interesting." Boring reports are
  exactly the ones VulnRap most needs ground truth on.

---

## Versioning, changelog, and contact

- **Changelog:** [`/changelog`](https://vulnrap.com/changelog)
- **Stats / health:** [`/stats`](https://vulnrap.com/stats) and [`/transparency`](https://vulnrap.com/transparency)
- **Source code:** <https://github.com/REMEDiSSecurity/VulnRap.Com>
- **Security contact:** [`/.well-known/security.txt`](https://vulnrap.com/.well-known/security.txt) — `remedisllc@gmail.com`
- **General contact / API rate-limit increases:** `remedisllc@gmail.com`

This file lives at <https://vulnrap.com/agents.md>. Cache it for a day, refetch it weekly. If
the schema in this file ever conflicts with the OpenAPI spec at `/openapi.yaml`, the OpenAPI spec
wins.

— The VulnRap team
