vulnerability-analyzer 2.0.0

Streamlined network security analysis for PCAP files and Nmap scans with flexible output formats

Vulnerability Analyzer 2.0

Streamlined network security analysis for PCAP files and Nmap scans with flexible output formats

A simplified, focused tool for extracting network data and matching it against vulnerability databases. Provides both CSV and JSON output formats for integration with security analysis workflows.

Features

• PCAP Analysis - Extract network packet data using tshark
• Nmap Analysis - Parse XML scan results for service discovery
• Vulnerability Matching - Keyword-based vulnerability detection
• Multiple Output Formats - CSV, JSON, or both formats
• High Performance - Lightweight with minimal dependencies
• CLI Ready - Simple command-line interface

Quick Start

Installation

From PyPI (Recommended):

pip install vulnerability-analyzer

From Source:

# Clone the repository
git clone https://github.com/D14b0l1c/vulnerability-analyzer.git
cd vulnerability-analyzer

# Install dependencies
pip install -r requirements.txt

# Install tshark (for PCAP analysis)
# macOS
brew install wireshark

# Ubuntu/Debian  
sudo apt-get install tshark

Basic Usage

Using the installed CLI command:

# CSV output (default)
vulnerability-analyzer scan.pcap vulnerability_index.csv

# JSON output only
vulnerability-analyzer scan.pcap vulnerability_index.csv json

# Both CSV and JSON output
vulnerability-analyzer scan.pcap vulnerability_index.csv both

Using the script directly:

# CSV output (default)
python unified_analyzer.py scan.pcap vulnerability_index.csv

# JSON output only
python unified_analyzer.py scan.pcap vulnerability_index.csv json

# Both CSV and JSON output
python unified_analyzer.py scan.pcap vulnerability_index.csv both

Example with Sample Data

# Test with included sample data
python unified_analyzer.py examples/sample_data/nmap_example.xml examples/vulnerability_index.csv json

How to Use This Tool

Quick Start

1. Install the tool:

   pip install vulnerability-analyzer
   

2. Get a vulnerability database (CSV format with vulnerability information)

3. Run analysis on your files:

   # Analyze a PCAP file
   vulnerability-analyzer network_traffic.pcap vulnerability_database.csv
   
   # Analyze an Nmap XML file
   vulnerability-analyzer nmap_scan.xml vulnerability_database.csv
   

Step-by-Step Usage Guide

Step 1: Prepare Your Input Files

For PCAP Analysis:

• Capture network traffic using tools like Wireshark, tcpdump, or tshark
• Supported formats: .pcap, .pcapng, .pcapppi
• Example: wireshark → Save as → network_capture.pcap

For Nmap Analysis:

• Run Nmap scans with XML output
• Example: nmap -sV -oX scan_results.xml target_network

Step 2: Get a Vulnerability Database

The tool requires a CSV file containing vulnerability information with columns like:

• exploit_description - Description of the vulnerability
• cve_id - CVE identifier
• Keywords for matching against services/traffic

Step 3: Run the Analysis

Basic Commands:

# Using the installed CLI command
vulnerability-analyzer input_file.pcap vulnerability_db.csv

# Using the script directly (if running from source)
python unified_analyzer.py input_file.pcap vulnerability_db.csv

With Different Output Formats:

# CSV output only (default)
vulnerability-analyzer scan.xml vulnerability_db.csv csv

# JSON output only
vulnerability-analyzer scan.xml vulnerability_db.csv json

# Both CSV and JSON output
vulnerability-analyzer scan.xml vulnerability_db.csv both

Practical Examples

Example 1: Network Security Assessment

# 1. Capture network traffic
sudo tcpdump -i eth0 -w network_traffic.pcap

# 2. Analyze for vulnerabilities
vulnerability-analyzer network_traffic.pcap vuln_database.csv json

# 3. Review results in network_matches.json
cat pcap_matches.json | jq '.matches[] | select(.cve_id)'

Example 2: Host Discovery and Vulnerability Scanning

# 1. Run Nmap scan with service detection
nmap -sV -sC -oX network_scan.xml 192.168.1.0/24

# 2. Analyze scan results
vulnerability-analyzer network_scan.xml vuln_database.csv both

# 3. Check both CSV and JSON outputs
ls -la *matches.*

Example 3: Using Sample Data (Testing)

# Test with included sample files
cd examples/sample_data

# Analyze sample Nmap results
vulnerability-analyzer nmap_example.xml /path/to/vuln_db.csv json

# Analyze sample PCAP traffic  
vulnerability-analyzer vulnerable_traffic.pcap /path/to/vuln_db.csv csv

# View sample outputs
ls sample_output/

Understanding the Output

PCAP Analysis Output

• Raw Data: pcap_extracted_output.csv - All extracted network fields
• Matches: pcap_matches.csv/json - Potential vulnerabilities found
• Fields: Source/destination IPs, MAC addresses, matched traffic patterns

Nmap Analysis Output

• Raw Data: nmap_extracted_output.csv - All discovered services
• Matches: nmap_matches.csv/json - Services with known vulnerabilities
• Fields: IP addresses, service names, versions, CVE mappings

Advanced Usage

Programmatic Usage (Python API)

import vulnerability_analyzer

