.github/workflows/security-risk.yml

a Flow:** Scan Tool → JSON Output → Risk Engine API → Enrichment (Context Lookup) → Risk Calculation → Policy Decision → CI Gate / Ticket Creation.

Step-by-Step Implementation

1. Define Risk Taxonomy: Establish a quantitative model. We use a modified FAIR-lite model adapted for code: Risk = Likelihood × Impact.
2. Context Enrichment Service: Create a service that maps assets to context. For example, an API endpoint might be tagged as public, internal, or admin, and data sensitivity as public, confidential, or restricted.
3. Risk Calculation Engine: Implement the scoring logic in TypeScript. This engine takes a vulnerability finding and context to output a risk score.
4. Policy Enforcement: Configure the CI pipeline to fail or warn based on risk thresholds, not just severity.

Code Implementation: Risk Calculation Engine

The following TypeScript implementation demonstrates a context-aware risk calculator. It moves beyond CVSS by incorporating exploitability factors and business impact modifiers.

// models.ts
export interface Vulnerability {
  id: string;
  cveId?: string;
  cvss: number;
  type: 'SAST' | 'SCA' | 'DAST';
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
  location: string; // e.g., 'src/auth/login.ts'
}

export interface AssetContext {
  exposure: 'PUBLIC' | 'INTERNAL' | 'ADMIN';
  dataSensitivity: 'PUBLIC' | 'INTERNAL' | 'PII' | 'PCI';
  hasWaf: boolean;
  isAuthenticationRequired: boolean;
  exploitAvailability: 'NONE' | 'POC' | 'EXPLOIT' | 'IN_WILD';
}

export interface RiskResult {
  vulnId: string;
  riskScore: number; // 0-100
  riskLevel: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'NEGLIGIBLE';
  rationale: string[];
}

// riskEngine.ts
export class SecurityRiskEngine {
  
  // Weights for calculation
  private static readonly IMPACT_WEIGHT = 0.6;
  private static readonly LIKELIHOOD_WEIGHT = 0.4;

  calculateRisk(vuln: Vulnerability, context: AssetContext): RiskResult {
    const rationale: string[] = [];
    
    // 1. Calculate Likelihood (0-100)
    // Base on CVSS but modified by exploit availability and controls
    let likelihood = this.calculateLikelihood(vuln.cvss, context, rationale);
    
    // 2. Calculate Impact (0-100)
    // Based on data sensitivity and exposure
    let impact = this.calculateImpact(context, rationale);
    
    // 3. Composite Risk Score
    const riskScore = Math.round(
      (likelihood * this.LIKELIHOOD_WEIGHT) + 
      (impact * this.IMPACT_WEIGHT)
    );

    return {
      vulnId: vuln.id,
      riskScore,
      riskLevel: this.mapScoreToLevel(riskScore),
      rationale
    };
  }

  private calculateLikelihood(cvss: number, context: AssetContext, rationale: string[]): number {
    let score = cvss * 10; // Normalize CVSS 0-10 to 0-100
    
    // Exploit availability modifier
    switch (context.exploitAvailability) {
      case 'IN_WILD': score *= 1.2; rationale.push("Exploit available in the wild (+20%)"); break;
      case 'EXPLOIT': score *= 1.1; rationale.push("Public exploit available (+10%)"); break;
      case 'POC': break; // No change
      case 'NONE': score *= 0.5; rationale.push("No exploit available (-50%)"); break;
    }

    // Compensating controls
    if (context.hasWaf) {
      score *= 0.7;
      rationale.push("WAF active reduces likelihood (-30%)");
    }
    
    if (!context.isAuthenticationRequired && context.exposure === 'PUBLIC') {
      score *= 1.15;
      rationale.push("Unauthenticated public access increases likelihood (+15%)");
    }

    return Math.min(100, Math.max(0, score));
  }

