https://github.com/harshanandhan/vulnerability-scanner

Python-based vulnerability scanner for network and web security assessment. Features port scanning, service detection, SQL injection/XSS testing, SSL analysis, and PDF reporting. Security Analyst portfolio project by Harshanandhan Reddy Gajulapalli.
https://github.com/harshanandhan/vulnerability-scanner

cybersecurity ethical-hacking network-security penetration-testing portfolio-project python security security-analyst vulnerability-scanner web-security

Last synced: about 1 month ago
JSON representation

Python-based vulnerability scanner for network and web security assessment. Features port scanning, service detection, SQL injection/XSS testing, SSL analysis, and PDF reporting. Security Analyst portfolio project by Harshanandhan Reddy Gajulapalli.

• Host: GitHub
• URL: https://github.com/harshanandhan/vulnerability-scanner
• Owner: Harshanandhan
• License: mit
• Created: 2025-12-22T07:23:37.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2025-12-22T07:30:31.000Z (6 months ago)
• Last Synced: 2025-12-23T18:47:30.564Z (6 months ago)
• Topics: cybersecurity, ethical-hacking, network-security, penetration-testing, portfolio-project, python, security, security-analyst, vulnerability-scanner, web-security
• Language: Python
• Homepage:
• Size: 44.9 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Vulnerability Scanner v2.0

