CLI Pre-Commit Hooks

Block commits with security vulnerabilities using BlockSecOps CLI hooks.

---

Overview

Pre-commit hooks scan your contracts before each commit, catching security issues early:

• Immediate feedback (no waiting for CI)
• Prevents vulnerable code from entering git history
• Configurable severity thresholds
• Works with any git workflow

---

Quick Setup

Option 1: pre-commit Framework (Recommended)

The pre-commit framework is the easiest way to manage hooks.

Install pre-commit:

pip install pre-commit

Configure .pre-commit-config.yaml:

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan

Install hooks:

pre-commit install

Now every git commit runs a security scan on staged .sol, .vy, and .rs files.

Option 2: Standalone Script

Copy the provided hook script:

# Download hook
curl -o .git/hooks/pre-commit \
  https://raw.githubusercontent.com/blocksecops/blocksecops-cli/main/hooks/pre-commit-hook.sh

# Make executable
chmod +x .git/hooks/pre-commit

---

Available Hooks

blocksecops-scan (Default)

Standard security scan, fails on high severity or above.

- repo: https://github.com/blocksecops/blocksecops-cli
  rev: v0.1.0
  hooks:
    - id: blocksecops-scan

Configuration:

• Scans: .sol, .vy, .rs files
• Fails on: High or Critical severity
• Output: Table format

blocksecops-scan-critical

Only fail on critical vulnerabilities (fastest for development).

- repo: https://github.com/blocksecops/blocksecops-cli
  rev: v0.1.0
  hooks:
    - id: blocksecops-scan-critical

blocksecops-scan-sarif

Output SARIF format for additional tooling.

- repo: https://github.com/blocksecops/blocksecops-cli
  rev: v0.1.0
  hooks:
    - id: blocksecops-scan-sarif

---

Custom Configuration

Custom Severity Threshold

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan
        args:
          - --fail-on=critical  # Only block on critical

Specific Scanners

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan
        args:
          - --scanner=slither
          - --scanner=aderyn
          - --fail-on=high

Custom File Patterns

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan
        files: ^contracts/.*\.sol$  # Only contracts/ directory

Exclude Test Files

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan
        exclude: ^test/|\.t\.sol$|Mock.*\.sol$

---

Environment Variables

Configure hook behavior via environment variables:

Variable	Default	Description
BLOCKSECOPS_FAIL_ON	high	Severity threshold
BLOCKSECOPS_TIMEOUT	300	Max seconds to wait
BLOCKSECOPS_OUTPUT	table	Output format

Example:

# Block only on critical during rapid development
BLOCKSECOPS_FAIL_ON=critical git commit -m "WIP"

---

Skipping Hooks

One-Time Skip

git commit --no-verify -m "WIP: incomplete feature"

Environment Variable Skip

The standalone hook supports:

SKIP_SECURITY_SCAN=1 git commit -m "urgent hotfix"

pre-commit Skip

SKIP=blocksecops-scan git commit -m "skip security only"

---

Team Setup

Share Configuration

Commit .pre-commit-config.yaml to your repository:

git add .pre-commit-config.yaml
git commit -m "Add security pre-commit hooks"

Automated Setup for Team

Add to your package.json or setup script:

{
  "scripts": {
    "prepare": "pip install pre-commit && pre-commit install"
  }
}

Or create a setup.sh:

#!/bin/bash
pip install pre-commit blocksecops-cli
pre-commit install
echo "Pre-commit hooks installed!"

CI Verification

Verify hooks are configured in CI:

# .github/workflows/hooks-check.yml
name: Check Pre-Commit
on: pull_request

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
      - run: pip install pre-commit
      - run: pre-commit run --all-files

---

Combining with Other Hooks

With Solidity Linting

repos:
  # Solhint linting first (fast)
  - repo: local
    hooks:
      - id: solhint
        name: Solidity Linting
        entry: npx solhint
        language: system
        files: \.sol$

  # Security scan after (slower)
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan

With Formatting

repos:
  # Format first
  - repo: local
    hooks:
      - id: prettier
        name: Prettier
        entry: npx prettier --write
        language: system
        files: \.(sol|js|ts)$

  # Then lint
  - repo: local
    hooks:
      - id: solhint
        name: Solhint
        entry: npx solhint
        language: system
        files: \.sol$

  # Security last
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      - id: blocksecops-scan

---

Performance Tips

Fast Feedback Loop

For rapid development, use critical-only scanning:

hooks:
  - id: blocksecops-scan
    args: [--fail-on=critical]

Scan Only Changed Directories

hooks:
  - id: blocksecops-scan
    files: ^contracts/  # Only scan contracts directory

Push Hook for Thorough Scan

Run quick scan on commit, thorough on push:

repos:
  - repo: https://github.com/blocksecops/blocksecops-cli
    rev: v0.1.0
    hooks:
      # Quick scan on commit
      - id: blocksecops-scan-critical
        stages: [commit]

      # Full scan on push
      - id: blocksecops-scan
        stages: [push]
        args: [--fail-on=medium]

---

Troubleshooting

"Not Authenticated"

The hook requires authentication:

blocksecops auth login

If running in CI, set the environment variable:

export BLOCKSECOPS_API_KEY=your_key

Hook Not Running

1. Verify hook is installed:

   pre-commit run --all-files
   

2. Check hook exists:

   ls -la .git/hooks/pre-commit
   

3. Reinstall hooks:

   pre-commit install --force
   

Too Slow

1. Use --fail-on=critical for faster scans
2. Exclude test files with exclude: pattern
3. Save thorough scans for CI

False Positives

1. Mark false positives in the dashboard (they won't fail future scans)
2. Lower threshold temporarily:

   BLOCKSECOPS_FAIL_ON=critical git commit -m "message"
   

---

Standalone Hook Script

The full standalone script for reference:

#!/usr/bin/env bash
# BlockSecOps pre-commit hook

set -e

BLOCKSECOPS_FAIL_ON="${BLOCKSECOPS_FAIL_ON:-high}"
BLOCKSECOPS_TIMEOUT="${BLOCKSECOPS_TIMEOUT:-300}"

# Check CLI installed
if ! command -v blocksecops &> /dev/null; then
    echo "Error: blocksecops CLI not installed"
    echo "Install: pip install blocksecops-cli"
    exit 1
fi

# Check authenticated
if ! blocksecops auth status &> /dev/null; then
    echo "Warning: Not authenticated, skipping scan"
    exit 0
fi

# Get staged contract files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(sol|vy|rs)$' || true)

if [ -z "$STAGED_FILES" ]; then
    exit 0  # No contract files
fi

echo "BlockSecOps: Scanning staged contracts..."

for FILE in $STAGED_FILES; do
    if [ -f "$FILE" ]; then
        if ! blocksecops scan run "$FILE" --fail-on "$BLOCKSECOPS_FAIL_ON"; then
            echo ""
            echo "Commit blocked: Security vulnerabilities found"
            echo "Fix issues or use: git commit --no-verify"
            exit 1
        fi
    fi
done

echo "Security scan passed"

---

Next Steps

• CLI Commands - Full command reference
• CI Security Gates - CI/CD integration
• Developer Quickstart - Full workflow