Skip to content

CLI Reference: bd-review

The bd-review CLI is the core tool for all CI/CD operations. It runs inside the bd-sast Docker image and can also be installed standalone via pip.

Installation

# Inside Docker (pre-installed)
docker run --rm ghcr.io/bedefended/bd-sast:latest bd-review --version

# Standalone (for local development)
pip install -e ci/bd-review/
bd-review --version

Global Options

bd-review [OPTIONS] COMMAND [ARGS]

Options:
  --version      Show version and exit
  -v, --verbose  Enable debug logging
  --help         Show help and exit

Commands

bd-review scan

Run SAST security scanners and output normalized results.

bd-review scan [OPTIONS]
Option Default Description
--mode full diff (changed files only) or full (entire repo)
--output, -o sast-results.json Output file path
--config, -c auto-detect Path to .bedefended.yml
--work-dir, -d . Working directory to scan

Example:

docker run --rm -v $(pwd):/work ghcr.io/bedefended/bd-sast:latest \
  bd-review scan --mode full --output /work/sast-results.json

Output format (sast-results.json):

{
  "version": "1.0",
  "mode": "full",
  "findings": [
    {
      "tool": "semgrep",
      "rule_id": "python.django.security.injection.sql.sql-injection",
      "severity": "high",
      "message": "SQL Injection detected",
      "file": "app/views.py",
      "line_start": 42,
      "line_end": 42,
      "snippet": "cursor.execute(f\"SELECT * FROM users WHERE id={uid}\")",
      "metadata": {"cwe": {"id": "89"}}
    }
  ],
  "summary": {
    "total": 5,
    "by_severity": {"critical": 1, "high": 2, "medium": 1, "low": 1},
    "by_tool": {"semgrep": 2, "gitleaks": 1, "bandit": 1, "trivy": 1}
  }
}

bd-review submit

Send SAST results to the BeDefended API for AI enrichment.

bd-review submit [OPTIONS]
Option Default Description
--api-key $BD_API_KEY BeDefended API key (required)
--api-url $BD_API_URL API URL override
--sast-results - Path to sast-results.json (required)
--repo - Repository URL or slug (required)
--commit-sha $COMMIT_SHA Git commit SHA (required)
--pr-number - Pull request number
--branch - Branch name
--output, -o review-results.json Output file
--wait / --no-wait --wait Wait for AI analysis to complete
--timeout 300 Max seconds to wait

Example:

bd-review submit \
  --api-key bd_sk_abc123... \
  --sast-results sast-results.json \
  --repo owner/repo \
  --commit-sha abc123 \
  --pr-number 42

bd-review sarif

Convert findings to SARIF 2.1.0 or GitLab Code Quality format.

bd-review sarif [OPTIONS]
Option Default Description
--input, -i - Input findings JSON (required)
--output, -o results.sarif Output file
--format sarif sarif or gitlab

SARIF uploads to GitHub Security tab via github/codeql-action/upload-sarif@v3.

GitLab format produces the Code Quality JSON for the merge request widget.

# SARIF for GitHub
bd-review sarif -i review-results.json -o results.sarif

# GitLab Code Quality
bd-review sarif -i review-results.json -o gl-code-quality.json --format gitlab

bd-review gate

Evaluate quality gate. Exits with code 0 (pass) or 1 (fail).

bd-review gate [OPTIONS]
Option Default Description
--input, -i - Input findings JSON (required)
--fail-on - Override: critical, high, medium, or none
--config, -c - Path to .bedefended.yml for custom thresholds

Presets:

Preset Fail on Min Confidence
strict Any Medium+ confirmed only
standard Any High+ confirmed + likely
permissive Any Critical confirmed only

Example:

bd-review gate -i review-results.json --fail-on high
# Exit code: 0 (pass) or 1 (fail)

Output:

Quality Gate: FAILED
  Reason: 1 critical finding(s) exceed threshold of 0

  Severity Counts:
    Critical: 1
    High:     2
    Medium:   1
    Low:      1
    Info:     0

  Findings evaluated: 5
  Findings filtered:  0

bd-review comment

Post inline PR/MR comments with findings.

bd-review comment [OPTIONS]
Option Default Description
--input, -i - Input review results JSON (required)
--provider - github, gitlab, or azure (required)
--token $GIT_TOKEN Auth token
--repo - Repository (owner/repo)
--pr-number - PR/MR number
--commit-sha - Commit SHA

bd-review crossref

Cross-reference CI findings with a pentest engagement.

bd-review crossref [OPTIONS]
Option Default Description
--input, -i - Input review results JSON (required)
--engagement-dir - Path to pentest engagement directory (required)
--output, -o crossref-report.md Output markdown report

Output is a markdown report showing:

  • Findings confirmed by both code review and blackbox testing
  • Code review findings not confirmed by blackbox (potential false positives)
  • Blackbox findings not found by code review (logic bugs, config issues)