Initial server source import

2026-09-30 20:30:56 +03:00
commit 170dd941b9
498 changed files with 261563 additions and 0 deletions
@@ -0,0 +1,74 @@
+## ADDED Requirements
+
+### Requirement: External Docker scan lifecycle ownership
+The system SHALL bypass TruffleHog's embedded overseer for DockerHub image scans while retaining the existing external supervisor, scan-slot lease, timeout, output bounds, and Windows Job containment.
+
+#### Scenario: Docker command construction
+- **WHEN** the system constructs a TruffleHog command for a DockerHub image
+- **THEN** the command includes both `--local-dev` and `--no-update`
+
+#### Scenario: Non-Docker command construction
+- **WHEN** the system constructs a TruffleHog command for a non-Docker source
+- **THEN** this Docker-only capability does not add `--local-dev`
+
+### Requirement: Explicit Docker scan completion
+The system SHALL record whether TruffleHog emitted the exact normal completion message `finished scanning`, and SHALL require both that marker and exit code 0 before treating process execution as complete.
+
+#### Scenario: Normal completion
+- **WHEN** a Docker TruffleHog process exits with code 0 after emitting `finished scanning`
+- **THEN** diagnostic metadata records completed execution and no lifecycle error is added
+
+#### Scenario: Missing completion marker
+- **WHEN** a Docker TruffleHog process exits without emitting `finished scanning`
+- **THEN** the result is classified as an incomplete retryable run and is not treated as clean or done
+
+#### Scenario: Nonzero exit after completion marker
+- **WHEN** a Docker TruffleHog process emits `finished scanning` but exits nonzero without a more specific diagnostic
+- **THEN** the result is classified as a retryable wrapper exit rather than successful execution
+
+### Requirement: Bounded retry for incomplete Docker runs
+The system SHALL route incomplete Docker lifecycle failures through the existing bounded target retry policy and SHALL preserve the terminal attempt limit.
+
+#### Scenario: Retry remains available
+- **WHEN** an incomplete Docker run occurs before the configured maximum target attempt
+- **THEN** the queue defers the target using the configured retry delay
+
+#### Scenario: Attempt limit is reached
+- **WHEN** an incomplete Docker run occurs at the configured maximum target attempt
+- **THEN** the queue records a terminal failed target and does not create an unbounded retry loop
+
+### Requirement: Partial finding preservation
+The system SHALL retain findings emitted before an incomplete Docker process exit without representing the target as fully scanned.
+
+#### Scenario: Findings precede incomplete exit
+- **WHEN** TruffleHog emits one or more findings and then exits before complete execution is confirmed
+- **THEN** those findings remain durable while the target receives retryable incomplete disposition
+
+### Requirement: Bounded Docker internal parallelism
+The system SHALL pass source-configured internal concurrency to Docker TruffleHog commands while retaining the existing source worker and Windows Job limits.
+
+#### Scenario: Docker canary resource settings
+- **WHEN** the configured DockerHub source starts an image scan
+- **THEN** TruffleHog runs with internal concurrency 4 and a target timeout of 600 seconds
+
+### Requirement: Nonfatal detector context timeout
+The system SHALL retain the exact diagnostic `a detector ignored the context timeout` as degraded detector coverage rather than a fatal image-scan error.
+
+#### Scenario: Completed scan with detector timeout
+- **WHEN** a Docker scan emits the detector context-timeout diagnostic, emits `finished scanning`, and exits with code 0
+- **THEN** the target result contains a `detector_timeout` warning and no lifecycle error
+
+#### Scenario: Other timeout diagnostic
+- **WHEN** a Docker scan emits a different timeout diagnostic
+- **THEN** the existing retryable timeout error policy remains in effect
+
+### Requirement: Controlled historical replay
+The system SHALL replay historical Docker failures matching the exact incomplete-exit signature only in bounded batches after lifecycle canary criteria pass.
+
+#### Scenario: Canary has not passed
+- **WHEN** lifecycle health has not met the defined canary criteria
+- **THEN** historical terminal failures are not mass-requeued
+
+#### Scenario: Canary has passed
+- **WHEN** lifecycle health meets the defined canary criteria and a bounded replay batch is selected
+- **THEN** only exact-signature Docker failures in that batch are returned to the pending queue