# Scoring Profiles

**Sprint:** SPRINT_3407_0001_0001  
**Task:** PROF-3407-014  
**Last Updated:** 2025-12-16

## Overview

StellaOps supports multiple scoring profiles to accommodate different customer needs, from simple transparent scoring to advanced entropy-based analysis. Scoring profiles determine how vulnerability findings are evaluated and scored.

## Available Profiles

### Simple Profile

The Simple profile uses a transparent 4-factor basis-points weighted formula:

```
riskScore = (wB × B + wR × R + wE × E + wP × P) / 10000
```

Where:
- **B** (Base Severity): CVSS score × 10 (0-100 range)
- **R** (Reachability): Hop-based score with gate multipliers
- **E** (Evidence): Evidence points × freshness multiplier
- **P** (Provenance): Level-based score (unsigned to reproducible)
- **wB, wR, wE, wP**: Weight basis points (must sum to 10000)

**Default weights:**
| Factor | Weight (bps) | Percentage |
|--------|-------------|------------|
| Base Severity | 1000 | 10% |
| Reachability | 4500 | 45% |
| Evidence | 3000 | 30% |
| Provenance | 1500 | 15% |

**Use cases:**
- Organizations requiring audit-friendly, explainable scoring
- Compliance scenarios requiring transparent formulas
- Initial deployments before advanced analysis is available

### Advanced Profile (Default)

The Advanced profile extends Simple with:

- **CVSS version adjustment**: Scores weighted by CVSS version (4.0 > 3.1 > 3.0 > 2.0)
- **KEV boost**: +20 points for Known Exploited Vulnerabilities
- **Uncertainty penalty**: Deductions for missing data (reachability, evidence, provenance, CVSS version)
- **Semantic category multipliers**: Entry points and API endpoints scored higher than internal services
- **Multi-evidence overlap bonus**: 10% bonus per additional evidence type
- **Advanced score passthrough**: Uses pre-computed advanced scores when available

**Use cases:**
- Production deployments with full telemetry
- Organizations with mature security programs
- Scenarios requiring nuanced risk differentiation

### Custom Profile (Enterprise)

The Custom profile allows fully user-defined scoring via Rego policies. Requires:
- Valid Rego policy path
- Policy Engine license with Custom Scoring feature

## Configuration

### Score Policy YAML

Add the `scoringProfile` field to your score policy:

```yaml
policyVersion: score.v1
scoringProfile: simple  # Options: simple, advanced, custom

weightsBps:
  baseSeverity: 1000
  reachability: 4500
  evidence: 3000
  provenance: 1500

# ... rest of policy configuration
```

### Tenant Override

Tenants can override the default profile via the Scoring Profile Service:

```csharp
// Set profile for a tenant
scoringProfileService.SetProfileForTenant("tenant-id", new ScoringProfileConfig
{
    Profile = ScoringProfile.Simple
});

// Remove override (revert to default)
scoringProfileService.RemoveProfileForTenant("tenant-id");
```

## API Integration

### Scoring with Default Profile

```csharp
var result = await profileAwareScoringService.ScoreAsync(input);
// Uses tenant's configured profile
```

### Scoring with Explicit Profile

```csharp
var result = await profileAwareScoringService.ScoreWithProfileAsync(
    input,
    ScoringProfile.Simple);
```

### Profile Comparison

```csharp
var comparison = await profileAwareScoringService.CompareProfilesAsync(input);
// Returns scores from all profiles for analysis
```

## Audit Trail

All scoring results include profile identification:

```json
{
  "finding_id": "CVE-2024-12345-pkg-1.0.0",
  "scoring_profile": "simple",
  "profile_version": "simple-v1",
  "raw_score": 65,
  "final_score": 65,
  "severity": "medium",
  "signal_values": {
    "baseSeverity": 75,
    "reachability": 70,
    "evidence": 45,
    "provenance": 60
  },
  "signal_contributions": {
    "baseSeverity": 7.5,
    "reachability": 31.5,
    "evidence": 13.5,
    "provenance": 9.0
  },
  "explain": [
    { "factor": "baseSeverity", "value": 75, "reason": "CVSS 7.5 (v3.1) with version adjustment" },
    { "factor": "evidence", "value": 45, "reason": "45 evidence points, 14 days old (90% freshness)" },
    { "factor": "provenance", "value": 60, "reason": "Provenance level: SignedWithSbom" },
    { "factor": "reachability", "value": 70, "reason": "2 hops from call graph" }
  ]
}
```

## Migration Guide

### From Legacy Scoring

1. **Audit current scores**: Export current scores for baseline comparison
2. **Enable Simple profile**: Start with Simple for predictable behavior
3. **Compare profiles**: Use `CompareProfilesAsync` to understand differences
4. **Gradual rollout**: Move to Advanced when confidence is established

### Profile Switching Best Practices

- **Test in staging first**: Validate score distribution before production
- **Monitor severity distribution**: Watch for unexpected shifts
- **Document changes**: Record profile changes in policy lifecycle
- **Use replay**: Re-score historical findings to validate behavior

## Determinism

Both Simple and Advanced profiles are fully deterministic:

- **Explicit time**: All calculations use `AsOf` timestamp
- **Integer math**: Basis-point arithmetic avoids floating-point drift
- **Stable ordering**: Explanations sorted alphabetically by factor
- **Input digests**: Track input hashes for replay validation

## Performance

| Profile | Typical Latency | Memory |
|---------|----------------|--------|
| Simple | < 1ms | Minimal |
| Advanced | < 5ms | Minimal |
| Custom | Varies | Depends on Rego complexity |

## Related Documentation

- [Score Policy YAML](./score-policy-yaml.md)
- [Signals Weighting](./signals-weighting.md)
- [VEX Trust Model](./vex-trust-model.md)
- [Policy Overview](./overview.md)