vulnerability-analyzer 2.0.0
Streamlined network security analysis for PCAP files and Nmap scans with flexible output formats
Requires Python: >=3.8
Keywords: vulnerability, security, network, pcap, nmap, analysis, penetration-testing, cybersecurity

# Vulnerability Analyzer 2.0

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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):**
```bash
pip install vulnerability-analyzer
```

**From Source:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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

```bash
# 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:**
   ```bash
   pip install vulnerability-analyzer
   ```

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

3. **Run analysis on your files:**
   ```bash
   # 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:**
```bash
# 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:**
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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)
```python
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:
```csv
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
```csv
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
```json
{
  "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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](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](https://github.com/D14b0l1c/vulnerability-analyzer/issues) page.