Your browser sucks, JavaScript disabled! Gunnar's console needs JavaScript and WebAssembly. Git over SSH on port 2222 does not.

mikronova/modgunn

.nornir/guide.md

Móðguðr — guide (f0, the whole)

Class: guide · audience: a techie driving modgunn end to end. The what is in design.md; the why in reasoning.md. This file is the workflow that spans functions; per-function how-tos are each {fn}-guide.md.

f0 — a full session

modgunn ships as a library (both engines) plus one binary (modgunn, the secure-side warehouse driver, required-features = ["warehouse", "scan"]). A whole session is three moves:

# 1 · build the plane you need
#    The BINARY has exactly ONE build door — the declaration in
#    `.nornir/build-variants.toml`, resolved by the one build verb. Do NOT hand-write a
#    `cargo build --features …` for it: a second recipe is a second declaration, and the
#    two drift.
cargo xtask build --suite ORIGINAL          # the `modgunn` binary (client · fat), as declared
dwarves buildthing modgunn --suite ORIGINAL # the same resolver, from outside the repo

#    The raw feature axis below is for CONSUMERS LINKING THE LIBRARY (holger's gate,
#    static-holger, nornir) — it names no binary.
cargo build                    # Engine A — the lean artifact verdict (default = scan)
cargo build --features scip    # + Engine B — the heavy world-delta

# 2 · import an offline advisory generation (secure side)
modgunn warehouse import --warehouse <root> --rev 2026-07-04-a \
        --osv <dir> [--nvd <dir>] [--malicious <dir>] [--epss epss.csv] [--kev kev.json]

# 3 · scan the whole fleet against it
modgunn warehouse scan  --warehouse <root> [--since <snapshot_id>] [--vex <dir>] [--sql]
modgunn warehouse stats --warehouse <root> [--ecosystem cargo]

import reads every *.json under each --<feed> dir, merges + dedups by alias, enriches with EPSS/KEV, and appends the corpus as a new db_rev generation (main.rs:cmd_import). scan joins the whole sbom_components table × the latest advisories and prints every vulnerable dependency; --since <snapshot_id> does the incremental CDC delta — only the components added since that snapshot, printing the next watermark to poll (main.rs:cmd_scan).

To embed the gate in another Rust app, depend on modgunn with no extra features and call Engine A directly — see verdict-guide.md. To run the world-delta, see worlddelta-guide.md.

Per-function how-tos

function do this guide
verdict build a Policy + AdvisoryDb, call OsvScanner::scan(&artifact) verdict-guide.md
feeds parse a feed dir → merge_by_alias → enrich → Advisorys feeds-guide.md
warehouse Warehouse::open → append_advisories / scan_fleet / table_delta warehouse-guide.md
worlddelta build two WorldSnapshots → scip::diff → read BehaviorDelta worlddelta-guide.md
provenance ProvenanceRequirement::evaluate(att) → findings provenance-guide.md
sbom build a SbomInput → to_cyclonedx → serialize sbom-guide.md
rollup rollup_fleet_findings(&findings) → FleetRollup rollup-guide.md

Which feature do I need?