Metadata-Version: 2.4
Name: prototyyppi
Version: 2026.8.10
Summary: Candidate for the next CSAF Python Reference Implementation.
Author-email: Stefan Hagen <stefan@hagen.link>
Maintainer-email: Stefan Hagen <stefan@hagen.link>
License-Expression: MIT
Project-URL: Documentation, https://codes.dilettant.life/docs/prototyyppi
Keywords: developer-tools,security-advisory,vex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: kaava>=2026.6.20
Requires-Dist: msgspec>=0.21.1
Requires-Dist: python-jsonpath>=2.2.1
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Provides-Extra: fast-schema
Requires-Dist: jsonschema-rs>=0.49.2; extra == "fast-schema"
Provides-Extra: manifest
Provides-Extra: render
Requires-Dist: jinja2>=3.1; extra == "render"
Provides-Extra: tui
Requires-Dist: textual>=8.2.8; extra == "tui"
Provides-Extra: yaml
Requires-Dist: ruamel.yaml>=0.19.1; extra == "yaml"

# prototyyppi

Candidate for the next Python reference implementation of [CSAF 2.1](https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html).
Validates CSAF advisory documents against the full three-tier test suite
(mandatory, recommended, informative) specified in the CSAF 2.1 standard.

Requires Python 3.11 or later.

## Install

```sh
pip install prototyyppi
```

The package name on PyPI is `prototyyppi` (Finnish: "prototype").
The final stable release will be published as `csaf`.

Optional extras activate additional subcommands or a faster schema backend:

| Extra         | Installs        | Enables                                                                               |
|:--------------|:----------------|:--------------------------------------------------------------------------------------|
| `tui`         | `textual`       | `view`, `edit`, and `render markdown --interactive` - advisory browser, JSON editor, markdown renderer |
| `fast-schema` | `jsonschema-rs` | Compiled JSON Schema backend - typically 10–15× faster schema validation              |
| `yaml`        | `ruamel.yaml`   | `--format yaml` output and `edit --yaml` YAML view mode                               |

```sh
pip install 'prototyyppi[tui]'                       # view + edit + render --interactive (TUI subcommands)
pip install 'prototyyppi[fast-schema]'                # fast schema backend
pip install 'prototyyppi[yaml]'                       # YAML output and edit --yaml view mode
pip install 'prototyyppi[fast-schema,tui,yaml]'       # all extras
```

## Manual

The [man page](docs/man/prototyyppi.1) provides the full CLI reference.
After installation, place it on your `MANPATH`:

```sh
mkdir -p ~/.local/share/man/man1
cp docs/man/prototyyppi.1 ~/.local/share/man/man1/
man prototyyppi
```

## Quickstart

### CLI

Validate a CSAF 2.1 advisory and get a human-readable report:

```sh
prototyyppi validate advisory.json
```

```
File: advisory.json
Overall: FAIL

  [PASS] schema - JSON Schema (CSAF 2.1)
  [FAIL] 6.1.1 - Missing Definition of Product ID
          /product_tree/product_groups/0/product_ids/0: product id `CSAFPID-9080700` is not defined in product_tree
  [PASS] 6.1.2 - Multiple Definition of Product ID
  …
```

Exit code is `0` for a valid document, `1` for invalid, `2` for usage errors.

**Validation levels** - run additional test tiers:

```sh
# Basic: schema + mandatory (6.1.x) - default
prototyyppi validate advisory.json

# Extended: + recommended (6.2.x)
prototyyppi validate --level extended advisory.json

# Full: + informative (6.3.x)
prototyyppi validate --level full advisory.json
```

**Output formats:**

```sh
# TC-compatible JSON (matches the OASIS test-result schema)
prototyyppi validate --format json advisory.json

# SARIF 2.2 (GitHub code scanning, VS Code SARIF viewer)
prototyyppi validate --format sarif advisory.json > results.sarif

# GitHub-flavored markdown - paste directly into a GitHub issue or PR comment
prototyyppi validate --format markdown advisory.json
```

**Batch validation:**

```sh
# All files in a directory
prototyyppi validate advisories/*.json

# Recursive glob (quote to let Python expand it - avoids shell ARG_MAX limits)
prototyyppi validate 'advisories/**/*.json'

# Batch markdown for a GitHub issue
prototyyppi validate --format markdown 'advisories/*.json'
```

**Rule filtering** - suppress or allow-list specific rules:

