# Remediation Module Architecture

Technical architecture for the Remediation module of the Stella Ops release control plane — a developer-facing marketplace for signed-PR fix templates that remediate known vulnerabilities. Audience: backend engineers working on the remediation API, persistence, and verification pipeline, plus reviewers tracking which parts of the design are live versus planned.

Status: Partially implemented. Persistence-backed CRUD-style APIs exist for templates, submissions, contributors, and marketplace sources (Postgres-only, tenant-scoped, auditable). What is real and what is still missing, verified against src/Remediation on 2026-07-12:

• Authorization is enforced (SPRINT W1h). The three policies are real scope policies over remediation:read / remediation:submit / remediation:manage — the old RequireAssertion(_ => true) placeholders are gone. The three scope values are now catalogued and seeded (SPRINT_20260712_002 / AUTH-2): they are StellaOpsScopes.RemediationRead / RemediationSubmit / RemediationManage, and S038_remediation_and_scanner_local_scopes.sql seeds the matching authority.permissions rows, so the fail-closed 403 lockout described here previously is closed — see Authorization Policies.
• A real proof validator exists (SPRINT W1h-2). ScannerRemediationProofValidator verifies the ReachGraph reachability-delta and the Attestor fix-chain DSSE envelope. A signature-valid Attestor envelope is accepted only when its payload is an in-toto Statement/v1 with the exact FixChain predicate type, the requested CVE, a fixed verdict, and reachability proof that a positive pre-patch path count fell to zero. It is wired only when both Remediation:ProofValidation:ReachGraphBaseUrl and :AttestorBaseUrl are configured, otherwise the host degrades to the fail-closed UnavailableRemediationProofValidator and logs a startup WARNING.
• Still not wired: the verification pipeline is not orchestrated — nothing populates the scan/reachability/DSSE digests, advances Status, or signs envelopes; RemediationVerifier only evaluates digests already present on a submission.
• No compose host. The module is not deployed in devops/compose, so the scope-catalog lockout above is latent rather than live.

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 or disabled per tenant.

Domain Model

FixTemplate (remediation.fix_templates)
|- TenantId (text, NOT NULL - tenant isolation key)
|- 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)
|- TenantId (text, NOT NULL - tenant isolation key)
|- FixTemplateId (nullable FK -> fix_templates.id)
|- PrUrl, RepositoryUrl, SourceBranch, TargetBranch
|- CveId (text, indexed)
|- Status (text, default 'opened'; free-text column, indexed)
|- PreScanDigest, PostScanDigest
|- ReachabilityDeltaDigest, FixChainDsseDigest
|- Verdict (text, nullable)
|- ContributorId
`- CreatedAt, MergedAt, VerifiedAt

Contributor (remediation.contributors)
|- TenantId (text, NOT NULL - tenant isolation key)
|- Username (unique PER TENANT - ux_contributors_tenant_username)
|- VerifiedFixes, TotalSubmissions, RejectedSubmissions
`- TrustScore (computed)

