breach-gate

v1.2.3

Published

2 days ago

OWASP API security scanner with AI-assisted behavioral testing, static analysis, container scanning, and GraphQL probing.

0High
0Medium
0Low

epten08

owasp api-security security-scanner penetration-testing devsecops sast graphql-security jwt-security ssrf sql-injection github-actions ci-security vulnerability-scanner owasp-top-10

Breach Gate

Attack Feasibility Analyzer - CLI-based automated security analysis tool for REST APIs. Goes beyond vulnerability detection to answer the key question: "Is it safe to deploy?"

Combines static analysis, container scanning, dynamic API testing, and AI-assisted behavioral testing to provide deployment verdicts with contextual remediation.

What Makes This Different

Most security scanners answer: "What vulnerabilities exist?"

Breach Gate answers: "Can an attacker actually compromise the system?"

| Traditional Scanner | Breach Gate | |---------------------|--------------| | Lists vulnerabilities | Analyzes attack feasibility | | Severity-based sorting | Risk = Impact × Exploitability × Reachability × Confidence | | Generic recommendations | Contextual remediation with code examples | | Pass/fail on severity | Deployment verdict: SAFE / UNSAFE / REVIEW_REQUIRED |

Features

Attack Feasibility Analysis - Multiplicative risk scoring: reachability × exploitability × impact × confidence
Deployment Verdicts - Clear SAFE/UNSAFE/REVIEW_REQUIRED decisions with reasons
Attack Chain Detection - Identifies multi-step attack paths (e.g., Auth Bypass → Data Exfiltration)
Confirmed Exploit Tracking - AI/dynamic testing success = auto-critical priority
Endpoint Correlation - Groups findings by attack surface area
Contextual Remediation - Specific fixes with code examples, not generic advice
Multi-Scanner Integration - Trivy (SAST), ZAP (DAST), Container scanning, AI behavioral testing, GraphQL probing
CI Auth And Safety - Short-lived auth hooks, multi-role scans, session cookies, AI replay artifacts, and active-scan guardrails
Parallel Execution - AI tests run concurrently with a configurable concurrency cap for faster scans
Baseline Response Diffing - Benign baseline captured per endpoint; body matches that appear in normal responses are discarded as noise
Time-Based Blind Injection - Detects blind SQL and command injection via response timing (>3s and >3× baseline)
Extended AI Attack Categories - SSRF, Mass Assignment, JWT algorithm confusion/claim tampering, plus standard injection and XSS
Watch Mode - Continuous scanning on a configurable interval with new/resolved finding diffs
Finding Suppression - .breachgateignore file for suppressing known-acceptable findings by ID, pattern, or endpoint

Quick Start

# Install
npm install
npm run build

# Start demo vulnerable API
npm run demo

# Run attack feasibility analysis
npm run scan -- -t http://localhost:3000 -v

Sample Output

═══════════════════════════════════════════════════════════
                    SCAN RESULTS
═══════════════════════════════════════════════════════════

  SECURITY VERDICT:

  ╔════════════════════════════════════════════════════════╗
  ║            ⛔  UNSAFE TO DEPLOY  ⛔                    ║
  ╚════════════════════════════════════════════════════════╝

  Reason: Confirmed exploitation: SQL Injection, Command Injection. Active attacks succeeded during testing.

  ⚡ 2 CONFIRMED EXPLOITS:
     • SQL Injection on POST /api/data
     • Command Injection on POST /api/execute

  Attack Surface (by endpoint):

  POST /api/execute
     Risk: ████████████████████ 95%
     ├── Command Injection
     └── Attack chain: Command Injection → Full System Compromise

  POST /api/data
     Risk: ██████████████████░░ 90%
     ├── SQL Injection
     └── Attack chain: Injection → System Compromise

═══════════════════════════════════════════════════════════
  DEPLOYMENT BLOCKED
  2 confirmed exploit(s) must be fixed before deployment.
═══════════════════════════════════════════════════════════

Prerequisites

Required

Node.js >= 18.0.0
npm >= 8.0.0

Optional (for full scanning capabilities)

