SCAN Plugin User Guide

Welcome to the comprehensive user guide for the SCAN (Sensitive Code Analyzer for Nerds) Gradle Plugin. This guide will walk you through everything you need to know to secure your codebase effectively.

Overview

SCAN (Sensitive Code Analyzer for Nerds) is a comprehensive security tool that helps protect your codebase from accidentally committed secrets. This guide covers everything from basic setup to advanced configuration and best practices.

Installation

The fastest way to get started with SCAN is to add it to your build.gradle.kts and run a scan:

plugins {
    id("io.github.theaniketraj.scan") version "2.0.0"
}

Run your first scan:

./gradlew scanForSecrets

That's it! SCAN will analyze your codebase with sensible defaults and report any potential security issues.

Installation

Gradle Kotlin DSL (build.gradle.kts)

plugins {
    id("io.github.theaniketraj.scan") version "2.0.0"
}

Gradle Groovy DSL (build.gradle)

plugins {
    id 'io.github.theaniketraj.scan' version '2.0.0'
}

Legacy Plugin Application

buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("io.github.theaniketraj:scan-gradle-plugin:2.0.0")
    }
}

apply(plugin = "io.github.theaniketraj.scan")

Basic Usage

The fastest way to get started with SCAN is to add it to your build.gradle.kts and run a scan:

plugins {
    id("io.github.theaniketraj.scan") version "2.0.0"
}

// Run the scan
./gradlew scanForSecrets

Configuration

Minimal Configuration

SCAN works out of the box with zero configuration:

// No configuration needed - SCAN uses intelligent defaults

Common Configurations

scan {
    // Fail the build if secrets are found (default: true)
    failOnSecrets = true
    
    // Include test files in scanning (default: true)
    scanTests = false
    
    // Generate HTML report (default: false)
    generateHtmlReport = true
    
    // Set entropy threshold for random string detection (default: 4.5)
    entropyThreshold = 5.0
    
    // Enable verbose output (default: false)
    verbose = true
}

Understanding Patterns

SCAN uses over 50 built-in patterns to detect common secret types:

• API keys (AWS, GitHub, Stripe, etc.)
• Database connection strings
• Private keys and certificates
• OAuth tokens and JWT secrets

Custom Patterns

Add organization-specific patterns:

scan {
    customPatterns = listOf(
        "COMPANY_API_[A-Z0-9]{32}",
        "INTERNAL_SECRET_.*"
    )
}

Output Formats

Choose between console, JSON, or HTML output:

scan {
    generateHtmlReport = true  // Creates detailed HTML report
    generateJsonReport = true  // Machine-readable JSON output
}

File Exclusions

Exclude files and directories from scanning:

scan {
    excludePatterns = setOf(
        "**/test/**",
        "**/build/**",
        "**/*.min.js"
    )
}

Understanding Results

Console Output

SCAN provides clear, actionable output:

> Task :scanForSecrets
🔍 SCAN: Analyzing 147 files for sensitive information...

❌ CRITICAL: AWS Access Key detected
   File: src/main/resources/application.yml:12
   Pattern: AWS Access Key
   Content: AKIAIOSFODNN7EXAMPLE
   
⚠️  WARNING: High entropy string detected
   File: src/main/kotlin/Config.kt:25
   Entropy: 4.8/5.0
   Content: dGhpc19pc19hX3Rlc3Rfc2VjcmV0XzEyMzQ1
   
✅ SAFE: Test API key (whitelisted)
   File: src/test/resources/test.properties:5
   Content: test_api_key_12345

📊 Scan Results:
   - Files scanned: 147
   - Secrets found: 1 critical, 1 warning
   - Scan duration: 2.3s

CI Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-java@v3
      with:
        java-version: '21'
        distribution: 'temurin'
    
    - name: Run Security Scan
      run: ./gradlew scanForSecrets
    
    - name: Upload Security Report
      if: always()
      uses: actions/upload-artifact@v3
      with:
        name: security-report
        path: build/reports/scan/

Troubleshooting

Common Issues

scan {
    scanTests = false
    // or
    excludePatterns = setOf("**/test/**")
}

Best Practices

Development Workflow

1. Run locally first: Always test SCAN locally before pushing
2. Start permissive: Begin with failOnSecrets = false to understand findings
3. Iterate gradually: Slowly tighten security as you clean up existing issues
4. Document exceptions: Use comments to explain why certain patterns are safe

Security Hygiene

1. Regular scans: Run SCAN on every commit
2. Review findings: Don't just ignore warnings
3. Update patterns: Keep custom patterns current
4. Document decisions: Record why certain patterns are excluded