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,56 @@
+## ADDED Requirements
+
+### Requirement: External GitLab scan lifecycle ownership
+The system SHALL bypass TruffleHog's embedded overseer for configured GitLab repository scans while retaining external supervision, scan-slot leases, timeout enforcement, output bounds, and Windows Job containment.
+
+#### Scenario: GitLab command construction
+- **WHEN** the GitLab source constructs a TruffleHog Git command with external lifecycle enabled
+- **THEN** the command includes both `--local-dev` and `--no-update`
+
+#### Scenario: Non-GitLab command construction
+- **WHEN** another source constructs a TruffleHog Git command without external lifecycle enabled
+- **THEN** the command does not gain `--local-dev` or GitLab completion policy
+
+### Requirement: Explicit GitLab scan completion
+The system SHALL require both exit code 0 and the exact `finished scanning` marker before treating an externally managed GitLab TruffleHog process as complete.
+
+#### Scenario: Normal GitLab completion
+- **WHEN** the process exits code 0 after emitting `finished scanning`
+- **THEN** completion metadata is recorded and no lifecycle error is added
+
+#### Scenario: Missing GitLab completion marker
+- **WHEN** the process exits without emitting `finished scanning`
+- **THEN** the result is classified as retryable `command_incomplete` and is not treated as complete
+
+#### Scenario: Nonzero exit after completion marker
+- **WHEN** the process emits `finished scanning` and exits nonzero without a more specific fatal diagnostic
+- **THEN** the result is classified as retryable `wrapper_exit`
+
+### Requirement: Bounded retry for incomplete GitLab scans
+The system SHALL route incomplete GitLab lifecycle outcomes through the existing bounded target retry policy.
+
+#### Scenario: Retry remains available
+- **WHEN** an incomplete GitLab scan 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 GitLab scan occurs at the maximum target attempt
+- **THEN** the queue records a terminal failed target without an unbounded loop
+
+### Requirement: Partial GitLab finding preservation
+The system SHALL retain findings emitted before an incomplete GitLab process exit without representing the repository as fully scanned.
+
+#### Scenario: Findings precede incomplete exit
+- **WHEN** TruffleHog emits findings and then exits before completion is confirmed
+- **THEN** those findings remain durable while the target receives retryable incomplete disposition
+
+### Requirement: Controlled GitLab lifecycle rollout
+The system SHALL enable and replay GitLab lifecycle behavior only through bounded, observable stages.
+
+#### Scenario: Canary has not passed
+- **WHEN** the GitLab lifecycle canary has not reached its observation threshold
+- **THEN** historical terminal failures are not mass-requeued
+
+#### Scenario: Canary has passed
+- **WHEN** the canary is healthy and a bounded exact-signature batch is selected
+- **THEN** only targets in that batch are returned to the pending queue