```sh
# Skip by ID or from a YAML file (shown as [SKIP])
prototyyppi validate --skip-rules 6.1.9 advisory.json
prototyyppi validate --skip-rules skip.yaml advisory.json

# Run only specific rules (allowlist; composes with --skip-rules)
prototyyppi validate --only-rules 6.1.1,6.1.2 advisory.json
prototyyppi validate --only-rules rules.yaml advisory.json
```

**Suppress output:**

```sh
prototyyppi validate --quiet advisory.json    # hide passing rules
prototyyppi validate --silent advisory.json   # exit code only
```

**Performance instrumentation:**

```sh
# Per-rule timing and peak RSS delta - report to stderr
prototyyppi validate --perf advisory.json

# Save a JSON baseline for later comparison
prototyyppi validate --level full --perf --perf-format json \
    --perf-output baseline.json advisory.json
```

Exit code is unchanged by `--perf`.
On Windows the RSS delta column shows `n/a` (the `resource` module is POSIX-only);
wall-clock timing works on all platforms.

**Advisory browser (TUI):**

```sh
# Open an advisory in the interactive terminal browser
prototyyppi view advisory.json

# Multiple files - navigate with arrow keys in the sidebar
prototyyppi view advisories/*.json

# Pipe from the producer API
python build_advisory.py | prototyyppi view
```

Requires `pip install 'prototyyppi[tui]'`.
Five tabs: **Summary** (metadata and conformance status), **Validation** (rule-by-rule table),
**Dimensions** (Appendix C soft-limit report, computed lazily in the background),
**Document** (full structured rendering of the CSAF document), and **Log** (append-only
per-file validation record that persists across rule re-runs).
The loading screen streams rule results in real time as validation runs in the background;
the advisory view is available immediately once all files finish loading.
The theme indicator in the header subtitle (e.g. `advisory.json  [textual-dark]`)
updates automatically when the theme is changed via the command palette (`Ctrl+P`).

**JSON editor (TUI):**

```sh
# Edit a CSAF advisory file
prototyyppi edit advisory.json

# Choose a file from an in-app directory browser
prototyyppi edit

# Pipe from a script (stdin is re-routed so Ctrl+S works)
python draft_advisory.py | prototyyppi edit
```

Requires `pip install 'prototyyppi[tui]'`.
The editor formats the JSON canonically (2-space indent, POSIX newline) on load.
A **Fields** pane on the right tracks the cursor and shows the CSAF schema field's
title, description, type, and all active constraints (enum values, `format`, `pattern`,
`minLength`/`maxLength`, numeric ranges).
Key bindings: `Ctrl+S` save, `Ctrl+Q` quit (unsaved-changes guard),
`Ctrl+F` toggle / `F7` narrow / `F8` widen the fields pane,
`Ctrl+Z` undo, `Ctrl+R` redo, `Ctrl+Y` copy current field constraints to clipboard,
`Ctrl+P` command palette.

**Form editor (TUI):**

```sh
# Open the schema-driven full document editor
prototyyppi edit --form advisory.json

# Pipe from a script
python draft_advisory.py | prototyyppi edit --form
```

Requires `pip install 'prototyyppi[tui]'`.
The form editor renders every field in the advisory as a purpose-built widget:
enum-constrained fields become `Select` drop-downs (including all CVSS metric fields),
and free-text fields become `Input` boxes.
Nested objects and arrays of objects are shown as indented section groups driven by
the CSAF 2.1 JSON schema, with **Add** and **Delete** controls on each array section.
CVSS v2, v3, and v4 objects are rendered from their referenced external schemas;
`cvss_v3` resolves the correct sub-schema (v3.0 or v3.1) by matching the document's
`version` field.
A **Hints** pane on the right shows the JSON path, schema title, description, allowed
values, type, and constraints for the focused field, plus the external schema URL for
CVSS and other referenced-schema fields.
Below the schema metadata the pane shows editorial guidance from the built-in hints
catalog (14 entries covering key CSAF 2.1 fields); organisations can extend the catalog
via `prototyyppi eject hints`, the `[hints]` config section, or the `--hints-dir PATH` flag.
Key bindings: `Ctrl+S` save · `Ctrl+Q` quit · `Ctrl+F` toggle hints pane ·
`F5`/`F6` narrow/widen label column · `F7`/`F8` narrow/widen hints pane ·
`Ctrl+Y` copy hints pane to clipboard.

