sashatrask
191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
## 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
|