git.stella-ops.org/docs/reachability/gates.md

# 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

```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;
}
```

### 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)