Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/architecture/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/security/THREAT_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 7 additions & 0 deletions docs/testing/TESTING_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading