This project is a modular, production-ready network scanner with a modern GUI, designed for security professionals, engineers, and open-source contributors. It supports single host and subnet (CIDR) scanning, real-time feedback, banner analysis, and secure, extensible architecture.
Modern organizations require fast, reliable, and secure tools to audit network ports and services. This scanner provides a professional, open-source solution with a focus on code quality, security, and extensibility.
- src/: Core scanning logic, modularized by responsibility
- config/: Configuration and environment setup
- tests/: Unit and integration tests
- docs/: Architecture, contributing, changelog, security
- scripts/: Automation and utilities
- results/: Scan outputs (log, CSV, JSON, graphs)
See docs/ARCHITECTURE.md for details.
- Python 3.x
- Tkinter (GUI)
- Matplotlib (visualization)
- Pillow (image handling)
- Standard Library (threading, socket, ipaddress, etc.)
- Multi-threaded port and subnet scanning
- Real-time GUI with live feedback
- Banner grabbing and vulnerability signature check
- Results export: TXT, CSV, JSON, PNG
- Modular, testable, and secure codebase
- Clone the repository:
git clone https://github.com/yourusername/port-scanner-project.git cd port-scanner-project - Install dependencies:
pip install -r requirements.txt
- Run the GUI:
Or run a CLI scan:
python -m src.gui_app
python -m src.main <target> [start_port] [end_port]
- No hardcoded secrets; use environment variables (see
.env.example) - Input validation and error handling throughout
- See SECURITY.md for responsible disclosure and security policy
- Tests in
tests/(see example unit test) - Linting: flake8, Formatting: black
- Pre-commit hooks: see
.pre-commit-config.yaml - CI: GitHub Actions (.github/workflows/ci.yml)
See docs/CONTRIBUTING.md.
- Recruiter- and reviewer-friendly codebase
- Secure, maintainable, and extensible for enterprise and open-source
- Easy to run, understand, and extend
MIT License