fix(onboarding): separate observation vs requirement signals — a demanded SBOM is not a present SBOM

Semantic correction of the knowledge base BEFORE the empirical loop (#59) is built — otherwise the
Observation Store would learn from already-misclassified signals. The Silent Pass conflated two kinds of
signal into one: an OBSERVATION ("I saw an SBOM in the repo") and a REQUIREMENT ("a tender DEMANDS an
SBOM"). They were aliased to the same canonical id, so a tender clause read as "SBOM already present" and
suppressed the very question that should have been asked.

Fix — make the kind explicit and authoritative (no new architecture, data + thin wiring):
  - `kind` ∈ {observation, requirement} on ProducedSignal (producer may declare) and on the canonical
    SignalVocabularyEntry (AUTHORITATIVE — a mislabelled producer cannot collapse the two).
  - Vocabulary split: sbom_file_found → sbom_present (obs) + sbom_required (req);
    security_txt_or_cvd_policy → cvd_policy_present (obs) + psirt_required (req); add signed_updates_required.
    requirement signals are intentionally UNMAPPED in intake_signal_map (they describe a target, not state).
  - silent_intake() consumes ONLY kind==observation; requirement signals are preserved in
    `requirements_seen` (visible/auditable) but NEVER become a detected capability.
  - normalize_signals() stamps the vocabulary's kind onto every IntakeSignal; unknown ids still pass through.

This is the same Observation-vs-Requirement split the Requirements Verification Platform rests on:
observations are reality, requirements are targets, and their comparison is the delta. A tender / OEM spec /
law now produces requirement signals; scanners / repos / documents produce observation signals.

Tests: rewrote the two test_signal_producer cases that previously ASSERTED the bug (tender == repo) to pin
the correct split; regression — `requires_sbom` yields no capability + stays in requirements_seen while
`cyclonedx_found` still detects sbom_creation; endpoint-level regression that a tender requirement does not
auto-detect and the gap stays asked; vocabulary-kind-overrides-mislabelled-producer. 25 onboarding tests
pass, mypy --strict clean, demo runs, check-loc 0. Runtime effect → deploy + smoke. (Fix A; partial-vs-
detected decoupling follows as Fix B before #59.)
This commit is contained in:
Benjamin Admin
2026-06-28 15:52:50 +02:00
parent b5b6cdddb3
commit c39787ad96
7 changed files with 121 additions and 42 deletions
@@ -7,13 +7,16 @@
# are UPSTREAM and produce the signals; this file only interprets them. No norm text, no real names.
mappings:
# Only OBSERVATION-kind signals appear here. requirement-kind signals (sbom_required, psirt_required,
# signed_updates_required) are intentionally ABSENT — they describe a target, never the present state,
# and the Silent Pass would never consume them anyway (it filters on kind == observation).
# ── website ───────────────────────────────────────────────────────────────────────────────
- {signal: security_txt_or_cvd_policy, capability: coordinated_vulnerability_disclosure, relationship: detected, evidence: cvd_policy}
- {signal: cvd_policy_present, capability: coordinated_vulnerability_disclosure, relationship: detected, evidence: cvd_policy}
- {signal: ce_marking_on_site, capability: ce_conformity_assessment_and_technical_documentation, relationship: partial, evidence: ce_declaration}
- {signal: support_lifecycle_page, capability: security_update_support_period, relationship: partial, evidence: support_policy}
- {signal: security_policy_page, capability: information_security_management, relationship: partial}
# ── repository ────────────────────────────────────────────────────────────────────────────
- {signal: sbom_file_found, capability: sbom_creation, relationship: detected, evidence: sbom}
- {signal: sbom_present, capability: sbom_creation, relationship: detected, evidence: sbom}
- {signal: signed_releases, capability: secure_signed_update_distribution, relationship: detected, evidence: signing_config}
- {signal: github_actions_ci, capability: secure_development_lifecycle, relationship: partial, evidence: ci_pipeline}
- {signal: dependency_scanning, capability: technical_vulnerability_management, relationship: partial, evidence: vuln_scanning_config}
@@ -1,14 +1,23 @@
# Signal Vocabulary — canonical signal id + the producer-specific aliases that mean the same thing.
# Signal Vocabulary — canonical signal id + aliases + KIND. One language, but TWO kinds of signal.
#
# The same fact ("SBOM present") can arrive as CycloneDX, SPDX, a GitHub Action, a Maven plugin, a
# document upload, a customer statement, a tender clause or a repo file. For the Silent Pass they are
# ALL identical: `sbom_file_found`. This file reduces them to one canonical signal — same pattern as the
# regulation-alias vocabulary, MCAPs and Requirement Sources: many inputs, one language. No scanner-
# specific logic ever reaches the Silent Pass. Pure DATA, injected into normalize_signals(). No real names.
# document upload or a customer statement — for the Silent Pass they are ALL `sbom_present`. This file
# reduces producer dialects to one canonical signal — same pattern as the regulation-alias vocabulary,
# MCAPs and Requirement Sources: many inputs, one language. No scanner-specific logic reaches the Silent
# Pass. Pure DATA, injected into normalize_signals(). No real names.
#
# KIND is the load-bearing distinction (default: observation):
# observation = "I SAW X" — a repo with an SBOM, a published security.txt, a risk-assessment PDF.
# requirement = "someone DEMANDS X" — a tender clause `requires_sbom`, an OEM spec `supplier_requires_psirt`.
# A DEMANDED SBOM is NOT a PRESENT SBOM. `kind` lives on the canonical entry (AUTHORITATIVE), so even a
# mislabelled producer signal cannot collapse the two. The Silent Pass consumes ONLY observations;
# requirement signals are preserved (requirements_seen) and drive the required-set / prioritisation later
# (Requirement Source). This is the Observation-vs-Requirement split the Verification Platform rests on.
signals:
- {id: sbom_file_found, aliases: [cyclonedx_found, spdx_found, sbom_in_repo, sbom_present, sbom_uploaded, requires_sbom, sbom_in_tender]}
- {id: security_txt_or_cvd_policy, aliases: [security_txt, vdp_found, cvd_policy_pdf, psirt_page, coordinated_disclosure_policy, supplier_requires_psirt]}
# ── OBSERVATIONS — "I saw X" (kind: observation, the default) ────────────────────────────────
- {id: sbom_present, aliases: [cyclonedx_found, spdx_found, sbom_in_repo, sbom_uploaded]}
- {id: cvd_policy_present, aliases: [security_txt, vdp_found, cvd_policy_pdf, psirt_page, coordinated_disclosure_policy]}
- {id: signed_releases, aliases: [signed_artifacts, cosign_found, gpg_signed_releases, code_signing_cert, secure_boot]}
- {id: github_actions_ci, aliases: [ci_pipeline, gitlab_ci, jenkins_pipeline, build_automation]}
- {id: dependency_scanning, aliases: [dependabot, renovate, snyk_found, trivy_in_ci, sca_tool]}
@@ -19,10 +28,17 @@ signals:
- {id: product_risk_assessment_doc, aliases: [risk_assessment_pdf, hazard_analysis_doc, tara_doc]}
- {id: patch_policy_doc, aliases: [patch_management_policy, update_policy_pdf]}
- {id: incident_response_plan_doc, aliases: [irp_doc, incident_playbook]}
# product facts
# product facts (also observations: an observed product property that drives scope)
- {id: cloud_connectivity, aliases: [cloud_hosted, saas, internet_facing, connected_product]}
- {id: plc_sps, aliases: [plc_detected, sps_steuerung, industrial_controller]}
- {id: embedded_software, aliases: [firmware_present, embedded_device]}
- {id: wireless_radio, aliases: [bluetooth, wifi_module, radio_equipment, funkmodul]}
- {id: remote_access, aliases: [remote_maintenance, vpn_access, teleservice, fernwartung]}
- {id: generates_usage_data, aliases: [telemetry_collected, usage_analytics]}
# ── REQUIREMENTS — "someone DEMANDS X" (kind: requirement; NEVER read as present) ─────────────
# Preserved + visible, but the Silent Pass does NOT turn them into detected capabilities. A tender /
# OEM spec / law lands here; a scanner / repo / document lands above. Intentionally UNMAPPED in
# intake_signal_map.yaml — they describe the target, not the present state.
- {id: sbom_required, kind: requirement, aliases: [requires_sbom, sbom_in_tender, tender_requires_sbom]}
- {id: psirt_required, kind: requirement, aliases: [supplier_requires_psirt, requires_psirt, requires_cvd, oem_requires_psirt]}
- {id: signed_updates_required, kind: requirement, aliases: [requires_signed_updates, supplier_requires_signed_updates]}