truf-server/openspec/changes/add-layer-aware-docker-scanning/specs/docker-layer-content-scanning/spec.md

ADDED Requirements

Requirement: Docker timeout retries are bounded

The system SHALL count target-scoped Docker command timeouts against the configured target-attempt maximum and SHALL preserve partial findings without creating an unbounded retry loop.

Scenario: Timeout before attempt limit

• WHEN a Docker command times out before the configured maximum attempt
• THEN its emitted findings remain durable and the immutable target is deferred using the configured timeout delay without resetting its attempt count

Scenario: Timeout reaches attempt limit

• WHEN a Docker command times out at the configured maximum attempt
• THEN its emitted findings remain durable and the queue records a terminal target disposition

Scenario: Source-wide outage

• WHEN Docker execution is prevented by a source-wide infrastructure failure rather than target-scoped work
• THEN the existing fenced source-failure recovery policy remains applicable

Requirement: Immutable image content plans are bound after claim

The system SHALL resolve a claimed Docker image's exact platform manifest into a canonical bounded plan containing its configuration and ordered layer descriptors, and SHALL bind that plan to the active result reservation before content execution.

Scenario: Valid immutable manifest

• WHEN the claimed repository@sha256:<digest> resolves to a valid requested-platform manifest
• THEN the bound plan identifies the same manifest digest and contains only bounded valid SHA-256 content descriptors, sizes, media types, and order

Scenario: Changed replay

• WHEN the same reservation attempts to bind a different content plan
• THEN the system rejects the replay as a fenced conflict and executes neither plan

Scenario: Invalid or oversized manifest

• WHEN the Registry manifest is malformed, exceeds descriptor bounds, or disagrees with the immutable target
• THEN the system fails closed without claiming complete content coverage

Requirement: Content selection is bounded and application-first

The system SHALL always select bounded image configuration and SHALL select new layers from highest to lowest under configured per-layer and per-image compressed-byte limits.

Scenario: Giant base or model layer

• WHEN a layer exceeds the configured per-layer limit
• THEN the layer is not downloaded by the normal layer scanner and coverage records layer_too_large

Scenario: Image byte budget is exhausted

• WHEN another unscanned layer would exceed the remaining per-image budget
• THEN the layer remains unselected and coverage records image_budget_exhausted

Scenario: Shared layer is already covered

• WHEN a layer digest has successful global coverage
• THEN the image reuses that coverage without consuming its transfer budget or launching another scan

Scenario: Upper and base layers both fit

• WHEN multiple unscanned layers fit within all configured bounds
• THEN the system selects them in highest-to-lowest manifest order

Requirement: Layer coverage is globally deduplicated and fenced

The system SHALL maintain one authoritative content-scan state per immutable digest and SHALL change successful coverage only through matching reservation, lease, plan, and ingestion fences.

Scenario: Concurrent images share a layer

• WHEN two image plans reference the same unscanned digest concurrently
• THEN at most one reservation owns its active scan and the other image records shared pending work without duplicate execution

Scenario: Successful matching ingestion

• WHEN a result bundle contains a successful execution for a blob leased by its exact bound plan
• THEN ingestion marks that digest globally covered in the same durable transaction

Scenario: Stale completion

• WHEN a bundle or worker presents an expired, refunded, or mismatched blob lease
• THEN it cannot mark the digest covered or advance image coverage

Scenario: Reservation is refunded

• WHEN an image reservation is durably refunded before handoff
• THEN only blob leases owned by that reservation are released for bounded reclamation

Requirement: Registry blob transfer is authenticated, bounded, and verified

The system SHALL fetch selected content from the trusted Docker Registry using the existing account pool, bounded streaming, private storage, safe redirect handling, and exact digest verification.

Scenario: Valid content download

• WHEN the Registry returns exactly the declared bounded blob bytes whose SHA-256 matches the descriptor
• THEN the private work artifact becomes eligible for scanning

Scenario: Cross-host redirect

• WHEN the trusted Registry redirects a blob request to an allowed public HTTPS content host
• THEN the system follows only the bounded validated redirect and does not forward Registry authorization to the other host

Scenario: Unsafe redirect

• WHEN a blob redirect uses HTTP, userinfo, a local/private destination, or exceeds redirect bounds
• THEN the transfer fails closed without exposing authentication material

Scenario: Size or digest mismatch

• WHEN streamed bytes exceed bounds, end short, or do not match the expected digest
• THEN the system deletes the work artifact and does not record successful coverage

Scenario: Insufficient private storage

• WHEN the configured private work volume cannot retain its required free-space floor
• THEN no blob download begins and the failure receives bounded retry disposition

