Pre-Commit Hook Setup

Catch security issues before they're committed to your repository using Socket Basics as a pre-commit hook.

Quick Start
Docker Installation (Recommended)
Native Installation
Configuration
Customization
Troubleshooting

Quick Start

Choose your installation method:

Docker (Recommended) — No tool installation required, everything runs in a container
Native — Install tools directly on your system for faster execution

Both methods integrate with Git's pre-commit hook system to automatically scan your code before each commit.

Docker Installation (Recommended)

Best for: Teams wanting consistent environments without installing security tools locally.

Prerequisites

Docker installed and running
Git repository initialized

Setup Steps

1. Build the Socket Basics Docker image:

# Clone the repository (if not already)
git clone https://github.com/SocketDev/socket-basics.git
cd socket-basics

# Build the Docker image with version tag
docker build -t socket-basics:1.1.3 .

2. Create pre-commit hook:

Create .git/hooks/pre-commit in your project:

#!/bin/bash
set -e

echo "🔍 Running Socket Basics security scan..."

# Get list of staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)

if [ -z "$STAGED_FILES" ]; then
  echo "No files to scan"
  exit 0
fi

# Run Socket Basics in Docker
docker run --rm \
  -v "$PWD:/workspace" \
  -e INPUT_CONSOLE_ENABLED=true \
  socket-basics \
  --workspace /workspace \
  --python-sast-enabled \
  --javascript-sast-enabled \
  --secret-scanning-enabled \
  --console-tabular-enabled

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ Security scan failed! Please fix the issues above before committing."
  exit 1
fi

echo "✅ Security scan passed!"
exit 0

3. Make the hook executable:

chmod +x .git/hooks/pre-commit

4. Test the hook:

# Try to commit a file
git add .
git commit -m "Test commit"

Docker Pre-Commit Configuration

Scan only changed files:

#!/bin/bash
set -e

echo "🔍 Running Socket Basics security scan on staged files..."

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)

if [ -z "$STAGED_FILES" ]; then
  echo "No files to scan"
  exit 0
fi

# Create temporary file list
TEMP_FILE=$(mktemp)
echo "$STAGED_FILES" > "$TEMP_FILE"

# Run scan only on staged files
docker run --rm \
  -v "$PWD:/workspace" \
  -v "$TEMP_FILE:/tmp/scan-files.txt" \
  -e INPUT_CONSOLE_ENABLED=true \
  socket-basics \
  --workspace /workspace \
  --python-sast-enabled \
  --secret-scanning-enabled \
  --console-tabular-enabled

EXIT_CODE=$?
rm "$TEMP_FILE"

if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ Security issues found! Please fix before committing."
  exit 1
fi

echo "✅ Security scan passed!"
exit 0

With Enterprise features:

#!/bin/bash
set -e

echo "🔍 Running Socket Basics security scan..."

# Load environment variables if .env exists
if [ -f .env ]; then
  export $(cat .env | grep -v '^#' | xargs)
fi

docker run --rm \
  -v "$PWD:/workspace" \
  -e INPUT_CONSOLE_ENABLED=true \
  -e SOCKET_ORG="$SOCKET_ORG" \
  -e SOCKET_SECURITY_API_KEY="$SOCKET_SECURITY_API_KEY" \
  -e INPUT_SLACK_WEBHOOK_URL="$SLACK_WEBHOOK_URL" \
  socket-basics \
  --workspace /workspace \
  --python-sast-enabled \
  --javascript-sast-enabled \
  --secret-scanning-enabled \
  --socket-tier-1-enabled \
  --console-tabular-enabled

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ Security scan failed!"
  exit 1
fi

echo "✅ Security scan passed!"
exit 0

Native Installation

Best for: Developers who want faster scan times and don't mind installing tools locally.

Prerequisites

Install the required security tools:

Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Socket Basics:

# Install from source (Socket Basics is not on PyPI)
git clone https://github.com/SocketDev/socket-basics.git
cd socket-basics
pip install -e .

Security tools:

See Local Installation Guide for detailed instructions on installing:

Socket CLI
Trivy
OpenGrep
TruffleHog

Setup Steps

1. Create pre-commit hook:

Create .git/hooks/pre-commit:

#!/bin/bash
set -e

echo "🔍 Running Socket Basics security scan..."

# Activate virtual environment if it exists
if [ -d ".venv" ]; then
  source .venv/bin/activate
fi

