Initial server source import
This commit is contained in:
sashatrask
+190
@@ -0,0 +1,190 @@
|
||||
## 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
|
||||
Reference in New Issue
Block a user