**Advisory markdown renderer (TUI):**

```sh
# Render a CSAF advisory as markdown - print to stdout
prototyyppi render markdown advisory.json

# Interactive TUI browser with gruvbox theme and TOC pane
prototyyppi render markdown --interactive advisory.json
```

Requires `pip install 'prototyyppi[tui]'` for the interactive mode.
The product tree is rendered as a table; each vulnerability opens with a description paragraph,
an identity table (CVE, CWE, external IDs), and CVSS metrics.
Key bindings: `q` quit · `F7`/`F8` narrow/widen TOC · `Ctrl+Y` copy full markdown to clipboard · `Ctrl+P` palette.

**Shell completion:**

```sh
prototyyppi completion bash >> ~/.bash_completion    # bash
prototyyppi completion zsh  >> ~/.zshrc              # zsh
prototyyppi completion fish > ~/.config/fish/completions/prototyyppi.fish
```

**Version and info -- machine-readable output:**

```sh
prototyyppi version                      # plain-text version string
prototyyppi version --format json        # {"version": "2026.8.10", "package": "prototyyppi"}
prototyyppi version --format yaml        # same fields in YAML
prototyyppi info version --format json   # same content via info subcommand group
prototyyppi info config --format json    # effective config as a JSON dict (dataclasses.asdict)
prototyyppi info config --format yaml    # same as YAML
```

**Configuration:**

```sh
prototyyppi config eject --format toml              # generate a ready-to-edit config template
prototyyppi config explain                          # show effective values with source provenance
prototyyppi config explain --format json            # machine-readable config dict
prototyyppi config doctor                           # validate all discovered config files
```

User config lives in `~/.config/prototyyppi/config.toml`;
project config in `.prototyyppi.toml` (or `.yaml`/`.json`) in the project root.
CLI flags override both.
Multi-word keys are written in `kebab-case` in the template (`skip-rules`, `url-cache`, etc.);
both `kebab-case` and `snake_case` are accepted when reading.

The `[ui]` section controls TUI appearance across all interactive screens:

```toml
[ui]
theme = "gruvbox"     # Textual theme name; try also: nord, dracula, catppuccin-mocha
dialog-style = "text" # "text" for ASCII [ Label ] buttons, "native" for Textual Button
```

Set `PROTOTYYPPI_UI_THEME` and `PROTOTYYPPI_UI_DIALOG_STYLE` to override per-invocation.

The `[log]` section enables audit logging of CLI and TUI operations (off by default):

```toml
[log]
level = "info"   # debug, info, warning, error, critical, or off
sink  = "stderr" # stderr (default), stdout, or a file path
```

Set `PROTOTYYPPI_LOG_LEVEL` and `PROTOTYYPPI_LOG_SINK` to override per-invocation.
See the [Configuration tutorial](docs/tutorial/configuration/README.md) for all supported keys.

**Rule catalog:**

```sh
prototyyppi info rules                         # full list
prototyyppi info rules --only-groups mandatory # filter by tier
prototyyppi info rules --format json           # machine-readable
```

```
Spec   ID         Group           Status           Title
--------------------------------------------------------------------------------
2.1    6.1.1      mandatory       implemented      Missing Definition of Product ID
2.1    6.1.2      mandatory       implemented      Multiple Definition of Product ID
…
61 rule(s) in catalog (CSAF 2.1).
```

**Environment info:**

```sh
prototyyppi info env                    # CSAF support, catalogs, interpreter, platform
prototyyppi info env --level extended   # + runtime config, paths, host OS identity
prototyyppi info env --level full       # + interpreter detail, flags, CPU, resource usage
prototyyppi info env --format json      # machine-readable
```

For a condensed single-page reference see the [Quickstart guide](docs/quickstart/README.md).
For tutorials covering validation and document production see the [Tutorial index](docs/tutorial/README.md).

### Python API - consumer (validate)

```python
from prototyyppi import validate, validate_file

# From a file path
report = validate_file("advisory.json")

# From an already-parsed dict
import msgspec
doc = msgspec.json.decode(open("advisory.json", "rb").read())
report = validate(doc, path="advisory.json")

print("valid:", report.overall_valid)
for result in report.results:
    if not result.passed:
        print(f"[FAIL] {result.id} - {result.title}")
        for err in result.errors:
            print(f"       {err.instance_path}: {err.message}")
```

