From e9a9cc9387071af96574c667a4d765006a348074 Mon Sep 17 00:00:00 2001
From: Douglas Coburn <douglas@dactbc.com>
Date: Mon, 20 Oct 2025 23:03:57 -0700
Subject: [PATCH] Fixed documentation and version checks

---
 .hooks/version-check.py      |  23 +-
 README.md                    |  10 +-
 docs/github-action.md        | 507 ++++++++++++++++++++++++
 docs/local-install-docker.md | 628 ++++++++++++++++++++++++++++++
 docs/local-installation.md   | 726 +++++++++++++++++++++++++++++++++++
 docs/parameters.md           | 597 ++++++++++++++++++++++++++++
 docs/pre-commit-hook.md      | 607 +++++++++++++++++++++++++++++
 pyproject.toml               |   2 +-
 socket_basics/version.py     |   2 +-
 9 files changed, 3090 insertions(+), 12 deletions(-)
 create mode 100644 docs/github-action.md
 create mode 100644 docs/local-install-docker.md
 create mode 100644 docs/local-installation.md
 create mode 100644 docs/parameters.md
 create mode 100644 docs/pre-commit-hook.md

diff --git a/.hooks/version-check.py b/.hooks/version-check.py
index ddb23a5..f639739 100755
--- a/.hooks/version-check.py
+++ b/.hooks/version-check.py
@@ -29,16 +29,24 @@
 PYPROJECT_FILE = pathlib.Path("pyproject.toml")
 README_FILES = [
     pathlib.Path("README.md"),
+    pathlib.Path("blog.md"),
     pathlib.Path("docs/github-action.md"),
     pathlib.Path("docs/pre-commit-hook.md"),
+    pathlib.Path("docs/local-install-docker.md"),
+    pathlib.Path("docs/version-management.md"),
+    pathlib.Path("docs/parameters.md"),
 ]
 
 VERSION_PATTERN = re.compile(r"__version__\s*=\s*['\"]([^'\"]+)['\"]")
 PYPROJECT_PATTERN = re.compile(r'^version\s*=\s*"([^"]+)"$', re.MULTILINE)
 # Pattern to match SocketDev/socket-basics@vX.X.X or @vX.X.X
 ACTION_VERSION_PATTERN = re.compile(r'(SocketDev/socket-basics|socket-basics)@v\d+\.\d+\.\d+')
-# Pattern to match docker build with version tag
-DOCKER_BUILD_PATTERN = re.compile(r'docker build -t (socketdev/socket-basics|socket-basics)(?::\d+\.\d+\.\d+)?')
+# Pattern to match docker build with optional version tag (handles both new and existing tags)
+DOCKER_BUILD_PATTERN = re.compile(r'docker build (?:--platform [^\s]+ )?-t ([^\s:]+)(?::\d+\.\d+\.\d+)?')
+# Pattern to match docker run commands with version tags
+DOCKER_RUN_PATTERN = re.compile(r'(docker run [^\n]*?)([^\s:]+):(\d+\.\d+\.\d+)')
+# Pattern to match standalone image references with version (in docker run or other contexts)
+IMAGE_VERSION_PATTERN = re.compile(r'\b(socket-basics|socketdev/socket-basics|myorg/security-scanner):(\d+\.\d+\.\d+)\b')
 # Update this URL to match your actual PyPI package if you publish it
 PYPI_API = "https://pypi.org/pypi/security-wrapper/json"
 
@@ -113,10 +121,15 @@ def update_readme_versions(version: str):
         content = ACTION_VERSION_PATTERN.sub(rf'\1@v{version}', content)
         
         # Update docker build commands to include version tag
-        def docker_replacement(match):
+        def docker_build_replacement(match):
+            # Group 0 is the whole match, group 1 is the image name
+            prefix = match.group(0).split('-t')[0] + '-t '
             image_name = match.group(1)
-            return f'docker build -t {image_name}:{version}'
-        content = DOCKER_BUILD_PATTERN.sub(docker_replacement, content)
+            return f'{prefix}{image_name}:{version}'
+        content = DOCKER_BUILD_PATTERN.sub(docker_build_replacement, content)
+        
+        # Update standalone image references with version (e.g., socket-basics:1.0.2)
+        content = IMAGE_VERSION_PATTERN.sub(rf'\1:{version}', content)
         
         if content != original_content:
             readme_file.write_text(content)
diff --git a/README.md b/README.md
index d12205b..66a5573 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v4
       
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v1.0.3
+        uses: SocketDev/socket-basics@v1.0.4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
@@ -106,7 +106,7 @@ Configure scanning policies, notification channels, and rule sets for your entir
 
 **Dashboard-Configured (Enterprise):**
 ```yaml
-- uses: SocketDev/socket-basics@v1.0.3
+- uses: SocketDev/socket-basics@v1.0.4
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
@@ -115,7 +115,7 @@ Configure scanning policies, notification channels, and rule sets for your entir
 
 **CLI-Configured:**
 ```yaml
