A sophisticated tool for analyzing CVE vulnerabilities against Linux kernel configurations

VEX Kernel Checker is an advanced vulnerability analysis tool that correlates CVE (Common Vulnerabilities and Exposures) data with Linux kernel configurations to determine whether specific vulnerabilities affect a given kernel build. It processes VEX (Vulnerability Exploitability eXchange) files and provides automated analysis of vulnerability impact based on:

• Kernel configuration analysis - Maps CVEs to required CONFIG options
• Patch analysis - Extracts source files from security patches
• Makefile parsing - Analyzes build system dependencies
• Architecture awareness - Considers target architecture implications

vex-kernel-checker/
├── vex-kernel-checker.py          # Main CLI application (modular implementation)
├── vex_kernel_checker/            # Modular Python package
│   ├── __init__.py                # Package initialization
│   ├── common.py                  # Shared data structures and utilities
│   ├── base.py                    # Base classes and performance tracking
│   ├── cve_manager.py             # CVE data fetching and management
│   ├── config_analyzer.py         # Kernel configuration analysis
│   ├── vulnerability_analyzer.py  # Core vulnerability analysis logic
│   ├── patch_manager.py           # Patch fetching and analysis
│   ├── architecture_manager.py    # Architecture-specific logic
│   ├── report_generator.py        # VEX report generation
│   └── main_checker.py            # Main orchestration logic
├── tests/                         # Clean, comprehensive test suite
│   ├── run_tests.py               # Modern test runner with coverage
│   ├── test_common.py             # Tests for shared utilities
│   ├── test_base.py               # Tests for base functionality
│   ├── test_cve_manager.py        # CVE management tests
│   ├── test_config_analyzer.py    # Configuration analysis tests
│   ├── test_vulnerability_analyzer.py  # Core analysis tests
│   ├── test_patch_manager.py      # Patch management tests
│   ├── test_architecture_manager.py    # Architecture tests
│   ├── test_report_generator.py   # Report generation tests
│   └── test_integration.py        # End-to-end integration tests
├── examples/                      # Sample data and configurations
│   ├── README.md                  # Usage examples
│   ├── test_demo.config           # Sample kernel config
│   ├── test_vex.json              # Sample VEX file
│   └── [other samples]           # Test data and examples
├── docs/                          # Comprehensive documentation
├── scripts/                       # Development and utility scripts
├── README.md                      # Project documentation
├── requirements.txt               # Python dependencies
├── Dockerfile                     # Container build configuration
├── Makefile                       # Build and test automation
└── [other config files]          # Project configuration

• Multi-level caching system (Makefile, config, source analysis)
• Parallel processing for large vulnerability datasets
• Smart search ordering and aggressive optimization
• Cache hit/miss tracking with performance statistics

• Kernel CVE filtering: Automatically identifies and analyzes only kernel-related CVEs (use --analyze-all-cves to override)
• Driver-specific CONFIG detection: Intelligently extracts specific driver configs (e.g., CONFIG_DRM_XE) from CVE descriptions to avoid false positives from broad parent configs (e.g., CONFIG_DRM)
• GitHub-prioritized patch analysis: Fetches and analyzes security patches with GitHub as the primary source for reliability
• Config-only fallback: Graceful degradation when patch data unavailable
• Makefile intelligence: Recursive parsing with variable expansion
• Architecture filtering: ARM-focused analysis with multi-arch support
• AI-assisted triage (optional): Uses Claude AI to reduce manual triage by analyzing CVE relevance against actual kernel configuration

• Thread-safe NVD API rate limiting with exponential backoff
• Comprehensive error handling and validation
• Existing analysis preservation (only modifies with --reanalyse)
• Detailed progress reporting with status indicators

• Automatic patch checking when API credentials provided
• Intuitive command-line interface with helpful error messages
• Verbose mode for debugging and development
• Cache management with --clear-cache option

• Comprehensive test suite with >90% code coverage
• Performance benchmarking and optimization tracking
• Configuration validation and environment verification
• Continuous integration with automated quality checks
• MIT licensed with comprehensive documentation

• Python 3.8 or higher
• Linux environment (tested on Ubuntu/Debian)
• Internet connection for CVE data fetching

pip install vex-kernel-checker

# With AI assistant support (OpenAI/Anthropic)
pip install vex-kernel-checker[ai]

# With all optional dependencies
pip install vex-kernel-checker[all]

git clone https://github.com/laerdal/vex-kernel-checker.git
cd vex-kernel-checker
pip install -e .

# Or with AI support
pip install -e ".[ai]"

pip install requests selenium beautifulsoup4 lxml

