🛡️ Vulnerability Scanner - Educational Mini-Nessus Tool

A Python-based vulnerability scanner that detects open ports and identifies known CVEs in running services. Built for educational purposes to understand network security scanning and vulnerability detection.

⚠️ IMPORTANT DISCLAIMER

This tool is for EDUCATIONAL PURPOSES ONLY.

Only scan systems you own or have explicit written permission to test
Unauthorized network scanning is illegal in most jurisdictions
Misuse of this tool is your legal responsibility
By using this tool, you agree to comply with all applicable laws and regulations

🎯 Features

Port Scanning

Nmap Integration: Uses industry-standard nmap for comprehensive port scanning
Two Scan Modes:
- --fast: Scans top 100 common ports (quick baseline)
- --full: Scans top 1000 ports (thorough, default)
Service Detection: Identifies service names, versions, and banners
Timeout Control: Configurable timeout with --timeout flag
Graceful Fallback: TCP connection scanning if nmap is unavailable

Vulnerability Detection

Dual API Queries:
- Primary: NVD (National Vulnerability Database) - https://services.nvd.nist.gov/
- Fallback: CIRCL CVE Database - https://cve.circl.lu/api/
CVSS Scoring: Extracts CVSS v3.1 scores for severity ranking
Exponential Backoff: Implements 3-retry logic with exponential backoff for API failures
Rate Limiting: Respects API rate limits with configurable delays
Rich Descriptions: Retrieves and displays CVE descriptions (max 150 chars)

Output & Reporting

Color-Coded CLI Table: Uses rich library for beautiful, color-coded tables:
- 🔴 Critical (CVSS 9.0-10.0)
- 🟠 High (CVSS 7.0-8.9)
- 🟡 Medium (CVSS 4.0-6.9)
- 🟢 Low (CVSS 0.1-3.9)
JSON Export: Full results with metadata (timestamp, all CVE details)
CSV Export: Spreadsheet-friendly format with --csv flag
Summary Statistics: Total ports, CVEs found, severity breakdown
Streamlit Web UI (bonus): Interactive web dashboard with real-time progress

Error Handling

✅ Invalid target validation (IP, domain, CIDR)
✅ Network timeout handling with partial results
✅ API rate limit detection and recovery
✅ Missing nmap detection with installation guidance
✅ Graceful error messages with exit codes
✅ Comprehensive logging with --verbose flag

📋 Requirements

Python 3.8+
nmap (system package) - Installation Guide
Python packages (see requirements.txt)

📥 Installation

1. Install nmap (System Package)

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install nmap

Linux (Red Hat/CentOS):

sudo yum install nmap

macOS:

brew install nmap

Windows: Download and install from: https://nmap.org/download.html

Verify installation:

nmap --version

2. Clone/Download the Project

cd /path/to/vulnerability_scanner

3. Install Python Dependencies

pip install -r requirements.txt

Or with pip3 if you have multiple Python versions:

pip3 install -r requirements.txt

🚀 Quick Start

Basic Usage

Scan a single IP address (fast mode, top 100 ports):

python main.py 192.168.1.1 --fast

Scan a domain (full mode, top 1000 ports):

python main.py example.com

Scan a CIDR range with custom timeout:

python main.py 192.168.1.0/24 --timeout 120

Advanced Usage

Export to JSON and CSV:

python main.py 192.168.1.1 --csv

Verbose output for debugging:

python main.py 192.168.1.1 --verbose

Custom output directory:

python main.py 192.168.1.1 --output-dir ./my_scans

Full syntax:

python main.py [TARGET] [--fast|--full] [--timeout SECONDS] [--csv] [--verbose] [--output-dir DIR]

Streamlit Web UI (Bonus)

Run the interactive web dashboard:

streamlit run app.py

Then open your browser to http://localhost:8501

Features:

Text input for target selection
Dropdown for scan type (Fast/Full)
Real-time progress bar
Color-coded results table
Download JSON/CSV reports

📊 Output Example

Terminal Output