# Run Socket Basics
socket-basics \
  --python-sast-enabled \
  --javascript-sast-enabled \
  --secret-scanning-enabled \
  --console-tabular-enabled

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ Security scan failed! Please fix the issues above before committing."
  exit 1
fi

echo "✅ Security scan passed!"
exit 0

2. Make executable:

chmod +x .git/hooks/pre-commit

3. Test the hook:

git add .
git commit -m "Test commit"

Native Pre-Commit Configuration

Fast scan (secrets only):

#!/bin/bash
set -e

echo "🔍 Quick security check..."

if [ -d ".venv" ]; then
  source .venv/bin/activate
fi

socket-basics \
  --secret-scanning-enabled \
  --console-tabular-enabled

if [ $? -ne 0 ]; then
  echo "❌ Security issues found!"
  exit 1
fi

echo "✅ Scan passed!"
exit 0

Comprehensive scan:

#!/bin/bash
set -e

echo "🔍 Running comprehensive security scan..."

if [ -d ".venv" ]; then
  source .venv/bin/activate
fi

# Load environment variables if .env exists
if [ -f .env ]; then
  export $(cat .env | grep -v '^#' | xargs)
fi

socket-basics \
  --all-languages-enabled \
  --secret-scanning-enabled \
  --socket-tier-1-enabled \
  --console-tabular-enabled \
  --verbose

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ Security scan failed!"
  echo "Run 'socket-basics --help' for more information"
  exit 1
fi

echo "✅ Security scan passed!"
exit 0

Configuration

Speed vs Coverage Trade-offs

Fast (< 10 seconds):

socket-basics --secret-scanning-enabled

Only scans for leaked secrets
Best for quick feedback during development

Balanced (30-60 seconds):

socket-basics \
  --python-sast-enabled \
  --secret-scanning-enabled

Language-specific SAST + secrets
Good balance of speed and coverage

Comprehensive (2-5 minutes):

socket-basics \
  --all-languages-enabled \
  --secret-scanning-enabled \
  --socket-tier-1-enabled

All security features enabled
Best for final checks or CI/CD

Conditional Scanning

Only scan relevant languages based on file extensions:

#!/bin/bash
set -e

STAGED_FILES=$(git diff --cached --name-only)

SCAN_ARGS=""

# Check for Python files
if echo "$STAGED_FILES" | grep -q "\.py$"; then
  SCAN_ARGS="$SCAN_ARGS --python-sast-enabled"
fi

# Check for JavaScript/TypeScript files
if echo "$STAGED_FILES" | grep -qE "\.(js|ts|jsx|tsx)$"; then
  SCAN_ARGS="$SCAN_ARGS --javascript-sast-enabled --typescript-sast-enabled"
fi

# Check for Go files
if echo "$STAGED_FILES" | grep -q "\.go$"; then
  SCAN_ARGS="$SCAN_ARGS --go-sast-enabled"
fi

# Always scan for secrets
SCAN_ARGS="$SCAN_ARGS --secret-scanning-enabled"

if [ -z "$SCAN_ARGS" ]; then
  echo "No scannable files in commit"
  exit 0
fi

socket-basics $SCAN_ARGS --console-tabular-enabled

if [ $? -ne 0 ]; then
  echo "❌ Security issues found!"
  exit 1
fi

echo "✅ Scan passed!"
exit 0

Environment Variables

Create .env in your project root (add to .gitignore):

# Socket Configuration (Enterprise)
SOCKET_ORG=your-org-slug
SOCKET_SECURITY_API_KEY=your-api-key

# Notification webhooks (optional, Enterprise)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Scanning options
INPUT_CONSOLE_ENABLED=true
INPUT_VERBOSE=false

Configuration File

Create .socket-basics.json in your project root:

{
  "python_sast_enabled": true,
  "javascript_sast_enabled": true,
  "secret_scanning_enabled": true,
  "console_tabular_enabled": true,
  "trufflehog_exclude_dir": "node_modules,vendor,dist",
  "python_disabled_rules": "unused-import"
}

Reference in hook:

socket-basics --config .socket-basics.json

Customization

Skip Hook When Needed

# Skip pre-commit hook for emergency commits
git commit --no-verify -m "Emergency fix"

Warning-Only Mode

Make the hook non-blocking but still show warnings:

#!/bin/bash
set -e

echo "🔍 Running Socket Basics security scan..."

