CLI Scanner Reference

examine.py runs the 59 native checks in checks.json, the native ALIGNMENT analyzer, and optional allowlisted security feeders. Native scoring remains identical to the web app; orchestration evidence is reported separately.

Usage

python3 examine.py <path-or-github-url> [options]

The target can be a local directory or a GitHub repository URL (with or without .git, /tree/{ref}, or a trailing slash). For a GitHub URL, examine.py resolves the default branch, fetches the file tree, and pulls file contents from the raw.githubusercontent.com CDN. For a local path, it walks the directory directly.

Examples

# Local clone
python3 examine.py ./my-saas-app

# GitHub URL
python3 examine.py https://github.com/owner/repo

# Native checks only, fully offline
python3 examine.py . --native-only

# ALIGNMENT plus every applicable Phase 1 feeder
python3 examine.py . --feeders auto --json report.json --html report.html \
  --sarif report.sarif --feeder-json feeders.json

The default runs native checks plus ALIGNMENT with feeders disabled. Cerberus never downloads or installs external tools.

Flags

CI / GitHub Actions

Cerberus is designed for zero-friction integration with GitHub Actions CI/CD pipelines. It ships a production-ready reusable workflow template at .github/workflow-templates/cerberus-security-review.yml that executes fast security audits on pull requests and pushes without requiring complex runner setups or cloud API keys.

Workflow Deployment Steps

1. Copy the workflow file into your repository at .github/workflows/cerberus.yml.
2. Pin the Cerberus scanner checkout step to an approved commit SHA (e.g. ref: eb78139399c022e2cea68dd3fdeb201f3847da48). Avoid floating tags like main in production.
3. Configure your gating threshold via --fail-under <score> (default: 80).
4. Ensure repository permissions include security-events: write so findings appear under the GitHub Security tab.

Workflow Architecture

Recommended Workflow Definition

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

Feeder Tools in CI

When running in auto feeder mode, Cerberus executes pre-installed external security tools if available on the runner:

Cerberus never automatically downloads or executes unreviewed remote binaries during CI runs. For feeder-enabled runners, construct a hardened container image with exact tool version pins and cryptographic checksum verification.

Exclusions

The native engine honours the same global_exclude and test_paths globs defined in checks.json. Feeder discovery additionally honors .cerberusignore, prunes ignored directories and symlinks, and protects the nested scanner checkout:

node_modules/, vendor/, .git/, dist/, build/, out/, target/, coverage/,
.next/, .nuxt/, *.min.js, *.min.css, *.bundle.js, *.map,
package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, Cargo.lock,
composer.lock, Gemfile.lock, go.sum, *.snap, __snapshots__/, migrations/

Paths under test/, tests/, spec/, __tests__/, fixtures/, examples/, docs/, and similar are excluded from native content-matching checks by default. Specialized feeders may intentionally consume files that native content checks exclude—for example, OSV-Scanner consumes lockfiles—but only from their filtered applicable input set.

Output schema

examine.py emits the same Report shape as the web app — see docs/IMPROVEMENTS.md §3.3 for the authoritative schema. In short:

{
  "schema": "cerberus.report/2",
  "target": { "kind": "github", "display": "owner/repo", "sha": "…" },
  "score": 87.5,
  "grade": "B",
  "counts": { "critical": 0, "high": 2, "medium": 5, "low": 3,
              "pass": 47, "fail": 9, "not_applicable": 2, "skipped": 1, "total": 59 },
  "coverage": { "filesInTree": 842, "filesEligible": 310, "filesScanned": 310,
                "filesSkipped": 0, "bytesScanned": 4210233, "truncated": false },
  "agents": [
    { "id": "sentinel", "name": "SENTINEL", "domain": "Code Analysis", "weight": 14, "score": 12.0,
      "checks": [ { "id": "S-01", "status": "fail", "findings": [ { "path": "...", "line": 42, "snippet": "...", "url": "https://github.com/o/r/blob/sha/path#L42" } ] } ] }
  ],
  "native": { "score": 87.5, "grade": "B", "findings": [] },
  "alignment": { "schema": "cerberus.alignment/1", "score": 94, "grade": "A", "findings": [] },
  "feeders": { "schema": "cerberus.feeders/1",
    "summary": { "completed": 3, "not_applicable": 1, "unavailable": 1, "failed": 0 },
    "tools": [], "findings": [] },
  "policy": { "passed": true, "blockers": [], "warnings": [] }
}

Legacy top-level fields retain cerberus.report/2 semantics. Every native check remains present, including passes. Additive sections distinguish the native score, ALIGNMENT score, feeder evidence, and combined policy. SARIF keeps Cerberus native results first and adds producer-specific runs with provenance and fingerprints.

Limitations