Requirement: Configuration and layers are scanned independently

The system SHALL scan bounded image configuration and each newly leased supported layer as independent contained commands while preserving image and layer provenance on findings.

Scenario: Configuration contains candidate material

• WHEN bounded configuration JSON contains detector-matching data
• THEN findings identify the image and configuration digest and enter the normal result and keycheck pipeline

Scenario: Supported layer completes

• WHEN TruffleHog filesystem scanning of a verified layer archive completes successfully
• THEN its findings retain image, layer digest, kind, and position provenance and the layer becomes globally covered after fenced ingestion

Scenario: Layer scan is incomplete

• WHEN a layer command times out or exits without confirmed completion
• THEN emitted findings remain durable but that digest does not become covered

Scenario: Unsupported media type

• WHEN a layer compression or media type is not supported by the validated scanner path
• THEN no unsafe fallback executes and image coverage records unsupported_media_type

Requirement: Image coverage is explicit and honest

The system SHALL persist and expose selected, covered, shared-pending, failed, and intentionally skipped content for each immutable image plan.

Scenario: Every descriptor is covered

• WHEN configuration and all image layers have successful global coverage
• THEN the image records complete content coverage

Scenario: Bounds skip content

• WHEN one or more descriptors are excluded by configured size, budget, or format bounds
• THEN the image may finish as bounded partial coverage but SHALL NOT report complete content coverage

Scenario: Selected content remains retryable

• WHEN at least one selected blob failed retryably or is actively covered by another reservation
• THEN the image remains deferred without claiming complete coverage

Scenario: Selected content exhausts retries

• WHEN required selected content reaches its terminal attempt limit
• THEN the image receives terminal incomplete disposition with durable coverage detail

Requirement: Layer work resumes without repeating completed content

The system SHALL resume an incomplete image from selected content that lacks successful global coverage and SHALL NOT relaunch completed content digests.

Scenario: Parent image retries

• WHEN an image retry follows partial layer completion
• THEN the new plan reuses covered digests and leases only remaining eligible content

Scenario: Process crashes after one layer

• WHEN one layer was durably ingested before a later layer or parent process failed
• THEN recovery preserves the completed layer and reclaims only unfinished leased content

Requirement: Full-image compatibility and deterministic canary are retained

The system SHALL retain the existing full-image scanner behind configuration. Canary layer execution SHALL require a durable previous full-image command timeout and SHALL be selected deterministically from immutable manifest identity within that eligible set.

Scenario: Full mode

• WHEN Docker layer mode is disabled or set to full
• THEN the existing immutable full-image execution path remains authoritative

Scenario: Canary retry

• WHEN a canary image is retried
• THEN its immutable manifest digest selects the same scanner mode as its previous attempt

Scenario: Non-timeout image during canary rollout

• WHEN an image has no durable previous full-image command timeout
• THEN canary configuration keeps that image on the full-image execution path

Scenario: Layer mode rollback

• WHEN operators return configuration from layer or canary to full
• THEN new claims use full-image execution without deleting durable layer audit state

Requirement: Controlled evidence gates production rollout

The system SHALL compare layer scanning with completed full-image controls and SHALL keep broad production layer mode disabled until security, coverage, and throughput gates pass.

Scenario: Controlled spike

• WHEN the offline spike runs against bounded heavy and completed-control samples
• THEN it records aggregate bytes, wall time, slot time, coverage, distinct detector identities, and routed key recall without printing findings or keys

Scenario: Acceptance criteria fail

• WHEN digest integrity, fence safety, routed-key recall, resource bounds, or throughput criteria fail
• THEN production remains in full mode

Scenario: Completed-control recall fails but timeout fallback passes

• WHEN bounded layer scanning materially reduces timeout-heavy work but does not retain completed-control routed-key recall
• THEN operators may canary only prior full-image timeout retries and SHALL NOT enable broad layer mode

Scenario: Acceptance criteria pass

• WHEN the controlled spike and deterministic production canary satisfy all defined gates
• THEN operators may increase canary coverage or enable layer mode through configuration

Requirement: Historical timeout state is repaired safely

The system SHALL reconcile incorrectly reset Docker timeout attempts only while sources are stopped and only for unfenced immutable targets backed by durable timeout results.

Scenario: Exhausted historical timeout target

• WHEN an unfenced deferred Docker target has durable timeout executions at or above the configured maximum
• THEN repair marks it terminal without deleting its existing findings

Scenario: Active or ambiguous target

• WHEN a Docker target has an active lease, reservation, event fence, or ambiguous latest result
• THEN repair leaves it unchanged