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.

The CLI flags are the same in both: --python, --javascript, --secrets, --all-languages, --socket-tier1, --exclude-dir. These are the flag names socket-basics --help prints; the GitHub Action uses different names (python_sast_enabled, ...) and the CLI rejects those. See the name mapping.

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. Pull the Socket Basics Docker image:

# Pull the pre-built image (no build step required)
docker pull ghcr.io/socketdev/socket-basics:3.1.0

2. Create pre-commit hook:

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

#!/bin/bash

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" \
  ghcr.io/socketdev/socket-basics:3.1.0 \
  --workspace /workspace \
  --python \
  --javascript \
  --secrets \
  --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 staged files:

--changed-files auto scopes every scanner to the staged changes when there is no pull-request context, which is exactly what a pre-commit hook wants. Git runs inside the container against the mounted .git directory, so nothing else is needed.

#!/bin/bash

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

if [ -z "$(git diff --cached --name-only --diff-filter=ACMR)" ]; then
  echo "No files to scan"
  exit 0
fi

# Scope the scan to the staged changes
docker run --rm \
  -v "$PWD:/workspace" \
  ghcr.io/socketdev/socket-basics:3.1.0 \
  --workspace /workspace \
  --changed-files auto \
  --python \
  --secrets \
  --console-tabular-enabled

EXIT_CODE=$?

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

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 SOCKET_ORG="$SOCKET_ORG" \
  -e SOCKET_SECURITY_API_KEY="$SOCKET_SECURITY_API_KEY" \
  -e SLACK_WEBHOOK_URL="$SLACK_WEBHOOK_URL" \
  ghcr.io/socketdev/socket-basics:3.1.0 \
  --workspace /workspace \
  --python \
  --javascript \
  --secrets \
  --socket-tier1 \
  --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 pinned versions of:

Socket CLI
Trivy (required if you want native container scanning)
OpenGrep
TruffleHog

The Trivy section in that guide covers version guidance for native installs (including versions to avoid): Trivy (Container Scanning).

Setup Steps

1. Create pre-commit hook:

Create .git/hooks/pre-commit:

#!/bin/bash

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 \
  --javascript \
  --secrets \
  --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

echo "🔍 Quick security check..."

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

socket-basics \
  --secrets \
  --console-tabular-enabled

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

echo "✅ Scan passed!"
exit 0

Comprehensive scan:

#!/bin/bash

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 \
  --secrets \
  --socket-tier1 \
  --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 --secrets

Only scans for leaked secrets
Best for quick feedback during development

Balanced (30-60 seconds):

socket-basics \
  --python \
  --secrets

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

Comprehensive (2-5 minutes):

socket-basics \
  --all-languages \
  --secrets \
  --socket-tier1

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

Conditional Scanning

Only scan relevant languages based on file extensions:

#!/bin/bash

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"
fi

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

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

# Always scan for secrets
SCAN_ARGS="$SCAN_ARGS --secrets"

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_* names mirror the CLI flags; see docs/parameters.md#name-mapping)
INPUT_CONSOLE_TABULAR_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": "python-bare-except"
}

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

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

socket-basics \
  --python \
  --secrets \
  --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

OUTPUT=$(socket-basics \
  --python \
  --secrets \
  --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" ghcr.io/socketdev/socket-basics:3.1.0 --workspace /workspace --changed-files auto --python --secrets
        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 --secrets  # 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
```
Use the Docker hook instead. Socket Basics is not published to PyPI, so there is no global pip install.

False Positives

Problem: Scanner reports false positives.

Solutions:

Disable specific rules:

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

Exclude directories:

socket-basics \
  --secrets \
  --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
Parameters Reference — Every CLI flag, action input and environment variable, with the mapping between them

Navigation Menu

Uh oh!

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

Uh oh!

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