Local Installation Guide

Complete guide to installing Socket Basics and security tools for native execution on your local machine.

Quick Install
Prerequisites
Socket Basics Installation
Security Tools Installation
Verification
Configuration
Usage Examples
Troubleshooting

Quick Install

For experienced users on macOS/Linux with Homebrew:

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

# Install pinned security tools
brew install socket trivy trufflehog

# Install OpenGrep (SAST scanning)
curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash

# Verify installation
socket-basics --version
socket --version
trivy --version
opengrep --version
trufflehog --version

Note

The supported pre-built GitHub Action and Docker image paths currently ship without Trivy while we evaluate the safest way to bundle it with Basics again. If you need container or Dockerfile scanning today, use Trivy (Container Scanning) and review the upstream install path and artifacts carefully before adopting it in production CI.

For detailed installation instructions, continue reading below.

Prerequisites

Required Software

Python 3.8 or higher:

# Check Python version
python --version  # or python3 --version

# Install Python if needed
# macOS with Homebrew:
brew install python

# Ubuntu/Debian:
sudo apt update && sudo apt install python3 python3-pip python3-venv

# Windows:
# Download from https://www.python.org/downloads/

pip (Python package manager):

# Usually included with Python, verify:
pip --version  # or pip3 --version

# Install/upgrade if needed:
python -m ensurepip --upgrade

Git:

# Verify Git is installed
git --version

# Install if needed
# macOS: (included with Xcode Command Line Tools)
xcode-select --install

# Ubuntu/Debian:
sudo apt install git

# Windows:
# Download from https://git-scm.com/download/win

Optional but Recommended

Virtual environment manager:

# Using venv (built-in)
python -m venv --help

# Or install virtualenv
pip install virtualenv

# Or use uv (faster, modern alternative)
curl -LsSf https://astral.sh/uv/install.sh | sh

Socket Basics Installation

Method 1: From Source (Required - Not on PyPI)

Socket Basics is not published to PyPI. You must install from source:

# Clone the repository
git clone https://github.com/SocketDev/socket-basics.git
cd socket-basics

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

# Install in development mode
pip install -e .

# Or using uv (faster)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
pip install -e .

# Verify installation
socket-basics --version

Method 2: Using uv (Faster Alternative)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/SocketDev/socket-basics.git
cd socket-basics

# Create venv and install dependencies
uv venv
source .venv/bin/activate
uv sync
pip install -e .

Security Tools Installation

Socket Basics orchestrates multiple security tools. Install only the scanners you plan to use, and prefer exact version pins whenever your package manager supports them.

Socket CLI (Dependency Analysis)

Required for: Socket Tier 1 reachability analysis

Installation:

# Using npm (if you have Node.js):
npm install -g socket

# Verify installation
socket --version

Configuration:

# Login to Socket (requires Socket account)
socket login

# Or set API key directly
export SOCKET_SECURITY_API_KEY="your-api-key"

Documentation: https://docs.socket.dev/docs/cli

Trivy (Container Scanning)

Required for: Container image and Dockerfile vulnerability scanning

Important

The supported pre-built GitHub Action and Docker image paths currently ship without Trivy while we evaluate the safest way to bundle it with Basics again.

If you need Trivy before it formally returns to Socket Basics:

Pin the binary to v0.69.3 or the Docker image to aquasec/trivy:0.69.3.
Do not use v0.69.4 of the binary.
Audit any cached Docker Hub images for 0.69.5 and 0.69.6.

Aqua's official incident summary lists the known-safe Trivy binary range as v0.69.2 to v0.69.3; the corresponding Docker image tags are 0.69.2 to 0.69.3 without the v prefix. We standardize on v0.69.3 / Docker tag 0.69.3.

If you use Aqua's own GitHub Actions independently of Socket Basics, pin aquasecurity/trivy-action@v0.35.0 and aquasecurity/setup-trivy@v0.2.6 by full commit SHA rather than by tag.

Installation:

# macOS with Homebrew:
brew install trivy

# Ubuntu/Debian:
sudo apt-get install wget apt-transport-https gnupg lsb-release
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