| Tool | Purpose | Installation | |------|---------|--------------| | Docker | Container scanning, ZAP/Trivy via containers | docker.com | | Trivy | Static analysis & container vulnerability scanning | trivy docs | | OWASP ZAP | Dynamic API security testing | zaproxy.org | | AI Provider | LLM for AI-assisted behavioral testing — pick one: Anthropic, OpenAI, or Ollama (local) | See AI Provider Setup |

Installing Prerequisites

Windows (with winget):

winget install Docker.DockerDesktop
winget install AquaSecurity.Trivy
# Optional: only needed for local Ollama
winget install Ollama.Ollama

macOS (with Homebrew):

brew install --cask docker
brew install trivy
# Optional: only needed for local Ollama
brew install ollama

Linux (Ubuntu/Debian):

# Docker
curl -fsSL https://get.docker.com | sh

# Trivy
sudo apt-get install wget apt-transport-https gnupg lsb-release
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update && sudo apt-get install trivy

# Optional: only needed for local Ollama
curl -fsSL https://ollama.ai/install.sh | sh

Developer Setup

Use this path if you are cloning the repository to develop Breach Gate itself.

1. Install dependencies

npm install

Node.js 20 is the easiest target because it matches the repository CI and release workflows.

2. Add local environment values

If you need cloud AI providers or protected API credentials locally, create a .env from .env.example and add only the values you need.

Common variables:

OPENAI_API_KEY
ANTHROPIC_API_KEY
JWT_TOKEN
API_KEY
ZAP_API_KEY

3. Verify the repository

npm run typecheck
npm test
npm run test:cli
npm run build

Or run the main local verification path in one command:

npm run test:all

4. Bootstrap a starter config

npm run dev -- init --baseline --ci-provider github

That creates:

security.config.yml
.breach-gate-baseline.yml
.github/workflows/breach-gate.yml

5. Validate local prerequisites

npm run dev -- doctor --config security.config.yml

Use --ci when you want to confirm that the enabled scanners and target are suitable for pipeline execution.

Common Developer Commands

| Command | Purpose | |--------|---------| | npm run dev -- scan ... | Run the CLI from source with tsx | | npm run scan -- ... | Shortcut for scan during local development | | npm run demo | Start the intentionally vulnerable demo API | | npm run typecheck | TypeScript validation | | npm test | Integration tests | | npm run test:cli | CLI exit-code, schema, and multi-config tests | | npm run build | Compile the CLI into dist/ | | npm run sbom -- sbom.cdx.json | Generate a CycloneDX SBOM for the package |

Usage

# Run with tsx (development)
npm run dev -- scan [options]

# Or use the scan shortcut
npm run scan -- [options]

# Or directly
npx tsx src/cli/index.ts scan [options]

Commands

`scan`

Run attack feasibility analysis against a target API.

breach-gate scan [options]

Options:

| Option | Description | |--------|-------------| | -c, --config <path> | Path to config file (default: security.config.yml) | | --configs <paths> | Comma-separated config files for monorepo or multi-service scans | | --workdir <path> | Working directory used to resolve config, compose, report, and scanner paths | | -t, --target <url> | Target URL (overrides config) | | -o, --output <dir> | Output directory for reports | | -f, --format <formats> | Output formats, comma-separated: markdown, json, sarif | | --fail-on <severity> | Legacy: fail on severity (now uses attack feasibility) | | --profile <name> | Policy profile: pull-request, main, release, nightly | | --baseline <path> | Path to baseline/ignore file | | --differential | Fail only on findings not covered by the baseline | | -v, --verbose | Enable verbose output with attack chains and remediations | | -q, --quiet | Suppress non-essential output | | --ci | CI mode - minimal, deterministic output for pipelines | | --skip-static | Skip static analysis | | --skip-container | Skip container scanning | | --skip-dynamic | Skip dynamic API scanning | | --skip-ai | Skip AI-assisted behavioral testing | | -h, --help | Display help |

`init`

Create starter configuration and optional baseline/CI files.

breach-gate init --baseline --ci-provider github

`watch`

