Phase 2: Detection

[chriswayneh]

Phase 2 gives RedDock findings without letting them absorb observations. An observation still states what an adapter saw. A finding is a separate thing: a normalized conclusion one named detector drew from one or more observations, which cannot exist without them.

Phase 1   Discovery → Asset / Service / Observation → Evidence
Phase 2   Discovery → Observation → Detection → Finding → Evidence

The detector boundary

A detector is deliberately weaker than a discovery adapter. An adapter may contact a target after DockGuard allows it; a detector may not contact anything. It receives an immutable snapshot of one Dockyard and returns value objects — no database session, no socket, no subprocess, no target string, no operator-supplied option. There is nothing for it to widen, execute, or reach, which is why it needs no scope decision.

That is enforced structurally rather than by convention. tests/test_detection_contract.py parses the detection package and fails the build if a detector imports anything that could leave the process or touch the database, and asserts that nothing in detection calls eval, exec, compile, or __import__.

Everything a detector could get wrong belongs to the runner: building the snapshot, validating the output, computing identity, reconciling, resolving, writing evidence. A detector that raises, returns an unknown severity, uses an unusable rule id, names another Dockyard's data, or cites no observation is failed as a whole and its results are discarded. The other detectors still run, and a failed detector resolves nothing — not running is not evidence that an issue went away.

Two invariants

A finding must cite evidence. A conclusion with nothing behind it is refused, not stored with a caveat. FindingEvidence links each finding to the observations it was drawn from, their discovery run, and that run's hashed EvidenceRecord, so "which detector, from what observation, during which run, verified by which hash" is answerable without leaving the database.

A finding is never deleted. Identity is a SHA-256 fingerprint over the detector, the rule, and the asset and service concerned — deterministic across runs, restarts, and processes, which Python's randomized hash() would not be. One issue stays one row whose last_seen moves. An issue a later successful run no longer reproduces is marked resolved; an operator may suppress, accept, or reopen one but may not declare it resolved, because whether something is still reproduced is a fact about the data rather than an opinion about it.

Detectors

Three, and each says only what Phase 1 data actually supports.

Detector	Reports
http.security_headers	Plaintext transport, and response-level protections the response did not carry
service.rules	A fixed table of protocol rules over services RedDock identified, plus disclosed versions
tls.certificates	What certificate verification objected to

The false-positive controls are the point:

• A header is only reported when the probe recorded that it looked for it, so "RedDock did not look" is never rendered as "the server did not send it". This required a Phase 1 change: the response observation now states the header set it examined.
• Content-level headers are judged only on a response that represents how an endpoint normally answers. A 301 to HTTPS carrying no Content-Security-Policy is a correct configuration, not a finding.
• HSTS is not reported over plaintext HTTP, where it is meaningless. The plaintext transport is the finding there.
• A service rule needs an identification observation. A port number alone still says nothing.
• Severity is restrained: missing hardening headers are low, and severity and confidence stay separate fields.

What is deliberately absent: there is no TLS protocol-version rule. The probe negotiates with a default client, so it can only ever record a version a current client accepted, and a rule about obsolete versions could never fire from RedDock's own data. Shipping it would suggest a capability that does not exist.

CVE enrichment

RedDock downloads no CVE data. This ships the boundary plus a local catalogue reader behind REDDOCK_CVE_CATALOG, off by default.

An association never creates a finding, never changes a severity, confidence, or status, and attaches to the version-disclosure finding that already stood on its own evidence. Matching is exact product and version only — version ranges are not interpreted, because an inference printed beside a CVE identifier reads as a result. A missing or malformed catalogue is a warning on the run, not a failure, and each run records which enrichment source was in effect so a finding with no CVE reference can be told apart from one RedDock could not enrich. A test asserts the same data produces the same rating with and without a catalogue loaded.

The limitation is documented rather than hidden: out of the box, no finding carries a CVE reference. See ADR 0007.

Preflight fixes

Three issues found before building on top of the existing code, all in the same branch:

1. The HTTP probe recorded no statement of which headers it examined, so any header detector built on it would generate false positives on pre-Phase-2 evidence. It now records the examined set alongside the headers present, and examines the response-level protections a detector needs.
2. An unverified TLS handshake returns an empty peer certificate, so verified: false alone supports no claim about a certificate. The probe now records the code and message OpenSSL gave.
3. The probe User-Agent was a hardcoded RedDock/0.2.1, which the 0.2.1 changelog claims tracks the application version. It now derives from settings, and a test asserts the application, API, and both package manifests report one version.

Schema

Purely additive: three new tables, no existing column changed, so create_all upgrades a deployed database in place. tests/test_schema_upgrade.py now builds a real 0.2.1-shaped database, runs a full detection over data the previous release wrote, and asserts every Phase 1 table keeps the shape it had.

That constraint shaped a decision rather than merely being stated. Detection artifact hashes live on the detection run because evidence_records.discovery_run_id is NOT NULL and relaxing it would be the first destructive schema change — which this architecture already says arrives with versioned migrations rather than an ad hoc alteration. Both halves are written by the same store, under the same root, both SHA-256 hashed.

Validation

• 261 backend tests (was 119), 16 frontend tests (was 7); ruff, eslint, tsc, and the production build clean
• Container built and the end-to-end smoke test run against it, now covering detection, findings, evidence traceability, deduplication, and that detection accepts no operator parameters — against RedDock's own origin inside the container, so nothing outside the machine is contacted
• Security review of the diff found no HIGH or MEDIUM issues: the new evidence scope is validated against a closed set before path construction, every findings query is dockyard-scoped, the detection endpoint takes no operator input, and no new deserialization or dangerouslySetInnerHTML was introduced

Safety

Phase 2 adds no exploitation, credential attack, brute force, payload execution, evasion, persistence, lateral movement, or autonomous behaviour, and no active vulnerability testing. Detection reasons over data an earlier non-invasive discovery recorded; it sends nothing and confirms nothing by attempting it. DockGuard is unchanged and remains authoritative for everything that does reach a target. No AI is involved: every detector is a deterministic rule, and the same input produces the same findings.

🤖 Generated with Claude Code