The `ValidationReport` is a frozen `msgspec.Struct`.
Pass it to the formatters to render as text, JSON, SARIF, or markdown:

```python
from prototyyppi import to_text, to_tc_json, to_sarif, to_markdown

print(to_text(report))
print(to_tc_json(report))
print(to_sarif(report, version='0.0.0'))
print(to_markdown(report))
```

### Python API - producer (build)

Construct a typed document and call `build()` to get validated JSON:

```python
from prototyyppi import (
    Document, Distribution, FullProductName, Note, Publisher, ProductStatus,
    ProductTree, Revision, Tlp, Tracking, Vulnerability,
    Metric, MetricContent, cvss31_from_vector, cwe_entry,
)

doc = Document(
    category='csaf_security_advisory',
    title='Acme Corp - Advisory 2026-001',
    publisher=Publisher(category='vendor', name='Acme Corp',
                        namespace='https://acme.example.com'),
    tracking=Tracking(
        id='ACME-2026-SA-001', status='final', version='1',
        initial_release_date='2026-01-15T10:00:00Z',
        current_release_date='2026-01-15T10:00:00Z',
        revision_history=[Revision(date='2026-01-15T10:00:00Z', number='1',
                                   summary='Initial release.')],
    ),
    distribution=Distribution(tlp=Tlp(label='CLEAR')),
    product_tree=ProductTree(full_product_names=[
        FullProductName(name='Widget 1.0', product_id='CSAFPID-W100'),
    ]),
    vulnerabilities=[
        Vulnerability(
            cve='CVE-2026-10001',
            cwes=[cwe_entry('CWE-122')],
            notes=[Note(category='description', text='Heap overflow in widget parser.')],
            product_status=ProductStatus(known_affected=['CSAFPID-W100']),
            metrics=[Metric(
                content=MetricContent(
                    cvss_v3=cvss31_from_vector(
                        'CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H'
                    ),
                ),
                products=['CSAFPID-W100'],
            )],
        ),
    ],
)

json_str, report = doc.build()   # raises BuildError on structural violations
assert report.overall_valid
import pathlib
pathlib.Path('advisory.json').write_text(json_str, encoding='utf-8')
```

`build()` validates the document and returns `(json_str, ValidationReport)`.
The JSON output has sorted keys, two-space indentation, and an auto-injected generator block.
See the [producer tutorial](docs/tutorial/producer/README.md) for step-by-step coverage of all five profiles, CVSS helpers, and build modes.

## URL reachability cache

Rules 6.3.06 and 6.3.07 check that URLs in advisory documents resolve to live endpoints.
Because HTTP requests are slow and advisory corpora can be large,
the validator provides a four-mode URL cache:

| Mode      | Behaviour                                        | When to use                  |
|:----------|:-------------------------------------------------|:-----------------------------|
| `run`     | In-memory dedup within the current invocation    | Default; interactive use     |
| `disk`    | Persist results to disk with a configurable TTL  | CI pipelines                 |
| `disk-ro` | Read disk cache; skip on cache miss (no network) | Air-gapped or offline builds |
| `none`    | No caching; each URL is checked fresh every run  | Debugging                    |

```sh
# Default: in-memory dedup (no flags needed)
prototyyppi validate --level full advisory.json

# Disk cache with default TTL (24h) and default directory (~/.cache/prototyyppi)
prototyyppi validate --level full --url-cache disk advisory.json

# Custom TTL and cache directory
prototyyppi validate --level full \
    --url-cache disk \
    --url-cache-ttl 7d \
    --url-cache-dir /var/cache/prototyyppi \
    advisory.json

# Read-only: use cache, skip URL rules on miss (no network calls)
prototyyppi validate --level full --url-cache disk-ro advisory.json

# Disable URL rules entirely (shown as [SKIP]; implies --skip-rules 6.3.06,6.3.07)
prototyyppi validate --level full --no-network advisory.json
```

TTL accepts: `30m`, `6h`, `7d` (minutes, hours, days).
The disk cache is stored as a JSON file; entries expire individually based on their write time.

**Recommended CI pattern:**

```sh
prototyyppi validate \
    --level full \
    --url-cache disk \
    --url-cache-dir .cache/prototyyppi \
    --url-cache-ttl 24h \
    'advisories/**/*.json'
```

## Document dimension report (`doc-stats`)