# PCAP Analysis
pcap_analyzer = vulnerability_analyzer.PcapAnalyzer()
pcap_data = pcap_analyzer.analyze('traffic.pcap')

# Nmap Analysis
nmap_analyzer = vulnerability_analyzer.NmapAnalyzer()
nmap_data = nmap_analyzer.analyze('scan.xml')

# Vulnerability Matching
matcher = vulnerability_analyzer.VulnerabilityMatcher()
matches = matcher.match_pcap_to_exploits(
    'extracted_data.csv', 
    'vulnerability_db.csv',
    'output.csv',
    'output.json'
)

Custom Vulnerability Databases

Create your own vulnerability database CSV with these columns:

exploit_description,cve_id,keywords,severity
"Apache HTTP Server Buffer Overflow",CVE-2021-1234,"apache http server",High
"OpenSSL Heartbleed",CVE-2014-0160,"openssl ssl tls",Critical

Command Line Interface

Usage: vulnerability-analyzer <input_file> <vulnerability_database.csv> [output_format]

Arguments:
  input_file              PCAP file (.pcap, .pcapng) or Nmap XML file (.xml)
  vulnerability_database  CSV file containing vulnerability data
  output_format          Output format: csv, json, or both (default: csv)

Examples:
  vulnerability-analyzer scan.pcap vulnerability_index.csv
  vulnerability-analyzer nmap.xml vulnerability_index.csv json
  vulnerability-analyzer traffic.pcap vulnerability_index.csv both

Sample Output

See examples/sample_data/sample_output/ for example output files showing the expected results from both Nmap and PCAP analysis in CSV and JSON formats.

Output Formats

CSV Output

ip.src,mac.src,ip.dst,mac.dst,matched_info,exploit_description,cve_id
192.168.1.100,aa:bb:cc:dd:ee:ff,192.168.1.1,11:22:33:44:55:66,http apache,Buffer overflow in Apache,CVE-2021-1234

JSON Output

{
  "analysis_type": "pcap_vulnerability_matching",
  "total_matches": 8,
  "matches": [
    {
      "ip.src": "192.168.1.100",
      "mac.src": "aa:bb:cc:dd:ee:ff",
      "ip.dst": "192.168.1.1", 
      "mac.dst": "11:22:33:44:55:66",
      "matched_info": "http apache",
      "exploit_description": "Buffer overflow in Apache",
      "cve_id": "CVE-2021-1234"
    }
  ]
}

Architecture

• PcapAnalyzer - Extracts network packet fields using tshark
• NmapAnalyzer - Parses XML scan results into structured data
• VulnerabilityMatcher - Matches extracted data against vulnerability databases
• unified_analyzer.py - Command-line interface orchestrating the analysis pipeline

Project Structure

vulnerability-analyzer/
├── src/
│   └── vulnerability_analyzer/
│       ├── analysis/
│       │   ├── pcap_analyzer.py
│       │   └── nmap_analyzer.py
│       └── vulnerability/
│           └── matcher.py
├── examples/
│   └── sample_data/
│       ├── nmap_example.xml
│       ├── sample-nmap-output.xml
│       └── vulnerable_traffic.pcap
├── unified_analyzer.py
├── requirements.txt
└── README.md

Requirements

• Python 3.8+
• pandas
• Wireshark/tshark (for PCAP analysis)

Supported File Types

Input Files

• PCAP files: .pcap, .pcapng, .pcapppi
• Nmap XML files: .xml

Vulnerability Databases

• CSV format with columns for vulnerability information
• Compatible with standard vulnerability databases

Troubleshooting

Common Issues and Solutions

"tshark not found" or PCAP analysis fails

# Install Wireshark/tshark for PCAP analysis
# macOS
brew install wireshark

# Ubuntu/Debian
sudo apt-get install tshark

# Windows
# Download from https://www.wireshark.org/

"File not found" errors

# Check file paths - use absolute paths if needed
ls -la your_file.pcap
vulnerability-analyzer /full/path/to/file.pcap /full/path/to/vuln_db.csv

"No matches found" or empty results

• Verify your vulnerability database has appropriate keywords
• Check that your input files contain relevant data
• Try with sample data first: vulnerability-analyzer examples/sample_data/nmap_example.xml vuln_db.csv

Permission errors on Linux/macOS

# For PCAP files captured with sudo
sudo chown $USER:$USER network_capture.pcap

# For tshark permissions
sudo usermod -a -G wireshark $USER
# (logout and login again)

"Module not found" errors

# Reinstall the package
pip uninstall vulnerability-analyzer
pip install vulnerability-analyzer

# Or install in development mode
pip install -e .

Getting Help

1. Check sample outputs: Look at examples/sample_data/sample_output/ for expected format
2. Test with sample data: Use included sample files to verify installation
3. Enable verbose output: Check console output for detailed error messages
4. Report issues: Create an issue on GitHub with your error message and system info

Performance Tips

• Large PCAP files: Consider splitting large captures into smaller files
• Many Nmap targets: Process scan results in batches
• Custom databases: Keep vulnerability databases focused and up-to-date

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Version History

• 2.0.0 - Simplified architecture, added JSON output support, improved CLI
• 1.x.x - Complex feature-rich version (deprecated)

🐛 Issues and Support

Please report issues on the GitHub Issues page.