Initial server source import
This commit is contained in:
sashatrask
+49
@@ -0,0 +1,49 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Platform-specific layer graphs are resolved
|
||||
The system SHALL resolve each bounded Docker tag candidate to the requested platform child manifest and SHALL represent its image contents as the ordered sequence of valid layer digests.
|
||||
|
||||
#### Scenario: Multi-platform tag contains the requested platform
|
||||
- **WHEN** a tag exposes a matching `linux/amd64` child manifest
|
||||
- **THEN** the system uses that child manifest digest and its ordered layers rather than the top-level index digest
|
||||
|
||||
#### Scenario: Candidate manifest is malformed
|
||||
- **WHEN** a registry response is oversized, malformed, or contains invalid layer identities
|
||||
- **THEN** the candidate is not represented as a resolved layer graph
|
||||
|
||||
### Requirement: Docker selection covers distinct graphs
|
||||
The system SHALL emit no more than the configured one-to-three image targets per repository and SHALL NOT emit two candidates with identical ordered layer digest sequences.
|
||||
|
||||
#### Scenario: Tags alias one graph
|
||||
- **WHEN** multiple tags resolve to the same ordered layer sequence
|
||||
- **THEN** only the newest alias remains eligible for selection
|
||||
|
||||
#### Scenario: Three or more graphs are available
|
||||
- **WHEN** at least three distinct graphs resolve successfully
|
||||
- **THEN** the system selects the newest graph, the remaining graph adding the most not-yet-selected layers, and the oldest remaining distinct graph
|
||||
|
||||
#### Scenario: Fewer graphs are available
|
||||
- **WHEN** fewer distinct graphs resolve successfully than the configured maximum
|
||||
- **THEN** the system emits only the distinct graphs that exist
|
||||
|
||||
#### Scenario: Layer order differs
|
||||
- **WHEN** two manifests contain the same layer identities in a different order
|
||||
- **THEN** the system treats them as distinct graphs
|
||||
|
||||
### Requirement: Selected Docker targets remain immutable
|
||||
The system SHALL emit each selected target as the canonical requested-platform manifest digest identity `repository@sha256:<digest>`.
|
||||
|
||||
#### Scenario: Selected tag moves later
|
||||
- **WHEN** a tag is republished after discovery
|
||||
- **THEN** the queued target continues to identify the originally selected platform manifest digest
|
||||
|
||||
### Requirement: Docker graph resolution is bounded and honest
|
||||
The system SHALL retain hard tag-candidate, selected-graph, response-size, retry, and timeout bounds and SHALL NOT cache partial graph resolution as complete.
|
||||
|
||||
#### Scenario: Some manifest requests fail
|
||||
- **WHEN** at least one candidate graph resolves and another candidate fails transiently
|
||||
- **THEN** the system may emit the resolved targets for the cycle but records partial resolution and does not write a complete positive cache entry
|
||||
|
||||
#### Scenario: Every manifest request fails transiently
|
||||
- **WHEN** no candidate graph can be resolved because registry metadata is unavailable
|
||||
- **THEN** the repository remains retryable through the existing deferred-resolution lifecycle
|
||||
@@ -0,0 +1,68 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Git scans are bound to an exact revision
|
||||
The system SHALL resolve a normalized ref and exact commit SHA for each claimed GitHub or GitLab repository before invoking TruffleHog and SHALL bind that immutable plan to the active reservation.
|
||||
|
||||
#### Scenario: Repository search supplies no ref hint
|
||||
- **WHEN** a claimed repository came from metadata search without an exact ref
|
||||
- **THEN** the system resolves the provider's current default branch and its exact head SHA
|
||||
|
||||
#### Scenario: Discovery supplies an exact ref hint
|
||||
- **WHEN** an event-backed target includes a valid branch ref
|
||||
- **THEN** the system resolves and binds that specific ref instead of substituting the default branch
|
||||
|
||||
#### Scenario: Revision lookup fails
|
||||
- **WHEN** the provider API cannot return a valid ref and commit SHA
|
||||
- **THEN** the claim receives a bounded retryable source failure and no exact coverage state advances
|
||||
|
||||
### Requirement: Git updates scan every newly introduced commit
|
||||
The system SHALL scan the exact claimed head after the last successfully covered head for the same ref and SHALL NOT apply rolling age or maximum-depth limits to that incremental range.
|
||||
|
||||
#### Scenario: Same ref advances
|
||||
- **WHEN** ref `R` was successfully covered at commit `A` and now resolves to descendant commit `D`
|
||||
- **THEN** the scan is pinned to `D` with `A` as its boundary and includes commits introduced between them
|
||||
|
||||
#### Scenario: Secret is added and then deleted in the delta
|
||||
- **WHEN** one newly introduced commit adds a secret and a later newly introduced commit removes it
|
||||
- **THEN** both commits remain in scan scope even though the final filesystem snapshot is clean
|
||||
|
||||
#### Scenario: Head is unchanged
|
||||
- **WHEN** the resolved head equals the successfully covered head for the same ref
|
||||
- **THEN** the system records an exact no-op without launching a redundant repository scan
|
||||
|
||||
### Requirement: Git baseline and discontinuity handling remain pinned
|
||||
The system SHALL use a pinned bounded baseline for a first-seen ref or an unusable incremental base and SHALL identify that mode without claiming unbounded historical coverage.
|
||||
|
||||
#### Scenario: Ref has no covered head
|
||||
- **WHEN** an exact ref is claimed without prior successful coverage
|
||||
- **THEN** the system scans its pinned head using the configured baseline depth bound and establishes that head as the future delta boundary on success
|
||||
|
||||
#### Scenario: Covered base is unavailable
|
||||
- **WHEN** force push, ref recreation, or remote history removal makes the covered SHA unusable
|
||||
- **THEN** the system falls back to a pinned bounded baseline and records the continuity reset
|
||||
|
||||
### Requirement: Git coverage advances only after successful fenced work
|
||||
The system SHALL update a queue row's covered ref and head only when successful ingestion applies a matching immutable reservation plan.
|
||||
|
||||
#### Scenario: Exact scan succeeds
|
||||
- **WHEN** a pinned baseline or delta result is ingested with queue disposition `done` and its plan matches the active reservation
|
||||
- **THEN** the queue's covered ref and head advance to the claimed head
|
||||
|
||||
#### Scenario: Exact scan fails or is deferred
|
||||
- **WHEN** execution fails, times out, loses its fence, or receives a deferred disposition
|
||||
- **THEN** the previously covered ref and head remain unchanged
|
||||
|
||||
#### Scenario: Remote advances during a scan
|
||||
- **WHEN** a newer commit appears after the worker binds its immutable head
|
||||
- **THEN** successful completion advances coverage only to the bound head and leaves the newer update eligible for later discovery
|
||||
|
||||
### Requirement: Exact Git scope is observable
|
||||
The system SHALL durably record the executed ref, head, base, scan mode, baseline bound, and whether immutable execution was preserved.
|
||||
|
||||
#### Scenario: Operator inspects an incremental scan
|
||||
- **WHEN** an exact delta result is committed
|
||||
- **THEN** its normalized scan metadata identifies the covered range without exposing source credentials
|
||||
|
||||
#### Scenario: Metadata discovery observes repository-level activity
|
||||
- **WHEN** no branch-specific event exists
|
||||
- **THEN** observability identifies the provider-resolved default-branch scope rather than implying coverage of every repository ref
|
||||
Reference in New Issue
Block a user