Frontend gaps fill work. Testing fixes work. Auditing in progress.

2025-12-30 01:22:58 +02:00
parent 1dc4bcbf10
commit 7a5210e2aa
928 changed files with 183942 additions and 3941 deletions
--- a/docs/modules/signals/architecture.md
+++ b/docs/modules/signals/architecture.md
@@ -213,3 +213,94 @@ The Signals module maintains strict determinism:
 - Backport Detection: `docs/modules/concelier/backport-detection.md`
 - EPSS Enrichment: `docs/modules/scanner/epss-enrichment.md`
 - Trust Vector: `docs/modules/excititor/trust-vector.md`
+
+---
+
+## SCM/CI Integration (Webhooks)
+
+The Signals module also handles webhook ingestion from SCM (Source Code Management) and CI (Continuous Integration) providers. This enables:
+- Triggering scans on push/PR/release events
+- SBOM uploads from CI pipelines
+- Image push detection and automated scanning
+
+### Location
+
+```
+src/Signals/StellaOps.Signals/Scm/
+├── Models/
+│   ├── NormalizedScmEvent.cs      # Provider-agnostic event payload
+│   ├── ScmEventType.cs            # Event type enumeration
+│   └── ScmProvider.cs             # Provider enumeration
+├── Webhooks/
+│   ├── IWebhookSignatureValidator.cs
+│   ├── GitHubWebhookValidator.cs  # HMAC-SHA256 validation
+│   ├── GitLabWebhookValidator.cs  # Token-based validation
+│   ├── GiteaWebhookValidator.cs   # HMAC-SHA256 validation
+│   ├── IScmEventMapper.cs
+│   ├── GitHubEventMapper.cs       # GitHub -> NormalizedScmEvent
+│   ├── GitLabEventMapper.cs       # GitLab -> NormalizedScmEvent
+│   └── GiteaEventMapper.cs        # Gitea -> NormalizedScmEvent
+├── Services/
+│   ├── IScmWebhookService.cs
+│   ├── ScmWebhookService.cs       # Orchestrates validation + mapping
+│   ├── IScmTriggerService.cs
+│   └── ScmTriggerService.cs       # Routes events to Scanner/Orchestrator
+└── ScmWebhookEndpoints.cs         # Minimal API webhook endpoints
+```
+
+### Supported Providers
+
+| Provider | Webhook Endpoint | Signature Header | Validation |
+|----------|------------------|------------------|------------|
+| GitHub | `/webhooks/github` | `X-Hub-Signature-256` | HMAC-SHA256 |
+| GitLab | `/webhooks/gitlab` | `X-Gitlab-Token` | Token match |
+| Gitea | `/webhooks/gitea` | `X-Gitea-Signature` | HMAC-SHA256 |
+
+### Event Types
+
+| Event Type | Description | Triggers |
+|------------|-------------|----------|
+| `Push` | Code push to branch | Scan (main/release branches) |
+| `PullRequestOpened` | PR opened | —  |
+| `PullRequestMerged` | PR merged | Scan |
+| `ReleasePublished` | Release created | Scan |
+| `ImagePushed` | Container image pushed | Scan |
+| `PipelineSucceeded` | CI pipeline completed | Scan |
+| `SbomUploaded` | SBOM artifact uploaded | SBOM ingestion |
+
+### Webhook Payload Normalization
+
+All provider-specific payloads are normalized to `NormalizedScmEvent`:
+
+```csharp
+public sealed record NormalizedScmEvent
+{
+    public required string EventId { get; init; }
+    public ScmProvider Provider { get; init; }
+    public ScmEventType EventType { get; init; }
+    public DateTimeOffset Timestamp { get; init; }
+    public required ScmRepository Repository { get; init; }
+    public ScmActor? Actor { get; init; }
+    public string? Ref { get; init; }
+    public string? CommitSha { get; init; }
+    public ScmPullRequest? PullRequest { get; init; }
+    public ScmRelease? Release { get; init; }
+    public ScmPipeline? Pipeline { get; init; }
+    public ScmArtifact? Artifact { get; init; }
+    public string? TenantId { get; init; }
+    public string? IntegrationId { get; init; }
+}
+```
+
+### Trigger Routing
+
+The `ScmTriggerService` determines which events should trigger:
+1. **Scans:** Push to main/release, PR merges, releases, image pushes, successful pipelines
+2. **SBOM uploads:** Explicit `SbomUploaded` events or artifact releases with SBOM content
+
+### Security
+
+- **Signature verification:** All webhooks validate signatures before processing
+- **AuthRef integration:** Webhook secrets are managed via AuthRef (not stored in code)
+- **Rate limiting:** Built-in rate limiting to prevent webhook floods
+- **Audit trail:** All webhook deliveries are logged with delivery ID and result