Gaps fill up, fixes, ui restructuring
This commit is contained in:
master
137
docs/modules/remediation/architecture.md
Normal file
137
docs/modules/remediation/architecture.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user