Continuously scan the target on a fixed interval and report new or resolved findings as a diff.

breach-gate watch [options]

| Option | Description | |--------|-------------| | -c, --config <path> | Path to config file (default: security.config.yml) | | -i, --interval <seconds> | Seconds between scans (default: 60, minimum: 10) | | -v, --verbose | Verbose output |

# Rescan every 2 minutes and highlight new/resolved findings
breach-gate watch --interval 120

# Use a specific config
breach-gate watch -c staging.security.config.yml -i 300

Press Ctrl+C to stop. Each scan prints [Scan #N] N NEW finding(s) or [Scan #N] No new findings. and flags resolved findings from the previous run.

`doctor`

Check local or CI prerequisites.

breach-gate doctor --ci --config security.config.yml

Examples

# Full attack feasibility analysis
breach-gate scan -t http://localhost:3000 -v

# Quick scan (static + container only)
breach-gate scan -t http://localhost:3000 --skip-dynamic --skip-ai

# AI-focused testing
breach-gate scan -t http://localhost:3000 --skip-static --skip-container -v

# Output reports for CI/CD integration
breach-gate scan -t http://localhost:3000 -f json,markdown -o ./reports

# CI mode - minimal, deterministic output
breach-gate scan -t http://localhost:3000 --ci
# Output:
# SECURITY STATUS: PASSED|FAILED|INCONCLUSIVE
# Reason: <one-line reason>

# Monorepo scan across multiple service configs
breach-gate scan --ci --configs services/api/security.config.yml,services/admin/security.config.yml --output ./security-reports

# Run from a service directory without cd-ing into it
breach-gate scan --ci --workdir services/api --config security.config.yml

Local Development Workflow

Run the demo target

Start the vulnerable API in one terminal:

npm run demo

Run Breach Gate against it from another terminal:

npm run scan -- -t http://127.0.0.1:3000 -v

If you want to use the demo-specific config file instead of the repository root config:

npm run dev -- scan --workdir demo --config security.config.yml

Work on one service in a monorepo

npm run dev -- scan --workdir services/payments --config security.config.yml --ci

Scan multiple service configs in one run

npm run dev -- scan --ci --configs services/api/security.config.yml,services/admin/security.config.yml --output ./security-reports

Exit Codes

| Code | Verdict | Description | |------|---------|-------------| | 0 | SAFE | No exploitable vulnerabilities detected | | 0 | REVIEW_REQUIRED | Findings need review, but no confirmed exploits | | 1 | UNSAFE | Confirmed exploits detected - deployment blocked | | 1 | INCONCLUSIVE | Scan failed - cannot verify security, failing safely | | 2 | - | Configuration error |

Key principle: SCAN FAILED ≠ NO VULNERABILITIES. If scanners fail, the verdict is INCONCLUSIVE and exits non-zero.

How Attack Feasibility Works

Traditional scanners use simple severity (LOW/MEDIUM/HIGH/CRITICAL). Breach Gate uses multiplicative risk scoring:

risk = impact × exploitability × reachability × confidence

Risk Factors

| Factor | Description | Sources | |--------|-------------|---------| | Reachability | Can attacker access this? | Endpoint analysis, auth requirements | | Exploitability | Is exploit demonstrated? | AI success, ZAP active scan, CVE data | | Impact | What damage is possible? | Category mapping (RCE=1.0, XSS=0.75, etc.) | | Confidence | How strong is evidence? | Source type, evidence quality, deduplication |

Confirmed Exploits

When AI or dynamic testing successfully exploits a vulnerability:

Automatically marked as confirmed
Minimum feasibility score of 0.8
Verdict becomes UNSAFE
Prioritized for immediate remediation

Reports

Security Verdict

Every report leads with the deployment decision:

## Security Verdict

╔══════════════════════════════════════════════════════════╗
║              ⛔  UNSAFE TO DEPLOY  ⛔                     ║
╚══════════════════════════════════════════════════════════╝

**Reason:** Confirmed exploitation: SQL Injection, Command Injection.

### ⚡ Confirmed Exploits

These vulnerabilities were **actively exploited** during testing:

- **SQL Injection** on `POST /api/data`
- **Command Injection** on `POST /api/execute`

Attack Surface Analysis

| Endpoint | Risk | Vulnerabilities | Attack Feasibility |
|----------|------|-----------------|-------------------|
| `POST /api/execute` | 🔴 95% | Command Injection | High |
| `POST /api/data` | 🔴 90% | SQL Injection | High |
| `GET /api/users/:id` | 🟠 65% | Broken Access Control | Medium |

Contextual Remediation

Instead of generic advice, you get specific fixes:

### 🚨 SQL Injection

**Endpoint:** `POST /api/data`
**Priority:** IMMEDIATE

**Fix:** Parameterize query on POST /api/data for parameter 'id'

**Example:**
```javascript
// Instead of:
db.query(`SELECT * FROM users WHERE id = ${id}`);

// Use:
db.query('SELECT * FROM users WHERE id = ?', [id]);

Configuration

Create a security.config.yml file in your project root:

version: "1.0"

target:
  baseUrl: http://localhost:3000
  healthEndpoint: /health

  # Endpoints for AI testing (if no OpenAPI spec)
  endpoints:
    - path: /api/login
      method: POST
      body:
        username: test
        password: test
    - path: /api/users
      method: GET
      params:
        id: "1"

auth:
  type: none
  # type: jwt
  # token: ${JWT_TOKEN}

scanners:
  static:
    enabled: true
    trivy:
      severityThreshold: MEDIUM

  container:
    enabled: true
    images:
      - my-app:latest

  dynamic:
    enabled: true
    zap:
      apiScanType: api
      maxDuration: 300

  ai:
    enabled: true
    provider: anthropic        # ollama | openai | anthropic
    model: claude-haiku-4-5-20251001
    maxTests: 15

  # GraphQL scanner — auto-discovers common paths (/graphql, /api/graphql, /query)
  graphql:
    enabled: false             # set to true if the target exposes a GraphQL API

thresholds:
  failOn: HIGH
  warnOn: MEDIUM

policy:
  profile: main
  # baselinePath: ./.breach-gate-baseline.yml
  # differentialOnly: true

reporting:
  outputDir: ./security-reports
  formats:
    - markdown
    - json
    - sarif
  includeEvidence: true

Finding Suppression

Two complementary mechanisms exist for suppressing findings:

| Mechanism | Best for | |-----------|---------| | .breachgateignore | Permanently acceptable findings: intentional behaviour, CDN-handled headers, VPN-only endpoints | | .breach-gate-baseline.yml | Temporary waivers: tracked tickets, no upstream fix yet, sprint backlog items |

`.breachgateignore`

Create a .breachgateignore file in your project root. Findings matching a rule are removed before the verdict and policy evaluation — they won't fail CI and won't appear in reports.

# .breachgateignore
suppressions:
  # Suppress by exact finding ID (from the JSON report)
  - id: "7ba985bc-6885-4c1d-8666-92f317402bd4"
    reason: "Rate limiting is handled by the upstream load balancer"

  # Suppress by title/category pattern (case-insensitive substring)
  - pattern: "Missing security header"
    reason: "Security headers are added at the CDN layer, not the origin"

  # Narrow a pattern to a specific endpoint
  - pattern: "Path Traversal"
    endpoint: "/api/internal/files"
    reason: "Internal endpoint behind VPN, not reachable from the internet"

  # Rules can expire — finding resurfaces after this date
  - pattern: "Broken Access Control"
    endpoint: "/api/legacy"
    reason: "Tracked in SEC-456, scheduled for Q3"
    expires: "2026-09-01"

Rules are evaluated in order. A finding is suppressed if any rule matches. Expired rules are ignored automatically.

See .breachgateignore.example in the repository root for a full annotated reference.

AI-Assisted Behavioral Testing

The AI scanner is the key differentiator. It:

Understands endpoint semantics and business logic
Generates context-aware attack payloads per endpoint (not a bulk list)
Captures a benign baseline response before attacks, then filters matches that appear in normal traffic
Confirms exploitation with actual requests
Provides high-confidence findings

Attack Categories

The AI scanner generates test cases across all of these categories, choosing the most relevant ones per endpoint:

| Category | Detection method | |----------|-----------------| | SQL Injection | Response contains SQL error text or injected payload reflected | | Command Injection | Response contains command output; time-based blind via response delay | | Path Traversal | File content or internal paths in response | | Cross-Site Scripting (XSS) | Script tag reflected verbatim in HTML response | | Broken Access Control / IDOR | 2xx response when 4xx expected; different user data returned | | SSRF | Response contains cloud metadata (169.254.x.x, amazonaws.com) | | Mass Assignment | Privileged field (role, is_admin) echoed back with attacker value | | JWT attacks | Algorithm confusion (alg:none), claim tampering — when JWT auth is configured | | Information Disclosure | Debug fields, stack traces, internal paths in response |

Why AI Findings Matter More

| Source | Confidence | Why | |--------|------------|-----| | Static (Trivy) | Medium | Theoretical — pattern matching | | Dynamic (ZAP) | High | Active testing, but generic | | AI Tester | Very High | Context-aware behavioral testing with baseline diffing |

When AI successfully exploits a vulnerability, it's a confirmed attack path.

AI Provider Setup

Breach Gate supports three AI providers. Pick one and configure it in security.config.yml.

Anthropic (recommended for CI/CD)

No local server required. Get an API key from console.anthropic.com.

# .env
ANTHROPIC_API_KEY=sk-ant-...

# security.config.yml
scanners:
  ai:
    enabled: true
    provider: anthropic
    model: claude-haiku-4-5-20251001   # fast and cost-effective
    maxTests: 15

| Model | Speed | Best for | |-------|-------|----------| | claude-haiku-4-5-20251001 | Fastest | CI pipelines, high test volume | | claude-sonnet-4-6 | Balanced | Better reasoning on complex vulnerabilities | | claude-opus-4-7 | Thorough | Highest quality, nightly or release scans |

OpenAI

# .env
OPENAI_API_KEY=sk-...

scanners:
  ai:
    enabled: true
    provider: openai
    model: gpt-4o-mini    # or gpt-4o
    maxTests: 15

Ollama (local, no API key needed)

Requires a running Ollama server. Good for air-gapped environments.

# Install and start
ollama serve
ollama pull llama3

# Verify
curl http://localhost:11434/api/tags

scanners:
  ai:
    enabled: true
    provider: ollama
    model: llama3:8b
    baseUrl: http://localhost:11434    # optional, this is the default
    maxTests: 15

| RAM | Recommended model | |-----|------------------| | 16 GB+ | llama3:8b | | 8 GB | llama3:8b-q4_0 | | GPU | codellama:13b |

GraphQL Scanning

Enable the GraphQL scanner when the target exposes a GraphQL API:

scanners:
  graphql:
    enabled: true

The scanner auto-discovers common GraphQL paths (/graphql, /api/graphql, /query, /gql). If none of those respond with a GraphQL-shaped body, it skips silently.

What it probes:

| Check | Finding type | |-------|-------------| | Introspection enabled | Information Disclosure (MEDIUM) | | No query depth limit | Security Misconfiguration (MEDIUM) | | Field suggestion in errors | Information Disclosure (LOW) | | SQL injection via query variables | SQL Injection (CRITICAL) | | IDOR — querying other users' IDs | Broken Access Control (HIGH) |

Demo

A vulnerable demo API is included:

# Start demo API (intentionally vulnerable)
npm run demo

# Run full analysis
npm run scan -- -t http://localhost:3000 -v

Demo vulnerabilities:

SQL Injection
Command Injection
Path Traversal
IDOR (Broken Access Control)
Information Disclosure
Missing Security Headers

Project Structure

breach-gate/
├── src/
│   ├── cli/
│   │   └── commands/
│   │       ├── run.ts      # breach-gate scan
│   │       ├── watch.ts    # breach-gate watch (continuous scanning)
│   │       ├── init.ts     # breach-gate init
│   │       └── doctor.ts   # breach-gate doctor
│   ├── core/          # Config loader, logger, process runner
│   ├── orchestrator/  # Scan orchestration, environment management
│   ├── scanners/
│   │   ├── ai/        # AI behavioral tester
│   │   ├── graphql/   # GraphQL security prober
│   │   ├── static/    # Trivy SAST
│   │   ├── container/ # Trivy image scanning
│   │   └── dynamic/   # OWASP ZAP
│   ├── findings/      # Attack analysis, risk scoring, remediation
│   │   ├── attack.analyzer.ts  # Attack feasibility analysis
│   │   ├── risk.engine.ts      # Risk scoring
│   │   └── normalizer.ts       # Finding normalization
│   ├── policy/
│   │   ├── policy.ts           # Baseline and policy evaluation
│   │   └── suppression.ts      # .breachgateignore parser
│   ├── reports/       # Report generators (JSON, Markdown, SARIF, HTML)
│   └── ai/            # LLM integration, test generation, evaluation
├── demo/              # Vulnerable demo API
├── .breachgateignore.example
└── security.config.yml

Deploying Breach Gate

There are two common deployment stories:

deploy Breach Gate into another repository or CI/CD pipeline
publish a new Breach Gate release for other teams to consume

Use Breach Gate in another project

You can deploy it into a target pipeline in three main ways.

Option 1: npm package

npx [email protected] scan --ci --config security.config.yml --profile main --format json,markdown,sarif --output security-reports

Use this when the pipeline already has Node available.

Option 2: Docker image

docker run --rm \
  -v "$PWD:/workspace" \
  -w /workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/epten08/breach-gate:1.0.0 \
  scan --ci --config security.config.yml --profile main --format json,markdown,sarif --output security-reports

Use this when you want a pinned runtime with the CLI and Trivy already present.

Option 3: GitHub Action

- name: Run Breach Gate
  uses: epten08/breach-gate@v1
  with:
    config: security.config.yml
    target: ${{ vars.STAGING_API_URL }}
    output: security-reports
    format: json,markdown,sarif
    scan-args: --profile main

Use this when you want the shortest GitHub Actions setup path.

Release a new Breach Gate version

For maintainers, the release flow is:

npm install
npm run test:all
npm audit --omit=dev
npm run sbom -- sbom.cdx.json
git tag v1.2.3
git push origin v1.2.3

Pushing a semantic version tag triggers .github/workflows/release.yml, which verifies the package and publishes:

the npm package
the GHCR container image
the CycloneDX SBOM artifact
npm provenance
container provenance and SBOM attestations

Manual dry runs are also available through the workflow_dispatch input on the release workflow.

Repository CI

The repository CI workflow lives at .github/workflows/ci.yml and runs:

npm run typecheck
npm test
npm run test:cli
npm run build
npm audit --omit=dev
npm run sbom -- security-reports/sbom.cdx.json
npm pack --dry-run
a demo API scan smoke test

CI/CD Integration

First-party CI/CD examples are available in:

# GitHub Actions example
- name: Run Breach Gate
  uses: epten08/breach-gate@v1
  with:
    config: security.config.yml
    target: ${{ vars.STAGING_API_URL }}
    output: security-reports
    format: json,markdown,sarif
    scan-args: --profile main

- name: Upload security reports
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: security-reports
    path: security-reports/

Troubleshooting

"Trivy not found"

Breach Gate can use Trivy via Docker. Ensure Docker is running, or:

breach-gate scan --skip-static --skip-container

"ZAP not found"

Breach Gate can use ZAP via Docker (ghcr.io/zaproxy/zaproxy). Or:

breach-gate scan --skip-dynamic

"Ollama connection refused"

ollama serve  # Start the server first

Or switch to a cloud provider (no local server needed) — see AI Provider Setup. Or skip AI testing entirely:

breach-gate scan --skip-ai

"Anthropic API key not configured" / "OpenAI API key not configured"

Set the key in your .env file or export it in your shell:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

Low-confidence findings

Run with AI enabled - it provides the highest confidence through behavioral testing:

breach-gate scan -t http://localhost:3000 -v

License

MIT