diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 864ca38c..f5bd909d 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -144,6 +144,31 @@ flags, and raw configuration never enter the runtime edge, finding, or browser response. Missing, stale, duplicate, malformed, or collided facts produce no finding. +`docker.compose_declared_target_not_active` emits an advisory only when one +fresh, uniquely identified `depends_on` relationship is a Docker-recorded +Compose declaration from a running Docker container to a uniquely identified +Docker container whose normalized state is stopped or failed. Its one canonical +evidence reference is version 1 Docker `docker_compose_depends_on`, with an +`observed` assertion, the source container as subject, `fresh` freshness, and +no provider slot. The Docker observation attests the declared Compose edge; it +does not turn that declaration into a runtime dependency guarantee. + +The rule is advisory, rather than a warning or error, because it is a bounded +configuration state worth an operator review, not evidence of an outage or +security incident. Its static action is only to review the declared dependency +and the target container state. The derivation is deterministic (findings are +ordered by their stable opaque identifiers) and fails closed: stale or timed-out +evidence, malformed or extra edge metadata, non-Docker entities, non-running +sources, target states other than stopped/failed, duplicate relationship facts, +or identity collisions suppress it. It does not claim that the dependency is +required, that either service is ready or healthy, that traffic flows, that +Compose start order was applied, that one container caused the other's state, +or that configuration drift exists. + +This rule reads no new host state and makes no new collection call. It is a +cached, read-only projection of the already-published runtime map; mock mode +has no runtime evidence and therefore cannot produce it. + Each rule carries only its exact triggering evidence references. The API validates the fixed vocabulary, static display text, and rule-specific evidence shape before publication, and the browser displays findings only when their diff --git a/docs/security/THREAT_MODEL.md b/docs/security/THREAT_MODEL.md index f3c9cb44..c84b5fbc 100644 --- a/docs/security/THREAT_MODEL.md +++ b/docs/security/THREAT_MODEL.md @@ -56,6 +56,13 @@ changes them: - Docker daemon-state bind-mount evidence is a single closed, path-free fact. It never exposes a mount path, mount ID, mount options, or raw Docker configuration. npm dependency evidence is likewise a bounded declaration with a curated summary, never raw `package.json` content. +- The Compose target-state advisory is a cached read-only derivation, not a collector. It accepts + only one fresh version-1 Docker `docker_compose_depends_on` observed-declaration reference for + a unique running Docker-container source and unique stopped/failed Docker-container target. + Its static recommendation is to review that declaration and target state. Stale, malformed, + duplicate, collided, or non-Docker inputs are suppressed. It exposes no raw Compose content or + identifiers beyond the existing opaque runtime references, and it does not claim dependency + requiredness, readiness, health, traffic, start-order execution, root cause, or drift. ## Main Risks And Protections diff --git a/docs/testing/TESTING_PLAN.md b/docs/testing/TESTING_PLAN.md index c481565d..8e6b268a 100644 --- a/docs/testing/TESTING_PLAN.md +++ b/docs/testing/TESTING_PLAN.md @@ -17,6 +17,13 @@ containers, or services. requires a bounded nonzero host binding rather than a container-only listener; Docker daemon-state evidence is path-free; and Systemd/npm declaration evidence is checked against its dedicated scheduler-slot revision and `fresh`/`stale`/`timed_out` lifecycle. +- Bounded-finding tests: the Compose advisory accepts only a fresh, uniquely resolved Docker + Compose declaration from a running container to a stopped/failed container, keeps the single + canonical `docker_compose_depends_on` evidence reference, assigns advisory severity and static + review wording, and deterministically suppresses stale/timed-out, malformed, duplicate, + collided, ambiguous, non-Docker, and non-matching-status inputs. These are projection tests: + they add no collection and never assert requiredness, readiness, health, traffic, start-order, + root-cause, or drift conclusions. - Rust-owned JSON Schema and generated TypeScript declarations, Node-owned envelope/request/SSE schemas, and readable contract fixtures. The contract check fails on stale generated output, invalid fixtures, incomplete