# RHEL/CentOS:
sudo tee /etc/yum.repos.d/trivy.repo << 'EOF'
[trivy]
name=Trivy repository
baseurl=https://aquasecurity.github.io/trivy-repo/rpm/releases/$releasever/$basearch/
gpgcheck=0
enabled=1
EOF
sudo yum -y install trivy

# Using Docker (alternative; pin explicitly):
docker pull aquasec/trivy:0.69.3

# Verify installation
trivy --version

For this interim path, trivy --version should report Version: 0.69.3, and a container-based install should use image tag aquasec/trivy:0.69.3. If your package manager or container reference resolves to some other version, treat that as a separate review decision rather than assuming it matches the current Socket Basics guidance.

Documentation: https://github.com/aquasecurity/trivy

OpenGrep (SAST)

Required for: Static Application Security Testing (SAST) for all languages

Installation:

# Install OpenGrep using the official installer:
curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash

# Add to PATH (if not automatically added):
export PATH="$HOME/.opengrep/cli/latest:$PATH"

# Verify installation
opengrep --version

Configuration:

OpenGrep works with the bundled Socket Basics SAST rules. No additional configuration is required for basic usage.

Documentation: https://github.com/opengrep/opengrep

TruffleHog (Secret Scanning)

Required for: Detecting leaked credentials, API keys, and secrets

Installation:

# macOS/Linux with Homebrew:
brew install trufflehog

# Using Docker (alternative; pin explicitly):
docker pull trufflesecurity/trufflehog:v3.93.8

# Manual installation (Linux):
wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.93.8/trufflehog_3.93.8_linux_amd64.tar.gz
tar -xzf trufflehog_3.93.8_linux_amd64.tar.gz
sudo mv trufflehog /usr/local/bin/

# Manual installation (macOS):
wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.93.8/trufflehog_3.93.8_darwin_arm64.tar.gz
tar -xzf trufflehog_3.93.8_darwin_arm64.tar.gz
sudo mv trufflehog /usr/local/bin/

# Verify installation
trufflehog --version

Documentation: https://github.com/trufflesecurity/trufflehog

Verification

Test Socket Basics Installation

# Activate your virtual environment
source .venv/bin/activate

# Check version
socket-basics --version

# View help
socket-basics --help

# Test basic scan (dry run)
socket-basics --python-sast-enabled --verbose

Test Individual Tools

# Test Socket CLI
socket --version
socket cdxgen --help

# Test Trivy
trivy --version
trivy image --help

# Test OpenGrep
opengrep --version
opengrep --help

# Test TruffleHog
trufflehog --version
trufflehog --help

Complete System Check

Create a test script check-installation.sh:

#!/bin/bash

echo "Checking Socket Basics installation..."

ERRORS=0

# Check Python
if ! command -v python &> /dev/null && ! command -v python3 &> /dev/null; then
    echo "❌ Python not found"
    ERRORS=$((ERRORS+1))
else
    echo "✅ Python found: $(python --version 2>&1 || python3 --version 2>&1)"
fi

# Check Socket Basics
if ! command -v socket-basics &> /dev/null; then
    echo "❌ socket-basics not found"
    ERRORS=$((ERRORS+1))
else
    echo "✅ socket-basics found: $(socket-basics --version)"
fi

# Check Socket CLI
if ! command -v socket &> /dev/null; then
    echo "⚠️  socket CLI not found (needed for Socket Tier 1)"
else
    echo "✅ socket CLI found: $(socket --version)"
fi

# Check Trivy
if ! command -v trivy &> /dev/null; then
    echo "⚠️  trivy not found (needed for container scanning)"
else
    echo "✅ trivy found: $(trivy --version | head -1)"
fi

# Check OpenGrep
if ! command -v opengrep &> /dev/null; then
    echo "⚠️  opengrep not found (needed for SAST)"
else
    echo "✅ opengrep found: $(opengrep --version)"
fi

# Check TruffleHog
if ! command -v trufflehog &> /dev/null; then
    echo "⚠️  trufflehog not found (needed for secret scanning)"
else
    echo "✅ trufflehog found: $(trufflehog --version 2>&1 | head -1)"
fi

echo ""
if [ $ERRORS -eq 0 ]; then
    echo "✅ Core installation complete!"
    echo "⚠️  Missing tools will limit functionality but Socket Basics will still run."
else
    echo "❌ Installation incomplete. Please install missing components."
    exit 1
