allowWarnings: boolean; }

export class SecurityGate { constructor(private thresholds: PolicyThresholds) {}

evaluate(scanResults: ScanResult[]): { status: 'PASS' | 'WARN' | 'FAIL'; message: string } { const criticalCount = scanResults .filter(r => r.severity === 'critical') .reduce((sum, r) => sum + r.count, 0);

const highCount = scanResults
  .filter(r => r.severity === 'high')
  .reduce((sum, r) => sum + r.count, 0);

if (criticalCount > this.thresholds.maxCritical) {
  return {
    status: 'FAIL',
    message: `Policy violation: ${criticalCount} critical findings exceed threshold (${this.thresholds.maxCritical})`
  };
}

if (highCount > this.thresholds.maxHigh) {
  return {
    status: 'FAIL',
    message: `Policy violation: ${highCount} high findings exceed threshold (${this.thresholds.maxHigh})`
  };
}

if (this.thresholds.allowWarnings && (criticalCount > 0 || highCount > 0)) {
  return {
    status: 'WARN',
    message: `Security warnings: ${criticalCount} critical, ${highCount} high findings detected. Proceeding with manual review.`
  };
}

return { status: 'PASS', message: 'All security thresholds met.' };

} }

// Usage in pipeline const results: ScanResult[] = JSON.parse(readFileSync('./scan-results.json', 'utf-8')); const gate = new SecurityGate({ maxCritical: 0, maxHigh: 2, allowWarnings: false }); const decision = gate.evaluate(results);

if (decision.status === 'FAIL') { console.error([SECURITY GATE] ${decision.message}); process.exit(1); } else if (decision.status === 'WARN') { console.warn([SECURITY GATE] ${decision.message}); } else { console.log([SECURITY GATE] ${decision.message}); }

This engine decouples tool output from pipeline behavior. It enforces deterministic thresholds, supports warning states for non-blocking findings, and integrates with any CI system that can execute Node.js.

## Pitfall Guide

1. **Treating security as a CI stage, not a design constraint**
   Adding a scanner to the end of a pipeline does not change developer behavior. Security must be enforced at commit time with immediate feedback. Post-merge gates create batch rework and degrade developer experience.

2. **Ignoring false positive triage workflows**
   Scanners generate noise. Without a structured triage process (suppression rules, baseline files, manual review queues), teams disable gates or ignore output. Implement a false positive SLA and maintain a curated suppression policy.

3. **Scanning everything without risk-based prioritization**
   Equal weighting of all findings causes alert fatigue. Prioritize by attack surface, data classification, and exploitability. Focus SAST/SCA on user-facing services and infrastructure components first.

4. **Hardcoding secrets in pipeline configurations**
   Environment variables, CI secrets, and service accounts are frequently over-provisioned. Use dynamic credential injection, short-lived tokens, and audit logging. Never store secrets in version control or pipeline YAML.

5. **Neglecting runtime security (shift-right gap)**
   Pre-deployment scans cannot catch zero-days, misconfigurations applied post-deploy, or lateral movement. Implement runtime policy enforcement, eBPF-based monitoring, and SBOM verification in production.

6. **Security teams operating in isolation from DevOps**
   Security cannot be a separate ticket queue. Embed security champions in engineering squads, co-own pipeline policies, and measure security velocity alongside deployment metrics.

7. **Over-engineering the pipeline with redundant tools**
   Running three SAST scanners and two SCA tools increases noise without improving coverage. Standardize on a single authoritative source per category. Validate tool selection against attack models, not vendor marketing.

**Best Practices from Production:**
- Start with critical paths: authentication services, payment processing, data pipelines.
- Use policy-as-code for all enforcement; avoid tool-specific exceptions.
- Implement SLA-based remediation: criticals within 24h, highs within 7 days, medium within 30 days.
- Automate secret rotation and enforce least privilege per pipeline job.
- Measure security velocity: track policy violation rate, MTTR, and gate pass rate.
- Treat security findings as technical debt; backlog and prioritize alongside features.

## Production Bundle