socket-basics \
  --python-sast-enabled \
  --secret-scanning-enabled \
  --console-tabular-enabled

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "⚠️  Security issues found, but allowing commit."
  echo "Please review and fix these issues soon."
  # Don't exit with error - allow commit
  exit 0
fi

echo "✅ Security scan passed!"
exit 0

Severity Threshold

Only fail on high/critical issues:

#!/bin/bash
set -e

OUTPUT=$(socket-basics \
  --python-sast-enabled \
  --secret-scanning-enabled \
  --console-json-enabled 2>&1)

echo "$OUTPUT"

# Check if high or critical issues exist
if echo "$OUTPUT" | jq -e '.components[].alerts[] | select(.severity == "high" or .severity == "critical")' > /dev/null 2>&1; then
  echo "❌ High or critical security issues found!"
  exit 1
fi

echo "✅ No high/critical issues found!"
exit 0

Team-Wide Hook Distribution

Using pre-commit framework:

Install pre-commit:

pip install pre-commit

Create .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: socket-basics
        name: Socket Basics Security Scan
        entry: docker run --rm -v "$PWD:/workspace" socket-basics --workspace /workspace --python-sast-enabled --secret-scanning-enabled
        language: system
        pass_filenames: false

Team members install with:

pre-commit install

Troubleshooting

Hook Not Running

Problem: Pre-commit hook doesn't execute.

Solutions:

Verify hook is executable: chmod +x .git/hooks/pre-commit
Check shebang is correct: #!/bin/bash
Ensure no syntax errors: bash -n .git/hooks/pre-commit

Docker Permission Issues

Problem: Docker commands fail with permission errors.

Solutions:

Add user to docker group: sudo usermod -aG docker $USER
Run with sudo (not recommended): sudo docker run ...
Use Docker Desktop (macOS/Windows)

Slow Scan Times

Problem: Pre-commit hook takes too long.

Solutions:

Scan only changed files (see conditional scanning above)

Reduce scan scope:

socket-basics --secret-scanning-enabled  # Fast

Use warning-only mode for local commits
Run comprehensive scans only in CI/CD

Python Virtual Environment Issues

Problem: Hook can't find socket-basics command.

Solutions:

Activate venv in hook:
```
source .venv/bin/activate
```
Use absolute path:
```
/path/to/.venv/bin/socket-basics
```
Install globally: pip install --user socket-basics

False Positives

Problem: Scanner reports false positives.

Solutions:

Disable specific rules:

socket-basics \
  --python-sast-enabled \
  --python-disabled-rules "rule-id-1,rule-id-2"

Exclude directories:

socket-basics \
  --secret-scanning-enabled \
  --trufflehog-exclude-dir "test,fixtures,samples"

Use configuration file with exceptions

Enterprise Features Not Working

Problem: Dashboard configuration or notifications not working.

Solutions:

Verify .env file exists and is loaded in hook
Check SOCKET_ORG and SOCKET_SECURITY_API_KEY are set
Confirm Socket Enterprise subscription is active

Next Steps:

GitHub Actions Integration — Automated CI/CD scanning
Local Installation — Install security tools natively
Configuration Guide — Detailed configuration options

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pre-Commit Hook Setup

Table of Contents

Quick Start

Docker Installation (Recommended)

Prerequisites

Setup Steps

Docker Pre-Commit Configuration

Native Installation

Prerequisites

Setup Steps

Native Pre-Commit Configuration

Configuration

Speed vs Coverage Trade-offs

Conditional Scanning

Environment Variables

Configuration File

Customization

Skip Hook When Needed

Warning-Only Mode

Severity Threshold

Team-Wide Hook Distribution

Troubleshooting

Hook Not Running

Docker Permission Issues

Slow Scan Times

Python Virtual Environment Issues

False Positives

Enterprise Features Not Working

FilesExpand file tree

pre-commit-hook.md

Latest commit

History

pre-commit-hook.md

File metadata and controls

Pre-Commit Hook Setup

Table of Contents

Quick Start

Docker Installation (Recommended)

Prerequisites

Setup Steps

Docker Pre-Commit Configuration

Native Installation

Prerequisites

Setup Steps

Native Pre-Commit Configuration

Configuration

Speed vs Coverage Trade-offs

Conditional Scanning

Environment Variables

Configuration File

Customization

Skip Hook When Needed

Warning-Only Mode

Severity Threshold

Team-Wide Hook Distribution

Troubleshooting

Hook Not Running

Docker Permission Issues

Slow Scan Times

Python Virtual Environment Issues

False Positives

Enterprise Features Not Working