# How dcg Scan Mode Works in Pre-Commit Hooks and CI Integration > Learn how dcg scan mode statically analyzes staged files and diffs for destructive commands, blocking risky commits with pre-commit hooks and CI integration. - Repository: [Jeff Emanuel/destructive_command_guard](https://github.com/Dicklesworthstone/destructive_command_guard) - Tags: how-to-guide - Published: 2026-07-21 --- **The `dcg scan` command provides static analysis that inspects staged files and pull-request diffs for destructive commands before they enter your codebase, blocking commits via pre-commit hooks or CI pipelines when catastrophic patterns are detected.** The `dcg scan` mode in the Dicklesworthstone/destructive_command_guard repository offers a proactive defense against dangerous operations by analyzing executable contexts in source files before execution. Unlike the real-time interception provided by the standard `dcg` hook, scan mode operates as a **static analyzer** that parses GitHub Actions workflows, Dockerfiles, shell scripts, and Makefiles to identify destructive patterns during the commit process or in continuous integration environments. ## What Is dcg Scan Mode? `dcg scan` functions as a pre-flight check that examines code for commands that could cause data loss or system damage. According to the implementation in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs), the scanner executes a three-phase pipeline: 1. **Extract Commands** – Pack-specific extractors parse file formats and return only executable commands, ignoring comments, documentation strings, and non-executable content. 2. **Match Patterns** – Extracted commands are evaluated against DCG's safe/destructive pattern libraries defined in `src/packs/*`. Each match receives a stable `ruleId` (e.g., `core.git:reset-hard`) and severity classification. 3. **Report Findings** – Results are emitted in human-readable tables or JSON format, with optional redaction of quoted strings to prevent secret leakage in logs. The severity levels range from `critical` and `high` to `medium` and `low`, allowing granular control over which findings should block commits versus generate warnings. ## Installing dcg Scan as a Pre-Commit Hook You can integrate `dcg scan` into your Git workflow either through automated installation or manual configuration. **Automated Installation** The CLI entry point in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) provides a dedicated subcommand that installs the hook directly into `.git/hooks/pre-commit`: ```bash cd /path/to/your/repo dcg scan install-pre-commit ``` **Manual Integration** For existing hook infrastructure or hook managers like Husky, add the scanner to your pre-commit script: ```bash #!/bin/sh # Existing checks... dcg scan --staged ``` The `--staged` flag restricts analysis to files in the Git index, ensuring only proposed changes are evaluated. If any rule matches the configured `fail_on` threshold (default: `error`), the commit aborts with a non-zero exit code. ## Configuring Scan Behavior with .dcg/hooks.toml Repository-wide configuration resides in [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml) at your project root. The [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) module parses this file to override default scanning parameters: ```toml [scan] format = "pretty" # Use "json" for machine-readable CI output fail_on = "error" # Set to "warning" to treat all matches as failures redact = "quoted" # Hide secret strings in output max_file_size = 1048576 # Skip files larger than 1 MiB max_findings = 100 [scan.paths] include = [ ".github/workflows/**", "Dockerfile*", "**/Makefile", "scripts/**/*.sh", ] exclude = [ "vendor/**", "node_modules/**", "**/testdata/**", ] ``` By default, only catastrophic rules trigger commit rejection, while lower-severity matches generate warnings. The `include` and `exclude` globs define which files the scanning engine in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs) will examine. ## CI Integration for Pull Request Enforcement For CI pipelines, `dcg scan` can evaluate pull request diffs to prevent destructive commands from reaching protected branches. The implementation supports scanning arbitrary Git refs: ```yaml name: DCG Scan on: [pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - run: | curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh | bash - run: dcg scan --git-diff origin/${{ github.base_ref }}...HEAD --fail-on error ``` The `--git-diff` flag instructs the scanner to analyze only the changed lines between the base branch and HEAD, optimizing performance for large repositories. JSON output mode (`--format json`) facilitates integration with CI dashboards and PR comment systems. ## Understanding Scan Results and Remediation When `dcg scan` identifies a match, it references specific rule IDs from the pattern packs in `src/packs/*`. Investigate flagged commands using the explain utility: ```bash dcg explain "git reset --hard HEAD~1" ``` For false positives or intentional destructive operations (such as CI cleanup steps), allowlist specific rules at the project level: ```bash dcg allow core.git:reset-hard -r "CI cleanup step" --project ``` This creates an exception record that persists across scans while maintaining audit documentation via the reason flag (`-r`). ## Summary - **`dcg scan`** provides static analysis of source files, complementing the real-time interception of the standard `dcg` hook. - The scanning engine in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs) processes files through extractors, pattern matching against `src/packs/*` definitions, and configurable reporting. - Install via `dcg scan install-pre-commit` or manual integration with `--staged` to validate commits before they complete. - Configure behavior through [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml), specifying severity thresholds, path inclusions, and output formats. - Use `--git-diff` in CI pipelines to scan only pull request changes, enforcing policies before merge. ## Frequently Asked Questions ### How does dcg scan differ from the real-time dcg hook? The real-time `dcg` hook intercepts commands during interactive agent execution, blocking them before they run in your shell. In contrast, `dcg scan` performs static analysis on files in your repository, identifying destructive commands in code that has not yet executed. Scan mode is ideal for CI/CD and pre-commit validation, while the real-time hook protects your local development environment. ### What file formats does dcg scan analyze? The scanner processes executable contexts within GitHub Actions workflows, Dockerfiles, shell scripts, Makefiles, and other infrastructure-as-code formats. Pack-specific extractors in the codebase parse each format to isolate actual commands from comments and documentation, ensuring analysis focuses only on code that will execute. ### How do I prevent dcg scan from blocking legitimate commands in CI? Use the `dcg allow` command with the `--project` flag to create repository-specific exceptions for known-safe destructive operations. Alternatively, adjust the `fail_on` setting in [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml) from `"error"` to `"critical"` to allow only the most severe matches to block your pipeline, or configure path exclusions to skip files containing intentional maintenance commands. ### Where does dcg scan store its configuration? Configuration resides in [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml) at your repository root, parsed by the CLI logic in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs). This file controls scan parameters including output format (`pretty` or `json`), failure thresholds, redaction settings, and path globs for inclusion or exclusion. Project-specific allowlists are also stored within the `.dcg/` directory.