git.stella-ops.org/docs/modules/remediation/architecture.md

Remediation Module Architecture

Overview

The Remediation module provides a developer-facing signed-PR remediation marketplace for the Stella Ops platform. It enables developers to discover, apply, and verify community-contributed or vendor-supplied fix templates for known vulnerabilities (CVEs).

Key Concepts

Fix Templates

Structured remediation patches tied to specific CVE + PURL combinations. Templates include unified diff content, version range applicability, and trust scores from contributor history.

PR Submissions

Tracks the lifecycle of a remediation pull request from submission through scanning, merging, and post-merge verification. Each submission produces attestation evidence including reachability deltas and fix-chain DSSE envelopes.

Contributors

Community members or vendors who submit fix templates. Each contributor has a trust score computed from their verification history (verified fixes, rejections).

Marketplace Sources

Curated collections of fix templates from community, partner, or vendor origins. Sources are rated independently and can be enabled/disabled per tenant.

Domain Model

FixTemplate (remediation.fix_templates)
├── CveId (text, indexed)
├── Purl (text, indexed — pkg:type/name)
├── VersionRange (semver range)
├── PatchContent (unified diff)
├── Status (pending/verified/rejected)
├── TrustScore (0.0–1.0)
├── DsseDigest (nullable — signed envelope hash)
└── ContributorId / SourceId (foreign keys)

PrSubmission (remediation.pr_submissions)
├── FixTemplateId (nullable FK)
├── PrUrl, RepositoryUrl, SourceBranch, TargetBranch
├── CveId (text, indexed)
├── Status (opened/scanning/merged/verified/failed/inconclusive)
├── PreScanDigest, PostScanDigest
├── ReachabilityDeltaDigest, FixChainDsseDigest
├── Verdict (fixed/partial/not_fixed/inconclusive)
└── ContributorId

Contributor (remediation.contributors)
├── Username (unique)
├── VerifiedFixes, TotalSubmissions, RejectedSubmissions
└── TrustScore (computed)

MarketplaceSource (remediation.marketplace_sources)
├── Key (unique)
├── SourceType (community/partner/vendor)
├── Enabled, TrustScore
└── LastSyncAt

Trust Scoring

Contributor trust score formula:

score = clamp((verified * 1.0 - rejected * 0.5) / max(total, 1), 0, 1)

Trust tiers:

• trusted (> 0.8): Verified track record
• established (> 0.5): Growing history
• new (> 0.2): Recently joined
• untrusted (<= 0.2): Insufficient or negative history

API Surface

All endpoints under /api/v1/remediation/.

Templates

• GET /templates — List fix templates (filter by CVE, PURL)
• GET /templates/{id} — Get template detail
• POST /templates — Create template (requires remediation.submit)

Submissions

• GET /submissions — List PR submissions
• GET /submissions/{id} — Get submission with attestation chain
• POST /submissions — Submit PR for verification
• GET /submissions/{id}/status — Pipeline status

Matching

• GET /match?cve=...&purl=...&version=... — Find applicable fix templates

Contributors

• GET /contributors — List contributors
• GET /contributors/{username} — Profile with trust score

Sources

• GET /sources — List marketplace sources
• GET /sources/{key} — Source detail
• POST /sources — Create/update source (requires remediation.manage)

Authorization Policies

Policy	Description
remediation.read	Read templates, submissions, contributors, sources
remediation.submit	Create templates and submit PRs
remediation.manage	Manage marketplace sources, verify/reject templates

Verification Pipeline

1. PR submitted (status: opened)
2. Pre-merge scan captures baseline SBOM digest
3. PR merged (status: merged)
4. Post-merge scan captures updated SBOM digest
5. Reachability delta computed between pre/post digests
6. Fix-chain DSSE envelope signed
7. Verdict determined: fixed, partial, not_fixed, or inconclusive

Webhook Integration

The RemediationPrWebhookHandler in the Signals module detects remediation PRs by:

• Title convention: fix(CVE-XXXX-NNNNN): description
• Label: stella-ops/remediation

Module Location

src/Remediation/
├── StellaOps.Remediation.Core/         — Domain models, interfaces, services
├── StellaOps.Remediation.WebService/   — API endpoints, Program.cs
├── StellaOps.Remediation.Persistence/  — SQL migrations, repositories
└── __Tests/StellaOps.Remediation.Tests/ — Unit tests

Related Sprints

• SPRINT_20260220_010: Registry and persistence
• SPRINT_20260220_011: Signals webhook handler
• SPRINT_20260220_012: Verification pipeline
• SPRINT_20260220_013: Matching, sources, policy
• SPRINT_20260220_014: UI components
• SPRINT_20260220_015: Documentation

Related Contracts

• docs/contracts/remediation-pr-v1.md