How dcg Scan Mode Works in Pre-Commit Hooks and CI Integration

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, 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 provides a dedicated subcommand that installs the hook directly into .git/hooks/pre-commit:

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:

#!/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 at your project root. The src/cli.rs module parses this file to override default scanning parameters:

[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 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:

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:

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:

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 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, 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 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 at your repository root, parsed by the CLI logic in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}