22 KiB
22 KiB
SBOM Sources Architecture
Sprint: SPRINT_20251229_000_PLATFORM_sbom_sources_overview Last Updated: 2025-12-29
1. Overview
The SBOM Sources subsystem provides a unified configuration and management layer for all SBOM ingestion pathways: Zastava (registry webhooks), Docker (direct image scans), CLI (external submissions), and Git (repository scans).
1.1 Problem Statement
Current State:
- Fragmented source management across Orchestrator, Concelier, and Scanner
- No unified UI for configuring ingestion sources
- Credentials scattered without centralized management
- No visibility into source health and scan history
Target State:
- Single "Sources" module for all SBOM ingestion configuration
- Unified UI with type-specific wizards
- Centralized credential management via AuthRef pattern
- Real-time status monitoring and run history
2. Source Types Taxonomy
| Type | Trigger Mode | Target | Auth Pattern | Discovery |
|---|---|---|---|---|
| Zastava | Webhook (push) | Registry images | Registry creds + webhook secret | From webhook payload |
| Docker | Scheduled/Manual | Specific images | Registry credentials | Tag patterns |
| CLI | External submission | Any SBOM | API token | N/A (receives SBOMs) |
| Git | Webhook/Scheduled | Repository code | PAT/SSH + webhook secret | Branch patterns |
3. Health Signals
Each source maintains the following health signals:
| Signal | Description | Metric |
|---|---|---|
status |
Current operational state | active, paused, error, disabled, pending |
lastRunAt |
Timestamp of most recent run | ISO-8601 UTC |
lastRunStatus |
Status of most recent run | succeeded, failed, partial-success |
consecutiveFailures |
Count of consecutive failed runs | Integer, resets on success |
currentHourScans |
Scans executed in rate-limit window | Integer, resets hourly |
4. API Contract
4.1 Source CRUD Endpoints
GET /api/v1/sources List sources with filtering/pagination
POST /api/v1/sources Create new source
GET /api/v1/sources/{sourceId} Get source details
PUT /api/v1/sources/{sourceId} Update source configuration
DELETE /api/v1/sources/{sourceId} Delete source
4.2 Operational Endpoints
POST /api/v1/sources/{sourceId}/test Test source connection
POST /api/v1/sources/{sourceId}/trigger Manual scan trigger
POST /api/v1/sources/{sourceId}/pause Pause source (with reason)
POST /api/v1/sources/{sourceId}/resume Resume paused source
4.3 Run History Endpoints
GET /api/v1/sources/{sourceId}/runs List run history (paginated)
GET /api/v1/sources/{sourceId}/runs/{runId} Get run details
4.4 Webhook Endpoints
POST /api/v1/webhooks/zastava/{sourceId} Zastava registry webhook
POST /api/v1/webhooks/git/{sourceId} Git repository webhook
5. Domain Events
| Event | Payload | When Emitted |
|---|---|---|
source.created |
{ sourceId, sourceType, tenantId } |
New source registered |
source.updated |
{ sourceId, changedFields[] } |
Source configuration updated |
source.deleted |
{ sourceId } |
Source removed |
source.paused |
{ sourceId, reason, pausedBy } |
Source paused |
source.resumed |
{ sourceId, resumedBy } |
Source resumed |
source.run.started |
{ runId, sourceId, trigger } |
Run initiated |
source.run.completed |
{ runId, sourceId, status, metrics } |
Run finished |
6. Credential Lifecycle (AuthRef Pattern)
All source credentials use the AuthRef pattern for secure storage:
- Storage: Credentials stored in Authority vault, never inline in source configs
- Reference: Sources hold
authRefidentifiers pointing to vault entries - Rotation: Rotate-on-demand API; old refs invalidated, new ref issued
- Audit: All credential access logged with source context
6.1 Supported Credential Types
| Source Type | Credential Types |
|---|---|
| Zastava | Registry auth (basic/token), webhook secret |
| Docker | Registry auth (basic/token/ECR/GCR/ACR) |
| CLI | API token, OIDC identity |
| Git | PAT, SSH key, webhook secret |
7. Telemetry Schema
7.1 Metrics
| Metric | Type | Labels | Description |
|---|---|---|---|
sbom_source_runs_total |
Counter | source_type, status, trigger |
Total runs by type and outcome |
sbom_source_run_duration_seconds |
Histogram | source_type |
Run execution time |
sbom_source_items_scanned_total |
Counter | source_type |
Items processed per run |
sbom_source_connection_test_duration_seconds |
Histogram | source_type |
Connection test latency |
sbom_source_active_count |
Gauge | source_type, status |
Active sources by type |
7.2 Structured Logs
All source operations emit structured logs including:
tenantId,sourceId,sourceTyperunId(when applicable)correlationIdfor cross-service tracing
8. Module Ownership Matrix
| Component | Owner Module | Interface |
|---|---|---|
| Source entity persistence | SbomService | PostgreSQL + Repository |
| Credential storage | Authority | AuthRef vault API |
| Webhook signature verification | SbomService | HMAC validation |
| Scheduled trigger dispatch | Scheduler | Cron job registration |
| Scan job execution | Scanner | Job queue interface |
| UI configuration | Web | Sources Manager feature |
9. UI Information Architecture
9.1 Navigation Placement
| Section | Route | Purpose |
|---|---|---|
| Sources List | /sources |
Primary view with filtering, status overview, bulk actions |
| Source Detail | /sources/{id} |
Configuration view, run history, health metrics |
| Add Source Wizard | /sources/new |
Multi-step creation flow |
| Edit Source | /sources/{id}/edit |
Modify existing source configuration |
9.2 Wizard Flow Architecture
The Add/Edit Source Wizard follows a 6-step progressive disclosure pattern:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Source Type Selection │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Zastava │ │ Docker │ │ CLI │ │ Git │ │
│ │ (Webhook) │ │ (Scanner) │ │ (Receiver) │ │ (Repository)│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 2: Basic Information │
│ • Name (required, unique per tenant) │
│ • Description (optional) │
│ • Tags (multi-select, for filtering) │
│ • Metadata key-value pairs (optional) │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 3: Type-Specific Configuration (varies by source type) │
│ │
│ Zastava: Docker: │
│ • Registry URL • Registry URL │
│ • Registry type dropdown • Image references (multi-add) │
│ • Repository filters • Tag patterns (include/exclude) │
│ • Tag patterns • Platform selection │
│ • Webhook path (generated) • Scan options (analyzers, reachability) │
│ │
│ CLI: Git: │
│ • Allowed tools list • Provider (GitHub/GitLab/Gitea/etc.) │
│ • Allowed CI systems • Repository URL │
│ • Validation rules • Branch patterns (include/exclude) │
│ • Attribution requirements • Trigger modes (push/PR/tag/scheduled) │
│ • Max SBOM size limit • Scan paths and exclusions │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 4: Credentials (AuthRef Pattern) │
│ • Credential type selector (per source type) │
│ • Create new credential vs. select existing │
│ • Inline credential entry (stored via Authority vault) │
│ • Webhook secret generation (for Zastava/Git) │
│ • Test credential validity button │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 5: Schedule (Optional - for Docker/Git scheduled triggers) │
│ • Enable scheduled scans toggle │
│ • Cron expression builder or preset selector │
│ • Timezone picker │
│ • Rate limit (max scans per hour) │
│ • Next run preview │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 6: Review & Test Connection │
│ • Configuration summary (read-only) │
│ • Test Connection button with status indicator │
│ • Error details expansion if test fails │
│ • Create Source / Save Changes button │
│ • Webhook endpoint display (for Zastava/Git - copy to clipboard) │
└─────────────────────────────────────────────────────────────────────────────┘
9.3 Wizard Step Validation
| Step | Required Fields | Validation |
|---|---|---|
| 1 - Type | sourceType |
Must select one type |
| 2 - Basic Info | name |
Unique name, 3-100 chars |
| 3 - Config | Varies by type | Type-specific required fields |
| 4 - Credentials | authRef (if required) |
Valid credential for source type |
| 5 - Schedule | None (optional step) | Valid cron if enabled |
| 6 - Review | None | Connection test recommended |
9.4 Source List Page Components
┌─────────────────────────────────────────────────────────────────────────────┐
│ SBOM Sources [+ Add Source] │
├─────────────────────────────────────────────────────────────────────────────┤
│ Status Cards: │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Active │ │ Paused │ │ Error │ │ Pending │ │
│ │ 12 │ │ 3 │ │ 2 │ │ 1 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Filters: [Type ▼] [Status ▼] [Tags ▼] [Search: ________] │
├─────────────────────────────────────────────────────────────────────────────┤
│ □ │ Name │ Type │ Status │ Last Run │ Next Run │ Actions │
│ ──┼───────────────┼─────────┼──────────┼────────────┼──────────┼─────────│
│ □ │ DockerHub Prd │ Zastava │ ● Active │ 5 min ago │ - │ ⋮ │
│ □ │ Harbor Dev │ Zastava │ ● Active │ 12 min ago │ - │ ⋮ │
│ □ │ Nightly Scans │ Docker │ ● Active │ 2h ago │ 02:00 AM │ ⋮ │
│ □ │ CI Pipeline │ CLI │ ⏸ Paused │ 1 day ago │ - │ ⋮ │
│ □ │ Monorepo │ Git │ ⚠ Error │ Failed │ - │ ⋮ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Showing 1-5 of 18 [< Prev] [1] [2] [3] [4] [Next >] │
└─────────────────────────────────────────────────────────────────────────────┘
9.5 Row Actions Menu
| Action | Icon | Availability |
|---|---|---|
| View Details | 👁 | Always |
| Edit | ✏️ | Always |
| Trigger Scan | ▶ | Active sources |
| Test Connection | 🔌 | Always |
| Pause | ⏸ | Active sources |
| Resume | ▶ | Paused sources |
| Delete | 🗑 | Always (with confirmation) |
9.6 Source Detail Page Layout
┌─────────────────────────────────────────────────────────────────────────────┐
│ ← Back to Sources │
├─────────────────────────────────────────────────────────────────────────────┤
│ Docker Hub Production [Trigger] [Test] [Edit] [⋮] │
│ Type: Zastava │ Status: ● Active │ Created: Dec 15, 2025 │
├─────────────────────────────────────────────────────────────────────────────┤
│ [Overview] [Configuration] [Run History] [Metrics] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Configuration: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Registry URL: https://registry-1.docker.io │ │
│ │ Registry Type: Docker Hub │ │
│ │ Webhook Path: /api/v1/webhooks/zastava/src-abc123 │ │
│ │ Repository Filter: myorg/*, prod-* │ │
│ │ Tag Filter: v*, latest (excluding: *-dev, *-test) │ │
│ │ Analyzers: OS, Node.js, Python, Go │ │
│ │ Reachability: Enabled │ │
│ │ VEX Lookup: Enabled │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ Run History: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Run ID │ Trigger │ Status │ Started │ Duration │ Items │ │
│ │ run-456 │ Webhook │ ✓ Success │ 5 min ago │ 45s │ 3/3 │ │
│ │ run-455 │ Webhook │ ✓ Success │ 12 min ago │ 38s │ 1/1 │ │
│ │ run-454 │ Manual │ ✓ Success │ 1h ago │ 2m 15s │ 12/12 │ │
│ │ run-453 │ Webhook │ ⚠ Partial │ 2h ago │ 1m 30s │ 4/5 │ │
│ │ run-452 │ Schedule │ ✗ Failed │ 3h ago │ 12s │ 0/0 │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ [Load More] │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
10. Security Considerations
| Concern | Mitigation |
|---|---|
| Credential exposure | AuthRef pattern - never inline, always reference vault |
| Webhook forgery | HMAC signature verification for all webhooks |
| Unauthorized access | Scope-based authorization (sources:read, sources:write, sources:admin) |
| Secret logging | Audit logging excludes credential values |
| Webhook secret rotation | Rotate-on-demand API endpoint |
10. Configuration
Environment variables (prefix SBOM_SbomService__Sources__):
| Variable | Default | Description |
|---|---|---|
MaxSourcesPerTenant |
100 | Maximum sources per tenant |
DefaultMaxScansPerHour |
60 | Default rate limit per source |
RunHistoryRetentionDays |
90 | Run history retention period |
WebhookSignatureAlgorithm |
HMAC-SHA256 |
Webhook signature algorithm |
ConnectionTestTimeoutSeconds |
30 | Connection test timeout |