The `doc-stats` subcommand measures advisory documents against the informative soft limits
defined in Appendix C of the CSAF 2.1 specification -
file size (§C.1), array lengths (§C.2), and string lengths (§C.3).
It does not perform conformance validation.

Each dimension is rated `ok` (at or below the caution threshold),
`caution` (above threshold but within the limit), or `exceeds` (above the limit).
The overall posture is the worst-case rating across all dimensions.

```sh
# Single file - human-readable text
prototyyppi doc-stats advisory.json

# Structured output
prototyyppi doc-stats --format json advisory.json
prototyyppi doc-stats --format yaml advisory.json

# SARIF 2.2 - for GitHub code scanning or VS Code SARIF viewer
prototyyppi doc-stats --format sarif 'advisories/**/*.json' > doc-stats.sarif

# Batch - text report with grand total footer
prototyyppi doc-stats 'advisories/**/*.json'
```

**Adjusting the caution threshold:**

```sh
# Rate a dimension caution when it exceeds 75% of the limit (default: 50%)
prototyyppi doc-stats --caution-fraction 0.75 advisory.json
```

**Selecting the taxonomy version:**

```sh
# v21 (default) or its alias v21csd02
prototyyppi doc-stats --spec-version v21csd02 advisory.json
```

**Exit codes:** `0` (all ok or caution), `1` (any exceeds, or a file could not be read), `2` (usage error).

The four official OASIS Appendix examples (`example/appendix/`) all pass at `ok` posture.
See [`example/README.md`](example/README.md) for the full per-file dimension reports.

**Single-pass combined conformance + dimension report:**

`--with-doc-stats` on `validate` runs both pipelines on the same decoded document -
no second parse.
The dimension block is appended to each file's conformance output.

```sh
# Single file: conformance + dimensions in one invocation
prototyyppi validate --with-doc-stats advisory.json

# Also fail on any exceeds posture (default: dimension posture does not affect exit code)
prototyyppi validate --with-doc-stats --doc-stats-exit advisory.json

# Machine-readable output with embedded doc_stats key
prototyyppi validate --format json --with-doc-stats advisory.json

# SARIF with two runs per file (validation run + doc-stats run)
prototyyppi validate --format sarif --with-doc-stats advisory.json
```

## Skip rules

Rules can be suppressed individually or via a YAML skip file.
Suppressed rules appear as `[SKIP]` in the output and do not affect the exit code.

**CSV on the command line:**

```sh
prototyyppi validate --skip-rules 6.1.9,6.2.39.02 advisory.json

# May be specified multiple times (processed left to right)
prototyyppi validate --skip-rules 6.1.9 --skip-rules 6.2.39.02 advisory.json
```

**Re-enable a rule** skipped by a previous argument or file (prefix with `+`):

```sh
prototyyppi validate --skip-rules base.yaml --skip-rules +6.1.9 advisory.json
```

**YAML skip file** - supports structured entries with reason and expiry:

```yaml
# skip.yaml
- "schema"
- id: "6.1.9"
  reason: "CVSS v3 scorer deviation - under review"
  expires: "2026-12-31"
```

```sh
prototyyppi validate --skip-rules skip.yaml advisory.json
```

Expired entries still take effect; the validator prints a warning to stderr.

## Official examples