• NVD API Key: Register at NVD API
• Microsoft Edge WebDriver: Download from Microsoft Edge WebDriver

After installation, use vex-kernel-checker command (or vex-kernel-checker if running from source).

vex-kernel-checker \
  --vex-file vulnerabilities.json \
  --kernel-config /boot/config-$(uname -r) \
  --kernel-source /lib/modules/$(uname -r)/build

# Create a configuration file
vex-kernel-checker --create-config my-config.ini

# Edit the file with your settings, then run
vex-kernel-checker --config my-config.ini

Path Resolution in Config Files:

• Input paths (vex-file, kernel-config, kernel-source, edge-driver): Relative paths are resolved relative to the config file location
• Output paths (output, log-file): Relative paths are resolved relative to the current working directory where you run the command

This allows you to store config files anywhere and have outputs generated in your current working directory.

vex-kernel-checker \
  --vex-file vulnerabilities.json \
  --kernel-config /path/to/kernel/.config \
  --kernel-source /path/to/kernel/source \
  --api-key YOUR_NVD_API_KEY \
  --edge-driver /path/to/msedgedriver \
  --verbose

# Override config file settings with command-line arguments
vex-kernel-checker --config my-config.ini --verbose --reanalyse

vex-kernel-checker \
  --vex-file vulnerabilities.json \
  --kernel-config /path/to/.config \
  --kernel-source /path/to/source \
  --reanalyse \
  --output updated_vulnerabilities.json

Note: Options marked with ✅* are required unless provided in a configuration file or using Dependency-Track integration (--dt-url or --dt-project-name).

The VEX Kernel Checker supports configuration files to simplify usage by storing commonly used settings. This is particularly useful for repeated analysis with the same parameters.

• INI format (.ini, .cfg, .config) - Human-readable with section headers
• JSON format (.json) - Machine-readable structured format

# Create a sample INI configuration file
vex-kernel-checker --create-config my-config.ini

# Create a sample JSON configuration file  
vex-kernel-checker --create-config my-config.json --config-format json

INI Format (my-config.ini):

[vex-kernel-checker]
vex-file = /path/to/vulnerabilities.json
kernel-config = /path/to/.config
kernel-source = /path/to/kernel/source
api-key = your-nvd-api-key
edge-driver = /usr/bin/msedgedriver
verbose = true
performance-stats = true

JSON Format (my-config.json):

{
  "vex-file": "/path/to/vulnerabilities.json",
  "kernel-config": "/path/to/.config",
  "kernel-source": "/path/to/kernel/source",
  "api-key": "your-nvd-api-key",
  "edge-driver": "/usr/bin/msedgedriver",
  "verbose": true,
  "performance-stats": true
}

Note: Config file keys use hyphens to match CLI argument names (e.g., kernel-config matches --kernel-config). Underscores are also supported for backward compatibility.

# Use configuration file
vex-kernel-checker --config my-config.ini

# Override config settings with command-line arguments
vex-kernel-checker --config my-config.ini --verbose --reanalyse

# Mix configuration file with additional options
vex-kernel-checker --config my-config.ini --cve-id CVE-2023-1234

Command-line arguments take precedence over configuration file settings, allowing you to override specific options while keeping others from the config file.

The examples/ directory contains sample configuration files:

• examples/sample-config.ini - Basic INI format example
• examples/sample-config.json - Basic JSON format example
• examples/production-config.ini - Comprehensive production example

When NVD API key and WebDriver are available:

1. Fetches CVE details from NVD API
2. Extracts patch URLs from CVE references, prioritizing GitHub sources
3. Downloads patch content using optimized fetching strategy:
   • GitHub direct access (fastest, most reliable)
   • GitHub alternatives using extracted commit IDs
   • Original URLs with Selenium WebDriver fallback
   • Other patch repositories (kernel.org, lore.kernel.org) as last resort
4. Analyzes affected source files and configuration dependencies
5. Maps to kernel configuration options

When patch data is unavailable:

1. Fetches basic CVE information
2. Performs heuristic analysis based on CVE metadata
3. Provides conservative assessment requiring manual review

Input VEX files should follow this structure:

{
  "vulnerabilities": [
    {
      "id": "CVE-2023-XXXXX",
      "details": "Vulnerability description",
      "analysis": {
        "state": "not_affected|affected|under_investigation",
        "justification": "component_not_present|requires_configuration|...",
        "detail": "Detailed analysis explanation",
        "timestamp": "2025-01-01T12:00:00Z"
      }
    }
  ]
}

The tool uses CycloneDX v1.6 vulnerability states:

• not_affected: Vulnerability does not affect this kernel configuration
• exploitable: Vulnerability affects this kernel configuration and requires attention
• in_triage: CVE has been analyzed but requires manual review to determine impact
• resolved: Vulnerability has been patched or mitigated
• resolved_with_pedigree: Resolved with additional tracking information
• false_positive: Incorrectly identified as a vulnerability

When viewing analysis reports, CVEs are categorized as:

• ✅ Not Affected: Vulnerable code/component not present or not configured
• 🔧 Resolved: Security patch already applied or vulnerability mitigated
• ⚠️ Exploitable: Requires immediate attention - vulnerable and exploitable
• 🔍 In Triage: Analyzed but needs manual review to determine exact impact
• ❓ Unanalyzed: Not yet analyzed (run without --cve-id filter to analyze all)
• ❌ False Positive: Incorrectly flagged (rare)

• code_not_present: Vulnerable component/code not compiled or included
• vulnerable_code_not_present: Specific vulnerable code path not present
• requires_configuration: Specific configuration needed for vulnerability
• requires_dependency: External dependency required for vulnerability
• requires_environment: Specific runtime environment needed (e.g., network access, local shell)

Filter out CVEs based on CVSS attack vector requirements. This is useful for embedded devices with restricted access:

# Device has no local shell access (e.g., SSH requires certificate auth) - filter out AV:L CVEs
vex-kernel-checker --config my-config.json --no-local-access

# Device is network-isolated - filter out AV:A and AV:N CVEs
vex-kernel-checker --config my-config.json --no-adjacent-network --no-network-access

# Device has no network at all - filter out all network-based CVEs
vex-kernel-checker --config my-config.json --no-network-access

CVEs filtered by attack vector are marked as not_affected with justification requires_environment.

You can also set these in your JSON config file:

{
  "local-access": false,
  "adjacent-network": true,
  "network-access": true
}

VEX Kernel Checker integrates with Dependency-Track to download VEX files and upload analysis results.

# Download VEX from Dependency-Track, analyze, and save locally
vex-kernel-checker \
  --dt-url "https://deptrack.example.com/api/v1/bom/cyclonedx/project/{uuid}" \
  --dt-api-key "your-api-key" \
  --kernel-config /path/to/.config \
  --kernel-source /path/to/kernel/source \
  --output analyzed-vex.json

# Full round-trip: download, analyze, and upload back to Dependency-Track
vex-kernel-checker \
  --dt-url "https://deptrack.example.com/api/v1/bom/cyclonedx/project/{uuid}" \
  --dt-api-key "your-api-key" \
  --dt-upload \
  --kernel-config /path/to/.config \
  --kernel-source /path/to/kernel/source

# Look up project by name (optionally with parent)
vex-kernel-checker \
  --dt-api-url "https://deptrack.example.com/api" \
  --dt-api-key "your-api-key" \
  --dt-project-name "my-firmware" \
  --dt-project-version "1.0.0" \
  --dt-parent-name "my-product" \
  --dt-upload \
  --kernel-config /path/to/.config \
  --kernel-source /path/to/kernel/source

[vex-kernel-checker]
kernel-config = /path/to/.config
kernel-source = /path/to/kernel/source

# Dependency-Track settings
dt-api-url = https://deptrack.example.com/api
dt-api-key = your-api-key
dt-upload = true

# Option 1: Use project UUID directly
dt-project-uuid = your-project-uuid

# Option 2: Use project name (with optional parent)
dt-project-name = my-firmware
dt-project-version = 1.0.0
dt-parent-name = my-product

export DT_API_KEY="your-dependency-track-api-key"

The tool implements sophisticated caching for optimal performance:

• Makefile Cache: Parsed Makefile content and variables
• Config Cache: Resolved configuration option mappings
• Source Analysis Cache: Source file analysis results
• Path Cache: File path resolution results

Run with --performance-stats to see cache hit rates and timing information:

Cache Performance:
  makefile: 145 hits, 23 misses (86.3% hit rate)
  config: 89 hits, 15 misses (85.6% hit rate)
  Overall Cache Hit Rate: 86.1%

Primary focus on ARM architectures with support for:

• ARM32 (arm)
• ARM64 (aarch64, arm64)
• Limited x86/x86_64 support

Architecture-specific configuration options are automatically filtered.

The tool provides comprehensive error handling:

• Network failures: Automatic retry with exponential backoff
• API rate limiting: Thread-safe rate limiting with global coordination
• Missing files: Clear error messages with suggestions
• Invalid configurations: Validation with helpful diagnostics
• Bot detection: Automatic fallback to alternative patch sources

When accessing patch repositories, you may encounter access restrictions. The tool uses an optimized GitHub-first strategy to minimize these issues:

1. Prioritizes GitHub sources - Direct access without bot detection issues
2. Extracts commit IDs - Converts other URLs to reliable GitHub alternatives
3. Detects bot protection pages (Cloudflare, "Just a moment", etc.)
4. Tries multiple fallback sources (kernel.org, lore.kernel.org) as last resort
5. Falls back gracefully to config-only analysis when needed

The GitHub-first approach significantly reduces bot detection issues while providing faster and more reliable patch access.

For detailed troubleshooting, see docs/BOT_DETECTION.md.

VEX Kernel Checker includes a comprehensive testing framework to ensure reliability and performance:

# Run quick smoke tests
make test-quick

# Validate your configuration
make validate VEX_FILE=examples/test_real_cve.json KERNEL_CONFIG=/path/to/.config KERNEL_SOURCE=/path/to/kernel

# Run full test suite with coverage
make test-coverage

# Run performance benchmarks
make benchmark

# Format code and run quality checks
make workflow-fix

• Unit Tests: Core functionality, configuration analysis, pattern matching
• Integration Tests: End-to-end workflows, file system operations
• Performance Tests: Scalability testing with datasets up to 200 CVEs
• Validation Tests: Environment setup, configuration verification

• Code coverage: >90% target
• Performance benchmarking for all major operations
• Automated configuration validation
• Cross-platform compatibility testing

See docs/TESTING.md for comprehensive testing documentation.

VEX Kernel Checker includes a GitHub Actions workflow for automated analysis with deptracker integration:

Automatically fetch VEX files from deptracker, analyze vulnerabilities, and upload results:

# Trigger manually or on schedule
uses: ./.github/workflows/vex-analysis.yml
with:
  vex_url: 'https://deptracker.example.com/api/vex/latest'
  kernel_config_url: 'https://example.com/kernel-configs/6.1.config'
  kernel_source_git_url: 'https://github.com/torvalds/linux.git'
  kernel_branch: 'v6.1'
  upload_enabled: true
  upload_url: 'https://deptracker.example.com/api/vex/upload'
secrets:
  NVD_API_KEY: ${{ secrets.NVD_API_KEY }}
  VEX_API_TOKEN: ${{ secrets.VEX_API_TOKEN }}

Features:

• 📥 Fetch VEX files from deptracker or any HTTP(S) source
• 🔍 Automated vulnerability analysis with kernel config
• 🌐 Automated Edge WebDriver setup for patch checking
• 🔖 Flexible kernel branch/tag selection
• 📤 Upload completed analysis back to deptracker (optional)
• ⏰ Scheduled runs (weekly by default)
• 📊 Detailed reports and artifacts
• 🔔 PR comments with analysis results
• 🔒 Secure execution with command injection protection

Quick Start: See .github/workflows/QUICKSTART.md for setup instructions.

Full Documentation:

• Workflow Documentation
• Deptracker Setup Guide

We welcome contributions from the cybersecurity and Linux kernel communities!

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features through feature requests
• 🔧 Submit pull requests following our Contributing Guidelines
• 📖 Improve documentation and examples

• Additional architecture support (RISC-V, PowerPC, etc.)
• Enhanced patch parsing algorithms
• Performance optimizations
• Integration with CI/CD pipelines
• Web-based interface development
• Additional vulnerability database support

For detailed contribution guidelines, see CONTRIBUTING.md.

GitHub: https://github.com/Laerdal/vex-kernel-checker Issues: https://github.com/Laerdal/vex-kernel-checker/issues Releases: https://github.com/Laerdal/vex-kernel-checker/releases

This project is licensed under the MIT License - see the LICENSE file for details.

• Karsten S. Opdal (karsten.s.opdal@gmail.com) - Initial work and ongoing development
• AI Assistant - Architecture design and optimization contributions

• National Vulnerability Database (NVD) for CVE data
• Linux Kernel Community for patch information
• MITRE Corporation for CVE standards
• VEX Working Group for vulnerability exchange format

"Patch checking disabled"

• Ensure both --api-key and --edge-driver are provided
• Verify WebDriver is executable: chmod +x /path/to/msedgedriver

Rate limiting errors

• NVD API has rate limits (10 requests/minute without key, 50/minute with key)
• Tool automatically handles rate limiting with delays

WebDriver issues

• Ensure Microsoft Edge browser is installed
• Download WebDriver version matching your Edge browser version
• Check WebDriver permissions and path

Performance issues

• Use --config-only for faster analysis
• Clear caches periodically with --clear-cache
• Monitor cache hit rates with --performance-stats

• Web-based interface for easier access
• Integration with CI/CD pipelines
• Support for additional vulnerability databases
• Enhanced reporting and visualization
• Container-based deployment options