fi

Run the check:

chmod +x check-installation.sh
./check-installation.sh

Configuration

Environment Variables

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

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

# GitHub Integration (for PR comments)
GITHUB_TOKEN=your-github-token

# Notification Integrations (Enterprise)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
JIRA_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-jira-token
JIRA_PROJECT=SEC

# Scanning Options
INPUT_CONSOLE_ENABLED=true
INPUT_VERBOSE=false
INPUT_CONSOLE_TABULAR_ENABLED=true

Load environment variables:

# Option 1: Source the file
source .env

# Option 2: Use with export
export $(cat .env | grep -v '^#' | xargs)

# Option 3: Run with env prefix
env $(cat .env | grep -v '^#' | xargs) socket-basics --python-sast-enabled

Configuration File

Create .socket-basics.json:

{
  "workspace": ".",
  "python_sast_enabled": true,
  "javascript_sast_enabled": true,
  "secret_scanning_enabled": true,
  "console_tabular_enabled": true,
  "verbose": false,
  "trufflehog_exclude_dir": "node_modules,vendor,dist,.git",
  "python_disabled_rules": "unused-import,line-too-long",
  "socket_tier_1_enabled": false
}

Use configuration file:

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

Shell Aliases

Add to your ~/.bashrc or ~/.zshrc:

# Quick security scans
alias sb='socket-basics'
alias sb-quick='socket-basics --secret-scanning-enabled --console-tabular-enabled'
alias sb-python='socket-basics --python-sast-enabled --secret-scanning-enabled --console-tabular-enabled'
alias sb-js='socket-basics --javascript-sast-enabled --secret-scanning-enabled --console-tabular-enabled'
alias sb-full='socket-basics --all-languages-enabled --secret-scanning-enabled --socket-tier-1-enabled --console-tabular-enabled'

# With venv activation
alias sb-activate='source .venv/bin/activate && socket-basics'

Reload shell:

source ~/.bashrc  # or source ~/.zshrc

Usage Examples

Basic Scans

# Activate virtual environment
source .venv/bin/activate

# Quick secret scan
socket-basics --secret-scanning-enabled

# Python SAST + secrets
socket-basics --python-sast-enabled --secret-scanning-enabled

# JavaScript/TypeScript SAST + secrets
socket-basics --javascript-sast-enabled --typescript-sast-enabled --secret-scanning-enabled

# All languages
socket-basics --all-languages-enabled --secret-scanning-enabled

Advanced Scans

# With Socket Tier 1 reachability
socket-basics \
  --python-sast-enabled \
  --secret-scanning-enabled \
  --socket-tier-1-enabled \
  --socket-org your-org

# Container scanning
socket-basics \
  --container-images nginx:1.27.4,redis:7.4 \
  --dockerfiles Dockerfile,docker/Dockerfile.prod

# Scan specific workspace
socket-basics \
  --workspace /path/to/project \
  --python-sast-enabled \
  --secret-scanning-enabled

# Custom output file
socket-basics \
  --python-sast-enabled \
  --output ./security-results.json

With Enterprise Features

# Load environment variables
source .env

# Scan with Slack notifications
socket-basics \
  --python-sast-enabled \
  --secret-scanning-enabled \
  --socket-org $SOCKET_ORG \
  --console-tabular-enabled

# Scan with Jira ticket creation
socket-basics \
  --all-languages-enabled \
  --secret-scanning-enabled \
  --socket-org $SOCKET_ORG \
  --console-tabular-enabled

# Full enterprise scan
socket-basics \
  --all-languages-enabled \
  --secret-scanning-enabled \
  --socket-tier-1-enabled \
  --socket-org $SOCKET_ORG \
  --verbose

CI/CD Integration

Using GitHub Actions? Socket Basics has first-class GitHub Actions support with automatic PR comments, labels, and more — no local installation needed. See the Quick Start or the GitHub Actions Guide.

Continuous Scanning

Watch for file changes and re-scan:

# Install fswatch (macOS)
brew install fswatch

# Install inotify-tools (Linux)
sudo apt install inotify-tools

# Watch and scan on changes (macOS)
fswatch -o . | xargs -n1 -I{} socket-basics --python-sast-enabled --secret-scanning-enabled

