144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# Remediation Module Architecture
|
||
|
||
> **Status: Planned.** The Remediation marketplace is a planned feature for developer-facing fix templates, PR generation, and contributor trust scoring. Source code at `src/Remediation/` contains initial scaffolding. This architecture document is a design specification pending full implementation.
|
||
|
||
## 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`
|