Skip to main content

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.

GET
/api/v3/finding-types
Public

Request

bash
curl https://vulnradar.dev/api/v3/finding-types

Response

JSON
{
  "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

FieldTypeDescription
idstringUnique identifier (e.g., hsts-missing)
typestringDetection type (e.g., header, content, combined)
titlestringHuman-readable title for display
categorystringOne 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
severitystringcritical | high | medium | low | info
descriptionstringShort 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_:

HTTP
Authorization: Bearer vr_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Base URL

text
https://vulnradar.dev/api/v3

3. Core endpoints

MethodEndpointDescription
POST/scanRun a security scan on a URL
POST/scan/bulkQueue 5/10/25/100 URLs by plan in one request, then poll each scan id
POST/scan/crawlDeep-crawl and scan up to 25/50/100/250 pages by plan; unlimited when billing is off
POST/scan/crawl/discoverDiscover crawlable URLs, capped by the CRAWL_DISCOVER_MAX_PAGES setting (ships at 500)
POST/scan/discoverEnumerate subdomains via crt.sh, HackerTarget, etc.
GET/historyList 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/historyWipe 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

Bearer-token authentication via vr_live_ prefix
Configurable base URL (defaults to APP_URL/api/v3)
Type-safe response models matching the Vulnerability type
Typed exception classes for each HTTP status
Rate-limit handling with exponential backoff
Honors X-RateLimit-Reset, Retry-After, X-RateLimit-Remaining
Configurable timeout per request
Verifies the X-VulnRadar-Signature webhook header (sha256=<hex>, HMAC-SHA256 of the raw body)
Example usage in README
Unit tests with mocked fetch responses

Development Guide

Setup for contributing to VulnRadar. Covers local dev, scripts, commit conventions, common pitfalls.

Prerequisites

  • Node.js 22 LTS (the .nvmrc at the repo root says 22)
  • 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:

bash
# 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.x

Quick Start

bash
# 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:3000

The 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.

SQL
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.

Every npm script and what it does
ScriptWhat it does
npm run devStart Next.js dev server (HMR) on port 3000
npm run buildProduction build (next build)
npm startRun the production build
npm run lintESLint over the repo (no --fix)
npm run lint:fixESLint with --fix (auto-fixes where safe)
npm run typechecktsc --noEmit, the hard CI gate
npm run formatPrettier --write on every supported file type
npm run format:checkPrettier --check (no writes)
npm testVitest single run over tests/, mirrors the source tree
npm run test:watchVitest in watch mode
npm run test:coverageVitest with v8 coverage (per-file thresholds)
npm run db:migrateRun scripts/migrate/migrate.mjs (interactive)
npm run db:migrate:dry-runSame, but only prints the plan
npm run db:createRun scripts/create-fresh-db/create-fresh-db.mjs (side-by-side DB clone)
npm run db:create:dry-runSame, but only prints the plan
npm run db:diagnoseIntrospect the live schema and report data corruption: FK orphans, columns that will not decrypt, bad enum values, impossible timestamps. Read-only
npm run db:repairApply 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-2faReport accounts whose 2FA columns are internally inconsistent. Read-only
npm run db:repair-2faFix only the rows db:diagnose-2fa proved corrupt. It cannot unlock a healthy account
npm run db:repair-sequencesReset the Postgres identity sequences, which is what causes duplicate-key errors on insert after a restore
npm run db:migrate-avatarsOne-off: move avatars stored as database blobs onto the filesystem
npm run db:backupWrite a full dump. Run this before any upgrade or repair
npm run db:restoreRestore a dump written by db:backup
npm run build:knowledgeRegenerate 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:compileRegenerate lib/ai/docs-knowledge.md only
npm run changelog:compileRegenerate the changelog knowledge file only
npm run checks:compileRegenerate the checks knowledge file and lib/config/check-stats.generated.ts
npm run legal:compileRegenerate the legal knowledge file only
npm run audit:newStart 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.

bash
npm run lint        # check
npm run lint:fix    # auto-fix

Notable 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:

text
<type>(<scope>): <subject>

<body>

<footer>
Conventional Commits type prefixes and what each is used for
TypeUsed for
featNew user-facing feature
fixBug fix
choreMaintenance, deps, tooling, no production change
refactorCode change with no behavior change
docsDocumentation only
styleFormatting only (no logic change)
testAdding or updating tests
perfPerformance improvement
ciCI/CD changes

Examples:

  • feat(scan): add WebSocket CSWSH check
  • fix(auth): correct TOTP clock skew handling
  • chore(deps): bump next to 15.5.19
  • docs: add /docs/architecture page

Pull Request Process

  1. Branch off main (git switch -c fix/short-name)
  2. Make focused commits (one logical change per commit)
  3. Run npm run lint, npm run typecheck, npm test, and npm run build locally
  4. Use the PR template (.github/pull_request_template.md)
  5. Wait for CI (lint + typecheck + test + build + auto-applied labels)
  6. Request review from CODEOWNERS on security-critical paths
  7. After 1+ approval, squash-merge

Project Structure

  • app/: Next.js App Router (file-system routing)
  • components/: React components
  • lib/: Server-side libraries
  • hooks/: Custom React hooks
  • public/: Static assets
  • scripts/: admin and DB scripts (migrate/, create-fresh-db/, _lib/)
  • instrumentation.ts: Next.js startup hooks (schema init + version check)
  • middleware.ts: auth middleware
  • next.config.mjs, tailwind.config.mjs, eslint.config.mjs, vitest.config.ts, tsconfig.json

Deeper tour: see the Architecture page.

Common Pitfalls

  1. Editing a value in lib/config/constants.ts or registry.ts: both derive from config-values.ts. Edit config-values.ts to move the shipped default, or change the value in Admin → Settings if it is runtime tier, which 258 of the 296 settings are.
  2. Adding a database table: add the CREATE TABLE IF NOT EXISTS to the right file under lib/database/schema/ (the canonical source, and the same ordered list npm run db:create runs) AND mirror it to scripts/migrate/versions/_snippets.mjs. It is no longer in instrumentation.ts, which now only orders the boot phases.
  3. Adding a new API route: copy an existing one in app/api/v3/.../route.ts; wrap with withErrorHandling, use parseBody + Validate for input, and pick the right rate-limit helper from lib/rate-limiting/.
  4. Adding a new icon: use lucide-react (default) or react-icons(already installed). Don't bundle a new icon set.
  5. Adding a constant: if it's a deployment tunable, add it to lib/config/config-values.ts as a CONFIG_*. Avoid magic numbers in route handlers. If an admin should be able to change it without a redeploy, also add an entry to lib/config/registry.ts: a bare constant with no registry entry never appears in the admin settings UI.

Debugging

  • Server logs: stdout from npm run dev or docker compose logs -f app
  • Database queries: temporarily add console.log in lib/database/db-utils.ts (or any pool.query caller)
  • 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_modules from the build stage. Comments in next.config.mjs explain why.

Contributing

Open source

VulnRadar is GPL-3.0 open source and welcomes contributions: bug fixes, new checks, documentation, SDKs, and translations.

Developer Guide: Add a Detection Check | VulnRadar