  private calculateImpact(context: AssetContext, rationale: string[]): number {
    let score = 0;

    // Data sensitivity base score
    switch (context.dataSensitivity) {
      case 'PCI': score = 90; break;
      case 'PII': score = 75; break;
      case 'INTERNAL': score = 40; break;
      case 'PUBLIC': score = 10; break;
    }

    // Exposure modifier
    if (context.exposure === 'PUBLIC') {
      score += 20;
      rationale.push("Public exposure increases blast radius (+20)");
    } else if (context.exposure === 'ADMIN') {
      score += 15;
      rationale.push("Admin access implies high privilege (+15)");
    }

    return Math.min(100, score);
  }

  private mapScoreToLevel(score: number): RiskResult['riskLevel'] {
    if (score >= 80) return 'CRITICAL';
    if (score >= 60) return 'HIGH';
    if (score >= 40) return 'MEDIUM';
    if (score >= 20) return 'LOW';
    return 'NEGLIGIBLE';
  }
}

CI Integration Example

The risk engine integrates into the pipeline to gate builds. This snippet shows a GitHub Action workflow that runs the risk assessment and fails on Critical/High risk, while allowing Medium risk with a warning.

# .github/workflows/security-risk.yml
name: Security Risk Assessment

on:
  push:
    branches: [ main, develop ]

jobs:
  risk-assessment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run SAST Scanner
        run: ./run-sast-scan.sh --output findings.json
      
      - name: Run Risk Engine
        id: risk
        uses: docker://ghcr.io/codcompass/risk-engine:latest
        with:
          input: findings.json
          context-config: ./risk-context.yaml
          output: risk-report.json
      
      - name: Enforce Risk Policy
        run: |
          CRITICAL=$(jq '.results | map(select(.riskLevel == "CRITICAL")) | length' risk-report.json)
          HIGH=$(jq '.results | map(select(.riskLevel == "HIGH")) | length' risk-report.json)
          
          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
            echo "::error::Risk policy violation: $CRITICAL Critical, $HIGH High risk findings."
            exit 1
          fi
          
          if [ "$(jq '.results | map(select(.riskLevel == "MEDIUM")) | length' risk-report.json)" -gt 0 ]; then
            echo "::warning::Medium risk findings detected. Review required."
          fi
          
          echo "Risk assessment passed."

Pitfall Guide

1. Relying Solely on CVSS for Prioritization:

   • Mistake: Treating a CVSS 9.8 vulnerability in an internal admin tool with no internet access as equal risk to a CVSS 7.5 vulnerability in a public payment API.
   • Fix: Always apply context modifiers. CVSS is an input to risk, not the risk itself.

2. Ignoring Compensating Controls:

   • Mistake: Scoring vulnerabilities high even when mitigations like WAFs, strict network segmentation, or runtime application self-protection (RASP) are active.
   • Fix: Maintain an inventory of controls and feed this data into the risk engine to adjust likelihood scores dynamically.

3. Static Risk Thresholds:

   • Mistake: Setting a fixed "High" threshold (e.g., score > 60) and never revisiting it. Risk tolerance changes based on business goals, threat landscape, and audit cycles.
   • Fix: Implement dynamic thresholds that can be adjusted per repository or environment. Review thresholds quarterly.

4. Over-Engineering the Model:

   • Mistake: Building a complex FAIR model requiring 50 inputs per vulnerability, leading to analysis paralysis and incomplete data.
   • Fix: Start with a lightweight model (like the example above) using available data. Add complexity only where it provides measurable value.

5. Lack of Developer Feedback Loop:

   • Mistake: The risk engine flags issues, but developers cannot dispute or provide context (e.g., "This endpoint is deprecated").
   • Fix: Implement a risk acceptance workflow. Allow developers to annotate findings with context that feeds back into the engine for future assessments.

6. Context Data Decay:

   • Mistake: The context store (tags, exposure levels) becomes stale. A service marked INTERNAL is exposed publicly via a misconfigured load balancer, but the risk engine still scores it as internal.
   • Fix: Automate context discovery. Use infrastructure-as-code scanning to verify exposure labels. Trigger re-scans when infrastructure changes.

7. Treating Risk Assessment as a One-Time Event:

   • Mistake: Running a risk assessment at project kickoff and never updating it.
   • Fix: Risk is continuous. Integrate risk calculation into every build. Threat intelligence updates should trigger re-evaluation of existing findings.

