Catalog Authoring Guide

Overview

The CRA risk catalog is the source of truth for all assessment requirements. It is authored in Markdown at resources/structure.md and compiled to JSON at catalog/compiled/catalog.json.

Catalog Hierarchy

## N. Feature Category
### N.M Feature Name
  **Detection**: Static / Dependency / Interview hints
  **Risks**: Table of Risk ID | Description | Annex I Reference
  **Requirements**: Table of Req ID | Text | Assessment Method | Evidence Type

Editing the Catalog

Add a New Requirement

1. Find the correct Feature section (e.g., ### 4.1 Cryptographic Operations)
2. Add a row to the Requirements table:

| CRYPTO-01-R4 | The product shall use authenticated encryption modes (GCM, CCM) | Code review | Semi |

Convention: {CATEGORY}-{RISK_NUM}-R{SEQ}

Add a New Risk

Add a row to the Risks table under the relevant Feature:

| CRYPTO-04 | Insufficient key rotation | I.3(d) - stored data protection |

Add a New Feature

### 4.2 Post-Quantum Cryptography

**Detection**:
- Static: PQC library usage (liboqs, pqcrypto)
- Interview: "Does your product prepare for post-quantum migration?"

**Risks**:
| Risk ID | Risk | Annex I Reference |
|---------|------|-------------------|
| CRYPTO-PQ-01 | Vulnerable to quantum attacks | I.3(a) - confidentiality |

**Requirements**:
| Req ID | Requirement | Assessment Method | Evidence Type |
|--------|-------------|-------------------|---------------|
| CRYPTO-PQ-01-R1 | The manufacturer shall document PQC migration plan | Doc review | Doc |

Add a New Category

## 14. Physical Security

> **Legal Basis**: CRA Annex I requires...

### 14.1 Feature Name
...

Evidence Types

Type	Meaning	How Assessed
Auto	Fully automated — scanner can determine pass/fail	Pattern matching, config parsing
Semi	Automated detection + manual or LLM review needed	Scanner finds pattern, LLM/human judges compliance
Doc	Documentation submission required	Questionnaire, manual upload
Test	Active testing required	Penetration test, fuzz test results

Compiling the Catalog

cd catalog/compiler
pnpm install    # First time only
pnpm run compile

Output:

Compiling: /path/to/fleet/resources/structure.md
Output: /path/to/fleet/catalog/compiled/catalog.json
Stats:
  Categories:   13
  Features:     54
  Risks:        163
  Requirements: 401
    Auto: 56
    Semi: 150
    Doc:  187
    Test: 8

The compiled catalog.json is embedded in the Rust binary at compile time. After editing the catalog, rebuild Fleet:

pnpm run compile && cargo build

Custom Rulesets

While structure.md defines the built-in default catalog, organizations can create custom rulesets via the API:

curl -X POST /api/v1/assessment/rulesets \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "name": "my-org-ruleset",
    "version": "1.0.0",
    "description": "Custom requirements for our product",
    "catalog_json": <contents of catalog.json>
  }'

Custom rulesets can then be edited via the API or dashboard. Products pin to a specific ruleset version.

JSON Schema

The compiled catalog conforms to catalog/schema.json. Validate with any JSON Schema validator:

npx ajv validate -s catalog/schema.json -d catalog/compiled/catalog.json