-- uses: SocketDev/socket-basics@v1.0.3
+- uses: SocketDev/socket-basics@v1.0.4
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     python_sast_enabled: 'true'
@@ -129,10 +129,10 @@ Configure scanning policies, notification channels, and rule sets for your entir
 
 ```bash
 # Build with version tag
-docker build -t socketdev/socket-basics:1.0.3 .
+docker build -t socketdev/socket-basics:1.0.4 .
 
 # Run scan
-docker run --rm -v "$PWD:/workspace" socketdev/socket-basics:1.0.3 \
+docker run --rm -v "$PWD:/workspace" socketdev/socket-basics:1.0.4 \
   --workspace /workspace \
   --python-sast-enabled \
   --secret-scanning-enabled \
diff --git a/docs/github-action.md b/docs/github-action.md
new file mode 100644
index 0000000..617c23d
--- /dev/null
+++ b/docs/github-action.md
@@ -0,0 +1,507 @@
+# GitHub Actions Integration
+
+Complete guide to integrating Socket Basics into your GitHub Actions workflows for automated security scanning.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Basic Configuration](#basic-configuration)
+- [Enterprise Features](#enterprise-features)
+- [Advanced Workflows](#advanced-workflows)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+Add Socket Basics to your workflow in 3 steps:
+
+1. **Create workflow file** at `.github/workflows/security-scan.yml`
+2. **Add required secrets** to your repository
+3. **Configure scanning options**
+
+### Minimal Example
+
+```yaml
+name: Security Scan
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Run Socket Basics
+        uses: SocketDev/socket-basics@v1.0.4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          python_sast_enabled: 'true'
+          secret_scanning_enabled: 'true'
+```
+
+This will:
+- ✅ Run Python SAST on all `.py` files
+- ✅ Scan for leaked secrets
+- ✅ Post results as a PR comment
+
+## Basic Configuration
+
+### Required Inputs
+
+**`github_token`** (required)
+- GitHub token for posting PR comments and API access
+- Use `${{ secrets.GITHUB_TOKEN }}` (automatically provided)
+
+### Common Scanning Options
+
+**SAST (Static Analysis):**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    # Enable SAST for specific languages
+    python_sast_enabled: 'true'
+    javascript_sast_enabled: 'true'
+    go_sast_enabled: 'true'
+    java_sast_enabled: 'true'
+    # Or enable all languages
+    all_languages_enabled: 'true'
+```
+
+**Secret Scanning:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    secret_scanning_enabled: 'true'
+    # Optional: exclude directories
+    trufflehog_exclude_dir: 'node_modules,vendor,dist'
+    # Optional: show unverified secrets
+    trufflehog_show_unverified: 'true'
+```
+
+**Container Scanning:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    # Scan Docker images (auto-enables container scanning)
+    container_images: 'myorg/myapp:latest,redis:7'
+    # Scan Dockerfiles (auto-enables Dockerfile scanning)
+    dockerfiles: 'Dockerfile,docker/Dockerfile.prod'
+```
+
+**Socket Tier 1 Reachability:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_tier_1_enabled: 'true'
+```
+
+### Output Configuration
+
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    python_sast_enabled: 'true'
+    # Enable tabular console output
+    console_tabular_enabled: 'true'
+    # Or enable JSON output
+    console_json_enabled: 'true'
+    # Enable verbose logging for debugging
+    verbose: 'true'
+```
+
+## Enterprise Features
+
+Socket Basics Enterprise features require a [Socket Enterprise](https://socket.dev/enterprise) subscription.
+
+### Dashboard Configuration
+
+Configure Socket Basics centrally from the [Socket Dashboard](https://socket.dev/dashboard):
+
+![Socket Basics Settings](screenshots/socket_basics_settings.png)
+
+**Setup:**
+1. Log in to [Socket Dashboard](https://socket.dev/dashboard)
+2. Navigate to Settings → Socket Basics
+3. Configure scanning policies, notification channels, and rule sets
+4. Save your configuration
+
+**Enable in workflow:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    # Dashboard configuration (Enterprise required)
+    socket_org: 'your-org-slug'
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+```
+
+Your workflow will automatically use the settings configured in the dashboard.
+
+![Socket Basics Section Configuration](screenshots/socket_basics_section_config.png)
+
+### Notification Integrations
+
+All notification integrations require Socket Enterprise.
+
+**Slack Notifications:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_org: ${{ secrets.SOCKET_ORG }}
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    python_sast_enabled: 'true'
+    # Slack webhook (Enterprise required)
+    slack_webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
+
+**Jira Issue Creation:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_org: ${{ secrets.SOCKET_ORG }}
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    python_sast_enabled: 'true'
+    # Jira integration (Enterprise required)
+    jira_url: 'https://your-org.atlassian.net'
+    jira_email: ${{ secrets.JIRA_EMAIL }}
+    jira_api_token: ${{ secrets.JIRA_API_TOKEN }}
+    jira_project: 'SEC'
+```
+
+**Microsoft Teams:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_org: ${{ secrets.SOCKET_ORG }}
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    python_sast_enabled: 'true'
+    # MS Teams webhook (Enterprise required)
+    msteams_webhook_url: ${{ secrets.MSTEAMS_WEBHOOK_URL }}
+```
+
+**Generic Webhook:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_org: ${{ secrets.SOCKET_ORG }}
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    python_sast_enabled: 'true'
+    # Generic webhook (Enterprise required)
+    webhook_url: ${{ secrets.WEBHOOK_URL }}
+```
+
+**SIEM Integration:**
+```yaml
+- uses: SocketDev/socket-basics@v1.0.4
+  with:
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+    socket_org: ${{ secrets.SOCKET_ORG }}
+    socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    python_sast_enabled: 'true'
+    # Microsoft Sentinel (Enterprise required)
+    ms_sentinel_workspace_id: ${{ secrets.MS_SENTINEL_WORKSPACE_ID }}
+    ms_sentinel_shared_key: ${{ secrets.MS_SENTINEL_SHARED_KEY }}
+    # Sumo Logic (Enterprise required)
+    sumologic_endpoint: ${{ secrets.SUMOLOGIC_ENDPOINT }}
+```
+
+## Advanced Workflows
+
+### Multi-Language Scan
+
+```yaml
+name: Comprehensive Security Scan
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Run Socket Basics
+        uses: SocketDev/socket-basics@v1.0.4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          socket_org: ${{ secrets.SOCKET_ORG }}
+          socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          
+          # Enable multiple languages
+          python_sast_enabled: 'true'
+          javascript_sast_enabled: 'true'
+          typescript_sast_enabled: 'true'
+          go_sast_enabled: 'true'
+          
+          # Security scans
+          secret_scanning_enabled: 'true'
+          socket_tier_1_enabled: 'true'
+          
+          # Container scanning
+          dockerfiles: 'Dockerfile'
+          
+          # Notifications (Enterprise)
+          slack_webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
+
+### Scheduled Scanning
+
+```yaml
+name: Weekly Security Audit
+on:
+  schedule:
+    # Run every Monday at 9 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Run Full Security Scan
+        uses: SocketDev/socket-basics@v1.0.4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          socket_org: ${{ secrets.SOCKET_ORG }}
+          socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          
+          # Scan all supported languages
+          all_languages_enabled: 'true'
+          
+          # Enable all security features
+          secret_scanning_enabled: 'true'
+          socket_tier_1_enabled: 'true'
+          
+          # Verbose output for audit trail
+          verbose: 'true'
+          console_tabular_enabled: 'true'
+          
+          # Send to multiple channels (Enterprise)
+          slack_webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
+          jira_url: ${{ secrets.JIRA_URL }}
+          jira_email: ${{ secrets.JIRA_EMAIL }}
+          jira_api_token: ${{ secrets.JIRA_API_TOKEN }}
+          jira_project: 'SEC'
+```
+
+### Container Security Pipeline
+
+```yaml
+name: Container Security
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'Dockerfile*'
+      - 'docker/**'
+
+jobs:
+  container-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Build Docker Image
+        run: docker build -t myapp:1.0.4:${{ github.sha }} .
+      
+      - name: Scan Container
+        uses: SocketDev/socket-basics@v1.0.4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          
+          # Scan built image and Dockerfile
+          container_images: 'myapp:${{ github.sha }}'
+          dockerfiles: 'Dockerfile'
+          
+          # Additional Trivy options
+          trivy_vuln_enabled: 'true'
+```
+
+### Custom Rule Configuration
+
+```yaml
+name: Security Scan with Custom Rules
+on: [pull_request]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Run Socket Basics
+        uses: SocketDev/socket-basics@v1.0.4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          
+          # Enable Python SAST
+          python_sast_enabled: 'true'
+          
+          # Enable specific Python rules
+          python_enabled_rules: 'sql-injection,xss,hardcoded-credentials'
+          
+          # Disable noisy rules
+          python_disabled_rules: 'unused-import,line-too-long'
+          
+          # JavaScript with custom rules
+          javascript_sast_enabled: 'true'
+          javascript_enabled_rules: 'eval-usage,prototype-pollution'
+```
+
+## Configuration Reference
+
+### All Available Inputs
+
+See [`action.yml`](../action.yml) for the complete list of inputs.
+
+**Core Configuration:**
+- `socket_org` — Socket organization slug (Enterprise)
+- `socket_security_api_key` — Socket Security API key (Enterprise)
+- `github_token` — GitHub token (required)
+- `verbose` — Enable verbose logging
+- `console_tabular_enabled` — Tabular console output
+- `console_json_enabled` — JSON console output
+
+**SAST Languages:**
+- `all_languages_enabled` — Enable all languages
+- `python_sast_enabled`, `javascript_sast_enabled`, `typescript_sast_enabled`
+- `go_sast_enabled`, `golang_sast_enabled`
+- `java_sast_enabled`, `php_sast_enabled`, `ruby_sast_enabled`
+- `csharp_sast_enabled`, `dotnet_sast_enabled`
+- `c_sast_enabled`, `cpp_sast_enabled`
+- `kotlin_sast_enabled`, `scala_sast_enabled`, `swift_sast_enabled`
+- `rust_sast_enabled`, `elixir_sast_enabled`
+
+**Rule Configuration (per language):**
+- `<language>_enabled_rules` — Comma-separated rules to enable
+- `<language>_disabled_rules` — Comma-separated rules to disable
+
+**Security Scanning:**
+- `secret_scanning_enabled` — Enable secret scanning
+- `trufflehog_exclude_dir` — Directories to exclude
+- `trufflehog_show_unverified` — Show unverified secrets
+- `socket_tier_1_enabled` — Socket Tier 1 reachability
+
+**Container Scanning:**
+- `container_images` — Comma-separated images to scan
+- `dockerfiles` — Comma-separated Dockerfiles to scan
+- `trivy_disabled_rules` — Trivy rules to disable
+- `trivy_vuln_enabled` — Enable vulnerability scanning
+
+**Notifications (Enterprise Required):**
+- `slack_webhook_url` — Slack webhook
+- `jira_url`, `jira_email`, `jira_api_token`, `jira_project` — Jira config
+- `msteams_webhook_url` — MS Teams webhook
+- `webhook_url` — Generic webhook
+- `ms_sentinel_workspace_id`, `ms_sentinel_shared_key` — MS Sentinel
+- `sumologic_endpoint` — Sumo Logic
+
+**Storage:**
+- `s3_enabled`, `s3_bucket`, `s3_access_key`, `s3_secret_key` — S3 upload
+
+### Environment Variables
+
+All inputs support both standard and `INPUT_` prefixed environment variables:
+
+```yaml
+env:
+  INPUT_PYTHON_SAST_ENABLED: 'true'
+  INPUT_SECRET_SCANNING_ENABLED: 'true'
+  SOCKET_ORG: ${{ secrets.SOCKET_ORG }}
+  SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+```
+
+## Troubleshooting
+
+### Action Not Finding Files
+
+**Problem:** Scanner reports no files found.
+
+**Solution:** Ensure `actions/checkout@v4` runs before Socket Basics:
+```yaml
+steps:
+  - uses: actions/checkout@v4  # Must be first
+  - uses: SocketDev/socket-basics@v1.0.4
+```
+
+### PR Comments Not Appearing
+
+**Problem:** Security findings don't appear as PR comments.
+
+**Solutions:**
+1. Verify `github_token` is provided
+2. Check workflow permissions:
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+### Container Scanning Fails
+
+**Problem:** Container image scanning fails.
+
+**Solutions:**
+1. Ensure Docker is available in runner
+2. For private images, add authentication:
+```yaml
+- name: Login to Registry
+  run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u "${{ secrets.DOCKER_USERNAME }}" --password-stdin
+```
+
+### Enterprise Features Not Working
+
+**Problem:** Dashboard configuration or notifications not working.
+
+**Solutions:**
+1. Verify Socket Enterprise subscription is active
+2. Check that `socket_org` and `socket_security_api_key` are set correctly
+3. Confirm API key has required permissions in Socket Dashboard
+
+### High Memory Usage
+
+**Problem:** Action runs out of memory.
+
+**Solutions:**
+1. Exclude large directories:
+```yaml
+trufflehog_exclude_dir: 'node_modules,vendor,dist,.git'
+```
+2. Scan specific languages instead of `all_languages_enabled`
+3. Use self-hosted runner with more resources
+
+### Rate Limiting
+
+**Problem:** GitHub API rate limit exceeded.
+
+**Solution:** Use a personal access token with higher limits:
+```yaml
+with:
+  github_token: ${{ secrets.GITHUB_PAT }}
+```
+
+## Example Results
+
+![Socket Basics Example Results](screenshots/socket_basics_example_results.png)
+
+---
+
+**Next Steps:**
+- [Pre-Commit Hook Setup](pre-commit-hook.md) — Catch issues before commit
+- [Local Installation](local-installation.md) — Run scans from your terminal
+- [Configuration Guide](configuration.md) — Detailed configuration options
diff --git a/docs/local-install-docker.md b/docs/local-install-docker.md
new file mode 100644
index 0000000..d4cce5c
--- /dev/null
+++ b/docs/local-install-docker.md
@@ -0,0 +1,628 @@
+# Local Docker Installation
+
+Run Socket Basics locally using Docker without installing any security tools on your host machine. This guide covers building the Docker image, mounting your code, and configuring environment variables.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Building the Docker Image](#building-the-docker-image)
+- [Running Scans](#running-scans)
+- [Environment Configuration](#environment-configuration)
+- [Advanced Usage](#advanced-usage)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+```bash
+# 1. Clone and build
+git clone https://github.com/SocketDev/socket-basics.git
+cd socket-basics
+docker build -t socket-basics:1.0.4 .
+
+# 2. Create .env file with your credentials
+cat > .env << 'EOF'
+SOCKET_SECURITY_API_KEY=your-api-key-here
+SOCKET_ORG=your-org-slug
+EOF
+
+# 3. Run a scan on your project
+docker run --rm \
+  -v "$PWD:/workspace" \
+  --env-file .env \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python \
+  --secrets \
+  --console-tabular-enabled
+```
+
+## Building the Docker Image
+
+### Standard Build
+
+```bash
+# Clone the repository
+git clone https://github.com/SocketDev/socket-basics.git
+cd socket-basics
+
+# Build with version tag
+docker build -t socket-basics:1.0.4 .
+
+# Or build with latest tag
+docker build -t socket-basics:1.0.4:latest .
+
+# Verify the build
+docker images | grep socket-basics
+```
+
+### Build with Custom Name
+
+```bash
+# Use your own image name
+docker build -t myorg/security-scanner:1.0.4 .
+
+# Build for specific platform (e.g., for M1/M2 Macs)
+docker build --platform linux/amd64 -t socket-basics:1.0.4 .
+```
+
+### Verify Installation
+
+```bash
+# Check that all tools are available in the container
+docker run --rm socket-basics:1.0.4 socket-basics --version
+docker run --rm socket-basics:1.0.4 socket --version
+docker run --rm socket-basics:1.0.4 trivy --version
+docker run --rm socket-basics:1.0.4 semgrep --version
+docker run --rm socket-basics:1.0.4 trufflehog --version
+```
+
+## Running Scans
+
+### Basic Scan with Volume Mount
+
+Mount your project directory into the container:
+
+```bash
+# Scan current directory
+docker run --rm \
+  -v "$PWD:/workspace" \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python \
+  --secrets \
+  --console-tabular-enabled
+```
+
+**Important:** The `-v` flag mounts your local directory into the container:
+- `-v "$PWD:/workspace"` — Mounts current directory to `/workspace` in container
+- `--workspace /workspace` — Tells Socket Basics where to find your code inside the container
+
+### Scan Different Directory
+
+```bash
+# Scan a specific project directory
+docker run --rm \
+  -v "/path/to/your/project:/workspace" \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --javascript \
+  --secrets
+```
+
+### Multiple Language Scan
+
+```bash
+docker run --rm \
+  -v "$PWD:/workspace" \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --all-languages \
+  --secrets \
+  --console-tabular-enabled
+```
+
+## Environment Configuration
+
+### Method 1: Using .env File (Recommended)
+
+Create a `.env` file in your project (add to `.gitignore`):
+
+```bash
+# .env
+# Socket Configuration (Required for Enterprise features)
+SOCKET_SECURITY_API_KEY=scrt_your_api_key_here
+SOCKET_ORG=your-organization-slug
+
+# GitHub Integration (for PR comments)
+GITHUB_TOKEN=ghp_your_github_token
+
+# Notification Integrations (Enterprise)
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/XXXX
+JIRA_URL=https://your-org.atlassian.net
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=your-jira-api-token
+JIRA_PROJECT=SEC
+
+# Microsoft Teams (Enterprise)
+MSTEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/...
+
+# SIEM Integration (Enterprise)
+MS_SENTINEL_WORKSPACE_ID=your-workspace-id
+MS_SENTINEL_SHARED_KEY=your-shared-key
+SUMOLOGIC_ENDPOINT=https://endpoint.sumologic.com/...
+
+# Scanning Options
+CONSOLE_TABULAR_ENABLED=true
+VERBOSE=false
+```
+
+**Run with .env file:**
+
+```bash
+docker run --rm \
+  -v "$PWD:/workspace" \
+  --env-file .env \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python \
+  --secrets
+```
+
+### Method 2: Inline Environment Variables
+
+Pass environment variables directly with `-e` flag:
+
+```bash
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -e "SOCKET_SECURITY_API_KEY=scrt_your_api_key" \
+  -e "SOCKET_ORG=your-org-slug" \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python \
+  --secrets \
+  --console-tabular-enabled
+```
+
+### Method 3: Multiple .env Files
+
+Load multiple configuration files:
+
+```bash
+# Create separate config files
+# .env.socket - Socket credentials
+# .env.notifiers - Notification settings
+# .env.scanning - Scanning preferences
+
+docker run --rm \
+  -v "$PWD:/workspace" \
+  --env-file .env.socket \
+  --env-file .env.notifiers \
+  --env-file .env.scanning \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --all-languages
+```
+
+### Method 4: Environment Variables from Host
+
+Use environment variables already set in your shell:
+
+```bash
+# Export variables in your shell
+export SOCKET_SECURITY_API_KEY="scrt_your_api_key"
+export SOCKET_ORG="your-org-slug"
+
+# Pass specific variables to container
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -e "SOCKET_SECURITY_API_KEY=$SOCKET_SECURITY_API_KEY" \
+  -e "SOCKET_ORG=$SOCKET_ORG" \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python
+```
+
+## Advanced Usage
+
+### Container Scanning with Docker-in-Docker
+
+To scan Docker images, you need to provide Docker socket access:
+
+```bash
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -v "/var/run/docker.sock:/var/run/docker.sock" \
+  --env-file .env \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --images "nginx:latest,redis:7" \
+  --console-tabular-enabled
+```
+
+**Security Note:** Mounting the Docker socket gives the container full Docker access. Only use with trusted images.
+
+### Save Results to File
+
+Mount a volume to save scan results:
+
+```bash
+# Create results directory
+mkdir -p ./scan-results
+
+# Run scan and save output
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -v "$PWD/scan-results:/results" \
+  --env-file .env \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --python \
+  --secrets \
+  --output /results/scan-results.json
+```
+
+### Interactive Mode
+
+Run the container interactively for debugging:
+
+```bash
+# Start interactive shell
+docker run --rm -it \
+  -v "$PWD:/workspace" \
+  --env-file .env \
+  --entrypoint /bin/bash \
+  socket-basics:1.0.4
+
+# Inside container, run commands manually:
+# cd /workspace
+# socket-basics --python --verbose
+# exit
+```
+
+### Run with Custom Configuration File
+
+Mount a configuration file into the container:
+
+```bash
+# Create config file
+cat > socket-config.json << 'EOF'
+{
+  "python_sast_enabled": true,
+  "javascript_sast_enabled": true,
+  "secrets_enabled": true,
+  "console_tabular_enabled": true,
+  "trufflehog_exclude_dir": "node_modules,vendor,dist"
+}
+EOF
+
+# Run with config file
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -v "$PWD/socket-config.json:/config.json" \
+  --env-file .env \
+  socket-basics:1.0.4 \
+  --workspace /workspace \
+  --config /config.json
+```
+
+### Scan Multiple Projects
+
+Create a script to scan multiple projects:
+
+```bash
+#!/bin/bash
+# scan-all.sh
+
+PROJECTS=(
+  "/path/to/project1"
+  "/path/to/project2"
+  "/path/to/project3"
+)
+
+for PROJECT in "${PROJECTS[@]}"; do
+  echo "Scanning $PROJECT..."
+  docker run --rm \
+    -v "$PROJECT:/workspace" \
+    --env-file .env \
+    socket-basics:1.0.4 \
+    --workspace /workspace \
+    --all-languages \
+    --secrets \
+    --console-tabular-enabled
+done
+```
+
+### CI/CD Integration
+
+**Example: Jenkins**
+
+```groovy
+pipeline {
+    agent any
+    
+    stages {
+        stage('Security Scan') {
+            steps {
+                script {
+                    docker.image('socket-basics:1.0.4').inside(
+                        "-v ${WORKSPACE}:/workspace --env-file .env"
+                    ) {
+                        sh '''
+                            socket-basics \
+                              --workspace /workspace \
+                              --all-languages \
+                              --secrets \
+                              --console-tabular-enabled
+                        '''
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+**Example: GitLab CI**
+
+```yaml
+security-scan:
+  image: socket-basics:1.0.4
+  stage: test
+  script:
+    - socket-basics
+        --workspace /builds/$CI_PROJECT_PATH
+        --all-languages
+        --secrets
+        --console-tabular-enabled
+  variables:
+    SOCKET_SECURITY_API_KEY: $SOCKET_SECURITY_API_KEY
+    SOCKET_ORG: $SOCKET_ORG
+```
+
+## Troubleshooting
+
+### Permission Issues
+
+**Problem:** Cannot write to mounted volumes or files.
+
+**Solutions:**
+
+1. Run as current user:
+   ```bash
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     --user "$(id -u):$(id -g)" \
+     socket-basics:1.0.4 \
+     --workspace /workspace
+   ```
+
+2. Fix ownership after scan:
+   ```bash
+   sudo chown -R $USER:$USER ./scan-results
+   ```
+
+### Volume Mount Not Working
+
+**Problem:** Container can't see project files.
+
+**Solutions:**
+
+1. Use absolute paths:
+   ```bash
+   docker run --rm \
+     -v "$(pwd):/workspace" \  # Use $(pwd) instead of $PWD
+     socket-basics:1.0.4
+   ```
+
+2. Verify mount:
+   ```bash
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     socket-basics:1.0.4 \
+     ls -la /workspace
+   ```
+
+### Environment Variables Not Loaded
+
+**Problem:** `.env` file variables not available in container.
+
+**Solutions:**
+
+1. Verify `.env` file location:
+   ```bash
+   ls -la .env
+   cat .env
+   ```
+
+2. Check file format (no spaces around `=`):
+   ```bash
+   # Correct:
+   SOCKET_ORG=myorg
+   
+   # Incorrect:
+   SOCKET_ORG = myorg
+   ```
+
+3. Use absolute path to .env:
+   ```bash
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     --env-file "$(pwd)/.env" \
+     socket-basics:1.0.4
+   ```
+
+### Docker Socket Permission Denied
+
+**Problem:** Cannot scan Docker images (permission denied on `/var/run/docker.sock`).
+
+**Solutions:**
+
+1. Add user to docker group:
+   ```bash
+   sudo usermod -aG docker $USER
+   newgrp docker
+   ```
+
+2. Run with sudo (not recommended):
+   ```bash
+   sudo docker run ...
+   ```
+
+### Container Image Too Large
+
+**Problem:** Docker image takes too much disk space.
+
+**Solutions:**
+
+1. Clean up old images:
+   ```bash
+   docker system prune -a
+   ```
+
+2. Use multi-stage build (already optimized in Dockerfile)
+
+3. Remove unused containers:
+   ```bash
+   docker container prune
+   ```
+
+### Slow Scan Performance
+
+**Problem:** Scans take too long.
+
+**Solutions:**
+
+1. Exclude unnecessary directories:
+   ```bash
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     socket-basics:1.0.4 \
+     --workspace /workspace \
+     --python \
+     --secrets \
+     --exclude-dir "node_modules,vendor,dist,.git"
+   ```
+
+2. Scan specific languages only instead of `--all-languages`
+
+3. Increase Docker resources (CPU/Memory) in Docker Desktop settings
+
+### Can't Access Results File
+
+**Problem:** Output file not accessible after scan.
+
+**Solutions:**
+
+1. Check mount path:
+   ```bash
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     socket-basics:1.0.4 \
+     --workspace /workspace \
+     --output /workspace/results.json  # Save to mounted directory
+   ```
+
+2. Use separate results volume:
+   ```bash
+   mkdir -p ./results
+   docker run --rm \
+     -v "$PWD:/workspace" \
+     -v "$PWD/results:/results" \
+     socket-basics:1.0.4 \
+     --workspace /workspace \
+     --output /results/scan.json
+   ```
+
+## Shell Aliases
+
+Add these to your `~/.bashrc` or `~/.zshrc` for quick access:
+
+```bash
+# Socket Basics Docker aliases
+alias sb-docker='docker run --rm -v "$PWD:/workspace" --env-file .env socket-basics:1.0.4 --workspace /workspace'
+alias sb-quick='sb-docker --secrets --console-tabular-enabled'
+alias sb-python='sb-docker --python --secrets --console-tabular-enabled'
+alias sb-js='sb-docker --javascript --secrets --console-tabular-enabled'
+alias sb-all='sb-docker --all-languages --secrets --socket-tier1 --console-tabular-enabled'
+
+# Rebuild image
+alias sb-build='docker build -t socket-basics:1.0.4 .'
+```
+
+Usage:
+```bash
+# Quick secret scan
+sb-quick
+
+# Full Python scan
+sb-python
+
+# Comprehensive scan
+sb-all
+```
+
+## Best Practices
+
+1. **Use .env files** — Keep credentials out of command history
+2. **Add .env to .gitignore** — Never commit secrets
+3. **Use version tags** — Build with specific version tags for reproducibility
+4. **Mount minimal volumes** — Only mount what you need to scan
+5. **Regular updates** — Pull latest changes and rebuild periodically
+6. **Resource limits** — Set CPU/memory limits for long-running scans
+7. **Verify mounts** — Check that your code is visible in the container
+
+## Example: Complete Workflow
+
+```bash
+#!/bin/bash
+# complete-scan.sh - Full Docker-based security scan workflow
+
+set -e
+
+# Configuration
+PROJECT_DIR="$(pwd)"
+RESULTS_DIR="./scan-results"
+IMAGE_NAME="socket-basics:1.0.4"
+ENV_FILE=".env"
+
+# Create results directory
+mkdir -p "$RESULTS_DIR"
+
+# Verify .env exists
+if [ ! -f "$ENV_FILE" ]; then
+    echo "❌ .env file not found. Creating template..."
+    cat > "$ENV_FILE" << 'EOF'
+SOCKET_SECURITY_API_KEY=your-api-key-here
+SOCKET_ORG=your-org-slug
+CONSOLE_TABULAR_ENABLED=true
+EOF
+    echo "⚠️  Please edit .env with your credentials"
+    exit 1
+fi
+
+echo "🔍 Starting security scan..."
+
+# Run comprehensive scan
+docker run --rm \
+  -v "$PROJECT_DIR:/workspace" \
+  -v "$RESULTS_DIR:/results" \
+  --env-file "$ENV_FILE" \
+  "$IMAGE_NAME" \
+  --workspace /workspace \
+  --all-languages \
+  --secrets \
+  --socket-tier1 \
+  --console-tabular-enabled \
+  --output /results/scan-$(date +%Y%m%d-%H%M%S).json
+
+echo "✅ Scan complete! Results saved to $RESULTS_DIR"
+```
+
+---
+
+**Next Steps:**
+- [Parameters Reference](parameters.md) — Complete CLI and environment variable reference
+- [GitHub Actions Integration](github-action.md) — Automate in CI/CD
+- [Pre-Commit Hook Setup](pre-commit-hook.md) — Catch issues before commit
+- [Local Installation](local-installation.md) — Install tools natively
diff --git a/docs/local-installation.md b/docs/local-installation.md
new file mode 100644
index 0000000..a17dcb8
--- /dev/null
+++ b/docs/local-installation.md
@@ -0,0 +1,726 @@
+# Local Installation Guide
+
+Complete guide to installing Socket Basics and all security tools for native execution on your local machine.
+
+## Table of Contents
+
+- [Quick Install](#quick-install)
+- [Prerequisites](#prerequisites)
+- [Socket Basics Installation](#socket-basics-installation)
+- [Security Tools Installation](#security-tools-installation)
+- [Verification](#verification)
+- [Configuration](#configuration)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Install
+
+For experienced users on macOS/Linux with Homebrew:
+
+```bash
+# Install Socket Basics
+pip install socket-basics
+
+# Install security tools
+brew install socket trivy semgrep trufflehog
+
+# Verify installation
+socket-basics --version
+socket --version
+trivy --version
+semgrep --version
+trufflehog --version
+```
+
+For detailed installation instructions, continue reading below.
+
+## Prerequisites
+
+### Required Software
+
+**Python 3.8 or higher:**
+
+```bash
+# 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):**
+
+```bash
+# Usually included with Python, verify:
+pip --version  # or pip3 --version
+
+# Install/upgrade if needed:
+python -m ensurepip --upgrade
+```
+
+**Git:**
+
+```bash
+# 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:**
+
+```bash
+# 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 PyPI (Recommended for Users)
+
+```bash
+# Create and activate virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install Socket Basics
+pip install socket-basics
+
+# Verify installation
+socket-basics --version
+```
+
+### Method 2: From Source (Recommended for Development)
+
+```bash
+# 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 3: Using uv (Fastest)
+
+```bash
+# 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 the ones you need:
+
+### Socket CLI (Dependency Analysis)
+
+**Required for:** Socket Tier 1 reachability analysis
+
+**Installation:**
+
+```bash
+# macOS/Linux with Homebrew:
+brew install socket
+
+# Using npm (if you have Node.js):
+npm install -g @socketsecurity/cli
+
+# Manual installation (Linux):
+curl -sSL https://socket.dev/install.sh | sh
+
+# Manual installation (macOS):
+curl -sSL https://socket.dev/install.sh | sh
+
+# Verify installation
+socket --version
+```
+
+**Configuration:**
+
+```bash
+# 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
+
+**Installation:**
+
+```bash
+# 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):
+docker pull aquasec/trivy:latest
+
+# Verify installation
+trivy --version
+```
+
+**Documentation:** https://github.com/aquasecurity/trivy
+
+### Semgrep/OpenGrep (SAST)
+
+**Required for:** Static Application Security Testing (SAST) for all languages
+
+**Installation:**
+
+```bash
+# macOS/Linux with Homebrew:
+brew install semgrep
+
+# Using pip:
+pip install semgrep
+
+# Using Docker (alternative):
+docker pull semgrep/semgrep:latest
+
+# Verify installation
+semgrep --version
+```
+
+**Configuration:**
+
+```bash
+# Login to Semgrep (optional, for custom rules):
+semgrep login
+
+# Or run without login using bundled rules
+semgrep --config=auto
+```
+
+**Documentation:** https://semgrep.dev/docs/
+
+### TruffleHog (Secret Scanning)
+
+**Required for:** Detecting leaked credentials, API keys, and secrets
+
+**Installation:**
+
+```bash
+# macOS/Linux with Homebrew:
+brew install trufflehog
+
+# Using Docker (alternative):
+docker pull trufflesecurity/trufflehog:latest
+
+# Manual installation (Linux):
+wget https://github.com/trufflesecurity/trufflehog/releases/latest/download/trufflehog_linux_amd64.tar.gz
+tar -xzf trufflehog_linux_amd64.tar.gz
+sudo mv trufflehog /usr/local/bin/
+
+# Manual installation (macOS):
+wget https://github.com/trufflesecurity/trufflehog/releases/latest/download/trufflehog_darwin_arm64.tar.gz
+tar -xzf trufflehog_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
+
+```bash
+# 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
+
+```bash
+# Test Socket CLI
+socket --version
+socket cdxgen --help
+
+# Test Trivy
+trivy --version
+trivy image --help
+
+# Test Semgrep
+semgrep --version
+semgrep --help
+
+# Test TruffleHog
+trufflehog --version
+trufflehog --help
+```
+
+### Complete System Check
+
+Create a test script `check-installation.sh`:
+
+```bash
+#!/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 Semgrep
+if ! command -v semgrep &> /dev/null; then
+    echo "⚠️  semgrep not found (needed for SAST)"
+else
+    echo "✅ semgrep found: $(semgrep --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:
+
+```bash
+chmod +x check-installation.sh
+./check-installation.sh
+```
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file in your project (add to `.gitignore`):
+
+```bash
+# 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:
+
+```bash
+# 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`:
+
+```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:
+
+```bash
+socket-basics --config .socket-basics.json
+```
+
+### Shell Aliases
+
+Add to your `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# 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:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+## Usage Examples
+
+### Basic Scans
+
+```bash
+# 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
+
+```bash
+# 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:latest,redis:7 \
+  --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
+
+```bash
+# 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
+```
+
+### Continuous Scanning
+
+Watch for file changes and re-scan:
+
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# Check if tool is in PATH
+which trivy  # or semgrep, 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:**
+```bash
+# 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:**
+1. Exclude unnecessary directories:
+   ```bash
+   socket-basics \
+     --python-sast-enabled \
+     --trufflehog-exclude-dir "node_modules,vendor,dist,.git"
+   ```
+
+2. Scan specific languages only:
+   ```bash
+   # Instead of --all-languages-enabled
+   socket-basics --python-sast-enabled --javascript-sast-enabled
+   ```
+
+3. Use faster storage (SSD vs HDD)
+
+4. Increase available RAM
+
+### Socket CLI Authentication
+
+**Problem:** Socket CLI authentication errors
+
+**Solutions:**
+```bash
+# Login interactively
+socket login
+
+# Or set API key
+export SOCKET_SECURITY_API_KEY="your-api-key"
+
+# Verify authentication
+socket info
+```
+
+### Semgrep/OpenGrep Errors
+
+**Problem:** Semgrep crashes or fails
+
+**Solutions:**
+```bash
+# Update Semgrep
+pip install --upgrade semgrep
+
+# Clear Semgrep cache
+rm -rf ~/.semgrep/cache
+
+# Test Semgrep standalone
+semgrep --config=auto --test test_file.py
+```
+
+### Python Version Conflicts
+
+**Problem:** Conflicts between Python 2 and Python 3
+
+**Solutions:**
+```bash
+# Always use python3 explicitly
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install socket-basics
+
+# Or set Python 3 as default
+alias python=python3
+alias pip=pip3
+```
+
+### macOS-Specific Issues
+
+**Problem:** Command line tools not found on macOS
+
+**Solutions:**
+```bash
+# 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](github-action.md) — Automate in CI/CD
+- [Pre-Commit Hook Setup](pre-commit-hook.md) — Catch issues before commit
+- [Configuration Guide](configuration.md) — Detailed configuration options
diff --git a/docs/parameters.md b/docs/parameters.md
new file mode 100644
index 0000000..0a0105f
--- /dev/null
+++ b/docs/parameters.md
@@ -0,0 +1,597 @@
+# Socket Basics Parameters Reference
+
+Complete reference for all CLI options and environment variables supported by Socket Basics.
+
+## Table of Contents
+
+- [Core Options](#core-options)
+- [Language Scanning](#language-scanning)
+- [Secret Scanning](#secret-scanning)
+- [Container Scanning](#container-scanning)
+- [Socket Integration](#socket-integration)
+- [Notification Options](#notification-options)
+- [Environment Variables](#environment-variables)
+- [Configuration File](#configuration-file)
+
+## Core Options
+
+### `--config CONFIG`
+Path to JSON configuration file. JSON config is merged with environment variables (environment takes precedence).
+
+**Example:**
+```bash
+socket-basics --config /path/to/config.json
+```
+
+### `--output OUTPUT`
+Output file name for scan results.
+
+**Default:** `.socket.facts.json`
+
+**Example:**
+```bash
+socket-basics --output scan-results.json
+```
+
+### `--workspace WORKSPACE`
+Workspace directory to scan.
+
+**Default:** Current directory
+
+**Example:**
+```bash
+socket-basics --workspace /path/to/project
+```
+
+### `--repo REPO`
+Repository name (use when workspace is not a git repo).
+
+**Example:**
+```bash
+socket-basics --repo myorg/myproject
+```
+
+### `--branch BRANCH`
+Branch name (use when workspace is not a git repo).
+
+**Example:**
+```bash
+socket-basics --branch main
+```
+
+### `--default-branch`
+Explicitly mark this as the default branch (sets `make_default_branch=true` and `set_as_pending_head=true`).
+
+**Example:**
+```bash
+socket-basics --default-branch
+```
+
+### `--commit-message COMMIT_MESSAGE`
+Commit message for full scan submission.
+
+**Example:**
+```bash
+socket-basics --commit-message "feat: add new feature"
+```
+
+### `--pull-request PULL_REQUEST`
+Pull request number for full scan submission.
+
+**Example:**
+```bash
+socket-basics --pull-request 123
+```
+
+### `--committers COMMITTERS`
+Comma-separated list of committers for full scan submission.
+
+**Example:**
+```bash
+socket-basics --committers "user1@example.com,user2@example.com"
+```
+
+### `--scan-files SCAN_FILES`
+Comma-separated list of files to scan.
+
+**Example:**
+```bash
+socket-basics --scan-files "src/app.py,src/utils.js"
+```
+
+### `--changed-files CHANGED_FILES`
+Comma-separated list of files to scan or 'auto' to detect changed files from git.
+
+**Example:**
+```bash
+socket-basics --changed-files auto
+```
+
+### `--console-tabular-enabled`
+Enable consolidated console tabular output (displays results in formatted tables).
+
+**Example:**
+```bash
+socket-basics --console-tabular-enabled
+```
+
+### `--console-json-enabled`
+Enable consolidated console JSON output (displays results as JSON).
+
+**Example:**
+```bash
+socket-basics --console-json-enabled
+```
+
+### `--verbose`, `-v`
+Enable verbose logging for debugging.
+
+**Example:**
+```bash
+socket-basics --verbose
+```
+
+### `--enable-s3-upload`
+Enable uploading the output file to S3 using `SOCKET_S3_*` environment variables.
+
+**Example:**
+```bash
+socket-basics --enable-s3-upload
+```
+
+## Language Scanning
+
+### Enabling Languages
+
+Use these flags to enable SAST (Static Application Security Testing) scanning for specific languages:
+
+- `--python` - Enable Python SAST scanning
+- `--javascript` - Enable JavaScript/TypeScript SAST scanning
+- `--go` or `--golang` - Enable Go SAST scanning
+- `--java` - Enable Java SAST scanning
+- `--php` - Enable PHP SAST scanning
+- `--ruby` - Enable Ruby SAST scanning
+- `--csharp` or `--dotnet` - Enable C#/.NET SAST scanning
+- `--c` - Enable C SAST scanning
+- `--cpp` - Enable C++ SAST scanning
+- `--kotlin` - Enable Kotlin SAST scanning
+- `--scala` - Enable Scala SAST scanning
+- `--swift` - Enable Swift SAST scanning
+- `--rust` - Enable Rust SAST scanning
+- `--elixir` - Enable Elixir SAST scanning
+- `--erlang` - Enable Erlang SAST scanning
+
+**Example:**
+```bash
+socket-basics --python --javascript --go
+```
+
+### `--all-languages`
+Enable SAST for all supported languages.
+
+**Example:**
+```bash
+socket-basics --all-languages
+```
+
+### `--all-rules`
+Run all bundled SAST rules regardless of language filters.
+
+**Example:**
+```bash
+socket-basics --all-rules
+```
+
+### Language-Specific Rule Configuration
+
+For each language, you can enable or disable specific rules:
+
+**Pattern:** `--<language>-enabled-rules` or `--<language>-disabled-rules`
+
+**Examples:**
+```bash
+# Enable specific Python rules
+socket-basics --python --python-enabled-rules "sql-injection,xss-detection"
+
+# Disable specific JavaScript rules
+socket-basics --javascript --javascript-disabled-rules "console-log,debugger-statement"
+
+# Enable specific Go rules
+socket-basics --go --go-enabled-rules "error-handling,sql-injection"
+```
+
+**Available for:**
+- `--python-enabled-rules` / `--python-disabled-rules`
+- `--javascript-enabled-rules` / `--javascript-disabled-rules`
+- `--go-enabled-rules` / `--go-disabled-rules`
+- `--java-enabled-rules` / `--java-disabled-rules`
+- `--php-enabled-rules` / `--php-disabled-rules`
+- `--ruby-enabled-rules` / `--ruby-disabled-rules`
+- `--csharp-enabled-rules` / `--csharp-disabled-rules`
+- `--dotnet-enabled-rules` / `--dotnet-disabled-rules`
+- `--c-enabled-rules` / `--c-disabled-rules`
+- `--cpp-enabled-rules` / `--cpp-disabled-rules`
+- `--kotlin-enabled-rules` / `--kotlin-disabled-rules`
+- `--scala-enabled-rules` / `--scala-disabled-rules`
+- `--swift-enabled-rules` / `--swift-disabled-rules`
+- `--rust-enabled-rules` / `--rust-disabled-rules`
+- `--elixir-enabled-rules` / `--elixir-disabled-rules`
+
+### `--opengrep-notify OPENGREP_NOTIFY`
+Notification method for OpenGrep SAST results (e.g., console, slack).
+
+**Example:**
+```bash
+socket-basics --python --opengrep-notify console
+```
+
+## Secret Scanning
+
+### `--secrets`
+Enable secret scanning using TruffleHog.
+
+**Example:**
+```bash
+socket-basics --secrets
+```
+
+### `--disable-secrets`
+Disable all secret scanning features.
+
+**Example:**
+```bash
+socket-basics --disable-secrets
+```
+
+### `--exclude-dir EXCLUDE_DIR`
+Comma-separated list of directories to exclude from secret scanning.
+
+**Example:**
+```bash
+socket-basics --secrets --exclude-dir "node_modules,vendor,dist,.git"
+```
+
+### `--trufflehog-notify TRUFFLEHOG_NOTIFY`
+Notification method for TruffleHog secret scanning results.
+
+**Example:**
+```bash
+socket-basics --secrets --trufflehog-notify slack
+```
+
+### `--show-unverified`
+Show unverified secrets in TruffleHog results (by default only verified secrets are shown).
+
+**Example:**
+```bash
+socket-basics --secrets --show-unverified
+```
+
+## Container Scanning
+
+### `--images IMAGES`
+Comma-separated list of container images to scan (auto-enables image scanning).
+
+**Example:**
+```bash
+socket-basics --images "nginx:latest,redis:7,postgres:15"
+```
+
+### `--dockerfiles DOCKERFILES`
+Comma-separated list of Dockerfiles to scan (auto-enables Dockerfile scanning).
+
+**Example:**
+```bash
+socket-basics --dockerfiles "Dockerfile,docker/Dockerfile.prod"
+```
+
+### `--trivy-notify TRIVY_NOTIFY`
+Notification method for Trivy container scanning results.
+
+**Example:**
+```bash
+socket-basics --images "nginx:latest" --trivy-notify console
+```
+
+### `--trivy-disabled-rules TRIVY_DISABLED_RULES`
+Comma-separated list of Trivy rules to disable.
+
+**Example:**
+```bash
+socket-basics --images "nginx:latest" --trivy-disabled-rules "CVE-2023-1234,CVE-2023-5678"
+```
+
+### `--trivy-image-scanning-disabled`
+Disable Trivy image scanning.
+
+**Example:**
+```bash
+socket-basics --trivy-image-scanning-disabled
+```
+
+### `--trivy-vuln-enabled`
+Enable Trivy vulnerability scanning for all supported language ecosystems.
+
+**Example:**
+```bash
+socket-basics --trivy-vuln-enabled
+```
+
+## Socket Integration
+
+### `--socket-tier1`
+Enable Socket Tier 1 reachability analysis for dependency scanning.
+
+**Example:**
+```bash
+socket-basics --socket-tier1
+```
+
+### `--socket-additional-params SOCKET_ADDITIONAL_PARAMS`
+Additional CLI params for 'socket scan reach' (comma or space separated).
+
+**Example:**
+```bash
+socket-basics --socket-tier1 --socket-additional-params "--view=full,--all"
+```
+
+## Notification Options
+
+### Slack
+
+**CLI Option:** `--slack-webhook-url SLACK_WEBHOOK_URL`
+
+**Environment Variables:** `SLACK_WEBHOOK_URL`, `INPUT_SLACK_WEBHOOK_URL`
+
+**Example:**
+```bash
+socket-basics --slack-webhook-url "https://hooks.slack.com/services/T00/B00/XXXX"
+```
+
+### Generic Webhook
+
+**CLI Option:** `--webhook-url WEBHOOK_URL`
+
+**Environment Variable:** `WEBHOOK_URL`
+
+**Example:**
+```bash
+socket-basics --webhook-url "https://api.example.com/webhook"
+```
+
+### Microsoft Sentinel
+
+**CLI Options:**
+- `--ms-sentinel-workspace-id MS_SENTINEL_WORKSPACE_ID`
+- `--ms-sentinel-key MS_SENTINEL_KEY`
+
+**Environment Variables:**
+- `MS_SENTINEL_WORKSPACE_ID`, `INPUT_MS_SENTINEL_WORKSPACE_ID`
+- `MS_SENTINEL_SHARED_KEY`, `INPUT_MS_SENTINEL_SHARED_KEY`
+
+**Example:**
+```bash
+socket-basics --ms-sentinel-workspace-id "your-id" --ms-sentinel-key "your-key"
+```
+
+### Sumo Logic
+
+**CLI Option:** `--sumologic-endpoint SUMOLOGIC_ENDPOINT`
+
+**Environment Variables:** `SUMOLOGIC_ENDPOINT`, `INPUT_SUMOLOGIC_ENDPOINT`, `SUMO_LOGIC_HTTP_SOURCE_URL`
+
+**Example:**
+```bash
+socket-basics --sumologic-endpoint "https://endpoint.sumologic.com/..."
+```
+
+### Jira
+
+**CLI Options:**
+- `--jira-url JIRA_URL`
+- `--jira-project JIRA_PROJECT`
+- `--jira-email JIRA_EMAIL`
+- `--jira-api-token JIRA_API_TOKEN`
+
+**Environment Variables:**
+- `JIRA_URL`, `INPUT_JIRA_URL`
+- `JIRA_PROJECT`, `INPUT_JIRA_PROJECT`
+- `JIRA_EMAIL`, `INPUT_JIRA_EMAIL`
+- `JIRA_API_TOKEN`, `INPUT_JIRA_API_TOKEN`
+
+**Example:**
+```bash
+socket-basics \
+  --jira-url "https://your-org.atlassian.net" \
+  --jira-project "SEC" \
+  --jira-email "you@example.com" \
+  --jira-api-token "your-token"
+```
+
+### GitHub Pull Request Comments
+
+**CLI Options:**
+- `--github-token GITHUB_TOKEN`
+- `--github-api-url GITHUB_API_URL`
+
+**Environment Variables:**
+- `GITHUB_TOKEN`, `INPUT_GITHUB_TOKEN`
+- `GITHUB_API_URL` (optional, defaults to public GitHub API)
+
+**Example:**
+```bash
+socket-basics --github-token "ghp_your_token"
+```
+
+### Microsoft Teams
+
+**CLI Option:** `--msteams-webhook-url MSTEAMS_WEBHOOK_URL`
+
+**Environment Variables:** `MSTEAMS_WEBHOOK_URL`, `INPUT_MSTEAMS_WEBHOOK_URL`
+
+**Example:**
+```bash
+socket-basics --msteams-webhook-url "https://outlook.office.com/webhook/..."
+```
+
+## Environment Variables
+
+### Socket Configuration
+
+| Variable | Aliases | Description |
+|----------|---------|-------------|
+| `SOCKET_SECURITY_API_KEY` | `SOCKET_API_KEY`, `SOCKET_SECURITY_API_TOKEN`, `INPUT_SOCKET_SECURITY_API_KEY`, `INPUT_SOCKET_API_KEY` | Socket Security API key |
+| `SOCKET_ORG` | `SOCKET_ORG_SLUG`, `INPUT_SOCKET_ORG` | Socket organization slug |
+
+### GitHub Integration
+
+| Variable | Aliases | Description |
+|----------|---------|-------------|
+| `GITHUB_TOKEN` | `INPUT_GITHUB_TOKEN` | GitHub token for API access and PR comments |
+| `GITHUB_REPOSITORY` | `INPUT_GITHUB_REPOSITORY` | Repository name (owner/repo) |
+| `GITHUB_PR_NUMBER` | `INPUT_PR_NUMBER` | Pull request number |
+| `GITHUB_WORKSPACE` | - | Workspace directory (auto-set in GitHub Actions) |
+| `GITHUB_ACTOR` | - | GitHub username who triggered the action |
+| `GITHUB_HEAD_REF` | - | Source branch for pull request |
+| `GITHUB_SHA` | - | Commit SHA |
+| `GITHUB_REF_NAME` | - | Branch or tag name |
+| `GITHUB_EVENT_PATH` | - | Path to event payload file |
+
+### Scanning Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `OUTPUT_DIR` | Directory for output files (default: current directory) |
+| `INPUT_SCAN_ALL` | Set to 'true' to scan all files |
+| `INPUT_SCAN_FILES` | Comma-separated list of files to scan |
+| `INPUT_CONSOLE_TABULAR_ENABLED` | Enable tabular console output |
+| `INPUT_VERBOSE` | Enable verbose logging |
+
+### S3 Upload Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `SOCKET_S3_ENABLED` | Set to 'true', '1', or 'yes' to enable S3 upload |
+| `SOCKET_S3_BUCKET` | S3 bucket name |
+| `SOCKET_S3_REGION` | S3 bucket region |
+| `SOCKET_S3_ACCESS_KEY_ID` | AWS access key ID |
+| `SOCKET_S3_SECRET_ACCESS_KEY` | AWS secret access key |
+
+### Notification Configuration
+
+All notification integrations support environment variables as alternatives to CLI options. See [Notification Options](#notification-options) for details.
+
+### OpenGrep/SAST Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `INPUT_OPENGREP_RULES_DIR` | Custom directory containing SAST rules |
+
+## Configuration File
+
+You can provide configuration via a JSON file using `--config`:
+
+### Example Configuration File
+
+```json
+{
+  "workspace": "/path/to/project",
+  "output": "security-scan.json",
+  "console_tabular_enabled": true,
+  "verbose": false,
+  
+  "python_sast_enabled": true,
+  "javascript_sast_enabled": true,
+  "go_sast_enabled": true,
+  
+  "secrets_enabled": true,
+  "trufflehog_exclude_dir": "node_modules,vendor,dist,.git",
+  "show_unverified": false,
+  
+  "socket_tier_1_enabled": true,
+  "socket_org": "your-org-slug",
+  "socket_api_key": "scrt_your_api_key",
+  
+  "images": "nginx:latest,redis:7",
+  "trivy_vuln_enabled": true,
+  
+  "slack_webhook_url": "https://hooks.slack.com/services/T00/B00/XXXX",
+  "github_token": "ghp_your_token"
+}
+```
+
+### Configuration Precedence
+
+Configuration is merged in the following order (later sources override earlier ones):
+
+1. Default values
+2. JSON configuration file (via `--config`)
+3. Environment variables
+4. Command-line arguments
+
+**Example:**
+```bash
+# JSON file sets python_sast_enabled: true
+# Environment has PYTHON_SAST_ENABLED=false
+# CLI has --javascript
+# Result: JavaScript enabled, Python disabled (env override), other settings from JSON
+socket-basics --config config.json --javascript
+```
+
+## Common Usage Patterns
+
+### Scan Python and JavaScript with Secrets
+
+```bash
+socket-basics \
+  --workspace /path/to/project \
+  --python \
+  --javascript \
+  --secrets \
+  --console-tabular-enabled
+```
+
+### Full Scan with All Features
+
+```bash
+socket-basics \
+  --workspace /path/to/project \
+  --all-languages \
+  --secrets \
+  --socket-tier1 \
+  --images "myapp:latest" \
+  --console-tabular-enabled \
+  --verbose
+```
+
+### Scan with Notifications
+
+```bash
+socket-basics \
+  --workspace /path/to/project \
+  --python \
+  --secrets \
+  --slack-webhook-url "https://hooks.slack.com/..." \
+  --github-token "ghp_..."
+```
+
+### CI/CD Scan (Changed Files Only)
+
+```bash
+socket-basics \
+  --changed-files auto \
+  --python \
+  --javascript \
+  --secrets \
+  --console-json-enabled
+```
+
+### Docker Container Scan
+
+```bash
+socket-basics \
+  --images "nginx:latest,postgres:15" \
+  --dockerfiles "Dockerfile" \
+  --trivy-vuln-enabled \
+  --console-tabular-enabled
+```
diff --git a/docs/pre-commit-hook.md b/docs/pre-commit-hook.md
new file mode 100644
index 0000000..0bb79e6
--- /dev/null
+++ b/docs/pre-commit-hook.md
@@ -0,0 +1,607 @@
+# Pre-Commit Hook Setup
+
+Catch security issues before they're committed to your repository using Socket Basics as a pre-commit hook.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Docker Installation (Recommended)](#docker-installation-recommended)
+- [Native Installation](#native-installation)
+- [Configuration](#configuration)
+- [Customization](#customization)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+**Choose your installation method:**
+
+1. **Docker** (Recommended) — No tool installation required, everything runs in a container
+2. **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:**
+
+```bash
+# 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.0.4 .
+```
+
+**2. Create pre-commit hook:**
+
+Create `.git/hooks/pre-commit` in your project:
+
+```bash
+#!/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:**
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+**4. Test the hook:**
+
+```bash
+# Try to commit a file
+git add .
+git commit -m "Test commit"
+```
+
+### Docker Pre-Commit Configuration
+
+**Scan only changed files:**
+
+```bash
+#!/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:**
+
+```bash
+#!/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:**
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+**Socket Basics:**
+```bash
+pip install socket-basics
+# Or for development:
+git clone https://github.com/SocketDev/socket-basics.git
+cd socket-basics
+pip install -e .
+```
+
+**Security tools:**
+
+See [Local Installation Guide](local-installation.md) for detailed instructions on installing:
+- Socket CLI
+- Trivy
+- Semgrep (OpenGrep)
+- TruffleHog
+
+### Setup Steps
+
+**1. Create pre-commit hook:**
+
+Create `.git/hooks/pre-commit`:
+
+```bash
+#!/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:**
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+**3. Test the hook:**
+
+```bash
+git add .
+git commit -m "Test commit"
+```
+
+### Native Pre-Commit Configuration
+
+**Fast scan (secrets only):**
+
+```bash
+#!/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:**
+
+```bash
+#!/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):**
+```bash
+socket-basics --secret-scanning-enabled
+```
+- Only scans for leaked secrets
+- Best for quick feedback during development
+
+**Balanced (30-60 seconds):**
+```bash
+socket-basics \
+  --python-sast-enabled \
+  --secret-scanning-enabled
+```
+- Language-specific SAST + secrets
+- Good balance of speed and coverage
+
+**Comprehensive (2-5 minutes):**
+```bash
+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:
+
+```bash
+#!/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`):
+
+```bash
+# 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:
+
+```json
+{
+  "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:
+
+```bash
+socket-basics --config .socket-basics.json
+```
+
+## Customization
+
+### Skip Hook When Needed
+
+```bash
+# 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:
+
+```bash
+#!/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:
+
+```bash
+#!/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](https://pre-commit.com/):
+```bash
+pip install pre-commit
+```
+
+Create `.pre-commit-config.yaml`:
+
+```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:
+```bash
+pre-commit install
+```
+
+## Troubleshooting
+
+### Hook Not Running
+
+**Problem:** Pre-commit hook doesn't execute.
+
+**Solutions:**
+1. Verify hook is executable: `chmod +x .git/hooks/pre-commit`
+2. Check shebang is correct: `#!/bin/bash`
+3. Ensure no syntax errors: `bash -n .git/hooks/pre-commit`
+
+### Docker Permission Issues
+
+**Problem:** Docker commands fail with permission errors.
+
+**Solutions:**
+1. Add user to docker group: `sudo usermod -aG docker $USER`
+2. Run with sudo (not recommended): `sudo docker run ...`
+3. Use Docker Desktop (macOS/Windows)
+
+### Slow Scan Times
+
+**Problem:** Pre-commit hook takes too long.
+
+**Solutions:**
+1. Scan only changed files (see conditional scanning above)
+2. Reduce scan scope:
+   ```bash
+   socket-basics --secret-scanning-enabled  # Fast
+   ```
+3. Use warning-only mode for local commits
+4. Run comprehensive scans only in CI/CD
+
+### Python Virtual Environment Issues
+
+**Problem:** Hook can't find socket-basics command.
+
+**Solutions:**
+1. Activate venv in hook:
+   ```bash
+   source .venv/bin/activate
+   ```
+2. Use absolute path:
+   ```bash
+   /path/to/.venv/bin/socket-basics
+   ```
+3. Install globally: `pip install --user socket-basics`
+
+### False Positives
+
+**Problem:** Scanner reports false positives.
+
+**Solutions:**
+1. Disable specific rules:
+   ```bash
+   socket-basics \
+     --python-sast-enabled \
+     --python-disabled-rules "rule-id-1,rule-id-2"
+   ```
+2. Exclude directories:
+   ```bash
+   socket-basics \
+     --secret-scanning-enabled \
+     --trufflehog-exclude-dir "test,fixtures,samples"
+   ```
+3. Use configuration file with exceptions
+
+### Enterprise Features Not Working
+
+**Problem:** Dashboard configuration or notifications not working.
+
+**Solutions:**
+1. Verify `.env` file exists and is loaded in hook
+2. Check `SOCKET_ORG` and `SOCKET_SECURITY_API_KEY` are set
+3. Confirm Socket Enterprise subscription is active
+
+---
+
+**Next Steps:**
+- [GitHub Actions Integration](github-action.md) — Automated CI/CD scanning
+- [Local Installation](local-installation.md) — Install security tools natively
+- [Configuration Guide](configuration.md) — Detailed configuration options
diff --git a/pyproject.toml b/pyproject.toml
index 3ad5b2a..f45dd34 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "socket_basics"
-version = "1.0.3"
+version = "1.0.4"
 description = "Socket Basics with integrated SAST, secret scanning, and container analysis"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/socket_basics/version.py b/socket_basics/version.py
index 976498a..92192ee 100644
--- a/socket_basics/version.py
+++ b/socket_basics/version.py
@@ -1 +1 @@
-__version__ = "1.0.3"
+__version__ = "1.0.4"