Schemas
Fifteen JSON Schema Draft 2020-12 contracts covering scope, attack surface, applicability, evidence, findings, reports, catalog, extensions, knowledge, research, and Gold Check Packs.
Why contracts
Fifteen JSON Schema Draft 2020-12 contracts define the shapes the workflow produces. They exist so a report can be checked mechanically rather than read for plausibility, and so a different agent, a different model, or a later reviewer can consume the same output.
The skill is explicit about this: when the repository runtime is available, use its versioned contracts rather than inventing parallel report shapes.
The fifteen contracts
| Schema | Title | Notable fields |
|---|---|---|
scope-v1 | Authorized scope record | schema_version · scope_id · project · authorization · mode · in_scope · out_of_scope · allowed_tools · stop_conditions |
attack-surface-v1 | Attack-surface graph | graph_id · scope_id · nodes · edges · boundaries · role_object_actions · unknowns |
applicability-input-v1 | Applicability engine input | scope · architecture · blocked_hypotheses |
applicability-output-v1 | Applicability engine output | catalog_version · scope_id · engine · authorized · summary · decisions |
catalog-v2 | Explicit hypothesis catalog | families · lenses · hypotheses · hypothesis_count · selection_rule · claim_policy |
evidence-v1 | Evidence record | evidence_id · kind · status · source · summary · environment · artifacts · redactions |
finding-v1 | Candidate or verified finding | finding_id · status · severity · confidence · catalog_hypothesis_ids · affected_surface · evidence_chain |
report-v1 | Canonical report | report_id · scope_id · mode · coverage · tools · evidence · findings · rejected_false_positives · blocked_checks · release_recommendation |
gold-check-pack-v1 | Gold Check Pack | threat_model · applicability · framework_fingerprints · sources · boundary · sinks · detection_layers · validation |
extension-manifest-v1 | Community extension manifest | extension_type · lifecycle · compatibility · entrypoints · capabilities · permissions · safety |
extension-registry-v1 | Curated extension registry | project · policy · extensions |
source-registry-v1 | Source trust registry | checked_at · policy · sources |
knowledge-graph-v1 | Security knowledge graph | graph_id · updated_at · nodes · edges |
lesson-card-v1 | Lesson card | domains · summary · detection_signals · safe_local_tests · false_positive_traps · remediation_patterns |
research-packet-v1 | Live research packet | trigger · question · checked_at · subject · claim · sources · code_evidence · safe_reproduction · confidence |
Required fields worth knowing
scope-v1makesauthorization,mode,allowed_tools, andstop_conditionsrequired. A run without them is not a scoped run.attack-surface-v1requiresunknowns. The map has to state what it could not resolve.evidence-v1requiresredactions. Redaction is part of the record rather than a later cleanup.finding-v1requiresevidence_chainandcatalog_hypothesis_ids, so every finding points at both its proof and the hypothesis it answers.report-v1requiresrejected_false_positivesandblocked_checks. A report that only lists findings does not validate.
Validating
The repository validates catalog identity, source rights, knowledge provenance, research confidence, the standalone install bundle, schemas, adapters, reporting, policy gates, secrets, and public-release invariants in CI. The same scripts run locally.
python scripts/validate_catalog.py— catalog identity and the 21 by 26 model.python scripts/validate_knowledge.py— sources, graph, cards, and research packets.python scripts/validate_gold_packs.py— pack provenance, safety, and calibration.python scripts/validate_extensions.py— manifests and registry identity.python scripts/validate_skill.py— the standalone install bundle.