<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-pre-commit-security-hooks
description: >-
  Configure pre-commit hooks that catch secrets, vulnerable patterns, and
  misconfigurations before code reaches the repository. Uses detect-secrets,
  gitleaks, and custom hooks to enforce security at commit time.
domain: cybersecurity
subdomain: devsecops
tags:
  - pre-commit
  - secret-detection
  - gitleaks
  - detect-secrets
  - git-hooks
  - shift-left
  - developer-experience
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1195.002"]
---

# Implementing Pre-Commit Security Hooks

## Overview

Pre-commit hooks enforce security checks before code enters version control,
catching secrets, insecure patterns, and misconfigurations at the developer
workstation. This skill covers configuring detect-secrets, gitleaks, and custom
hooks using the pre-commit framework to create a frictionless security gate.

Mode: `[MODE: BLUE]` — Earliest possible shift-left security enforcement.

## Prerequisites

| Requirement | Details |
|---|---|
| pre-commit framework (`pip install pre-commit`) | Required |
| gitleaks (`brew install gitleaks`) | Required |
| detect-secrets (`pip install detect-secrets`) | Required |
| Git repository with commit access | Required |

## Key Concepts

### Pre-Commit Configuration

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks

  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: detect-private-key
      - id: check-added-large-files
        args: ['--maxkb=500']
      - id: check-merge-conflict

  - repo: https://github.com/PyCQA/bandit
    rev: 1.7.9
    hooks:
      - id: bandit
        args: ['-c', 'pyproject.toml']
        additional_dependencies: ['bandit[toml]']

  - repo: local
    hooks:
      - id: no-hardcoded-ips
        name: Check for hardcoded IPs
        entry: 'grep -nP "\b(?:\d{1,3}\.){3}\d{1,3}\b" --include="*.py" --include="*.js"'
        language: system
        types: [text]
        pass_filenames: false
```

### Gitleaks Custom Config

```toml
# .gitleaks.toml
title = "Custom Gitleaks Config"

[[rules]]
id = "custom-api-key"
description = "Custom API key pattern"
regex = '''(?i)(?:api[_-]?key|apikey)\s*[:=]\s*['"]?[a-zA-Z0-9_\-]{20,}['"]?'''
tags = ["key", "api"]

[[rules]]
id = "slack-webhook"
description = "Slack webhook URL"
regex = '''https://hooks\.slack\.com/services/T[a-zA-Z0-9_]{8,}/B[a-zA-Z0-9_]{8,}/[a-zA-Z0-9_]{24,}'''
tags = ["slack", "webhook"]

[allowlist]
paths = [
  '''(^|/)tests/''',
  '''\.secrets\.baseline$''',
  '''fixtures/''',
]
```

### Detect-Secrets Baseline

```bash
# Generate initial baseline
detect-secrets scan > .secrets.baseline

# Audit baseline (mark false positives)
detect-secrets audit .secrets.baseline

# Update baseline after new files
detect-secrets scan --update .secrets.baseline
```

### CI Enforcement

```yaml
name: Pre-commit CI
on: [pull_request]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: pre-commit/action@v3.0.1
```

## Workflow

### Step 1: Install Hooks

```bash
node scripts/agent.js --action install --repo-dir . --output /tmp/hook-status.json
```

### Step 2: Scan for Existing Secrets

```bash
node scripts/agent.js --action scan --repo-dir . --output /tmp/secret-scan.json
```

### Step 3: Generate Baseline

```bash
node scripts/agent.js --action baseline --repo-dir . --output /tmp/baseline.json
```

## Detection

```yaml
title: Pre Commit Security Hooks Detection
id: 61ad9401-17ee-4820-b24b-7b4b2d9b970c
status: experimental
description: Detects suspicious activity related to implementing pre commit security hooks techniques in devsecops context
logsource:
  category: process_creation
  product: linux
detection:
  selection:
    CommandLine: "*implementing*pre*"
  condition: selection
level: medium
tags:
  - attack.t1195.002
  - attack.execution
falsepositives:
  - CI/CD pipeline executing authorized security scanning tools
```


**Detection Opportunities**

| Indicator | Source | Detection Logic |
|---|---|---|
| Pre Commit Security Hooks Detection | linux/process_creation | Sigma rule (medium) |
| ATT&CK Coverage | MITRE ATT&CK | T1195.002 |

## Verification

- [ ] Pre-commit hooks installed in repository
- [ ] Gitleaks blocks commits containing secrets
- [ ] Detect-secrets baseline established and audited
- [ ] Private key detection enabled
- [ ] CI enforces pre-commit on all pull requests
- [ ] Developer onboarding includes hook installation

## References

- [pre-commit Framework](https://pre-commit.com/)
- [Gitleaks](https://github.com/gitleaks/gitleaks)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
