SDK Development
Developer Documentation
Build SDKs, integrations, and tools for VulnRadar: the finding types API, SDK conventions, and the contributor guide for the codebase itself.
- Detection Checks
- 905+
- License
- GPL-3.0
- API Version
- v3
Overview
This page covers two audiences:
- SDK authors integrating with
/api/v3/*from another language. - Contributors working on the VulnRadar codebase itself.
Endpoints, request/response shapes, and rate-limit semantics live on the API Reference and Rate Limits pages. The rest of this page is the integration manual.
Finding Types API
The Finding Types endpoint returns the full catalogue of detection checks. Use it to display human-readable titles, categorize findings, or build SDKs that know every check ID ahead of time.
/api/v3/finding-typesRequest
curl https://vulnradar.dev/api/v3/finding-typesResponse
{
"success": true,
"count": 907,
"data": [
{
"id": "hsts-missing",
"type": "header",
"title": "HSTS Header Missing",
"category": "headers",
"severity": "medium",
"description": "HTTP Strict Transport Security header is not set."
},
{
"id": "csp-missing",
"type": "header",
"title": "Content Security Policy Header Missing",
"category": "headers",
"severity": "medium",
"description": "Content Security Policy header is not set."
}
]
}Backed by lib/scanner/checks-data/*.json, one file per category, for the 852 legacy checks. Adding one of those means editing the JSON for its category and the matching detector in lib/scanner/checks/. The other 55 checks live on a newer PageCheck architecture under lib/scanner/checks/page-checks/ with metadata declared inline; see Architecture.
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., hsts-missing) |
type | string | Detection type (e.g., header, content, combined) |
title | string | Human-readable title for display |
category | string | One of the 17 categories in lib/scanner/types.ts: headers, ssl, tls, content, cookies, configuration, information-disclosure, dns, email, api, code, secrets-extended, vibe-code, client-side, supply-chain, host-validation, reputation |
severity | string | critical | high | medium | low | info |
description | string | Short human description |
Building SDKs
When building an SDK for VulnRadar, follow these guidelines.
1. Authentication
All authenticated requests require a Bearer token. Keys are prefixed vr_live_:
Authorization: Bearer vr_live_xxxxxxxxxxxxxxxxxxxxxxxx2. Base URL
https://vulnradar.dev/api/v33. Core endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /scan | Run a security scan on a URL |
| POST | /scan/bulk | Queue 5/10/25/100 URLs by plan in one request, then poll each scan id |
| POST | /scan/crawl | Deep-crawl and scan up to 25/50/100/250 pages by plan; unlimited when billing is off |
| POST | /scan/crawl/discover | Discover crawlable URLs, capped by the CRAWL_DISCOVER_MAX_PAGES setting (ships at 500) |
| POST | /scan/discover | Enumerate subdomains via crt.sh, HackerTarget, etc. |
| GET | /history | List scan history, newest first, paged with ?limit= and ?offset= (read maxLimit and truncated off the response) |
| GET | /history/[id] | Get full scan details, findings, and response headers |
| DELETE | /history | Wipe ALL scans for the authenticated user |
| DELETE | /history/[id] | Delete a single scan (owner only) |
Full request/response shapes: see API Reference.
4. Error handling
Each non-2xx response includes a JSON body with at minimum an error string. Map HTTP status to typed exceptions. The v3 API uses 400, 401, 402, 403, 404, 409, 413, 422, 429, 500, 502 and 503; the API reference says what each one means here. On 429, honour the Retry-After header and the X-RateLimit-Reset header.
SDK Checklist
Development Guide
Setup for contributing to VulnRadar. Covers local dev, scripts, commit conventions, common pitfalls.
Prerequisites
- Node.js 22 LTS (the
.nvmrcat the repo root says22) - npm 10+ (ships with Node 22)
- PostgreSQL 14+ (local install or via Docker)
- Git
Node Version Policy
VulnRadar targets Node.js 22 LTS exclusively.vitest@4, the test runner, additionally enforces ^20.0.0 || ^22.0.0 || >=24.0.0 in its own engines field, which is why an odd-numbered release like 21 or 23 fails before a single test runs rather than failing with a confusing error partway through.
Confirm your version and switch if needed:
# nvm / fnm / volta / asdf will all auto-pick this from the repo root
nvm use # reads .nvmrc (which says 22)
# or install + use explicitly
nvm install 22
nvm use 22
node --version # should print v22.x.xQuick Start
# 1. Clone
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.dev
# 2. Install dependencies
npm ci
# 3. Set up environment
cp .env.example .env
# Edit .env: DATABASE_URL, API_KEY_ENCRYPTION_KEY, NEXT_PUBLIC_APP_URL
# 4. Start the dev server (schema auto-creates on first boot)
npm run dev
# → http://localhost:3000The first run auto-initializes the schema via instrumentation.ts. Watch for Database schema verified successfully in the logs. The very first account created on a fresh install is made super_admin automatically, so on a new instance you just sign up and you already have full access. Only run the SQL below to promote a later account, and note it grants admin, which is one level below the first account. Running it against the first account would demote it, and no screen in the product can grant super_admin back.
UPDATE users SET role = 'admin' WHERE email = '[email protected]';Scripts
Every npm script and what it does. Defined in package.json. Not listed: predev and prebuild, which npm runs for you and which both do the same work as npm run build:knowledge.
| Script | What it does |
|---|---|
| npm run dev | Start Next.js dev server (HMR) on port 3000 |
| npm run build | Production build (next build) |
| npm start | Run the production build |
| npm run lint | ESLint over the repo (no --fix) |
| npm run lint:fix | ESLint with --fix (auto-fixes where safe) |
| npm run typecheck | tsc --noEmit, the hard CI gate |
| npm run format | Prettier --write on every supported file type |
| npm run format:check | Prettier --check (no writes) |
| npm test | Vitest single run over tests/, mirrors the source tree |
| npm run test:watch | Vitest in watch mode |
| npm run test:coverage | Vitest with v8 coverage (per-file thresholds) |
| npm run db:migrate | Run scripts/migrate/migrate.mjs (interactive) |
| npm run db:migrate:dry-run | Same, but only prints the plan |
| npm run db:create | Run scripts/create-fresh-db/create-fresh-db.mjs (side-by-side DB clone) |
| npm run db:create:dry-run | Same, but only prints the plan |
| npm run db:diagnose | Introspect the live schema and report data corruption: FK orphans, columns that will not decrypt, bad enum values, impossible timestamps. Read-only |
| npm run db:repair | Apply the fixes db:diagnose found. Dry run by default; real writes need --apply --admin-id=<id> and are logged to admin_audit_log |
| npm run db:diagnose-2fa | Report accounts whose 2FA columns are internally inconsistent. Read-only |
| npm run db:repair-2fa | Fix only the rows db:diagnose-2fa proved corrupt. It cannot unlock a healthy account |
| npm run db:repair-sequences | Reset the Postgres identity sequences, which is what causes duplicate-key errors on insert after a restore |
| npm run db:migrate-avatars | One-off: move avatars stored as database blobs onto the filesystem |
| npm run db:backup | Write a full dump. Run this before any upgrade or repair |
| npm run db:restore | Restore a dump written by db:backup |
| npm run build:knowledge | Regenerate every AI knowledge file. CI fails the PR if the committed output does not match, so run this after editing docs, changelog, checks, or legal pages |
| npm run docs:compile | Regenerate lib/ai/docs-knowledge.md only |
| npm run changelog:compile | Regenerate the changelog knowledge file only |
| npm run checks:compile | Regenerate the checks knowledge file and lib/config/check-stats.generated.ts |
| npm run legal:compile | Regenerate the legal knowledge file only |
| npm run audit:new | Start a new entry in audits/. The other audit:* scripts (add-finding, list, show, close) work the same record |
Linting
ESLint 9 with flat config (eslint.config.mjs). The config wraps next/core-web-vitals for React / Next / TS rules. CI runs npm run lint and fails on errors. Warnings don't block the build.
npm run lint # check
npm run lint:fix # auto-fixNotable rule overrides:
@typescript-eslint/no-unused-vars→warn(with^_underscore convention)@typescript-eslint/no-explicit-any→warn@next/next/no-html-link-for-pages→ off (we use<Link>exclusively)react/no-unescaped-entities→ off (too noisy for our content)
Type Checking
tsc --noEmit is a hard gate in CI. The build also fails on TypeScript errors via Next.js (next.config.mjs has typescript.ignoreBuildErrors unset). All merged code must type-check cleanly.
Commit Conventions
Conventional Commits format:
<type>(<scope>): <subject>
<body>
<footer>| Type | Used for |
|---|---|
| feat | New user-facing feature |
| fix | Bug fix |
| chore | Maintenance, deps, tooling, no production change |
| refactor | Code change with no behavior change |
| docs | Documentation only |
| style | Formatting only (no logic change) |
| test | Adding or updating tests |
| perf | Performance improvement |
| ci | CI/CD changes |
Examples:
feat(scan): add WebSocket CSWSH checkfix(auth): correct TOTP clock skew handlingchore(deps): bump next to 15.5.19docs: add /docs/architecture page
Pull Request Process
- Branch off
main(git switch -c fix/short-name) - Make focused commits (one logical change per commit)
- Run
npm run lint,npm run typecheck,npm test, andnpm run buildlocally - Use the PR template (
.github/pull_request_template.md) - Wait for CI (lint + typecheck + test + build + auto-applied labels)
- Request review from CODEOWNERS on security-critical paths
- After 1+ approval, squash-merge
Project Structure
app/: Next.js App Router (file-system routing)components/: React componentslib/: Server-side librarieshooks/: Custom React hookspublic/: Static assetsscripts/: admin and DB scripts (migrate/,create-fresh-db/,_lib/)instrumentation.ts: Next.js startup hooks (schema init + version check)middleware.ts: auth middlewarenext.config.mjs,tailwind.config.mjs,eslint.config.mjs,vitest.config.ts,tsconfig.json
Deeper tour: see the Architecture page.
Common Pitfalls
- Editing a value in
lib/config/constants.tsorregistry.ts: both derive fromconfig-values.ts. Editconfig-values.tsto move the shipped default, or change the value in Admin → Settings if it is runtime tier, which 258 of the 296 settings are. - Adding a database table: add the
CREATE TABLE IF NOT EXISTSto the right file underlib/database/schema/(the canonical source, and the same ordered listnpm run db:createruns) AND mirror it toscripts/migrate/versions/_snippets.mjs. It is no longer ininstrumentation.ts, which now only orders the boot phases. - Adding a new API route: copy an existing one in
app/api/v3/.../route.ts; wrap withwithErrorHandling, useparseBody+Validatefor input, and pick the right rate-limit helper fromlib/rate-limiting/. - Adding a new icon: use
lucide-react(default) orreact-icons(already installed). Don't bundle a new icon set. - Adding a constant: if it's a deployment tunable, add it to
lib/config/config-values.tsas aCONFIG_*. Avoid magic numbers in route handlers. If an admin should be able to change it without a redeploy, also add an entry tolib/config/registry.ts: a bare constant with no registry entry never appears in the admin settings UI.
Debugging
- Server logs: stdout from
npm run devordocker compose logs -f app - Database queries: temporarily add
console.loginlib/database/db-utils.ts(or anypool.querycaller) - Auth issues: inspect the session cookie in browser devtools (name:
vulnradar_session) - Build issues: the Dockerfile does not use Next.js
output: standalone; it copies.next+node_modulesfrom the build stage. Comments innext.config.mjsexplain why.
Contributing
Open source
VulnRadar is GPL-3.0 open source and welcomes contributions: bug fixes, new checks, documentation, SDKs, and translations.