207 lines
5.2 KiB
Markdown
207 lines
5.2 KiB
Markdown
# Gate Detection for Reachability Scoring
|
||
|
||
> **Sprint:** SPRINT_3405_0001_0001
|
||
> **Module:** Scanner Reachability / Signals
|
||
|
||
## Overview
|
||
|
||
Gate detection identifies protective controls in code paths that reduce the likelihood of vulnerability exploitation. When a vulnerable function is protected by authentication, feature flags, admin-only checks, or configuration gates, the reachability score is reduced proportionally.
|
||
|
||
## Gate Types
|
||
|
||
| Gate Type | Multiplier | Description |
|
||
|-----------|------------|-------------|
|
||
| `AuthRequired` | 30% | Code path requires authentication |
|
||
| `FeatureFlag` | 20% | Code path behind a feature flag |
|
||
| `AdminOnly` | 15% | Code path requires admin/elevated role |
|
||
| `NonDefaultConfig` | 50% | Code path requires non-default configuration |
|
||
|
||
### Multiplier Stacking
|
||
|
||
Multiple gate types stack multiplicatively:
|
||
|
||
```
|
||
Auth (30%) × Feature Flag (20%) = 6%
|
||
Auth (30%) × Admin (15%) = 4.5%
|
||
All four gates = ~0.45% (floored to 5%)
|
||
```
|
||
|
||
A minimum floor of **5%** prevents scores from reaching zero.
|
||
|
||
## Detection Methods
|
||
|
||
### AuthGateDetector
|
||
|
||
Detects authentication requirements:
|
||
|
||
**C# Patterns:**
|
||
- `[Authorize]` attribute
|
||
- `User.Identity.IsAuthenticated` checks
|
||
- `HttpContext.User` access
|
||
- JWT/Bearer token validation
|
||
|
||
**Java Patterns:**
|
||
- `@PreAuthorize`, `@Secured` annotations
|
||
- `SecurityContextHolder.getContext()`
|
||
- Spring Security filter chains
|
||
|
||
**Go Patterns:**
|
||
- Middleware patterns (`authMiddleware`, `RequireAuth`)
|
||
- Context-based auth checks
|
||
|
||
**JavaScript/TypeScript Patterns:**
|
||
- Express.js `passport` middleware
|
||
- JWT verification middleware
|
||
- Session checks
|
||
|
||
### FeatureFlagDetector
|
||
|
||
Detects feature flag guards:
|
||
|
||
**Patterns:**
|
||
- LaunchDarkly: `ldClient.variation()`, `ld.boolVariation()`
|
||
- Split.io: `splitClient.getTreatment()`
|
||
- Unleash: `unleash.isEnabled()`
|
||
- Custom: `featureFlags.isEnabled()`, `isFeatureEnabled()`
|
||
|
||
### AdminOnlyDetector
|
||
|
||
Detects admin/role requirements:
|
||
|
||
**Patterns:**
|
||
- `[Authorize(Roles = "Admin")]`
|
||
- `User.IsInRole("Admin")`
|
||
- `@RolesAllowed("ADMIN")`
|
||
- RBAC middleware checks
|
||
|
||
### ConfigGateDetector
|
||
|
||
Detects configuration-based gates:
|
||
|
||
**Patterns:**
|
||
- Environment variable checks (`process.env.ENABLE_FEATURE`)
|
||
- Configuration file conditionals
|
||
- Runtime feature toggles
|
||
- Debug-only code paths
|
||
|
||
## Output Contract
|
||
|
||
### DetectedGate
|
||
|
||
**Note:** In **Signals API outputs**, `type` is serialized as the C# enum name (e.g., `"AuthRequired"`). In **richgraph-v1** JSON, `type` is lowerCamelCase and gate fields are snake_case (see example below).
|
||
|
||
```typescript
|
||
interface DetectedGate {
|
||
type: 'AuthRequired' | 'FeatureFlag' | 'AdminOnly' | 'NonDefaultConfig';
|
||
detail: string; // Human-readable description
|
||
guardSymbol: string; // Symbol where gate was detected
|
||
sourceFile?: string; // Source file location
|
||
lineNumber?: number; // Line number
|
||
confidence: number; // 0.0-1.0 confidence score
|
||
detectionMethod: string; // Detection algorithm used
|
||
}
|
||
```
|
||
|
||
### GateDetectionResult
|
||
|
||
```typescript
|
||
interface GateDetectionResult {
|
||
gates: DetectedGate[];
|
||
hasGates: boolean;
|
||
primaryGate?: DetectedGate; // Highest confidence gate
|
||
combinedMultiplierBps: number; // Basis points (10000 = 100%)
|
||
}
|
||
```
|
||
|
||
## Integration
|
||
|
||
### RichGraph Edge Annotation
|
||
|
||
Gates are annotated on `RichGraphEdge` objects:
|
||
|
||
```csharp
|
||
public sealed record RichGraphEdge
|
||
{
|
||
// ... existing properties ...
|
||
|
||
/// <summary>Gates detected on this edge</summary>
|
||
public IReadOnlyList<DetectedGate> Gates { get; init; } = [];
|
||
|
||
/// <summary>Combined gate multiplier in basis points</summary>
|
||
public int GateMultiplierBps { get; init; } = 10000;
|
||
}
|
||
```
|
||
|
||
**richgraph-v1 JSON example (edge fragment):**
|
||
|
||
```json
|
||
{
|
||
"gate_multiplier_bps": 3000,
|
||
"gates": [
|
||
{
|
||
"type": "authRequired",
|
||
"detail": "[Authorize] attribute on controller",
|
||
"guard_symbol": "MyController.VulnerableAction",
|
||
"source_file": "src/MyController.cs",
|
||
"line_number": 42,
|
||
"detection_method": "csharp.attribute",
|
||
"confidence": 0.95
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### ReachabilityReport
|
||
|
||
Gates are included in the reachability report:
|
||
|
||
```json
|
||
{
|
||
"vulnId": "CVE-2024-0001",
|
||
"reachable": true,
|
||
"score": 7.5,
|
||
"adjustedScore": 2.25,
|
||
"gates": [
|
||
{
|
||
"type": "AuthRequired",
|
||
"detail": "[Authorize] attribute on controller",
|
||
"guardSymbol": "MyController.VulnerableAction",
|
||
"confidence": 0.95
|
||
}
|
||
],
|
||
"gateMultiplierBps": 3000
|
||
}
|
||
```
|
||
|
||
## Configuration
|
||
|
||
### appsettings.json
|
||
|
||
```json
|
||
{
|
||
"Reachability": {
|
||
"GateMultipliers": {
|
||
"AuthRequiredMultiplierBps": 3000,
|
||
"FeatureFlagMultiplierBps": 2000,
|
||
"AdminOnlyMultiplierBps": 1500,
|
||
"NonDefaultConfigMultiplierBps": 5000,
|
||
"MinimumMultiplierBps": 500
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Metrics
|
||
|
||
| Metric | Description |
|
||
|--------|-------------|
|
||
| `scanner.gates_detected_total` | Total gates detected by type |
|
||
| `scanner.gate_reduction_applied` | Histogram of multiplier reductions |
|
||
| `scanner.gated_vulns_total` | Vulnerabilities with gates detected |
|
||
|
||
## Related Documentation
|
||
|
||
- [Reachability Architecture](../modules/scanner/architecture.md)
|
||
- [Determinism Technical Reference](../product-advisories/14-Dec-2025%20-%20Determinism%20and%20Reproducibility%20Technical%20Reference.md) - Sections 2.2, 4.3
|
||
- [Signals Service](../modules/signals/architecture.md)
|