MarketplaceSource (remediation.marketplace_sources)
|- Key (TEXT, UNIQUE - stored as a `<tenant>::<key>` composite for tenant isolation)
|- Name, Url (nullable)
|- SourceType (community/partner/vendor)
|- Enabled, TrustScore
`- CreatedAt, LastSyncAt

Note on status/verdict columns: Status and Verdict are free-text TEXT columns in PostgreSQL, not DB-enforced enums. The values listed elsewhere in this doc reflect the strings the current code produces or consumes; the schema does not constrain them. The RemediationVerifier only emits fixed, not_fixed, or inconclusive — a partial verdict is not produced by the current verifier (see Verification Pipeline below).

Tenancy contract (claim-bound)

Tenant identity is the isolation key on every read and write, and it is resolved exclusively from the authenticated stellaops:tenant claim (via IStellaOpsTenantAccessor / the shared StellaOpsTenantResolver). It is never read from a query parameter, request body, or caller-supplied header.

Enforcement details:

• The repository interfaces take tenantId as a required first parameter, so a call site that forgets the isolation key fails to compile rather than reading across tenants.
• A blank tenant is rejected (ArgumentException), never silently defaulted to default — a silent default would reintroduce the cross-tenant read the column exists to prevent.
• Endpoint groups carry .RequireTenant(); a caller with no tenant claim (the compose bypass-network shape) is refused with 400 tenant_missing before any handler runs, even when its scopes are valid.

History (TEN-4, sprint 20260712_001): fix_templates, pr_submissions and contributors previously carried no tenant column and their repositories issued no tenant predicate, so any principal holding remediation:read could read every tenant’s fix templates, PR submissions (repository URLs, branch names, CVE ids) and contributor records. Migration 002_tenant_scoped_registry.sql adds tenant_id (backfilled to default) and scopes contributor-username uniqueness to the tenant. Proven by RemediationTenantIsolationTests (Postgres-backed) and RemediationTenancyEndpointTests (HTTP).

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 are under /api/v1/remediation/ and require tenant context (RequireTenant()). All routes are lowercased (LowercaseUrls = true). List endpoints accept limit and offset query parameters: limit defaults to 50, is clamped to the range [1, 200]; offset defaults to 0 and is clamped to >= 0. The Count field in list responses is the number of items on the returned page, not a total row count.

Templates

• GET /templates?cve=&purl=&limit=&offset= - List fix templates -> FixTemplateListResponse { Items, Count, Limit, Offset } of FixTemplateSummary(Id, CveId, Purl, VersionRange, Status, TrustScore, Description, CreatedAt). Requires remediation.read.
• GET /templates/{id:guid} - Get full FixTemplate (404 if absent). Requires remediation.read.
• POST /templates - Create template; body CreateFixTemplateRequest(CveId, Purl, VersionRange, PatchContent, Description?); returns 201 Created with the persisted FixTemplate. Requires remediation.submit. Emits audit action create_fix_template (entity fix_template).

Submissions

• GET /submissions?cve=&status=&limit=&offset= - List PR submissions -> PrSubmissionListResponse { Items, Count, Limit, Offset } of PrSubmissionSummary(Id, PrUrl, CveId, Status, Verdict, CreatedAt). Requires remediation.read.
• GET /submissions/{id:guid} - Get full PrSubmission (404 if absent). Requires remediation.read.
• POST /submissions - Submit PR; body CreatePrSubmissionRequest(PrUrl, RepositoryUrl, SourceBranch, TargetBranch, CveId, FixTemplateId?); returns 201 Created with the persisted PrSubmission. Requires remediation.submit. Emits audit action create_pr_submission (entity pr_submission).
• GET /submissions/{id:guid}/status - Returns { Id, Status, Verdict } only (404 if absent). Requires remediation.read.

Matching

• GET /match?cve=...&purl=...&version=... - Find applicable fix templates -> MatchResponse { Items, Count } of FixTemplateSummary. cve is required; a missing/blank cve returns 400 with body { error: <localized "remediation.match.cve_required"> }. Requires remediation.read.

Contributors

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

Implemented contributor API contract (2026-04-24):

• GET /api/v1/remediation/contributors lists persisted contributors from remediation.contributors with deterministic username ordering and standard limit/offset bounds.
• GET /api/v1/remediation/contributors/{username} resolves normalized usernames from PostgreSQL and returns 404 contributor_not_found only when no persisted contributor exists.
• Response trust score and trust tier are calculated from persisted verified/total/rejected submission counters.
• Contributor writes are currently repository-only; public contributor administration endpoints remain future scope.

Sources

• GET /sources - List marketplace sources -> MarketplaceSourceListResponse { Items, Count } of MarketplaceSourceSummary(Key, Name, Url, SourceType, Enabled, TrustScore, CreatedAt, LastSyncAt). Requires remediation.read.
• GET /sources/{key} - Source detail. Invalid keys return 400 (validation problem); a missing source returns 404 as RFC7807 ProblemDetails (type https://stellaops.dev/problems/remediation/source-not-found). Requires remediation.read.
• POST /sources - Create/update source (requires remediation.manage). Emits audit action upsert_marketplace_source (entity marketplace_source). Returns 200 OK with the upserted MarketplaceSourceSummary (not 201).

Implemented source API contract (2026-03-04):

• Request model for upsert (POST /sources): key, name, url, sourceType, enabled, trustScore, lastSyncAt (UpsertMarketplaceSourceRequest).
• Deterministic behavior:
  • key normalization uses lowercase invariant
  • list ordering is key-based ordinal ordering
  • upsert is idempotent by tenant + source key
• Validation:
  • key pattern: ^[a-z0-9][a-z0-9._-]{0,63}$
  • sourceType allowed values: community, partner, vendor
  • trustScore range: 0..1
  • url must be an absolute http/https URL when provided
• Tenant isolation:
  • all source endpoints require tenant context (RequireTenant)
  • repository operations are tenant-scoped for list/get/upsert behavior

Authorization Policies

Each endpoint declares a named authorization policy via RequireAuthorization("..."). The ASP.NET policy name is dot-form; the scope claim value it requires is colon-form:

Enforcement is real (SPRINT W1h). The earlier policy.RequireAssertion(_ => true) placeholders are gone. Program.cs:40 wires AddStellaOpsResourceServerAuthentication outside Testing (JWT bearer + bypass evaluator + scope handler), and Program.cs:57-59 registers the three policies with AddStellaOpsScopePolicy(<policy>, <scope>), which installs a real StellaOpsScopeRequirement. Endpoints enforce them (RemediationRegistryEndpoints.cs, RemediationSourceEndpoints.cs, RemediationMatchEndpoints.cs) in addition to RequireTenant().

✅ Scope-catalog lockout CLOSED (SPRINT_20260712_002 / AUTH-2, 2026-07-12). The three claims are now first-class catalog constants — StellaOpsScopes.RemediationRead / RemediationSubmit / RemediationManage — and Program.cs binds the policies to those constants rather than to magic strings.

This mattered more than it looked. StellaOpsScopes.All/KnownScopes are built by reflecting over the public string consts, and Authority calls options.RegisterScopes(…StellaOpsScopes.All) (StellaOps.Authority/Program.cs). An uncatalogued claim is therefore never registered with OpenIddict, so it could not be minted into a token by any path — not via the Console role editor, not via a config-defined role (AuthorityTenantRoleOptions.Validate throws on !IsKnown), not even via a hand-written authority.role_permissions row. Every Remediation endpoint would have returned 403 for every caller.

S038_remediation_and_scanner_local_scopes.sql seeds the matching authority.permissions rows (so the Console role editor offers them) and grants the trio to the admin role so the module is operable on an existing install. Proven by S038RemediationAndScannerScopeCatalogTests (a role assembled through the Console/RBAC path carries all three scopes) and StellaOpsScopesTests.Auth2_SingleScopePolicyClaims_AreRegistered.

Runtime Storage Contract (updated 2026-04-24)

Remediation runtime storage is now selected through Remediation:Storage:Driver (or Storage:Driver) with explicit startup validation:

• postgres (default):

  • Required settings: ConnectionStrings:Default or Remediation:Storage:Postgres:ConnectionString.
  • Optional schema override: Remediation:Storage:Postgres:SchemaName (defaults to remediation).
  • Behavior: repositories are wired with RemediationDataSource and Postgres-backed constructors.
  • Startup: embedded SQL migrations from StellaOps.Remediation.Persistence are applied automatically through AddStartupMigrations(...).
  • Startup: fails fast when required connection configuration is missing.

• inmemory:

  • Removed from runtime wiring. Storage:Driver=inmemory fails startup in every environment.
  • Deterministic automated tests use test-only repository implementations under src/Remediation/__Tests/** and override DI with WebApplicationFactory.

Postgres repository classes are Postgres-only. They require RemediationDataSource; parameterless constructors and silent process-local repository state are not supported in production assemblies.

Migration notes:

• Existing deployments must provide a Postgres connection string.
• Fresh databases converge at service startup from embedded migrations; external init scripts are bootstrap fallbacks only.
• Integration tests that do not need a database should keep Storage:Driver=postgres with test-host DI overrides, rather than enabling a runtime in-memory driver.

Service Integration Baseline (2026-03-05)

• Router integration enabled (serviceName: remediation) with endpoint refresh on startup.
• Local alias binding/logging enabled via remediation.stella-ops.local.
• CORS and tenant middleware are part of the default request pipeline before endpoint execution.

Verification Pipeline

Design / not orchestrated. Steps 1-6 below describe the intended end-to-end flow, but there is no orchestration code in the Remediation module that drives it. Nothing populates pre_scan_digest, post_scan_digest, reachability_delta_digest, or fix_chain_dsse_digest automatically, advances Status, or signs envelopes. IRemediationRegistry.UpdateSubmissionStatusAsync(...) exists but is not exposed by any endpoint. What is implemented is the verdict half: RemediationVerifier.VerifyAsync(submission) evaluates digests already present on a submission (step 7), and — when configured — ScannerRemediationProofValidator really does fetch and cryptographically verify the ReachGraph delta and the Attestor fix-chain DSSE envelope behind it (see Proof-validation contract). The pipeline that scans, merges, and stamps those digests is still future scope.

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 and post digests
6. Fix-chain DSSE envelope signed
7. Verdict determined by RemediationVerifier: fixed, not_fixed, or inconclusive. (The verifier never emits partial; that value appears only in older design notes.)

Proof-validation contract (updated 2026-04-28)

RemediationVerifier does not treat changed pre/post scan digests as proof that a vulnerability was fixed. A changed scan pair is only eligible for fixed after all of the following hold:

• PreScanDigest, PostScanDigest, ReachabilityDeltaDigest, and FixChainDsseDigest are well-formed sha256:<64 hex> values.
• The configured IRemediationProofValidator validates the reachability delta and fix-chain DSSE evidence.
• The validator returns a verified result for the submission and may include affected-path evidence.

Which validator is registered is config-driven (RegisterProofValidation, Program.cs:210-329):

• ScannerRemediationProofValidator (SPRINT W1h-2) — registered when both Remediation:ProofValidation:ReachGraphBaseUrl and Remediation:ProofValidation:AttestorBaseUrl are set. It fetches the reachability delta from the ReachGraph CAS and the fix-chain DSSE envelope from the Attestor, and verifies both with the shared IDsseEnvelopeVerifier against operator-supplied trust keys (Remediation:ProofValidation:TrustKeys:<keyId> = base64 SPKI). Signature verification is necessary but not sufficient: the Attestor payload must use application/vnd.in-toto+json, _type=https://in-toto.io/Statement/v1, predicateType=https://stella-ops.org/predicates/fix-chain/v1, a predicate.cveId matching the submission, predicate.verdict.status=fixed, and predicate.reachability showing prePathCount>0, postPathCount=0, and eliminated=true. Any mismatch returns the stable unavailable result. The Attestor client can carry a client-credentials bearer token (Remediation:ProofValidation:Authority:*, default scope attest:read).
• UnavailableRemediationProofValidator— the degraded fallback when either URL is absent. It returns inconclusive with diagnostic key remediation.proof_validation.unavailable, and ProofValidationDegradedWarningService emits a startup WARNING so the degradation is not silent. Fail-closed by construction: an unconfigured host can never mint a fixed verdict.

Missing or malformed proof material also returns inconclusive with stable diagnostic keys. The full set of diagnostic keys (RemediationProofDiagnostics) is:

• remediation.proof.scan_digest_missing
• remediation.proof.scan_digest_malformed
• remediation.proof.reachability_delta_digest_missing
• remediation.proof.reachability_delta_digest_malformed
• remediation.proof.fix_chain_dsse_digest_missing
• remediation.proof.fix_chain_dsse_digest_malformed
• remediation.proof_validation.unavailable

Evaluation order in RemediationVerifier.DetermineVerdictAsync: missing or malformed pre/post scan digests -> inconclusive; pre/post digests equal (case-insensitive) -> not_fixed (short-circuit, before reachability/DSSE checks); otherwise missing/malformed reachability-delta or fix-chain DSSE digest -> inconclusive; only when all four digests are well-formed sha256:<64 hex> is the candidate verdict fixed, at which point IRemediationProofValidator.ValidateAsync(...) runs and a non-validated result downgrades the verdict back to inconclusive.

Matching pre/post scan digests may still return not_fixed, because that is a negative outcome and does not claim remediation proof success.

Webhook Integration

The RemediationPrWebhookHandler (src/Signals/StellaOps.Signals/Services/RemediationPrWebhookHandler.cs) in the Signals module exposes two pure helpers:

• IsRemediationPr(title, labels) - detects remediation PRs by title prefix fix(CVE- (case-insensitive) or the label stella-ops/remediation.
• ExtractCveId(title) - extracts the CVE id via regex fix\((CVE-\d{4}-\d+)\).

Detection only. This handler does not create submissions or call back into the Remediation module — it only classifies a PR title/labels and pulls out a CVE id. There is no wiring from Signals to POST /api/v1/remediation/submissions. The RepositoryUrl/SourceBranch/TargetBranch example title convention fix(CVE-XXXX-NNNNN): description is the recognized format.

Audit Emission

Three state-changing endpoints emit audit events through StellaOps.Audit.Emission (.Audited(...)), under audit module remediation (AuditModules.Remediation):

Audit emission is wired in Program.cs via AddAuditEmission(builder.Configuration). Read (GET) and match endpoints are not audited.

Module Location

src/Remediation/
|- StellaOps.Remediation.Core/                  - Domain models, interfaces, services (verifier, trust scorer, proof validator)
|- StellaOps.Remediation.WebService/            - API endpoints, Program.cs, contract records
|- StellaOps.Remediation.Persistence/           - EF Core DbContext, Postgres repositories, embedded SQL migrations
|- __Tests/StellaOps.Remediation.Tests/         - Repository/domain unit tests (Postgres fixture-backed)
`- __Tests/StellaOps.Remediation.WebService.Tests/ - Endpoint, audit-emission, and startup-contract tests