![License](https://img.shields.io/badge/license-MIT-blue.svg)

![Python](https://img.shields.io/badge/python-3.8+-blue.svg)

![Security](https://img.shields.io/badge/security-testing-red.svg)

![Status](https://img.shields.io/badge/status-production--ready-success.svg)

A Python-based network and web application vulnerability scanner for security assessments and penetration testing. Built as part of a Security Analyst portfolio by **Harshanandhan Reddy Gajulapalli**.

**Author:** Harshanandhan Reddy Gajulapalli  

**Email:** harshanandhan820@gmail.com  

**GitHub:** [@Harshanandhan](https://github.com/Harshanandhan)  

**Purpose:** Security Analyst Portfolio Project #2

---

## 🎯 What This Tool Actually Does

**This README is 100% honest about what's implemented and what's not.**

### ✅ Currently Working Features

- **Multi-threaded Port Scanning** - TCP port scanning with configurable threads and timeout

- **Service Detection** - Banner grabbing and service version identification

- **Basic Web Vulnerability Testing**:

  - SQL Injection pattern detection (error-based)

  - XSS reflection testing

  - Security headers validation

- **SSL/TLS Analysis** - Certificate validation and cipher strength checking

- **PDF Report Generation** - Professional vulnerability assessment reports

- **JSON Export** - Machine-readable output for automation

- **Progress Tracking** - Real-time scan progress with tqdm

- **Proper Error Handling** - Comprehensive logging and error messages

### 🚧 NOT Currently Implemented (Honest Roadmap)

- ❌ Real CVE database integration (uses sample data)

- ❌ UDP port scanning

- ❌ Subdomain enumeration

- ❌ Directory traversal/bruteforcing

- ❌ CSRF detection

- ❌ Authenticated scanning

- ❌ Full OWASP Top 10 coverage

- ❌ OS fingerprinting

- ❌ Exploit availability checking via real APIs

**Why be honest?** Because integrity matters in cybersecurity. This tool does what it claims, and the code backs it up.

---

## 📋 Prerequisites

- Python 3.8 or higher

- pip package manager

- Root/sudo access (for port scanning on Linux/Mac)

- Internet connection

- 4GB RAM minimum

---

## 🛠️ Installation

```bash

# Clone the repository

git clone https://github.com/Harshanandhan/vulnerability-scanner.git

cd vulnerability-scanner

# Install dependencies

pip install -r requirements.txt

# Verify installation

python scanner.py --help

```

### Quick Test

```bash

# Test against a safe, legal target

python scanner.py -t scanme.nmap.org --quick

```

---

## 📊 Usage Examples

### Basic Scans

```bash

# Scan common ports (1-1000)

python scanner.py -t 192.168.1.1

# Quick scan (top 100 ports)

python scanner.py -t example.com --quick

# Scan specific port range

python scanner.py -t 192.168.1.1 -p 1-500

```

### Advanced Scans

```bash

# Full port scan (all 65535 ports) - WARNING: Takes time!

python scanner.py -t 192.168.1.1 --full

# Web application only (no port scan)

python scanner.py -t https://example.com --web-only

# Generate PDF report

python scanner.py -t example.com --report scan_report.pdf

# Export as JSON for automation

python scanner.py -t example.com --json results.json

# Verbose output with detailed logging

python scanner.py -t example.com --verbose

```

### Performance Tuning

```bash

# Increase threads for faster scanning

python scanner.py -t 192.168.1.1 --threads 100

# Adjust timeout for slow networks

python scanner.py -t example.com --timeout 10

# Quick scan with report

python scanner.py -t scanme.nmap.org --quick --report quick_scan.pdf

```

---

## 🔧 Command Line Options

```

Required Arguments:

  -t, --target TARGET          Target IP address, domain, or URL

Optional Arguments:

  -p, --ports PORTS           Port range (default: 1-1000)

                              Examples: 80, 1-1000, 80,443,8080

  

  --quick                     Scan top 100 most common ports

  --full                      Scan all 65535 ports (slow!)

  --web-only                  Skip port scan, web testing only

  --check-headers             Validate HTTP security headers

  

  --report FILENAME           Generate PDF report

  --json FILENAME             Export results as JSON

  

  --timeout SECONDS           Connection timeout (default: 3)

  --threads NUMBER            Concurrent threads (default: 50)

  

  -v, --verbose               Enable detailed logging

  -h, --help                  Show help message

```

---

## 📁 Project Structure

```

vulnerability-scanner/

├── scanner.py                 # Main entry point

├── README.md                  # This file

├── QUICKSTART.md              # 2-minute setup guide

├── IMPROVEMENTS.md            # v2.0 changelog

├── requirements.txt           # Python dependencies

├── LICENSE                    # MIT License

├── .gitignore                 # Git ignore rules

│

├── modules/                   # Core modules

│   ├── __init__.py           # Package initialization

│   ├── port_scanner.py       # Multi-threaded TCP scanning

│   ├── service_detector.py   # Service identification

│   ├── web_scanner.py        # Web vulnerability tests

│   ├── ssl_checker.py        # SSL/TLS analysis

│   ├── vuln_checker.py       # Vulnerability matching (sample data)

│   └── report_generator.py   # PDF report creation

│

├── data/                      # Data files

│   └── common_ports.json     # Port definitions

│

├── reports/                   # Generated reports (gitignored)

└── docs/                      # Additional documentation

```

---

## 🔍 How It Works

### 1. Port Scanning

Uses Python's `socket` library with multi-threading for performance:

```python

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

sock.settimeout(timeout)

result = sock.connect_ex((target, port))

# result == 0 means port is open

```

**Limitations:** TCP only, no UDP support yet.

### 2. Service Detection

Sends protocol-specific probes and analyzes banner responses:

```python

# HTTP probe example

sock.send(b'GET / HTTP/1.0\r\n\r\n')

banner = sock.recv(1024)

# Parse banner to identify service and version

```

**Limitations:** Basic banner grabbing, not as comprehensive as Nmap.

### 3. Web Vulnerability Testing

**SQL Injection:**

- Sends common SQL injection payloads

- Checks for database error messages in responses

- Pattern: `' OR '1'='1`, `UNION SELECT`, etc.

**XSS Testing:**

- Injects XSS payloads in parameters

- Checks if payload is reflected unescaped

- Pattern: `alert('XSS')`, etc.

**Security Headers:**

- Validates presence of security headers

- Checks: X-Frame-Options, CSP, HSTS, etc.

**Limitations:** Basic pattern matching, no crawling, manual verification recommended.

### 4. SSL/TLS Analysis

- Certificate validation and expiry checking

- Cipher suite strength analysis

- Protocol version verification

- Grade calculation (A+ to F)

**Limitations:** Not as comprehensive as SSL Labs, basic checks only.

### 5. Report Generation

Uses ReportLab to create professional PDF reports with:

- Executive summary

- Scan statistics

- Open ports and services

- Vulnerability findings

- Recommendations

---

## 📈 Sample Output

```

┌────────────────────────────────────────────────────────────┐

│         VulnScan v2.0 - Vulnerability Scanner              │

│         Target: example.com (93.184.216.34)                │

│         Author: Harshanandhan Reddy Gajulapalli           │

└────────────────────────────────────────────────────────────┘

[+] Starting scan at 2024-12-22 10:30:00

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] Port Scanning

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[*] Scanning ports 1-1000...

[+] Port 22/tcp - open - SSH

[+] Port 80/tcp - open - HTTP

[+] Port 443/tcp - open - HTTPS

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] Service Detection

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[*] Detecting service on port 22...

[+] OpenSSH 7.6p1

[*] Detecting service on port 80...

[+] Apache 2.4.29

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] Web Application Security

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[*] Testing https://example.com...

[*] Testing for SQL Injection...

[PASS] SQL Injection

[*] Testing for XSS...

[PASS] Cross-Site Scripting

[*] Checking security headers...

[WARN] Missing 3 security headers

  - X-Frame-Options

  - Content-Security-Policy

  - X-Content-Type-Options

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] SSL/TLS Analysis

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[*] Analyzing SSL/TLS configuration...

[+] Certificate valid

[+] Expires: 2025-06-15

[+] Grade: A

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] Scan Summary

[++++++++++++++++++++++++++++++++++++++++++++++++++++++++++]

[+] Open Ports: 3

[+] Services Detected: 2

[+] Web Findings: 3

[+] No vulnerabilities detected

[*] Scan completed in 2m 15s

════════════════════════════════════════════════════════════

```

---

## ⚖️ Legal Disclaimer

**⚠️ IMPORTANT - READ BEFORE USE ⚠️**

This tool is designed for **AUTHORIZED SECURITY TESTING ONLY**.

### You MUST:

✅ Only scan systems you own

✅ Obtain written permission before scanning

✅ Comply with all applicable laws and regulations

✅ Follow responsible disclosure practices

✅ Respect privacy and confidentiality

### You MUST NOT:

❌ Scan systems without authorization

❌ Use for malicious purposes

❌ Violate computer fraud laws

❌ Cause harm or disruption

**Unauthorized scanning is a CRIME in most jurisdictions.**

The author (Harshanandhan Reddy Gajulapalli) is **NOT responsible** for misuse of this tool.

**USE AT YOUR OWN RISK. FOR EDUCATIONAL AND AUTHORIZED TESTING ONLY.**

---

## 🛡️ Ethical Usage Guidelines

### Before Scanning:

1. **Get Permission** - Written authorization is essential

2. **Define Scope** - Clearly document what can be tested

3. **Set Timeframe** - Agree on testing windows

4. **Establish Communication** - Keep stakeholders informed

### During Scanning:

1. **Stay in Scope** - Only test agreed-upon targets

2. **Document Everything** - Keep detailed logs

3. **Be Respectful** - Avoid excessive load or disruption

4. **Monitor Impact** - Watch for unintended consequences

### After Scanning:

1. **Report Responsibly** - Follow responsible disclosure

2. **Secure Findings** - Handle data confidentially

3. **Provide Value** - Clear, actionable recommendations

4. **Follow Up** - Assist with remediation if requested

---

## 🧪 Safe Practice Targets

These targets are **LEGAL** to scan for practice:

```bash

# Nmap's official test server

python scanner.py -t scanme.nmap.org

# OWASP intentionally vulnerable sites

python scanner.py -t http://testphp.vulnweb.com --web-only

python scanner.py -t http://testaspnet.vulnweb.com --web-only

# Your own local test environment

python scanner.py -t localhost

python scanner.py -t 127.0.0.1

```

**Always verify** that scanning is permitted before testing any target.

---

## 🐛 Known Limitations

### Technical Limitations:

- **TCP Only** - No UDP port scanning support

- **No Authentication** - Cannot test authenticated endpoints

- **Basic Web Tests** - Not as thorough as Burp Suite/ZAP

- **Sample CVE Data** - Uses hardcoded vulnerabilities, not live API

- **No Crawling** - Doesn't discover hidden pages/endpoints

- **False Positives** - Manual verification recommended

### Performance Limitations:

- Full scans (65535 ports) are very slow

- No distributed scanning support

- Limited by single-threaded Python GIL

### Scope Limitations:

- No wireless network testing

- No physical security assessment

- No social engineering tests

- No mobile app testing

**This is a learning/portfolio project, not a replacement for professional tools.**

---

## 🔄 Version 2.0 Improvements

See [IMPROVEMENTS.md](IMPROVEMENTS.md) for complete changelog.

### Key Fixes from v1.0:

✅ **Honest Documentation** - README matches actual code

✅ **Fixed Crashes** - Implemented all promised methods

✅ **Cleaned Dependencies** - Removed unused libraries

✅ **Better Error Handling** - Comprehensive logging

✅ **Input Validation** - Validates targets before scanning

✅ **Complete Structure** - All folders and data files included

✅ **Author Attribution** - Proper credit throughout

---

## 🗺️ Roadmap

### v2.1 (Future)

- [ ] Real NVD API integration for CVE lookups

- [ ] UDP port scanning support

- [ ] Rate limiting to avoid IDS triggers

- [ ] Enhanced error messages

- [ ] Unit tests with pytest

### v2.2 (Future)

- [ ] Subdomain enumeration

- [ ] Directory bruteforcing

- [ ] Authenticated scanning

- [ ] HTML report generation

- [ ] REST API endpoint

### v3.0 (Long-term Vision)

- [ ] Machine learning for anomaly detection

- [ ] GUI interface (tkinter or web-based)

- [ ] Plugin system for extensions

- [ ] Docker containerization

- [ ] CI/CD with GitHub Actions

- [ ] Smart contract auditing (blockchain integration)

---

## 🧪 Testing

```bash

# Run against safe test target

python scanner.py -t scanme.nmap.org --quick

# Generate test report

python scanner.py -t scanme.nmap.org --report test_scan.pdf

# Verbose mode for debugging

python scanner.py -t localhost --verbose

# Export test results

python scanner.py -t 127.0.0.1 --json test_results.json

```

---

## 🤝 Contributing

Contributions are welcome! This is a learning project.

### How to Contribute:

1. Fork the repository

2. Create a feature branch (`git checkout -b feature/awesome-feature`)

3. Make your changes

4. Add tests if applicable

5. Commit (`git commit -m 'Add awesome feature'`)

6. Push (`git push origin feature/awesome-feature`)

7. Open a Pull Request

### Contribution Guidelines:

- Follow PEP 8 style guide

- Add docstrings to functions

- Update README if adding features

- Be honest about what works and what doesn't

---

## 📚 Learning Resources

This project was built while learning:

### Network Security:

- TCP/IP fundamentals

- Socket programming in Python

- Multi-threading and concurrency

- Port scanning techniques

### Web Security:

- OWASP Top 10 vulnerabilities

- SQL injection mechanics

- Cross-site scripting (XSS)

- HTTP security headers

- SSL/TLS protocols

### Python Development:

- Project structure and packaging

- Report generation with ReportLab

- Command-line argument parsing

- Logging and error handling

### Key Takeaways:

1. **Honesty in documentation builds trust**

2. **Error handling is critical for production code**

3. **Input validation prevents security issues**

4. **Testing reveals assumptions quickly**

See [docs/LESSONS_LEARNED.md](docs/LESSONS_LEARNED.md) for detailed learnings.

---

## 🙏 Acknowledgments

- **OWASP** - Web security testing methodology

- **Nmap Project** - Port scanning inspiration  

- **Python Community** - Excellent libraries and documentation

- **Code Reviewers** - Feedback that improved this tool

- **Security Community** - Shared knowledge and best practices

Special thanks to everyone who provided constructive feedback.

---

## 📧 Contact & Links

**Harshanandhan Reddy Gajulapalli**

- **Email:** harshanandhan820@gmail.com

- **GitHub:** [@Harshanandhan](https://github.com/Harshanandhan)

- **LinkedIn:** [Connect with me](https://linkedin.com/in/harshanandhan)

- **Portfolio:** Security Analyst Projects

---

## 📝 License

MIT License

Copyright (c) 2024 Harshanandhan Reddy Gajulapalli

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

## 📊 Project Stats

- **Language:** Python 3.8+

- **Lines of Code:** ~1,500

- **Modules:** 6

- **Dependencies:** 8

- **Version:** 2.0.0

- **Status:** Production Ready

- **License:** MIT

- **Maintained:** Yes

---

**⚠️ Final Reminder**: Always scan ethically and legally. Authorization is mandatory. When in doubt, don't scan.

**Built with integrity for the cybersecurity community.**

---

*Last Updated: December 22, 2024*  

*Version: 2.0.0*  

*Author: Harshanandhan Reddy Gajulapalli*