@diego007/security-scanner

Standalone npm package for comprehensive secret detection - uses TruffleHog's exact detection patterns without requiring the TruffleHog binary. This package provides consistent security scanning across all repositories.

Features

• 🔍 TruffleHog-Compatible Detection: Uses TruffleHog's exact regex patterns and detection logic extracted from 750+ detectors
• 🎯 Comprehensive Coverage: 100+ patterns covering major services (AWS, Stripe, GitHub, Slack, OpenAI, MongoDB, etc.)
• 🚀 Standalone: Pure npm package - no external binaries or dependencies required
• 📦 Easy Installation: Simple npm install - works out of the box
• 🪝 Pre-Commit Hooks: Works with Husky for automatic scanning on commits
• 🎨 Clear Output: Colorful, detailed output showing detected secrets with severity levels
• ⚡ Fast: Lightweight pattern matching with keyword pre-filtering - scans files in milliseconds
• 🧮 Entropy Filtering: Uses Shannon entropy calculation (ported from TruffleHog) to reduce false positives
• 🎯 False Positive Filtering: Filters out common false positives like "example", "test", placeholders, etc.
• 🔑 Keyword Pre-Filtering: Performance optimization - only scans files containing relevant keywords
• 🛡️ Production Ready: Tested and validated with comprehensive test suite

Installation

As a Development Dependency

npm install --save-dev @diego007/security-scanner

For Pre-Commit Hooks (with Husky)

npm install --save-dev @diego007/security-scanner husky
npx husky install
npx husky add .husky/pre-commit "npx @diego007/security-scanner --staged --fail"

Usage

Command Line

Scan Staged Files (Default)

npx @diego007/security-scanner

Scan All Files

npx @diego007/security-scanner --all-files

Fail on Secrets Found

npx @diego007/security-scanner --fail

Verbose Output

npx @diego007/security-scanner --verbose

Ignoring False Positives

When the scanner detects a false positive during pre-commit, you can ignore it by creating a .security-scanner.json file in your project root.

Quick Example

1. Scanner detects a false positive:

📄 src/config.js
  Line 10: AWS Secret Access Key
  Status: ⚠ Unverified
  Severity: CRITICAL

2. Create .security-scanner.json:

{
  "ignore": {
    "secrets": [
      {
        "file": "src/config.js",
        "line": 10,
        "pattern": "AWS Secret Access Key",
        "reason": "This is test data, not a real secret"
      }
    ]
  }
}

3. Commit again - the false positive is now ignored!

Common Use Cases

Ignore all secrets in test files:

{
  "ignore": {
    "patterns": ["^.*/test/.*$", "^.*\\.test\\.js$"]
  }
}

Ignore a specific file:

{
  "ignore": {
    "files": ["scripts/legacy-script.js"]
  }
}

Ignore deployment keys:

{
  "ignore": {
    "secrets": [
      {
        "file": "deployments/deploy-key.pem",
        "pattern": "RSA Private Key",
        "reason": "Deployment key for CI/CD"
      }
    ]
  }
}

See CONFIGURATION-GUIDE.md for complete documentation.

Configuration

You can configure the scanner to ignore false positives by creating a .security-scanner.json file in your project root:

{
  "ignore": {
    "files": [
      "**/*.pem",
      "**/test/**",
      "**/tests/**"
    ],
    "patterns": [
      "^.*/node_modules/.*$",
      "^.*\\.lock$"
    ],
    "secrets": [
      {
        "file": "deployments/deploy-key.pem",
        "line": 1,
        "pattern": "RSA Private Key",
        "reason": "This is a deployment key used in CI/CD, not a production secret"
      },
      {
        "file": "config/test-keys.json",
        "pattern": "AWS Secret Access Key",
        "reason": "Test file with example keys"
      },
      {
        "file": "**/test/**",
        "reason": "Ignore all secrets in test files"
      }
    ]
  },
  "excludePatterns": [
    "^.*\\.min\\.js$"
  ],
  "includeTestFiles": false
}

Configuration Options:

• ignore.files: Array of file paths or glob patterns to completely exclude from scanning
• ignore.patterns: Array of regex patterns to match against file paths
• ignore.secrets: Array of rules to ignore specific secrets (can specify file, line, pattern, and reason)
• excludePatterns: Additional regex patterns for file exclusion
• includeTestFiles: Whether to scan test files (default: false)

Supported Config Files:

• .security-scanner.json (JSON format)
• .secretscannerrc (JSON format)
• .security-scanner.js (JavaScript module that exports config)

Programmatic Usage

const { scanForSecrets } = require('@diego007/security-scanner');

const files = ['src/index.js', 'config/secrets.json'];
const results = await scanForSecrets(files, { verbose: true });

if (results.secretsFound.length > 0) {
  console.error('Secrets detected!');
  process.exit(1);
}

How It Works

1. Comprehensive Pattern Matching: Uses 100+ carefully crafted regex patterns to detect secrets
2. Service-Specific Detection: Detects secrets from 30+ major services (AWS, Stripe, GitHub, Google, Slack, etc.)
3. File Filtering: Automatically excludes binary files, node_modules, and other common exclusions
4. Git Integration: Can scan staged files or all tracked files
5. Severity Levels: Categorizes findings by severity (Critical, High, Medium, Low)

Supported Services

The scanner detects secrets from 30+ services including:

• Cloud: AWS, Azure, Google Cloud, DigitalOcean, Cloudflare
• Payment: Stripe, PayPal, Square, Braintree
• Code: GitHub, GitLab, Bitbucket
• Communication: Slack, Twilio, SendGrid, Mailgun
• Social: Facebook, Twitter, Instagram
• CI/CD: CircleCI, Travis CI, Jenkins
• Databases: PostgreSQL, MySQL, MongoDB, Redis
• Generic: API keys, tokens, passwords, private keys, JWT tokens
• And many more...

Documentation

• Configuration Guide - Complete guide on ignoring false positives
• Safeguards - Built-in safeguards to ensure intentional secret ignoring
• Example Configuration - Example configuration file

License

UNLICENSED - Internal use only