Analysis layers

How CodeGate’s four-layer pipeline discovers, analyses, and remediates AI tool configuration risks — from offline file walking to opt-in deep scan and guided remediation.

CodeGate uses a four-layer pipeline to inspect AI tool configuration surfaces. Layers 1 and 2 are offline-first and deterministic; they run on every scan without network access or external tool invocation. Layer 3 is opt-in and requires explicit per-resource consent. Layer 4 provides guided remediation with full undo support.

Offline-first design

Layers 1 and 2 run entirely offline. They make no network requests, spawn no external processes, and produce the same output for the same input on every run. This design means:

• A scan never leaks project content to external services by default.
• Results are reproducible and suitable for CI gating.
• The scan completes even in air-gapped environments.

Layer 3 departs from this by contacting external resources and invoking a local meta-agent. It is always opt-in and consent-gated.

Pipeline flow

1. Layer 1 — Discovery

   The file walker traverses the project tree up to five directory levels deep, skipping node_modules, dist, build, .venv, vendor, and .git internals while still descending into .git/hooks. It records symlink escapes (symlinks that resolve outside the project root) and circular symlinks for later static analysis.

   The config parser identifies AI tool configuration files by path pattern and format (JSON, YAML, TOML, Markdown, plain text). The tool detector checks whether AI coding tools are installed by probing PATH, known application bundle locations, and VS Code extension directories. Detected tools include: claude-code, codex-cli, opencode, cursor, windsurf, kiro, vscode, jetbrains, and github-copilot.

   The knowledge base provides the static lists that drive safe-server allow-listing, blocked command defaults, and known-safe formatter and LSP server references used in Layer 2 detections.

2. Layer 2 — Static analysis

   The static engine receives the parsed files, symlink escape list, and git hook list from Layer 1. It runs a set of registered file-level and global audits against each file without any network access.

   Built-in detectors cover: environment variable overrides, command execution patterns, consent bypass configurations, rule/instruction file injection, IDE settings issues, symlink escapes, git hook anomalies, plugin manifest issues, and advisory intelligence matching.

   The rule engine loads built-in rule packs (per-tool JSON rule packs for Claude Code, Codex, Cursor, Copilot, OpenCode, and common patterns) plus any additional rule_pack_paths from config. Rules support field-path queries and text pattern matching.

   All Layer 2 findings carry a layer: "L2" label and a confidence of HIGH, MEDIUM, or LOW.

3. Layer 3 — Deep scan (opt-in)

   Enabled with --deep. CodeGate discovers eligible external resources from known config paths and eligible local instruction files (AGENTS.md, CODEX.md, discovered skill/rule markdown) from the already-selected scan surface.

   In interactive mode, CodeGate enumerates installed meta-agents (claude, codex, opencode) and prompts for selection. For each candidate resource, it presents a per-resource consent prompt and a command preview before executing anything. No network request or meta-agent invocation occurs without user approval.

   MCP tool-description acquisition does not execute untrusted stdio command arrays. Local instruction-file analysis is text-only: file content and extracted URL strings are passed as inert text; referenced content is never executed.

   In non-interactive mode (CI), deep actions are skipped unless --force is provided.

   Layer 3 outcomes — including consent-skipped, timeout, auth failure, and schema-mismatch results — are normalized into findings so operators can audit why deep scan did not fully complete.

4. Layer 4 — Remediation

   Remediation is opt-in and guided. Use --remediate for interactive guided fixes, --fix-safe to apply unambiguous critical fixes automatically, --dry-run to preview proposed changes without writing, or --patch to generate a patch file for review workflows.

   Every remediation session writes a backup under .codegate-backup/ before modifying any file. Run codegate undo [dir] to restore the latest backup session. Remediation is best-effort: always review changes before committing them.

Layer 3 deep scan increases your exposure compared to a static-only scan because it may fetch remote metadata and invoke a selected local AI tool. Keep --deep off in automated pipelines unless you have reviewed its consent model and trust the installed meta-agent.

Summary table

Layer	Name	Network	Deterministic	Opt-in
L1	Discovery	No	Yes	No
L2	Static analysis	No	Yes	No
L3	Deep scan	Yes	No	Yes (--deep)
L4	Remediation	No	Yes	Yes (--remediate / --fix-safe)