# How to Use DCG Scan Mode with Pre‑Commit Hooks in Destructive Command Guard

> Learn how to use DCG scan mode with pre-commit hooks to detect destructive commands before they enter your commit history. Block catastrophic operations safely. Integrate Destructive Command Guard today.

- Repository: [Jeff Emanuel/destructive_command_guard](https://github.com/Dicklesworthstone/destructive_command_guard)
- Tags: how-to-guide
- Published: 2026-07-16

---

**`dcg scan` is a static analysis mode that inspects staged files for destructive commands before they enter your commit history, blocking catastrophic operations while allowing safe code to proceed.**

The Destructive Command Guard (DCG) provides two primary operational modes: a real‑time interactive hook that intercepts agent command execution, and the static `dcg scan` mode designed for version control integration. According to the Dicklesworthstone/destructive_command_guard source code, scan mode parses executable contexts within GitHub Actions workflows, Dockerfiles, shell scripts, and Makefiles to identify dangerous patterns before they reach production.

## What is DCG Scan Mode?

Unlike the interactive `dcg` hook that monitors live command execution, **scan mode** performs static analysis on repository files. It extracts commands that would actually execute, ignoring comments, documentation, and string literals. The scanner matches these commands against a curated database of destructive patterns—each annotated with a stable `ruleId` (e.g., `core.git:reset-hard`) and severity level (`critical`, `high`, `medium`, or `low`).

As implemented in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs), the scan command orchestrates the workflow by loading configuration from [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml), initializing the extraction engine, and delegating pattern matching to the core scanner in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs).

## How the Scan Workflow Operates

The scanning process follows a three‑stage pipeline defined in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs):

1. **Extract Commands** – Pack‑specific extractors parse file formats and return only executable commands. The `src/packs/` directory contains modular pattern packs (such as `core.git` and `core.filesystem`) that understand syntax specific to each file type.

2. **Match Patterns** – Extracted commands are evaluated against safe‑ and destructive‑pattern lists. Each match receives a severity classification and a stable identifier for consistent policy enforcement.

3. **Report Findings** – Results emit as human‑readable tables or JSON, with optional redaction of quoted strings to prevent secret leakage in CI logs.

## Installing the Pre‑Commit Hook

DCG provides a native installation command that creates a Git pre‑commit hook automatically.

```bash
cd /path/to/your/repo
dcg scan install-pre-commit

```

This command generates `.git/hooks/pre-commit` and configures it to run `dcg scan --staged` before each commit. If the scanner detects a catastrophic rule match, it aborts the commit and displays remediation guidance.

For custom hook managers or existing pre‑commit scripts, manually invoke the scanner:

```bash
#!/bin/sh

# Existing checks...

dcg scan --staged

```

The `--staged` flag restricts analysis to files in the Git index, ensuring you only evaluate changes intended for the current commit.

## Configuring Scan Behavior

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 scanner loads these settings at runtime from [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) and applies them during the extraction and matching phases.

```toml
[scan]
format = "pretty"          # Use "json" for machine-parsing in CI pipelines

fail_on = "error"          # Set to "warning" to treat all matches as blocking

redact = "quoted"          # Hide secret strings in output logs

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 `critical` severity matches (configured via `fail_on = "error"`) block commits. Lower‑severity findings generate warnings without preventing the commit.

## CI/CD Integration

Enforce policies on pull‑request diffs by running `dcg scan` in your continuous integration pipeline. The following GitHub Actions workflow installs DCG and scans only the changed files between the base branch and HEAD.

```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 optimizes performance by limiting analysis to modified lines, while `--fail-on error` ensures that catastrophic destructive commands break the build.

## Investigating and Suppressing Findings

When the scanner flags a command, investigate the specific rule using the explain command:

```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 a local exception that persists across scans while maintaining audit trails through the justification message (`-r` flag).

## Summary

- **`dcg scan`** performs static analysis on repository files before commit, distinct from the real‑time interactive hook.
- The workflow extracts executable commands using format‑specific parsers in `src/packs/`, matches them against destructive patterns in [`src/scan.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/scan.rs), and reports findings with stable `ruleId` identifiers.
- Install via `dcg scan install-pre-commit` or manually integrate into existing hooks using `dcg scan --staged`.
- 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 `dcg explain` to understand flagged commands and `dcg allow --project` to suppress false positives with documented justification.

## Frequently Asked Questions

### What file types does DCG scan mode analyze?

DCG scan mode analyzes any file format with a registered extractor pack in `src/packs/`. Out of the box, this includes GitHub Actions workflows, Dockerfiles, Makefiles, shell scripts, and other executable contexts. The extractors specifically target commands that would actually run, ignoring comments, documentation strings, and non‑executable content.

### How does DCG scan mode differ from the standard DCG hook?

The standard DCG hook operates as a real‑time interceptor for interactive command execution, typically used by AI agents or interactive shells. In contrast, `dcg scan` is a static analysis tool that examines files on disk—particularly staged changes—before they become part of the commit history. Scan mode is designed for version control integration, while the standard hook focuses on runtime protection.

### Can I use DCG scan mode without installing the pre‑commit hook?

Yes. While `dcg scan install-pre-commit` provides seamless Git integration, you can run `dcg scan` manually against specific files, directories, or Git diffs. Use `dcg scan --staged` to check pending changes, or `dcg scan --git-diff <range>` to analyze specific commit ranges in CI environments without modifying repository hooks.

### What happens when the scanner finds a destructive command?

When the scanner matches a destructive pattern, it assigns a severity level (`critical`, `high`, `medium`, or `low`) and compares it against your `fail_on` threshold in [`.dcg/hooks.toml`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/.dcg/hooks.toml). By default, only `critical` matches (errors) cause the pre‑commit hook to abort the commit. The output displays the `ruleId`, affected file, line number, and remediation guidance. In CI environments, you can configure `--fail-on warning` to block merges on any match.