VulnScanner

A comprehensive vulnerability detection tool for source code repositories that combines multiple scanning techniques to identify security issues.

Features

Core Scanning Modules

• Technology Detection: Automatically identifies frameworks, languages, and libraries
• SBOM Generation: Creates Software Bill of Materials for dependency tracking
• CVE Matching: Cross-references dependencies against vulnerability databases
• Secrets Scanner: Detects hardcoded credentials and sensitive data
• Endpoint Extraction: Maps API endpoints and routes
• SAST Analysis: Static application security testing for code vulnerabilities

Advisory Sources

• NVD (National Vulnerability Database)
• GitHub Security Advisories
• OSV (Open Source Vulnerabilities)

Reporting Formats

• JSON for programmatic access
• SARIF for IDE integration
• HTML for human-readable reports

Installation

From Source

# Clone the repository
git clone https://github.com/example/vulnscanner.git
cd vulnscanner

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Using pip

pip install vulnscanner

Quick Start

Scan a Local Repository

vulnscanner scan --path /path/to/repo

Scan a Git Repository

vulnscanner scan --git-url https://github.com/example/repo.git

Generate Reports

# JSON report
vulnscanner scan --path /path/to/repo --output-json report.json

# SARIF report for IDE integration
vulnscanner scan --path /path/to/repo --output-sarif report.sarif

# HTML report
vulnscanner scan --path /path/to/repo --output-html report.html

Usage Examples

Basic Scan with Filtering

# Scan with minimum severity threshold
vulnscanner scan --path ./my-project --severity high

# Scan with specific confidence level
vulnscanner scan --path ./my-project --confidence confirmed

Offline Scanning

# Run without network access
vulnscanner scan --path ./my-project --offline

Custom Configuration

# Use custom config file
vulnscanner scan --path ./my-project --config vulnscanner.yml

Update Advisory Databases

# Update all advisory sources
vulnscanner update-advisories

# Update specific sources
vulnscanner update-advisories --sources nvd github

Configuration

Create a vulnscanner.yml file in your project root:

# Scanning options
concurrency: 4
min_severity: medium
min_confidence: high

# Skip specific modules
skip_cve: false
skip_secrets: false
skip_sast: false
skip_endpoints: false
skip_sbom: false

# Exclusions
exclude_paths:
  - node_modules
  - vendor
  - test
  - .git

# Network settings
skip_network: false
offline: false

# Plugin configuration
enable_plugins: true
plugins:
  - docker_scanner
  - license_checker

Suppressing False Positives

Create a .vulnignore file in your repository:

# Global suppressions
global:
  - type: secret
    id: AWS_ACCESS_KEY
    reason: "Test credential in documentation"

# File-specific suppressions
files:
  tests/fixtures/test_data.py:
    - type: hardcoded_password
      line: 42
      reason: "Mock password for unit tests"

Command Line Options

Scan Command

vulnscanner scan [OPTIONS]

Options:
  --path PATH                    Local repository path
  --git-url URL                  Git repository URL
  --token TOKEN                  Auth token for private repos
  --output-json PATH             JSON output file
  --output-sarif PATH            SARIF output file
  --output-html PATH             HTML report file
  --skip-network                 Skip network-dependent checks
  --offline                      Run in fully offline mode
  --allow-active                 Allow active/dynamic scanning
  --concurrency N                Number of parallel workers (default: 4)
  --plugins NAME                 Additional plugins to load
  --exclude PATH                 Paths to exclude from scanning
  --config PATH                  Configuration file path
  --severity LEVEL               Minimum severity level to report
  --confidence LEVEL             Minimum confidence level to report
  --fail-on SEVERITY             Exit with error if findings exceed severity
  -v, --verbose                  Enable verbose output
  -q, --quiet                    Suppress non-essential output
  --no-cache                     Disable caching

Other Commands

# Update vulnerability databases
vulnscanner update-advisories [--sources SOURCE] [--force]

# Initialize local database
vulnscanner init-db [--db-path PATH] [--force]

# List available plugins
vulnscanner list-plugins [--verbose]

Plugin Development

Create custom plugins by extending the base plugin class:

from vulnscanner.plugins.base import BasePlugin
from vulnscanner.core.models import Finding

class MyCustomPlugin(BasePlugin):
    name = "custom_scanner"
    version = "1.0.0"

    def scan(self, repo_path: str, metadata: dict) -> list[Finding]:
        findings = []
        # Your scanning logic here
        return findings

Output Examples

Finding Structure

{
  "type": "vulnerability",
  "severity": "high",
  "confidence": "confirmed",
  "title": "SQL Injection vulnerability",
  "description": "User input directly concatenated in SQL query",
  "file_path": "src/database.py",
  "line_number": 42,
  "cve_id": "CVE-2023-12345",
  "remediation": "Use parameterized queries",
  "references": ["https://cwe.mitre.org/data/definitions/89.html"]
}

Summary Report

Scan Results Summary
╭────────────┬───────╮
│ Severity   │ Count │
├────────────┼───────┤
│ Critical   │ 2     │
│ High       │ 5     │
│ Medium     │ 12    │
│ Low        │ 23    │
│ Info       │ 47    │
│ Total      │ 89    │
╰────────────┴───────╯

Scan completed in 45.3 seconds
Repository: my-project
Scanner version: 1.0.0

Security Considerations

• Defensive Use Only: This tool is designed for defensive security testing
• Private Repositories: Use authentication tokens for private repos
• Sensitive Data: Be cautious when sharing scan reports
• Rate Limiting: Respect API rate limits when fetching advisories

Requirements

• Python 3.8 or higher
• Git (for repository cloning)
• Internet connection (for advisory updates and CVE matching)

License

MIT License - See LICENSE file for details

Support

For issues, feature requests, or questions:

• GitHub Issues: https://github.com/example/vulnscanner/issues
• Documentation: https://vulnscanner.readthedocs.io