Persistence is EF Core (RemediationDbContext) over Npgsql. Embedded migrations are applied at startup via AddStartupMigrations(schemaName, "Remediation", typeof(RemediationDataSource).Assembly), in filename order:

Repositories (PostgresFixTemplateRepository, PostgresPrSubmissionRepository, PostgresMarketplaceSourceRepository, PostgresContributorRepository) are all Postgres-only, require RemediationDataSource, and take the tenant as a required first parameter (see the tenancy contract above).

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

• Remediation PR contract (remediation-pr-v1)

Advisory Gap Status (2026-03-04 Batch)

Status:

• Advisory gap REM-001 is closed for marketplace sources.

Closed behaviors:

• GET /api/v1/remediation/sources returns persisted tenant-scoped sources with deterministic ordering.
• GET /api/v1/remediation/sources/{key} resolves persisted records (no unconditional stub source_not_found path).
• POST /api/v1/remediation/sources performs validated upsert and no longer returns 501.
• Marketplace source repository abstraction and implementation are wired through DI:
  • IMarketplaceSourceRepository
  • PostgresMarketplaceSourceRepository

Verification evidence:

• dotnet test src/Remediation/__Tests/StellaOps.Remediation.Tests/StellaOps.Remediation.Tests.csproj -m:1 -v minimal - 28 passed.
• dotnet test src/Remediation/__Tests/StellaOps.Remediation.WebService.Tests/StellaOps.Remediation.WebService.Tests.csproj -m:1 -v minimal - 4 passed.

Tracking sprint:

• docs/implplan/SPRINT_20260304_308_Remediation_marketplace_sources_api_completion.md