A comprehensive Python toolkit for network scanning, banner grabbing, host discovery, and security assessment. Built with modern Python features including asyncio, type hints, and a modular architecture.
- Port Scanning: TCP connect, TCP SYN (Scapy), and UDP scanning with async support
- Comprehensive Service Detection: 6-step detection process including banner grabbing, application probes, Nmap integration, TLS detection, protocol fingerprinting, and NSE scripts
- Sequential Multi-Host Scanning: Intelligent queue management for scanning multiple hosts one at a time
- Priority-Based Scan Management: Smart display sorting (RUNNING > PENDING > COMPLETED)
- Host Discovery: ICMP ping sweeps, ARP scanning, and DNS resolution
- OS Detection: Operating system fingerprinting using TTL analysis, TCP stack fingerprinting, and banner analysis
- IP Information Gathering: Geolocation, ISP, ASN, and network information for each host
- Output Formats: JSON, CSV, TXT, PDF, YAML, and Nmap XML compatible
- Comprehensive Reporting: HTML, PDF, TXT, CSV, JSON, and YAML reports with host information, OS detection, and vulnerability details
- Real-time Web Dashboard: FastAPI-based interface with WebSocket live updates and professional UI
- Plugin System: Extensible architecture for custom modules
- Vulnerability Assessment: HTTP security headers, server information disclosure
- Default Credential Checks: Common service vulnerabilities
- Comprehensive Shodan API Integration: Passive reconnaissance, threat intelligence, vulnerability correlation, and honeypot detection
- Security Reporting: Color-coded severity levels and detailed findings
- Rate Limiting: Configurable scan speed and throttling controls
- Cancellation Support: Graceful scan stopping with immediate response
- Unknown Port Investigation: Comprehensive analysis of uncommon ports (711, 982, 1337, 31337, etc.)
git clone https://github.com/mrxcherif/gingerscan.git
cd gingerscan
chmod +x install.sh
./install.sh- Clone and setup:
git clone https://github.com/mrxcherif/gingerscan.git
cd gingerscan
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
# Full installation (includes WebSocket support for web dashboard)
pip install --upgrade pip
pip install -r requirements.txt
# Install Nmap for comprehensive service detection (recommended)
sudo apt-get install nmap # Ubuntu/Debian
sudo yum install nmap # CentOS/RHEL
brew install nmap # macOS
# Or minimal installation (CLI-only)
pip install -r requirements-minimal.txtNote: Do not commit your local Python virtual environment directory
venv/. Addvenv/to your.gitignore.
- Build and run with Docker Compose:
docker-compose up --build- Or build and run manually:
docker build -t gingerscan .
docker run -it --rm --network host gingerscan# Basic port scan
python -m tools.scanner --target 192.168.1.1 --ports 1-1000
# Comprehensive scan with all features (sequential multi-host scanning)
python -m tools.scanner --target 192.168.1.0/24 --ports 1-1000 --banner --discover --os-detection --ip-info
# Scan multiple hosts with comprehensive service detection
python -m tools.scanner --target 192.168.1.1,192.168.1.2,192.168.1.3 --ports 1-1000 --banner --os-detection
# Generate comprehensive HTML report with host information
python -m tools.scanner --target 192.168.1.1 --ports 1-1000 --os-detection --ip-info --output report.html --format html
# Load configuration from file
python -m tools.scanner --config config.yamlStart the web interface:
python -m tools.web_dashboardAccess the dashboard at http://localhost:8000
Dashboard Features:
- Sequential Multi-Host Scanning: Scan multiple hosts one at a time with queue management
- Priority-Based Display: Running scans at top, pending in middle, completed at bottom
- Professional Messaging: Context-aware scan start messages
- Real-time Progress: Live updates with detailed phase information (ARP scan, OS detection, IP gathering, Port scanning)
- Enhanced Service Detection: 6-step service identification process
- Comprehensive Reports: Export in HTML, PDF, TXT, CSV, JSON, YAML formats
- Host Information: Geolocation, ISP, ASN data in all report formats
- Graceful Cancellation: Stop scans immediately with automatic next scan progression
Here's a look at the interactive web dashboard built with FastAPI:
Create a config.yaml file:
targets:
- 192.168.1.0/24
- 10.0.0.1
ports:
- 1-1000
- 22,80,443,8080
scan_options:
timeout: 3
rate_limit: 100
threads: 50
output:
format: json
file: scan_results.json
banner_grabbing:
enabled: true
timeout: 5
# Comprehensive service detection
service_detection:
enabled: true
use_nmap: true
timeout: 10
steps:
- banner_grab
- application_probes
- tls_detection
- nmap_version
- protocol_fingerprint
- nse_scripts
discovery:
icmp_ping: true
arp_scan: true
dns_resolution: true
# IP information gathering
ip_info:
enabled: true
timeout: 5
include_geolocation: true
include_asn: truegingerscan/
├── __init__.py
├── __main__.py
├── assets/
│ ├── logo.png
│ ├── text.png
│ ├── Screenshot1.jpg
│ ├── Screenshot2.jpg
│ └── Screenshot3.jpg
├── config/
│ ├── default.yaml
│ └── local.yaml
├── docker-compose.yml
├── Dockerfile
├── docs/
│ ├── design.md
│ ├── roadmap.md
│ ├── shodan_integration.md
│ └── usage.md
├── install.sh
├── LICENSE
├── logs/
├── PROJECT_SUMMARY.md
├── README.md
├── reports/
├── requirements-minimal.txt
├── requirements.txt
├── scripts/
│ ├── parse_output.sh
│ └── run_scan.sh
├── SETUP_GUIDE.md
├── setup.py
├── tests/
│ ├── test_parser.py
│ ├── test_reporter.py
│ └── test_scanner.py
└── tools/
├── __init__.py
├── banner_grabber.py
├── cli.py
├── comprehensive_service_detector.py
├── discover.py
├── enhanced_service_detector.py
├── ip_info.py
├── os_detection.py
├── parser.py
├── reporter.py
├── scanner.py
├── shodan_client.py
├── vuln_checks.py
└── web_dashboard.py
{
"scan_info": {
"target": "192.168.1.1",
"start_time": "2024-01-01T10:00:00Z",
"duration": 45.2
},
"hosts": [
{
"ip": "192.168.1.1",
"hostname": "router.local",
"ports": [
{
"port": 22,
"protocol": "tcp",
"state": "open",
"service": "ssh",
"banner": "SSH-2.0-OpenSSH_8.2p1"
}
]
}
]
}pytest tests/ -vThis project follows PEP 8 and uses:
- Type hints for all functions
- Black for code formatting
- Flake8 for linting
- MyPy for type checking
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
- LinkedIn: Mr Cherif
This project is licensed under the MIT License - see the LICENSE file for details.
The tool features a sophisticated 6-step service detection process:
- Banner Grab: Simple connection and banner reading
- Application Probes: Service-specific probes (HTTP GET, SMTP EHLO, FTP USER, MySQL handshake, Redis PING, etc.)
- TLS Detection: SSL/TLS certificate analysis and cipher identification
- Nmap Analysis: Industry-standard
nmap -sVversion detection - Protocol Fingerprinting: Response pattern analysis and binary protocol detection
- NSE Scripts: Nmap Scripting Engine for vulnerability detection
Requirements for Full Functionality:
# Install Nmap for best results
sudo apt-get install nmap # Ubuntu/Debian
sudo yum install nmap # CentOS/RHEL
brew install nmap # macOSService Detection Results:
- High Confidence (0.8-1.0): SSH, HTTP, HTTPS, FTP, SMTP, MySQL, etc.
- Medium Confidence (0.5-0.7): Custom applications with clear patterns
- Unknown Services (0.1-0.4): Ports requiring manual investigation (711, 982, 1337, etc.)
- Comprehensive service detection with Nmap integration
- Sequential multi-host scanning
- Priority-based scan management
- Professional web dashboard
- Enhanced reporting with host information
- Graceful scan cancellation
- Additional vulnerability checks
- Integration with more security APIs
- Advanced reporting features
- Mobile app for scan monitoring
- Cloud deployment templates
This tool is for authorized security testing only. Always ensure you have permission to scan the target networks. The authors are not responsible for any misuse of this software.