Skip to main content

CLI Scanner

The Control Zero CLI scanner analyzes your codebase and identifies AI tool calls that lack governance. It produces a governance grade and actionable findings you can address before shipping.

What It Does​

The scanner statically analyzes your project to find:

  • AI tool calls that are not wrapped by a Control Zero SDK client
  • MCP tool invocations without policy enforcement
  • Direct API calls to LLM providers that bypass governance
  • Missing or misconfigured policy bundles

Installation and Usage​

No installation required. Run it directly with npx. Configure the Control Zero registry once: add @controlzero:registry=https://npm.controlzero.ai to your .npmrc (or run npm config set @controlzero:registry https://npm.controlzero.ai). It applies to npm install and npx for the whole @controlzero scope.

npx @controlzero/scanner

The scanner auto-detects your project structure and scans all relevant source files.

Scan a Specific Directory​

npx @controlzero/scanner --path ./src

Output Format​

The scanner produces a structured report with a letter grade:

Control Zero Governance Scanner v1.0.0
=======================================

Scanning: ./src (47 files)

Grade: B

Findings:
  [HIGH]   src/agents/analyst.py:42    Direct OpenAI call without CZ wrapper
  [HIGH]   src/agents/writer.py:18     MCP tool call not governed
  [MEDIUM] src/tools/database.py:95    call_tool() missing context parameter
  [LOW]    src/config.py:12            API key hardcoded (use env var)

Summary: 4 findings (2 high, 1 medium, 1 low)

Grade Scale​

GradeMeaning
AAll AI tool calls are governed. No findings.
BMinor gaps. Most calls are governed.
CModerate gaps. Several ungoverned calls.
DLarge gaps. Most calls are ungoverned.
FNo governance detected.

CI/CD Integration​

Use the --fail-on flag to fail your CI pipeline when findings exceed a severity threshold:

# Fail if any HIGH severity findings exist
npx @controlzero/scanner --fail-on high

# Fail if any MEDIUM or higher findings exist
npx @controlzero/scanner --fail-on medium

GitHub Actions Example​

name: Governance Check
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Control Zero Scanner
        run: npx @controlzero/scanner --fail-on high

GitLab CI Example​

governance-scan:
  stage: test
  script:
    - npx @controlzero/scanner --fail-on high
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Command Reference​

npx @controlzero/scanner [options]

Options:
  --path <dir>        Directory to scan (default: current directory)
  --fail-on <level>   Exit with code 1 if findings at this level or above
                      Levels: low, medium, high
  --format <type>     Output format: text (default), json, sarif
  --ignore <pattern>  Glob pattern for files to skip
  --quiet             Only output the grade and finding count
  --help              Show help

JSON Output​

Use --format json for machine-readable output:

npx @controlzero/scanner --format json
{
  "grade": "B",
  "findings": [
    {
      "severity": "high",
      "file": "src/agents/analyst.py",
      "line": 42,
      "message": "Direct OpenAI call without CZ wrapper",
      "rule": "ungoverned-llm-call"
    }
  ],
  "summary": {
    "total": 4,
    "high": 2,
    "medium": 1,
    "low": 1
  }
}

SARIF Output​

Use --format sarif for integration with GitHub Code Scanning and other SARIF-compatible tools:

npx @controlzero/scanner --format sarif > results.sarif