========================================================================
📊 SCAN RESULTS
========================================================================
┏━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ Port ┃ Service ┃ Version ┃ CVE ID ┃ CVSS ┃ Severity ┃ Desc... ┃
┡━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ 22   │ SSH     │ 7.4    │ CVE-2023-1234 │ 8.5  │ 🟠 High   │ ...   │
│      │         │        │ CVE-2023-5678 │ 6.2  │ 🟡 Medium │ ...   │
│ 80   │ HTTP    │ 2.4.41 │ —             │ —    │ ✅ None   │ No... │
│ 443  │ HTTPS   │ 2.4.41 │ CVE-2024-9999 │ 9.8  │ 🔴 Crit.. │ ...   │
└──────┴─────────┴────────┴───────────────┴──────┴──────────┴───────┘

========================================================================
📈 SCAN SUMMARY
========================================================================
Total Ports Scanned: 1000
Open Ports Found: 3
Total CVEs Found: 3

Severity Breakdown:
  🔴 Critical: 1
  🟠 High: 1
  🟡 Medium: 1
  🟢 Low: 0

⚠️  Highest Severity Found: Critical

💾 Full results saved to: ./scan_results/scan_20240105_143022.json

JSON Export (`scan_20240105_143022.json`)

{
  "timestamp": "2024-01-05T14:30:22.123456",
  "ports": [
    {
      "port": "22",
      "service": "SSH",
      "version": "7.4",
      "banner": "protocol 2.0",
      "cves": [
        {
          "cve_id": "CVE-2023-1234",
          "cvss_score": 8.5,
          "severity": "High",
          "description": "Authentication bypass in OpenSSH < 8.0...",
          "source": "NVD"
        }
      ],
      "cve_count": 1
    }
  ],
  "total_cves": 3,
  "severity_counts": {
    "Critical": 1,
    "High": 1,
    "Medium": 1
  }
}

📁 File Structure

vulnerability_scanner/
├── main.py              # CLI entry point with argparse
├── scanner.py           # Nmap scanning logic
├── vuln_checker.py      # CVE API queries with retry logic
├── utils.py             # Input validation, formatting, logging
├── app.py               # Streamlit web UI (bonus)
├── requirements.txt     # Python dependencies with pinned versions
└── README.md            # This file

File Responsibilities

File	Purpose
`main.py`	CLI argument parsing, orchestration, output directory setup
`scanner.py`	Port scanning with nmap, service detection, fallback TCP scanning
`vuln_checker.py`	CVE API queries, exponential backoff retry, result formatting
`utils.py`	Target validation, logging setup, string formatting helpers
`app.py`	Streamlit web interface with interactive dashboard
`requirements.txt`	Python package dependencies (pinned versions for reproducibility)

🔄 Data Flow

user input (CLI args)
    ↓
main.py (parse & validate)
    ↓
scanner.py (port scan with nmap)
    ↓
[list of open ports with service info]
    ↓
vuln_checker.py (query NVD + CIRCL APIs)
    ↓
[CVE data with CVSS scores]
    ↓
utils.py (format & save results)
    ↓
CLI table output + JSON/CSV files

🛡️ Security Considerations

API Key Management

This tool uses public APIs that don't require authentication
NVD API: https://services.nvd.nist.gov/ (free, rate limited)
CIRCL API: https://cve.circl.lu/api/ (free, community-supported)
No API keys are hardcoded or stored

Rate Limiting

Tool respects API rate limits with exponential backoff
Implements 0.5s delay between consecutive requests
Retries failed requests up to 3 times with backoff

Network Safety

Input validation prevents command injection attacks
Timeout prevents hanging on unreachable targets
Graceful degradation if primary API is unavailable

Logging & Privacy

