Skip to content

CI/CD Architecture

System Overview

The CI/CD code review system is split into two planes: client-side (SAST scanning in the CI runner) and server-side (AI enrichment via the BeDefended API).

graph TB
    subgraph "Client CI Runner"
        A["PR / Push event"] --> B["bd-sast Docker<br/>(~800MB)"]
        B --> C["semgrep + bandit +<br/>gosec + brakeman"]
        B --> D["gitleaks + trufflehog<br/>(secrets)"]
        B --> E["trivy<br/>(dependencies)"]
        C --> F["sast-results.json"]
        D --> F
        E --> F
    end

    subgraph "BeDefended API"
        F -->|"HTTPS POST<br/>X-BD-API-Key"| G["API Gateway<br/>api.bedefended.com"]
        G --> H["Auth + Rate Limit<br/>+ Usage Metering"]
        H -->|Essentials| I["Normalize +<br/>Return"]
        H -->|Professional| J["Claude Analysis<br/>(taint flow, fixes)"]
        H -->|Enterprise| K["Claude + Codex<br/>(dual verify)"]
    end

    subgraph "Post-Processing"
        I --> L["SARIF 2.1.0"]
        J --> L
        K --> L
        L --> M["GitHub Security Tab"]
        L --> N["PR Inline Comments"]
        L --> O["Quality Gate<br/>(exit 0 or 1)"]
        L --> P["GitLab Code Quality"]
    end

    style A fill:#4a148c,color:#fff
    style G fill:#0277bd,color:#fff
    style J fill:#00838f,color:#fff
    style K fill:#00695c,color:#fff

Components

1. bd-sast Docker Image

Lightweight image (~800MB) with only SAST tools. No pentest tools, wordlists, or offensive capabilities.

Registry: ghcr.io/bedefended/bd-sast:latest

Build: Multi-stage Dockerfile at ci/Dockerfile.sast

  • Stage 1 (builder): Go toolchain compiles gitleaks and gosec
  • Stage 2 (runtime): Python 3.12 slim + semgrep + bandit + trivy + brakeman + trufflehog + bd-review CLI

2. bd-review CLI

Python CLI package installed inside the Docker image. Six commands:

Command Purpose Requires API?
bd-review scan Run SAST tools, output sast-results.json No
bd-review submit Send results to API, poll for AI analysis Yes
bd-review sarif Convert findings to SARIF 2.1.0 or GitLab format No
bd-review gate Evaluate quality gate, exit 0/1 No
bd-review comment Post PR inline comments (GitHub/GitLab/Azure) No (needs Git token)
bd-review crossref Link CI findings with pentest engagement No

3. API Gateway

FastAPI router at /api/v1/ci/ in the dashboard backend. Endpoints:

Method Path Auth Purpose
POST /ci/review API key Submit SAST results for review
GET /ci/review/{id} API key Poll review status
GET /ci/review/{id}/sarif API key Get SARIF output
POST /ci/api-keys JWT (admin) Create API key
GET /ci/usage/{company_id} JWT (staff) Usage metrics

4. AI Engine

Professional tier: Claude Sonnet via claude -p CLI analyzes findings:

  • Taint flow tracing (source -> propagation -> sink)
  • Confidence upgrade (possible -> likely -> confirmed)
  • Specific remediation advice
  • Suggested code fixes

Enterprise tier: Adds Codex dual-engine verification for high/critical findings.

Both engines use the Max subscription (no API credits consumed).

Database Models

Three new tables extend the existing dashboard:

ci_api_keys
  - id, company_id (FK), key_hash (SHA-256), key_prefix
  - repo_pattern, tier, monthly_scan_limit, scans_this_month
  - is_active, created_at, expires_at

ci_reviews
  - id, review_id (UUID), company_id (FK), api_key_id (FK)
  - repo_url, commit_sha, pr_number, branch, status
  - tier, diff_only, files_reviewed, findings_count
  - quality_gate_passed, sast_results_json, ai_findings_json
  - duration_ms, engagement_ref, created_at

ci_plans
  - id, name, display_name, price_eur_monthly
  - bundle_discount_pct, max_repos, max_scans_monthly
  - ai_analysis, dual_engine, sarif_export, pr_comments
  - priority_support, is_active, created_at

Security Design

Aspect Implementation
API key storage SHA-256 hash in DB, only prefix visible in UI
Source code Never stored on BeDefended servers. Only SAST tool output + diff metadata transit the API
AI analysis Only relevant code snippets sent to Claude, not entire repo
Tenant isolation Each company sees only their reviews via company_id FK
Rate limiting Per API key + per IP via slowapi
Audit trail Every review logged with timestamp, key used, result
Key rotation Create new key, deactivate old one. No downtime

Data Flow

  1. Developer pushes code or opens PR
  2. CI pipeline triggers, runs bd-sast Docker container
  3. SAST tools execute locally in the CI runner (source code never leaves)
  4. Only findings JSON + diff metadata sent to BeDefended API
  5. API validates key, checks tier, meters usage
  6. For Professional+: Claude analyzes snippets, enriches findings
  7. Enriched findings returned to CI runner
  8. CI runner generates SARIF, posts PR comments, evaluates quality gate
  9. Build passes or fails based on severity thresholds