The `example/` directory contains official OASIS CSAF 2.1 advisory examples
from the [CSAF TC repository](https://github.com/oasis-tcs/csaf/tree/master/csaf_2.1/examples/csaf):
six general advisories, four Appendix normative examples (Collapsing Product Paths, examples 11–14),
and thirteen VEX use-case documents.

See [example/README.md](example/README.md) for per-example validation reports and notes on findings.

To refresh the examples from upstream:

```sh
python bin/sync_examples.py           # download/update all files
python bin/sync_examples.py --show    # list bundled files and sizes
python bin/sync_examples.py --dry-run # compare with upstream without writing
```

## Bundled catalogs

All external reference data is bundled and kept up to date within the package.
No network access is required for validation.

| Catalog           | Bundled version             | Sync script                       |
|:------------------|:----------------------------|:----------------------------------|
| CWE               | v4.9–v4.13 (969 weaknesses) | `python bin/sync_cwe.py`          |
| SPDX              | 3.28.0 + ScanCode licensedb | `python bin/sync_spdx.py`         |
| SSVC              | format_version 3            | `python bin/sync_ssvc.py`         |
| CSAF translations | v2.1 (de)                   | `python bin/sync_translations.py` |

## Life Cycle Management

Four categories of data bundled in the package require periodic maintenance.

| Category           | Location                                 | Update trigger                               |
|:-------------------|:-----------------------------------------|:---------------------------------------------|
| TC fixture data    | `csaf/v21/data/`                         | New TC test suite release                    |
| Spec schema files  | `csaf/v21/schema/`                       | Schema normative change                      |
| Reference catalogs | `csaf/v21/{cwe,spdx,ssvc,translations}/` | Upstream version release                     |
| Official examples  | `example/`                               | New CSAF TC release (main, appendix, or VEX) |

### TC fixture data

The test suite reads fixture files from
`prototyyppi/csaf/v21/data/{mandatory,recommended,informative}/`.
These are a snapshot of the OASIS CSAF TC test suite
and require a sibling checkout of the TC repository to refresh.

```sh
make sync-fixtures csaf_tc_root=../csaf-2.1   # default: csaf_tc_root=../csaf-2.1
```

After syncing, run the test suite to confirm all fixture-driven tests still pass:

```sh
python -m pytest test/ -q
```

New fixtures for rules that were previously `not_implemented` will cause new tests
to be collected; updated fixtures may change pass/fail counts.
Investigate any unexpected failures before committing.

Once the test suite is green, stage and commit the changed files:

```sh
fossil add prototyyppi/csaf/v21/data/
fossil commit -m "sync: TC fixture data YYYY-MM-DD"
```

### CWE catalog

The CWE catalog at `prototyyppi/csaf/v21/cwe/catalog.json` is built
from MITRE's XML distribution.
Download the desired CWE versions and run:

```sh
python bin/sync_cwe.py --latest-version 4.13 \
    cwec_v4.9.xml cwec_v4.10.xml cwec_v4.13.xml cwec_v4.14.xml cwec_v4.20.xml
```

The script reads only local XML files; no network access is required.
`--latest-version` sets the version marker used by rule 6.2.24
(defaults to the highest version found in the supplied files when omitted).

### SPDX license catalog

The SPDX catalog at `prototyyppi/csaf/v21/spdx/catalog.json` combines
the SPDX license list with the ScanCode license database.

**Network (default):**

```sh
python bin/sync_spdx.py
```

**Air-gapped** - supply locally downloaded source files:

```sh
python bin/sync_spdx.py \
    --spdx-licenses licenses.json \
    --spdx-exceptions exceptions.json \
    --scancode scancode-index.json
```

Download sources from the SPDX license list JSON API and the ScanCode licensedb index.

### SSVC decision point catalog

The SSVC catalog at `prototyyppi/csaf/v21/ssvc/catalog.json` is built
from the CERTCC/SSVC repository.

```sh
python bin/sync_ssvc.py --sync ssvc --sync cvss   # sync both namespaces
python bin/sync_ssvc.py --show                    # print current catalog
python bin/sync_ssvc.py --namespace ssvc --key A --latest-version 3.0.0  # manual override
```

Syncing requires network access to the GitHub Contents API.
For air-gapped environments, review the upstream repository offline
and apply changes with `--namespace` / `--key` / `--latest-version`.

### CSAF translations catalog

The translations catalog at `prototyyppi/csaf/v21/translations/translations.json`
is maintained by the OASIS CSAF TC.

```sh
python bin/sync_translations.py             # fetch and write
python bin/sync_translations.py --show      # print current catalog
python bin/sync_translations.py --dry-run   # compare with upstream without writing
```

### OASIS examples

The official OASIS CSAF 2.1 examples are bundled in `example/` (main advisories),
`example/appendix/` (Appendix normative examples), and `example/csaf_vex/` (VEX use cases).
All three groups are refreshed via `bin/sync_examples.py`.

```sh
python bin/sync_examples.py             # download/refresh all groups
python bin/sync_examples.py --show      # print bundled filenames and sizes
python bin/sync_examples.py --dry-run   # compare with upstream without writing
python bin/sync_examples.py --no-appendix  # skip appendix/ group
python bin/sync_examples.py --no-vex       # skip csaf_vex/ group
```

After syncing, stage and commit the changed files:

```sh
fossil add example/
fossil commit -m "sync: OASIS CSAF examples YYYY-MM-DD"
```

### Adding a new bundled catalog

To add a new reference catalog following the established pattern:

1. Create `bin/sync_<name>.py` with network and (where possible) air-gap modes.
2. Create `prototyyppi/csaf/v21/<name>/` and add the generated JSON file.
3. Add `package-data` globs to `pyproject.toml`.
4. Add an `lru_cache` loader in `prototyyppi/csaf/v21/rules/_shared.py`.
5. Add a section provider in `prototyyppi/_env.py` for `info env` output.
6. Add the catalog to the "Bundled catalogs" table in this README.

---

## Fuzzing

Coverage-guided fuzz testing uses [AFL](https://github.com/google/AFL) via
[python-afl](https://github.com/jwilk/python-afl).
Seven harnesses cover the parser and filter functions with the highest attack surface.

| Target        | Harness                    | Functions covered                               |
|:--------------|:---------------------------|:------------------------------------------------|
| `cvss-vector` | `fuzz/fuzz_cvss_vector.py` | `_parse_cvss_vector`, `_cvss2/3/4_base_score`   |
| `vers`        | `fuzz/fuzz_vers.py`        | `_parse_vls`, `_get_vers_pairs`                 |
| `purl`        | `fuzz/fuzz_purl.py`        | `_validate_purl`, `_purl_base`, `_purl_version` |
| `spdx-expr`   | `fuzz/fuzz_spdx_expr.py`   | `_parse_spdx_expression`                        |
| `only-groups` | `fuzz/fuzz_only_groups.py` | `_filter_by_groups`                             |
| `skip-rules`  | `fuzz/fuzz_skip_rules.py`  | `_build_skip_rules` (CSV branch)                |
| `ttl`         | `fuzz/fuzz_ttl.py`         | `_parse_ttl`                                    |
| `prefix`      | `fuzz/fuzz_prefix.py`      | `_disambiguate`, `_expand_option_values`         |

Prerequisites: `afl-fuzz` and `python-afl` must be installed and on `PATH`.
On macOS with pyenv, ensure the virtualenv is active so `PYTHON_BIN` resolves to
the real interpreter (not the pyenv shim).

```sh
# Run all targets sequentially (default: 60 s each)
make fuzz

# Run a single target
make fuzz-ttl

# Adjust the time budget
make fuzz-cvss-vector fuzz_time=300

# After a run, promote AFL-discovered queue entries into the seed corpus
make fuzz-update-seeds
# Review fuzz/seeds/ and commit any valuable new seeds
```

Crash and hang findings land in `fuzz/findings/<target>/`.
The seed corpus lives in `fuzz/seeds/<target>/`.
Each target's seed directory contains at least one valid, non-crashing input
so AFL can establish a baseline before mutation begins.

## Design and requirements

| Document                            | Identifier  | File                                                      |
|:------------------------------------|:------------|:----------------------------------------------------------|
| Software Requirements Specification | PRO-SRS-001 | [docs/requirements/srs/](docs/requirements/srs/README.md) |
| Software Design Description         | PRO-SDD-001 | [docs/design/sdd/](docs/design/sdd/README.md)             |

Both documents follow the MIL-STD-498 DID structure
and are rendered into the documentation site alongside the
[quickstart](docs/quickstart/README.md), [tutorial](docs/tutorial/README.md),
and [example gallery](example/README.md).

## Bug Tracker

Feature requests and bug reports go to the [todos of prototyyppi](https://todo.sr.ht/~sthagen/prototyyppi).

## Primary Source repository

The main source of `prototyyppi` is on a mountain in Central Switzerland under
configuration control ([fossil](https://fossil-scm.org/)).

## Contributions

To share small changes under the repository's license,
kindly send a patchset per email using [git send-email](https://git-send-email.io).

## Support

Submit issues at https://todo.sr.ht/~sthagen/prototyyppi
or write plain text email to ~sthagen/prototyyppi@lists.sr.ht.

## Security Policy

See `SECURITY.md` for the security policy.

## Changes

See [docs/releases/](docs/releases/README.md) for release summaries
and [docs/releases/changes/](docs/releases/changes/README.md) for the detailed change log.

## Coverage

The test suite maintains high branch coverage (≥99%).
The HTML report (if generated) is in `site/coverage/`.

## SBOM

Runtime dependency information is published in `docs/sbom/` in SPDX 3.0 (JSON-LD)
and CycloneDX 1.6 (JSON) formats.
See `docs/sbom/README.md` for the component inventory and validation guide.
