Skip to main content

CLI Scanner

COMING SOON — not yet published

The scanner is not installable today. @controlzero/scanner has never been published, to the Control Zero registry or to npmjs.org, so every npx command below fails with E404 Not Found until it ships:

npm error code E404
npm error 404 Not Found - GET https://npm.controlzero.ai/@controlzero%2fscanner
npm error 404  '@controlzero/scanner@*' is not in this registry.

This page documents the interface implemented in the scanner source. What is missing is distribution: no runnable package has been published. Do not add these commands to a CI pipeline yet — they will fail the build.

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

Planned usage​

Once a package is published, no installation will be required — it runs 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​

The directory is a positional argument, not a flag:

npx @controlzero/scanner ./src

Output Format​

The scanner produces a structured report with a letter grade:

Control Zero Governance Scanner
===============================

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 [directory] [options]

Arguments:
  [directory]           Directory to scan (default: current directory)

Options:
  -o, --output <format> Output format: console (default), json
      --fail-on <sev>   Exit with code 1 if findings at this severity or above
                        Levels: low, medium, high, critical
      --no-color        Disable colored output
  -q, --quiet           Only output the grade and finding count
  -v, --version         Show the scanner version
      --help            Show help

JSON Output​

Use -o json for machine-readable output:

npx @controlzero/scanner -o 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
  }
}