# Watch and scan on changes (Linux)
while inotifywait -r -e modify .; do
  socket-basics --python-sast-enabled --secret-scanning-enabled
done

Troubleshooting

Virtual Environment Issues

Problem: socket-basics: command not found

Solutions:

# Ensure virtual environment is activated
source .venv/bin/activate

# Verify socket-basics is installed
pip list | grep socket-basics

# Reinstall if needed
pip install -e .

Tool Not Found Errors

Problem: Scanner reports tool not found (e.g., "trivy not found")

Solutions:

# Check if tool is in PATH
which trivy  # or opengrep, trufflehog, socket

# Add to PATH if needed
export PATH="/usr/local/bin:$PATH"

# Verify tool is executable
ls -l $(which trivy)

Permission Denied

Problem: Permission errors when running scans

Solutions:

# Ensure files are readable
chmod -R u+r /path/to/project

# Check directory permissions
ls -la /path/to/project

# Run with appropriate user permissions

Slow Scan Performance

Problem: Scans take too long

Solutions:

Exclude unnecessary directories:

socket-basics \
  --python-sast-enabled \
  --trufflehog-exclude-dir "node_modules,vendor,dist,.git"

Scan specific languages only:

# Instead of --all-languages-enabled
socket-basics --python-sast-enabled --javascript-sast-enabled

Use faster storage (SSD vs HDD)
Increase available RAM

Socket CLI Authentication

Problem: Socket CLI authentication errors

Solutions:

# Login interactively
socket login

# Or set API key
export SOCKET_SECURITY_API_KEY="your-api-key"

# Verify authentication
socket info

OpenGrep Errors

Problem: OpenGrep crashes or fails

Solutions:

# Reinstall OpenGrep
curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash

# Ensure OpenGrep is in PATH
export PATH="$HOME/.opengrep/cli/latest:$PATH"

# Test OpenGrep standalone
opengrep --version

Python Version Conflicts

Problem: Conflicts between Python 2 and Python 3

Solutions:

# Always use python3 explicitly
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

# Or set Python 3 as default
alias python=python3
alias pip=pip3

macOS-Specific Issues

Problem: Command line tools not found on macOS

Solutions:

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Next Steps:

GitHub Actions Integration — Automate in CI/CD
Pre-Commit Hook Setup — Catch issues before commit
Configuration Guide — Detailed configuration options

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Local Installation Guide

Table of Contents

Quick Install

Prerequisites

Required Software

Optional but Recommended

Socket Basics Installation

Method 1: From Source (Required - Not on PyPI)

Method 2: Using uv (Faster Alternative)

Security Tools Installation

Socket CLI (Dependency Analysis)

Trivy (Container Scanning)

OpenGrep (SAST)

TruffleHog (Secret Scanning)

Verification

Test Socket Basics Installation

Test Individual Tools

Complete System Check

Configuration

Environment Variables

Configuration File

Shell Aliases

Usage Examples

Basic Scans

Advanced Scans

With Enterprise Features

CI/CD Integration

Continuous Scanning

Troubleshooting

Virtual Environment Issues

Tool Not Found Errors

Permission Denied

Slow Scan Performance

Socket CLI Authentication

OpenGrep Errors

Python Version Conflicts

macOS-Specific Issues

FilesExpand file tree

local-installation.md

Latest commit

History

local-installation.md

File metadata and controls

Local Installation Guide

Table of Contents

Quick Install

Prerequisites

Required Software

Optional but Recommended

Socket Basics Installation

Method 1: From Source (Required - Not on PyPI)

Method 2: Using uv (Faster Alternative)

Security Tools Installation

Socket CLI (Dependency Analysis)

Trivy (Container Scanning)

OpenGrep (SAST)

TruffleHog (Secret Scanning)

Verification

Test Socket Basics Installation

Test Individual Tools

Complete System Check

Configuration

Environment Variables

Configuration File

Shell Aliases

Usage Examples

Basic Scans

Advanced Scans

With Enterprise Features

CI/CD Integration

Continuous Scanning

Troubleshooting

Virtual Environment Issues

Tool Not Found Errors

Permission Denied

Slow Scan Performance

Socket CLI Authentication

OpenGrep Errors

Python Version Conflicts

macOS-Specific Issues