Quickstart

There are two ways to run Cerberus: the web app for native GitHub scans and the CLI for local or GitHub targets, ALIGNMENT analysis, optional security feeders, and CI. Both share the same 59-check native catalog in checks.json.

Option A: Web app

The web app is a static site — no build step, no server required. Open Cerberus Agent in a browser and paste a GitHub repository URL.

GitHub only in the browser

Browsers cannot fetch arbitrary origins due to CORS, so the web app can only scan public GitHub repositories. To scan a local directory, a private repo, or a non-GitHub target, use the CLI below.

Option B: CLI (`examine.py`)

1. Prerequisites

Python 3.9 or later. Native checks, ALIGNMENT, normalization, and reporting use only the standard library.
A local clone of the project you want to scan, or a public GitHub URL.
Optional feeder executables installed and version-pinned separately if you want their specialized coverage.

2. Run a scan

python3 examine.py <path-or-github-url>

Examples:

python3 examine.py ./my-project
python3 examine.py https://github.com/owner/repo
python3 examine.py . --native-only
python3 examine.py . --feeders auto --json report.json --html report.html --sarif report.sarif

A normal CLI run performs native checks and ALIGNMENT. Feeders default to none; auto records unavailable tools gracefully and never installs them.

3. Useful flags

Flag	Purpose
`--json out.json`	Write the full report object (schema `cerberus.report/2`) to a file.
`--html out.html`	Write a standalone HTML report.
`--sarif out.sarif`	Write SARIF for GitHub code scanning upload.
`--feeders auto`	Run all applicable Phase 1 adapters; missing tools are warnings.
`--native-only`	Run only the catalog checks and disable ALIGNMENT/feeders.
`--feeder-timeout 60`	Set the timeout independently for each external tool.
`--feeder-json feeders.json`	Write normalized feeder statuses and findings.
`--strict-feeders`	Fail when a requested feeder is unavailable or fails.
`--fail-under 80`	Exit non-zero if the native score is below the threshold.
`--only sentinel,vault`	Restrict the run to specific agents.
`--severity high`	Only report findings at or above a severity level.

See the full CLI Scanner reference for every flag and the exact output schema.

What happens next

Work through findings in severity order:

Patch all CRITICAL issues first — they deduct the most per hit and usually represent immediate exploit risk.
Address HIGH findings next.
Triage MEDIUM and LOW findings into your backlog.
Re-run the scan to verify fixes and improve your score.

Setting up Cerberus as a GitHub Action

Automate Cerberus security reviews on every Pull Request and branch push using GitHub Actions. Cerberus will scan your codebase, post SARIF findings directly to the repository's Security → Code scanning tab, upload interactive HTML and JSON reports as workflow artifacts, and gate merges using --fail-under.

1. Quick Setup

Create a workflow file in your repository at .github/workflows/cerberus.yml.
Paste the production-ready workflow template below.
Adjust the --fail-under 80 score threshold to match your project's quality gate.
Commit and push to trigger your first automated security review.

2. Workflow Template (`.github/workflows/cerberus.yml`)

name: Cerberus Security Review

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      feeder_mode:
        description: Run reviewed native scanner only, or detect optional preinstalled feeders
        required: true
        default: native-only
        type: choice
        options:
          - native-only
          - auto
      strict_feeders:
        description: Fail when a requested feeder is unavailable, times out, or returns errors
        required: true
        default: false
        type: boolean

permissions:
  contents: read
  security-events: write

jobs:
  cerberus:
    name: Cerberus Security Review
    runs-on: ubuntu-latest

    steps:
      - name: Check out application code
        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6

      # Pin Cerberus checkout to a reviewed commit SHA for supply-chain security
      - name: Check out Cerberus scanner
        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
        with:
          repository: murderszn/cerberus
          ref: eb78139399c022e2cea68dd3fdeb201f3847da48
          path: .cerberus

      - name: Exclude scanner checkout from scan
        run: echo '.cerberus/' >> .cerberusignore

      - name: Run Cerberus examination
        id: scan
        continue-on-error: true
        env:
          FEEDER_MODE: ${{ inputs.feeder_mode || 'native-only' }}
          STRICT_FEEDERS: ${{ inputs.strict_feeders || 'false' }}
        run: |
          scan_args=(
            .
            --json cerberus-report.json
            --html cerberus-report.html
            --sarif cerberus.sarif
            --fail-under 80
            --no-color
          )

          if python3 .cerberus/examine.py --help | grep -q -- '--native-only'; then
            if [[ "$FEEDER_MODE" == 'auto' ]]; then
              scan_args+=(--feeders auto --feeder-json cerberus-feeders.json)
              if [[ "$STRICT_FEEDERS" == 'true' ]]; then
                scan_args+=(--strict-feeders)
              fi
            else
              scan_args+=(--native-only)
            fi
          fi

          python3 .cerberus/examine.py "${scan_args[@]}"

      - name: Publish findings to GitHub Code Security (SARIF)
        if: always()
        continue-on-error: true
        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          sarif_file: cerberus.sarif

      - name: Upload Cerberus report artifacts
        if: always()
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: cerberus-security-review
          path: |
            cerberus-report.json
            cerberus-report.html
            cerberus.sarif
            cerberus-feeders.json
          if-no-files-found: warn
          retention-days: 14

      - name: Add Cerberus summary
        if: always()
        env:
          SCAN_OUTCOME: ${{ steps.scan.outcome }}
          REPORT_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          {
            echo '# CERBERUS LABS — Security Review'
            echo
            echo "Cerberus review result: **${SCAN_OUTCOME}**"
            echo
            echo "[Open workflow run](${REPORT_URL}) · Download the full HTML/JSON reports from artifacts below."
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Enforce score threshold
        if: steps.scan.outcome == 'failure'
        run: |
          echo 'Cerberus found critical issues or the repository scored below the configured threshold.'
          exit 1

3. Key Features of the GitHub Action

Code Scanning Integration: Findings automatically populate inline pull request diff annotations and GitHub's Security Alerts tab via SARIF.
Custom Quality Gates: --fail-under 80 ensures pull requests cannot be merged if they introduce high-risk vulnerabilities that drop the score below 80.
Artifact Downloads: Standalone interactive HTML reports (cerberus-report.html) and full machine-readable JSON reports (cerberus-report.json) are attached to each workflow run.
Zero Third-Party Dependency Risk: Runs with standard Python 3.9+ runtime, requires no network downloads during scan execution, and operates in native-only mode by default.

Next steps

Read the in-depth CLI Scanner & CI Reference for feeder images, timeout tuning, and strict feeder rules.
Browse the Check Catalog to understand every check.
Learn how Severity & Scoring computes your final grade.

Quickstart

Option A: Web app

Option B: CLI (examine.py)

1. Prerequisites

2. Run a scan

3. Useful flags

What happens next

Setting up Cerberus as a GitHub Action

1. Quick Setup

2. Workflow Template (.github/workflows/cerberus.yml)

3. Key Features of the GitHub Action

Next steps

Option B: CLI (`examine.py`)

2. Workflow Template (`.github/workflows/cerberus.yml`)