scan

Scan a directory, file, or URL target for AI tool configuration risks. Runs Layers 1–2 (offline, deterministic) by default, with optional Layer 3 deep scan.

codegate scan [target] runs the multi-layer analysis pipeline against a target and reports findings. Layers 1 and 2 are offline-first and deterministic. Layer 3 deep scan is opt-in with --deep.

Layers 1 and 2 never make network calls. The scan target is inspected locally against the static knowledge base. Layer 3 (--deep) is the only mode that may fetch remote metadata or invoke a local AI agent.

Scan targets

The [target] argument accepts:

• Directory — scans all discovered AI tool config files under the directory (default: .)
• File — scans a single config file directly
• URL — clones or fetches the remote resource and scans the result; use --skill to select a single skill from a multi-skill index repo

codegate scan .
codegate scan ./path/to/project
codegate scan ~/.config/claude/claude_desktop_config.json
codegate scan https://github.com/owner/repo --skill security-review

Flags

--deep · boolean · default: "false"

Enable Layer 3 dynamic analysis. Discovers eligible external resources and local instruction files, prompts for per-resource consent, and optionally invokes a local AI meta-agent (Claude Code, Codex CLI, or OpenCode) for deeper inspection. No network calls are made without explicit consent.

--remediate · boolean · default: "false"

Enter remediation mode after the scan completes. Guides you through available fixes interactively. Backups are written to .codegate-backup/ before any file is modified.

--fix-safe · boolean · default: "false"

Automatically apply fixes for unambiguous critical findings without interactive prompts. Use with --dry-run to preview what would change.

--dry-run · boolean · default: "false"

Show proposed remediation changes without writing anything to disk.

--patch · boolean · default: "false"

Generate patch-style output for proposed fixes, suitable for review workflows.

--no-tui · boolean · default: "false"

Disable the TUI dashboard and interactive prompts. Use this flag in CI or when piping output.

--format · string · default: "terminal"

Output format. Valid values: terminal, json, sarif, markdown, html.

sarif output is designed for GitHub Code Scanning and other security tooling.

--output · string

Write the report to a file path instead of stdout.

--verbose · boolean · default: "false"

Show extended output in terminal format. Has no effect on other output formats.

--config · string

Path to a specific global config file. Overrides the default ~/.codegate/config.json location.

--force · boolean · default: "false"

Skip interactive confirmations, including deep scan consent prompts and remediation consent. In non-interactive or CI environments, deep scan actions are skipped unless --force is provided.

--include-user-scope · boolean · default: "false"

Force-include user/home AI tool config paths for this run. Useful when the config file has scan_user_scope: false but you want a one-off full scan.

--collect · string

Collection scope mode. Valid values: default, project, user, explicit, all. The flag is repeatable to combine modes.

--collect-kind · string

Restrict collection to specific artifact kinds. Valid values: workflows, actions, dependabot. The flag is repeatable.

--strict-collection · boolean · default: "false"

Treat parse failures in collected inputs as high-severity findings instead of warnings.

--persona · string · default: "regular"

Audit sensitivity level. Valid values: regular, pedantic, auditor.

--runtime-mode · string · default: "offline"

Runtime mode for optional online audits. Valid values: offline, online, online-no-audits.

--workflow-audits · boolean · default: "false"

Enable the CI/CD audit pack for GitHub Actions workflows, actions, and Dependabot inputs. Checks include unpinned action references, high-risk triggers, overly broad permissions, template expression injection, and known vulnerable action references (online mode only).

--skill · string

Select one skill directory when scanning a skills-index repo URL that contains multiple skills.

--reset-state · boolean · default: "false"

Clear the persisted scan-state baseline file (~/.codegate/scan-state.json) and exit immediately. Use this to reset rug-pull detection history.

Examples

# Basic scan of the current directory
codegate scan .

# Output as JSON to stdout
codegate scan . --format json

# Output as SARIF to a file (for GitHub Code Scanning)
codegate scan . --format sarif --output codegate.sarif

# Enable Layer 3 deep scan
codegate scan . --deep

# Deep scan including user/home config surfaces
codegate scan . --deep --include-user-scope

# Deep scan skipping consent prompts
codegate scan . --deep --force

# Enter guided remediation after scan
codegate scan . --remediate

# Auto-fix unambiguous critical findings
codegate scan . --fix-safe

# Preview remediation changes and generate a patch
codegate scan . --remediate --dry-run --patch

# Workflow audit pack with project scope, auditor persona, and online mode
codegate scan . --workflow-audits --collect project --persona auditor --runtime-mode online

# Workflow audit pack restricted to workflow files only
codegate scan . --workflow-audits --collect project --collect-kind workflows

# Treat collection parse failures as high-severity findings
codegate scan . --workflow-audits --strict-collection

# Scan a remote URL and select a specific skill
codegate scan https://github.com/owner/repo --skill security-review

# Reset scan-state baseline and exit
codegate scan . --reset-state

Exit codes

Code	Meaning
0	No unsuppressed findings
1	Findings exist below the configured severity threshold
2	Findings at or above the configured severity threshold
3	Scanner or runtime error