### Action Checklist
- [ ] Define policy-as-code thresholds for critical/high vulnerabilities and enforce them at PR time
- [ ] Integrate SAST, SCA, and secret detection into the commit pipeline with machine-readable output
- [ ] Implement a TypeScript/Node security gate that evaluates scan results against centralized policy
- [ ] Replace static pipeline credentials with dynamic secret injection and short-lived tokens
- [ ] Establish a false positive triage workflow with suppression baselines and manual review queues
- [ ] Deploy runtime security monitoring (eBPF, CSPM, SBOM verification) for production workloads
- [ ] Track security velocity metrics: violation rate, MTTR, gate pass rate, and deployment frequency
- [ ] Assign security champions to each engineering squad with shared ownership of pipeline policy

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Startup MVP (1-10 engineers) | Lightweight PaC + SCA + Secret Detection | Fast feedback, low overhead, prevents dependency breaches | Low tooling cost; minimal pipeline latency |
| Regulated Enterprise (Finance/Healthcare) | Full shift-left + IaC scanning + runtime CSPM + audit logging | Compliance requirements, audit trails, strict change control | High initial integration cost; reduces breach liability |
| High-Velocity Platform (SaaS, Microservices) | Policy-as-code gate + SAST/SCA + automated remediation PRs | Maintains deployment frequency while enforcing security baselines | Moderate tooling cost; reduces hotfix and rollback expenses |

### Configuration Template

```yaml
# .github/workflows/security-gate.yml
name: Security Gate
on: [pull_request, push]

jobs:
  security-evaluation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Run SAST (Semgrep)
        run: semgrep --config=auto --json > sast-results.json
      - name: Run SCA (npm audit)
        run: npm audit --json > sca-results.json
      - name: Run Secret Detection (gitleaks)
        run: gitleaks detect --report-format json --report-path secrets-results.json
      - name: Aggregate & Evaluate
        run: node scripts/security-gate.js
        env:
          MAX_CRITICAL: 0
          MAX_HIGH: 2
          ALLOW_WARNINGS: false
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: sast-results.json

// scripts/security-gate.ts
import { SecurityGate } from '../src/security-gate';
import { readFileSync } from 'fs';

const parseToolOutput = (file: string, tool: string): Array<{ severity: string; count: number }> => {
  const data = JSON.parse(readFileSync(file, 'utf-8'));
  // Normalize tool-specific formats to unified structure
  return data.results?.map((r: any) => ({
    severity: r.severity || 'low',
    count: 1,
    id: r.check_id || r.vulnerabilityId || 'unknown',
    file: r.file || r.filePath || 'unknown',
    line: r.line || r.startLine || 0
  })) || [];
};

const results = [
  ...parseToolOutput('sast-results.json', 'semgrep'),
  ...parseToolOutput('sca-results.json', 'npm-audit'),
  ...parseToolOutput('secrets-results.json', 'gitleaks')
];

const gate = new SecurityGate({
  maxCritical: parseInt(process.env.MAX_CRITICAL || '0'),
  maxHigh: parseInt(process.env.MAX_HIGH || '2'),
  allowWarnings: process.env.ALLOW_WARNINGS === 'true'
});

const decision = gate.evaluate(results);
console.log(`[GATE] ${decision.status}: ${decision.message}`);
process.exit(decision.status === 'FAIL' ? 1 : 0);

Quick Start Guide

1. Install baseline tools: npm install -D semgrep @gitleaks/gitleaks (or use GitHub Actions marketplace equivalents)
2. Create the security gate script: Copy the TypeScript gate engine into scripts/security-gate.ts and compile to JS
3. Add the workflow: Place the YAML template in .github/workflows/ and adjust thresholds to match your risk tolerance
4. Run locally: Execute semgrep --config=auto --json > sast-results.json and node scripts/security-gate.js to validate policy evaluation
5. Merge and monitor: Open a PR with a known vulnerable dependency or hardcoded secret. Verify the gate fails deterministically and produces actionable output

DevSecOps is not a toolchain; it is a delivery discipline. When policy evaluation is deterministic, feedback is immediate, and security metrics are treated as first-class engineering KPIs, pipelines stop being attack surfaces and start being assurance mechanisms.