up
This commit is contained in:
StellaOps Bot
@@ -29,6 +29,152 @@
|
||||
- Identify UI/reporting deltas for transparency
|
||||
- Note in sprint Decisions & Risks for CVSS receipts
|
||||
|
||||
### 1.4 CVSS v4.0 MacroVector Scoring System
|
||||
|
||||
CVSS v4.0 uses a **MacroVector-based scoring system** instead of the direct formula computation used in v2/v3. The MacroVector is a 6-digit string derived from the base metrics, which maps to a precomputed score table with 486 possible combinations.
|
||||
|
||||
**MacroVector Structure**:
|
||||
```
|
||||
MacroVector = EQ1 + EQ2 + EQ3 + EQ4 + EQ5 + EQ6
|
||||
Example: "001100" -> Base Score = 8.2
|
||||
```
|
||||
|
||||
**Equivalence Classes (EQ1-EQ6)**:
|
||||
|
||||
| EQ | Metrics Used | Values | Meaning |
|
||||
|----|--------------|--------|---------|
|
||||
| EQ1 | Attack Vector + Privileges Required | 0-2 | Network reachability and auth barrier |
|
||||
| EQ2 | Attack Complexity + User Interaction | 0-1 | Attack prerequisites |
|
||||
| EQ3 | Vulnerable System CIA | 0-2 | Impact on vulnerable system |
|
||||
| EQ4 | Subsequent System CIA | 0-2 | Impact on downstream systems |
|
||||
| EQ5 | Attack Requirements | 0-1 | Preconditions needed |
|
||||
| EQ6 | Combined Impact Pattern | 0-2 | Multi-impact severity |
|
||||
|
||||
**EQ1 (Attack Vector + Privileges Required)**:
|
||||
- AV=Network + PR=None -> 0 (worst case: remote, no auth)
|
||||
- AV=Network + PR=Low/High -> 1
|
||||
- AV=Adjacent + PR=None -> 1
|
||||
- AV=Adjacent + PR=Low/High -> 2
|
||||
- AV=Local or Physical -> 2 (requires local access)
|
||||
|
||||
**EQ2 (Attack Complexity + User Interaction)**:
|
||||
- AC=Low + UI=None -> 0 (easiest to exploit)
|
||||
- AC=Low + UI=Passive/Active -> 1
|
||||
- AC=High + any UI -> 1 (harder to exploit)
|
||||
|
||||
**EQ3 (Vulnerable System CIA)**:
|
||||
- Any High in VC/VI/VA -> 0 (severe impact)
|
||||
- Any Low in VC/VI/VA -> 1 (moderate impact)
|
||||
- All None -> 2 (no impact)
|
||||
|
||||
**EQ4 (Subsequent System CIA)**:
|
||||
- Any High in SC/SI/SA -> 0 (cascading impact)
|
||||
- Any Low in SC/SI/SA -> 1
|
||||
- All None -> 2
|
||||
|
||||
**EQ5 (Attack Requirements)**:
|
||||
- AT=None -> 0 (no preconditions)
|
||||
- AT=Present -> 1 (needs specific setup)
|
||||
|
||||
**EQ6 (Combined Impact Pattern)**:
|
||||
- >=2 High impacts (vuln OR sub) -> 0 (severe multi-impact)
|
||||
- 1 High impact -> 1
|
||||
- 0 High impacts -> 2
|
||||
|
||||
**Scoring Algorithm**:
|
||||
1. Parse base metrics from vector string
|
||||
2. Compute EQ1-EQ6 from metrics
|
||||
3. Build MacroVector string: "{EQ1}{EQ2}{EQ3}{EQ4}{EQ5}{EQ6}"
|
||||
4. Lookup base score from MacroVectorLookup table
|
||||
5. Round up to nearest 0.1 (per FIRST spec)
|
||||
|
||||
**Implementation**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV4Engine.cs:262-359`
|
||||
|
||||
### 1.5 Threat Metrics and Exploit Maturity
|
||||
|
||||
CVSS v4.0 introduces **Threat Metrics** to adjust scores based on real-world exploit intelligence. The primary metric is **Exploit Maturity (E)**, which applies a multiplier to the base score.
|
||||
|
||||
**Exploit Maturity Values**:
|
||||
|
||||
| Value | Code | Multiplier | Description |
|
||||
|-------|------|------------|-------------|
|
||||
| Attacked | A | **1.00** | Active exploitation in the wild |
|
||||
| Proof of Concept | P | **0.94** | Public PoC exists but no active exploitation |
|
||||
| Unreported | U | **0.91** | No known exploit activity |
|
||||
| Not Defined | X | 1.00 | Default (assume worst case) |
|
||||
|
||||
**Score Computation (CVSS-BT)**:
|
||||
```
|
||||
Threat Score = Base Score x Threat Multiplier
|
||||
|
||||
Example:
|
||||
Base Score = 9.1
|
||||
Exploit Maturity = Unreported (U)
|
||||
Threat Score = 9.1 x 0.91 = 8.3 (rounded up)
|
||||
```
|
||||
|
||||
**Threat Metrics in Vector String**:
|
||||
```
|
||||
CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/E:A
|
||||
^^^
|
||||
Exploit Maturity
|
||||
```
|
||||
|
||||
**Why Threat Metrics Matter**:
|
||||
- Reduces noise: An unreported vulnerability scores ~9% lower
|
||||
- Prioritizes real threats: Actively exploited vulns maintain full score
|
||||
- Evidence-based: Integrates with KEV, EPSS, and internal threat feeds
|
||||
|
||||
**Implementation**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV4Engine.cs:365-375`
|
||||
|
||||
### 1.6 Environmental Score Modifiers
|
||||
|
||||
**Security Requirements Multipliers**:
|
||||
|
||||
| Requirement | Low | Medium | High |
|
||||
|-------------|-----|--------|------|
|
||||
| Confidentiality (CR) | 0.5 | 1.0 | 1.5 |
|
||||
| Integrity (IR) | 0.5 | 1.0 | 1.5 |
|
||||
| Availability (AR) | 0.5 | 1.0 | 1.5 |
|
||||
|
||||
**Modified Base Metrics** (can override any base metric):
|
||||
- MAV (Modified Attack Vector)
|
||||
- MAC (Modified Attack Complexity)
|
||||
- MAT (Modified Attack Requirements)
|
||||
- MPR (Modified Privileges Required)
|
||||
- MUI (Modified User Interaction)
|
||||
- MVC/MVI/MVA (Modified Vulnerable System CIA)
|
||||
- MSC/MSI/MSA (Modified Subsequent System CIA)
|
||||
|
||||
**Score Computation (CVSS-BE)**:
|
||||
1. Apply modified metrics to base metrics (if defined)
|
||||
2. Compute modified MacroVector
|
||||
3. Lookup modified base score
|
||||
4. Multiply by average of Security Requirements
|
||||
5. Clamp to [0, 10]
|
||||
|
||||
```
|
||||
Environmental Score = Modified Base x (CR + IR + AR) / 3
|
||||
```
|
||||
|
||||
### 1.7 Supplemental Metrics (Non-Scoring)
|
||||
|
||||
CVSS v4.0 introduces supplemental metrics that provide context but **do not affect the score**:
|
||||
|
||||
| Metric | Values | Purpose |
|
||||
|--------|--------|---------|
|
||||
| Safety (S) | Negligible/Present | Safety impact (ICS/OT systems) |
|
||||
| Automatable (AU) | No/Yes | Can attack be automated? |
|
||||
| Recovery (R) | Automatic/User/Irrecoverable | System recovery difficulty |
|
||||
| Value Density (V) | Diffuse/Concentrated | Target value concentration |
|
||||
| Response Effort (RE) | Low/Moderate/High | Effort to respond |
|
||||
| Provider Urgency (U) | Clear/Green/Amber/Red | Vendor urgency rating |
|
||||
|
||||
**Use Cases**:
|
||||
- **Safety**: Critical for ICS/SCADA vulnerability prioritization
|
||||
- **Automatable**: Indicates wormable vulnerabilities
|
||||
- **Provider Urgency**: Vendor-supplied priority signal
|
||||
|
||||
## 2. SCANNER DISCREPANCIES ANALYSIS
|
||||
|
||||
### 2.1 Trivy vs Grype Comparative Study (927 images)
|
||||
@@ -74,6 +220,55 @@
|
||||
- **Proof coverage**: % of dependencies with valid SBOM/VEX proofs
|
||||
- **Differential-closure**: Impact of database updates or policy changes on prior scan results
|
||||
|
||||
### 2.4 Deterministic Receipt System
|
||||
|
||||
Every CVSS scoring decision in StellaOps is captured in a **deterministic receipt** that enables audit-grade reproducibility.
|
||||
|
||||
**Receipt Schema**:
|
||||
```json
|
||||
{
|
||||
"receiptId": "uuid",
|
||||
"inputHash": "sha256:...",
|
||||
"baseMetrics": { ... },
|
||||
"threatMetrics": { ... },
|
||||
"environmentalMetrics": { ... },
|
||||
"supplementalMetrics": { ... },
|
||||
"scores": {
|
||||
"baseScore": 9.1,
|
||||
"threatScore": 8.3,
|
||||
"environmentalScore": null,
|
||||
"fullScore": null,
|
||||
"effectiveScore": 8.3,
|
||||
"effectiveScoreType": "threat"
|
||||
},
|
||||
"policyRef": "policy/cvss-v4-default@v1.2.0",
|
||||
"policyDigest": "sha256:...",
|
||||
"evidence": [ ... ],
|
||||
"attestationRefs": [ ... ],
|
||||
"createdAt": "2025-12-14T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**InputHash Computation**:
|
||||
```
|
||||
inputHash = SHA256(canonicalize({
|
||||
baseMetrics,
|
||||
threatMetrics,
|
||||
environmentalMetrics,
|
||||
supplementalMetrics,
|
||||
policyRef,
|
||||
policyDigest
|
||||
}))
|
||||
```
|
||||
|
||||
**Determinism Guarantees**:
|
||||
- Same inputs -> same `inputHash` -> same scores
|
||||
- Receipts are immutable once created
|
||||
- Amendments create new receipts with `supersedes` reference
|
||||
- Optional DSSE signatures for cryptographic binding
|
||||
|
||||
**Implementation**: `src/Policy/StellaOps.Policy.Scoring/Receipts/ReceiptBuilder.cs`
|
||||
|
||||
## 3. RUNTIME REACHABILITY APPROACHES
|
||||
|
||||
### 3.1 Runtime-Aware Vulnerability Prioritization
|
||||
@@ -229,6 +424,38 @@
|
||||
- Bundled feeds, keys, Rekor snapshots
|
||||
- Verifiable without internet access
|
||||
|
||||
### 6.6 CVSS + KEV Risk Signal Combination
|
||||
|
||||
StellaOps combines CVSS scores with KEV (Known Exploited Vulnerabilities) data using a deterministic formula:
|
||||
|
||||
**Risk Formula**:
|
||||
```
|
||||
risk_score = clamp01((cvss / 10) + kevBonus)
|
||||
|
||||
where:
|
||||
kevBonus = 0.2 if vulnerability is in CISA KEV catalog
|
||||
kevBonus = 0.0 otherwise
|
||||
```
|
||||
|
||||
**Example Calculations**:
|
||||
|
||||
| CVSS Score | KEV Flag | Risk Score |
|
||||
|------------|----------|------------|
|
||||
| 9.0 | No | 0.90 |
|
||||
| 9.0 | Yes | 1.00 (clamped) |
|
||||
| 7.5 | No | 0.75 |
|
||||
| 7.5 | Yes | 0.95 |
|
||||
| 5.0 | No | 0.50 |
|
||||
| 5.0 | Yes | 0.70 |
|
||||
|
||||
**Rationale**:
|
||||
- KEV inclusion indicates active exploitation
|
||||
- 20% bonus prioritizes known-exploited over theoretical risks
|
||||
- Clamping prevents scores > 1.0
|
||||
- Deterministic formula enables reproducible prioritization
|
||||
|
||||
**Implementation**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/CvssKevProvider.cs`
|
||||
|
||||
## 7. COMPETITIVE POSITIONING
|
||||
|
||||
### 7.1 Market Segments
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
- 30-Nov-2025 - Standup Sprint Kickstarters
|
||||
|
||||
**Last Updated**: 2025-12-14
|
||||
**Revision**: 1.1 (Corrected to match actual implementation)
|
||||
|
||||
---
|
||||
|
||||
@@ -25,7 +26,7 @@
|
||||
- **SOLID First**: Interface and dependency inversion required
|
||||
- **100-line File Rule**: Files >100 lines must be split/refactored
|
||||
- **Contracts vs Runtime**: Public DTOs/interfaces in `*.Contracts` projects
|
||||
- **Single Composition Root**: DI wiring in `StellaOps.Web/Program.cs` and plugin `IoCConfigurator`
|
||||
- **Single Composition Root**: DI wiring in `StellaOps.Web/Program.cs` and plugin `IDependencyInjectionRoutine`
|
||||
- **No Service Locator**: Constructor injection only
|
||||
- **Fail-fast Startup**: Validate configuration before web host starts
|
||||
- **Hot-load Compatibility**: Avoid static singletons that survive plugin unload
|
||||
@@ -53,8 +54,8 @@
|
||||
- **Namespaces**: File-scoped, `StellaOps.*`
|
||||
- **Classes/records**: PascalCase
|
||||
- **Interfaces**: `I` prefix (`IScannerRunner`)
|
||||
- **Private fields**: `camelCase` (no leading `_`)
|
||||
- **Constants**: `SCREAMING_SNAKE_CASE`
|
||||
- **Private fields**: `_camelCase` (with leading underscore, standard C# convention)
|
||||
- **Constants**: `PascalCase` (standard C# convention, e.g., `MaxRetries`)
|
||||
- **Async methods**: End with `Async`
|
||||
|
||||
### 3.2 Usings
|
||||
@@ -76,7 +77,7 @@
|
||||
### 5.1 Composition Root
|
||||
|
||||
- **One composition root** per process
|
||||
- Plugins contribute via `[ServiceBinding]` or `IoCConfigurator : IDependencyInjectionRoutine`
|
||||
- Plugins contribute via `[ServiceBinding]` attribute or `IDependencyInjectionRoutine` implementations
|
||||
- Default lifetime: **scoped**
|
||||
- Singletons only for stateless, thread-safe helpers
|
||||
- Never use service locator or manually build nested service providers
|
||||
@@ -94,12 +95,13 @@ public class MyService : IMyContract
|
||||
### 5.3 Advanced DI Configuration
|
||||
|
||||
```csharp
|
||||
public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
public class MyPluginDependencyInjectionRoutine : IDependencyInjectionRoutine
|
||||
{
|
||||
public void Configure(IServiceCollection services, IConfiguration config)
|
||||
public IServiceCollection Register(IServiceCollection services, IConfiguration configuration)
|
||||
{
|
||||
services.AddScoped<IMyContract, MyService>();
|
||||
services.Configure<MyOptions>(config.GetSection("MyPlugin"));
|
||||
services.Configure<MyOptions>(configuration.GetSection("MyPlugin"));
|
||||
return services;
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -112,12 +114,12 @@ public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
|
||||
## 7. TEST LAYERS
|
||||
|
||||
- **Unit**: xUnit
|
||||
- **Property-based**: FsCheck
|
||||
- **Integration**: API with Testcontainers, DB/merge with Mongo + Redis
|
||||
- **Contracts**: gRPC breakage checks with Buf
|
||||
- **Frontend**: Jest (unit), Playwright (e2e), Lighthouse (performance/a11y)
|
||||
- **Non-functional**: k6 (load), Docker (chaos), dependency/license scanning, SBOM reproducibility
|
||||
- **Unit**: xUnit with FluentAssertions
|
||||
- **Property-based**: FsCheck (for fuzz testing in Attestor module)
|
||||
- **Integration**: API with Testcontainers (PostgreSQL)
|
||||
- **Contracts**: OpenAPI validation with Spectral
|
||||
- **Frontend**: Karma/Jasmine (unit), Playwright (e2e), Lighthouse CI (performance/a11y)
|
||||
- **Non-functional**: Dependency/license scanning, SBOM reproducibility, Axe accessibility audits
|
||||
|
||||
## 8. QUALITY GATES
|
||||
|
||||
@@ -131,21 +133,35 @@ public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
### 9.1 Plugin Templates
|
||||
|
||||
```bash
|
||||
dotnet new stellaops-plugin-schedule -n MyPlugin.Schedule
|
||||
# Install templates
|
||||
dotnet new install ./templates
|
||||
|
||||
# Create a connector plugin
|
||||
dotnet new stellaops-plugin-connector -n MyCompany.AcmeConnector
|
||||
|
||||
# Create a scheduled job plugin
|
||||
dotnet new stellaops-plugin-scheduler -n MyCompany.CleanupJob
|
||||
```
|
||||
|
||||
### 9.2 Plugin Publishing
|
||||
|
||||
- Publish signed artifacts to `src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/`
|
||||
- Backend verifies Cosign signature
|
||||
- Enforces `[StellaPluginVersion]` compatibility
|
||||
- Publish signed artifacts to `<Module>.PluginBinaries/<MyPlugin>/`
|
||||
- Backend verifies Cosign signature when `EnforceSignatureVerification` is enabled
|
||||
- Enforces `[StellaPluginVersion]` compatibility when `HostVersion` is configured
|
||||
- Loads plugins in isolated `AssemblyLoadContext`s
|
||||
|
||||
### 9.3 Plugin Signing
|
||||
|
||||
```bash
|
||||
dotnet publish -c Release -p:PublishSingleFile=true -o out
|
||||
cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
|
||||
dotnet publish -c Release -o out
|
||||
cosign sign --key $COSIGN_KEY out/StellaOps.Plugin.MyConnector.dll
|
||||
```
|
||||
|
||||
### 9.4 Plugin Version Attribute
|
||||
|
||||
```csharp
|
||||
// In AssemblyInfo.cs or any file
|
||||
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "1.0.0")]
|
||||
```
|
||||
|
||||
## 10. POLICY DSL (stella-dsl@1)
|
||||
@@ -240,13 +256,17 @@ cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
|
||||
- Merge strategies named and versioned
|
||||
- Artifacts record which lattice algorithm used
|
||||
|
||||
### 14.5 Sbomer Module
|
||||
### 14.5 SbomService Module
|
||||
|
||||
> Note: This module is implemented as `src/SbomService/` in the codebase.
|
||||
|
||||
- Emit SPDX 3.0.1 and CycloneDX 1.6 with stable ordering and deterministic IDs
|
||||
- Persist raw bytes + canonical form; hash canonical bytes for digest binding
|
||||
- Produce DSSE attestations for SBOM linkage and generation provenance
|
||||
|
||||
### 14.6 Feedser Module
|
||||
### 14.6 Concelier Feed Handling
|
||||
|
||||
> Note: Feed handling is implemented within the Concelier module via connectors in `src/Concelier/__Libraries/`.
|
||||
|
||||
- Treat every feed import as a versioned snapshot (URI + time + content hashes)
|
||||
- Support deterministic export/import for offline bundles
|
||||
@@ -308,9 +328,10 @@ dotnet run --project src/Scanner/StellaOps.Scanner.WebService
|
||||
### 16.2 Log Correlation
|
||||
|
||||
```csharp
|
||||
// Note: Private fields use _camelCase convention
|
||||
using var activity = Activity.Current;
|
||||
activity?.SetTag("scan.id", scanId);
|
||||
_logger.LogInformation("Processing scan {ScanId}", scanId);
|
||||
activity?.SetTag("scan.id", _scanId);
|
||||
_logger.LogInformation("Processing scan {ScanId}", _scanId);
|
||||
```
|
||||
|
||||
### 16.3 OpenTelemetry
|
||||
@@ -442,5 +463,12 @@ dotnet ef database update -p src/Module -s src/WebService
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Document Version**: 1.1
|
||||
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17
|
||||
|
||||
## Revision History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.1 | 2025-12-14 | Corrected naming conventions (`_camelCase` for fields, `PascalCase` for constants), updated DI interface name to `IDependencyInjectionRoutine`, corrected test frameworks (PostgreSQL not Mongo/Redis, Karma/Jasmine not Jest), added plugin templates and version attribute documentation, clarified module names (SbomService, Concelier feed handling) |
|
||||
| 1.0 | 2025-12-14 | Initial consolidated reference |
|
||||
|
||||
Reference in New Issue
Block a user