Skip to main content

Add a checklist item

Adding a check means editing one data file. You never touch a React component — the UI renders any data that follows the schema, and TypeScript (plus bun test) validates your contribution when you run bun run typecheck (and in CI).

The hierarchy is four levels:

Platform (module)  →  Category  →  Technology / Feature  →  Checklist Item

1. Find the right place​

Categories live in src/data/checklist/categories/. Open the relevant file (e.g. authentication.ts) and find the technology your check belongs to (e.g. jwt, oauth, session-management). Each technology owns an items array.

2. Append an item​

Copy this template into the technology's items array and fill it in:

{
  id: 'webapp-auth-jwt-something-unique', // globally unique, kebab-case, stable
  title: 'Test for <the thing>',          // short, imperative
  description:
    'What the check is about and why it matters. One or two sentences.',
  whatToVerify:
    'Concrete, practical "what to verify" guidance — actionable, not theory.',
  severity: 'high',                       // 'critical' | 'high' | 'medium' | 'low' | 'info'
  tags: ['jwt', 'owasp-a07'],             // for search + filtering
  tools: ['jwt_tool', 'Burp Suite'],      // real tools useful for this check
  references: [
    {
      label: 'PortSwigger – JWT attacks',
      url: 'https://portswigger.net/web-security/jwt',
    },
  ],
},

Rules the build enforces​

  • id must be globally unique — a duplicate id throws during bun run build.
  • severity must be one of the five allowed values (it's a union type).
  • references must have at least one entry with an https:// URL.
  • Every technology must have at least one item, and every category at least one technology.

3. Add a new technology​

Add a Technology object to a category's technologies array:

{
  id: 'graphql',                          // globally unique, kebab-case
  title: 'GraphQL',
  description: 'One line on what this technology/feature covers.',
  items: [
    /* one or more items, as above */
  ],
},

4. Add a new category (optional)​

Create src/data/checklist/categories/my-category.ts:

import type {ChecklistCategory} from '../types';

export const myCategory: ChecklistCategory = {
  id: 'my-category',
  title: 'My Category',
  description: 'One line on what this covers.',
  module: 'webapp',
  order: 8,
  technologies: [
    /* one or more Technology objects */
  ],
};

Then register it in src/data/checklist/index.ts (import it and add it to RAW_CATEGORIES). Nothing else needs to change — the renderer, search index, and exports all pick it up automatically.

5. Verify locally​

bun install
bun run typecheck   # schema validation
bun test            # unique ids + valid references across the whole corpus
bun run build       # full static build (also runs the uniqueness assertion)
bun run start       # preview at http://localhost:3000

6. Open a pull request​

Use the New checklist item issue template to propose, or open a PR directly. Good items are specific, testable, and cite a reputable reference (OWASP WSTG/ASVS, PortSwigger, RFCs, vendor docs).