All logging goes to stderr (doesn't pollute output)
Verbose mode includes detailed debugging info
No sensitive data is logged by default
All results are stored locally (not uploaded anywhere)

🐛 Troubleshooting

Issue: "nmap not found"

Solution: Install nmap using the instructions above for your OS.

Workaround: The tool will automatically fall back to TCP connection scanning, but with limited functionality.

Issue: "API rate limit exceeded"

Solution: The tool automatically implements exponential backoff and retries. Wait a few seconds and try again.

Details: NVD API allows ~120 requests per minute. If you hit the limit, the tool will:

Wait 1 second and retry
Wait 2 seconds and retry
Wait 4 seconds and retry
Fall back to CIRCL API

Issue: "Connection timeout"

Solution: Increase the timeout with --timeout flag:

python main.py 192.168.1.1 --timeout 180

Issue: "Invalid CIDR range"

Solution: Ensure proper CIDR notation (e.g., 192.168.1.0/24, not 192.168.1.0/255).

Issue: "No open ports found"

This is normal! It means either:

Target is unreachable
Firewall is blocking all scanned ports
Timeout is too short (increase with --timeout)

🔍 Example Commands

# Scan localhost (development)
python main.py localhost --fast --verbose

# Scan internal server
python main.py 10.0.0.50 --timeout 120 --csv

# Scan subnet
python main.py 192.168.1.0/24 --full --output-dir ./network_scan

# Scan domain with verbose logging
python main.py api.example.com --verbose

# Quick scan of common ports
python main.py example.com --fast --csv --output-dir ./results

🧪 Testing

Test the tool against public targets (with permission):

# Shodan honeypot (publically available for testing)
python main.py -h  # Show help

# Local machine
python main.py 127.0.0.1 --fast

# Well-known vulnerable services (intentionally exposed for learning)
# Hack The Box (https://www.hackthebox.com/)
# TryHackMe (https://tryhackme.com/)

📚 Educational Resources

NVD Database: https://nvd.nist.gov/
CVSS Scoring: https://www.first.org/cvss/
Nmap Tutorial: https://nmap.org/book/
Security Testing: https://owasp.org/www-project-web-security-testing-guide/

📝 License

Educational tool - Use responsibly and legally only.

🤝 Contributing

This is an educational project. Suggestions and improvements are welcome!

❓ FAQ

Q: Can I scan other people's systems? A: No. Only scan systems you own or have explicit written permission to test.

Q: Is this a replacement for professional tools like Nessus? A: No. This is an educational tool for learning purposes. Professional security assessments require licensed, comprehensive tools.

Q: Why does the scan take so long? A: The full mode scans top 1000 ports and queries APIs. Use --fast to scan only common ports.

Q: Can I run this against multiple targets? A: Currently, it scans one target at a time. For multiple targets, run the command multiple times.

Q: How often are the CVE databases updated? A: NVD updates daily. CIRCL updates in near real-time. Each scan queries the latest data.

Built with ❤️ for educational purposes

Remember: "With great power comes great responsibility." Use this tool ethically and legally.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
__pycache__		__pycache__
IMPLEMENTATION_GUIDE.md		IMPLEMENTATION_GUIDE.md
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
__init__.py		__init__.py
app.py		app.py
demo.py		demo.py
main.py		main.py
requirements.txt		requirements.txt
scanner.py		scanner.py
test_scan_example.csv		test_scan_example.csv
test_scan_example.json		test_scan_example.json
utils.py		utils.py
vuln_checker.py		vuln_checker.py

Folders and files

Latest commit

History

Repository files navigation

🛡️ Vulnerability Scanner - Educational Mini-Nessus Tool

⚠️ IMPORTANT DISCLAIMER

🎯 Features

Port Scanning

Vulnerability Detection

Output & Reporting

Error Handling

📋 Requirements

📥 Installation

1. Install nmap (System Package)

2. Clone/Download the Project

3. Install Python Dependencies

🚀 Quick Start

Basic Usage

Advanced Usage

Streamlit Web UI (Bonus)

📊 Output Example

Terminal Output

JSON Export (scan_20240105_143022.json)

📁 File Structure

File Responsibilities

🔄 Data Flow

🛡️ Security Considerations

API Key Management

Rate Limiting

Network Safety

Logging & Privacy

🐛 Troubleshooting

Issue: "nmap not found"

Issue: "API rate limit exceeded"

Issue: "Connection timeout"

Issue: "Invalid CIDR range"

Issue: "No open ports found"

🔍 Example Commands

🧪 Testing

📚 Educational Resources

📝 License

🤝 Contributing

❓ FAQ

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

JSON Export (`scan_20240105_143022.json`)

Packages