Production Bundle

Action Checklist

• Define Risk Taxonomy: Establish quantitative scoring rules (Likelihood/Impact) aligned with business risk appetite.
• Inventory Context Sources: Identify data sources for asset context (IaC, CMDB, data classification tags).
• Implement Risk Engine: Deploy the risk calculation service and integrate with SAST/DAST/SCA outputs.
• Configure CI Gates: Set pipeline policies to block on Critical/High risk and warn on Medium.
• Enable Risk Acceptance: Create a workflow for developers to accept risk with justification and expiration.
• Automate Context Validation: Set up checks to ensure asset metadata matches actual infrastructure state.
• Schedule Review Cadence: Monthly review of risk thresholds and quarterly review of the risk model weights.
• Monitor Drift: Track metrics like MTTR and risk score distribution to detect security posture degradation.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-Stage Startup	Lightweight DREAD + CVSS	Speed is critical. Complex models slow delivery. DREAD provides enough differentiation without heavy context needs.	Low. Minimal engineering overhead.
Regulated Enterprise (Finance/Health)	Full FAIR-lite + Automated Context	Compliance requires defensible risk quantification. Context is mandatory to prove compensating controls.	High. Requires investment in context automation and policy governance.
Microservices Architecture	Context-Aware Quantitative (Sidecar)	High volume of services requires automated enrichment. Manual context tagging is impossible at scale.	Medium. DevOps effort to integrate sidecar and context APIs.
Legacy Monolith	Hybrid Approach	Start with qualitative risk for legacy debt, quantitative for new features. Gradually refactor legacy context.	Medium. Dual maintenance during transition period.

Configuration Template

Use this YAML configuration to define risk policies and context rules for the risk engine.

# risk-policy.yaml
version: "1.0"

risk_model:
  type: "quantitative"
  weights:
    likelihood: 0.4
    impact: 0.6

thresholds:
  critical: 80
  high: 60
  medium: 40
  low: 20

context_rules:
  exposure:
    public:
      impact_modifier: 20
      likelihood_modifier: 10
    internal:
      impact_modifier: 0
      likelihood_modifier: 0
    admin:
      impact_modifier: 15
      likelihood_modifier: 5

  data_sensitivity:
    pci:
      base_impact: 90
    pii:
      base_impact: 75
    internal:
      base_impact: 40
    public:
      base_impact: 10

  controls:
    waf_active:
      likelihood_modifier: -30
    mfa_required:
      likelihood_modifier: -20

policy:
  ci_gate:
    fail_on: ["CRITICAL", "HIGH"]
    warn_on: ["MEDIUM"]
  risk_acceptance:
    max_duration_days: 90
    requires_approval: true
    approvers: ["security-lead", "tech-lead"]

Quick Start Guide

1. Initialize the Engine: Add the risk engine package to your repository and create the risk-policy.yaml based on the template above.

   npm install @codcompass/risk-engine
   cp node_modules/@codcompass/risk-engine/templates/risk-policy.yaml ./
   

2. Define Asset Context: Create a context.json file mapping your services to their exposure and data sensitivity. For production, replace this with an API call to your context store.

   {
     "service-a": {
       "exposure": "PUBLIC",
       "dataSensitivity": "PII",
       "hasWaf": true
     }
   }
   

3. Run Assessment Locally: Execute the risk engine against a sample scan output to validate scoring.

   risk-engine assess \
     --input ./sample-sast-report.json \
     --context ./context.json \
     --policy ./risk-policy.yaml \
     --output ./risk-report.json
   

4. Integrate into CI: Add the risk engine step to your pipeline configuration. Ensure the step fails the build if Critical or High risks are detected.

   - name: Security Risk Gate
     run: risk-engine ci-gate --report risk-report.json
   

5. Review and Tune: Analyze the initial risk-report.json. Adjust weights and thresholds in risk-policy.yaml to align with your team's risk appetite. Enable the risk acceptance workflow for false positives or accepted risks.