{"id":31698789,"url":"https://github.com/mrxcherif/gingerscan","last_synced_at":"2026-05-07T05:40:34.151Z","repository":{"id":318666393,"uuid":"1072229156","full_name":"mrxcherif/gingerscan","owner":"mrxcherif","description":"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.","archived":false,"fork":false,"pushed_at":"2025-10-08T13:22:18.000Z","size":1937,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T15:13:14.970Z","etag":null,"topics":["asyncio","automation","bash-scripting","cybersecurity","cybersecurity-tools","dashboard-design","docker","docker-compose","fastapi","network-analysis","network-scanner","network-scanner-python","network-security","nmap","nmap-scan","pentesting","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrxcherif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T12:39:55.000Z","updated_at":"2025-10-08T13:22:21.000Z","dependencies_parsed_at":"2025-10-08T15:23:36.168Z","dependency_job_id":null,"html_url":"https://github.com/mrxcherif/gingerscan","commit_stats":null,"previous_names":["mrxcherif/gingerscan"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mrxcherif/gingerscan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrxcherif%2Fgingerscan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrxcherif%2Fgingerscan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrxcherif%2Fgingerscan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrxcherif%2Fgingerscan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrxcherif","download_url":"https://codeload.github.com/mrxcherif/gingerscan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrxcherif%2Fgingerscan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000701,"owners_count":26082805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","automation","bash-scripting","cybersecurity","cybersecurity-tools","dashboard-design","docker","docker-compose","fastapi","network-analysis","network-scanner","network-scanner-python","network-security","nmap","nmap-scan","pentesting","python"],"created_at":"2025-10-08T19:10:51.390Z","updated_at":"2025-10-08T19:11:02.592Z","avatar_url":"https://github.com/mrxcherif.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ginger Scan\n\n\u003cdiv align=\"center\" style=\"display: flex; align-items: center; justify-content: center; gap: 30px; margin: 20px 0;\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"GingerScan Logo\" style=\"height: 150px; width: auto; max-width: 500px; object-fit: contain;\"\u003e\n  \u003cimg src=\"assets/text.png\" alt=\"GingerScan Text\" style=\"height: 120px; width: auto; max-width: 600px; object-fit: contain;\"\u003e\n\u003c/div\u003e\n\n\nA 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.\n\n## Features\n\n### Core Functionality\n- **Port Scanning**: TCP connect, TCP SYN (Scapy), and UDP scanning with async support\n- **Comprehensive Service Detection**: 6-step detection process including banner grabbing, application probes, Nmap integration, TLS detection, protocol fingerprinting, and NSE scripts\n- **Sequential Multi-Host Scanning**: Intelligent queue management for scanning multiple hosts one at a time\n- **Priority-Based Scan Management**: Smart display sorting (RUNNING \u003e PENDING \u003e COMPLETED)\n- **Host Discovery**: ICMP ping sweeps, ARP scanning, and DNS resolution\n- **OS Detection**: Operating system fingerprinting using TTL analysis, TCP stack fingerprinting, and banner analysis\n- **IP Information Gathering**: Geolocation, ISP, ASN, and network information for each host\n- **Output Formats**: JSON, CSV, TXT, PDF, YAML, and Nmap XML compatible\n- **Comprehensive Reporting**: HTML, PDF, TXT, CSV, JSON, and YAML reports with host information, OS detection, and vulnerability details\n- **Real-time Web Dashboard**: FastAPI-based interface with WebSocket live updates and professional UI\n- **Plugin System**: Extensible architecture for custom modules\n\n### Security Features\n- **Vulnerability Assessment**: HTTP security headers, server information disclosure\n- **Default Credential Checks**: Common service vulnerabilities\n- **Comprehensive Shodan API Integration**: Passive reconnaissance, threat intelligence, vulnerability correlation, and honeypot detection\n- **Security Reporting**: Color-coded severity levels and detailed findings\n- **Rate Limiting**: Configurable scan speed and throttling controls\n- **Cancellation Support**: Graceful scan stopping with immediate response\n- **Unknown Port Investigation**: Comprehensive analysis of uncommon ports (711, 982, 1337, 31337, etc.)\n\n## Installation\n\n### Quick Start (Recommended)\n\n```bash\ngit clone https://github.com/mrxcherif/gingerscan.git\ncd gingerscan\nchmod +x install.sh\n./install.sh\n```\n\n### Manual Installation\n\n1. Clone and setup:\n```bash\ngit clone https://github.com/mrxcherif/gingerscan.git\ncd gingerscan\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n2. Install dependencies:\n```bash\n# Full installation (includes WebSocket support for web dashboard)\npip install --upgrade pip\npip install -r requirements.txt\n\n# Install Nmap for comprehensive service detection (recommended)\nsudo apt-get install nmap  # Ubuntu/Debian\nsudo yum install nmap      # CentOS/RHEL\nbrew install nmap         # macOS\n\n# Or minimal installation (CLI-only)\npip install -r requirements-minimal.txt\n```\n\n\u003e Note: Do not commit your local Python virtual environment directory `venv/`. Add `venv/` to your `.gitignore`.\n\n### Docker Installation\n\n1. Build and run with Docker Compose:\n```bash\ndocker-compose up --build\n```\n\n2. Or build and run manually:\n```bash\ndocker build -t gingerscan .\ndocker run -it --rm --network host gingerscan\n```\n\n## Quick Start\n\n### Command Line Interface\n\n```bash\n# Basic port scan\npython -m tools.scanner --target 192.168.1.1 --ports 1-1000\n\n# Comprehensive scan with all features (sequential multi-host scanning)\npython -m tools.scanner --target 192.168.1.0/24 --ports 1-1000 --banner --discover --os-detection --ip-info\n\n# Scan multiple hosts with comprehensive service detection\npython -m tools.scanner --target 192.168.1.1,192.168.1.2,192.168.1.3 --ports 1-1000 --banner --os-detection\n\n# Generate comprehensive HTML report with host information\npython -m tools.scanner --target 192.168.1.1 --ports 1-1000 --os-detection --ip-info --output report.html --format html\n\n# Load configuration from file\npython -m tools.scanner --config config.yaml\n```\n\n### Web Dashboard\n\nStart the web interface:\n```bash\npython -m tools.web_dashboard\n```\n\nAccess the dashboard at `http://localhost:8000`\n\n**Dashboard Features:**\n- **Sequential Multi-Host Scanning**: Scan multiple hosts one at a time with queue management\n- **Priority-Based Display**: Running scans at top, pending in middle, completed at bottom\n- **Professional Messaging**: Context-aware scan start messages\n- **Real-time Progress**: Live updates with detailed phase information (ARP scan, OS detection, IP gathering, Port scanning)\n- **Enhanced Service Detection**: 6-step service identification process\n- **Comprehensive Reports**: Export in HTML, PDF, TXT, CSV, JSON, YAML formats\n- **Host Information**: Geolocation, ISP, ASN data in all report formats\n- **Graceful Cancellation**: Stop scans immediately with automatic next scan progression\n\n## Dashboard Preview\n\nHere's a look at the interactive web dashboard built with FastAPI:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Screenshot1.jpg\" alt=\"GingerScan Dashboard - Main Interface\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Screenshot2.jpg\" alt=\"GingerScan Dashboard - Scan Results\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Screenshot3.jpg\" alt=\"GingerScan Dashboard - Reports\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Configuration\n\nCreate a `config.yaml` file:\n\n```yaml\ntargets:\n  - 192.168.1.0/24\n  - 10.0.0.1\n\nports:\n  - 1-1000\n  - 22,80,443,8080\n\nscan_options:\n  timeout: 3\n  rate_limit: 100\n  threads: 50\n\noutput:\n  format: json\n  file: scan_results.json\n\nbanner_grabbing:\n  enabled: true\n  timeout: 5\n\n# Comprehensive service detection\nservice_detection:\n  enabled: true\n  use_nmap: true\n  timeout: 10\n  steps:\n    - banner_grab\n    - application_probes\n    - tls_detection\n    - nmap_version\n    - protocol_fingerprint\n    - nse_scripts\n\ndiscovery:\n  icmp_ping: true\n  arp_scan: true\n  dns_resolution: true\n\n# IP information gathering\nip_info:\n  enabled: true\n  timeout: 5\n  include_geolocation: true\n  include_asn: true\n```\n\n## Project Structure\n\n```\ngingerscan/\n├── __init__.py\n├── __main__.py\n├── assets/\n│   ├── logo.png\n│   ├── text.png\n│   ├── Screenshot1.jpg\n│   ├── Screenshot2.jpg\n│   └── Screenshot3.jpg\n├── config/\n│   ├── default.yaml\n│   └── local.yaml\n├── docker-compose.yml\n├── Dockerfile\n├── docs/\n│   ├── design.md\n│   ├── roadmap.md\n│   ├── shodan_integration.md\n│   └── usage.md\n├── install.sh\n├── LICENSE\n├── logs/\n├── PROJECT_SUMMARY.md\n├── README.md\n├── reports/\n├── requirements-minimal.txt\n├── requirements.txt\n├── scripts/\n│   ├── parse_output.sh\n│   └── run_scan.sh\n├── SETUP_GUIDE.md\n├── setup.py\n├── tests/\n│   ├── test_parser.py\n│   ├── test_reporter.py\n│   └── test_scanner.py\n└── tools/\n    ├── __init__.py\n    ├── banner_grabber.py\n    ├── cli.py\n    ├── comprehensive_service_detector.py\n    ├── discover.py\n    ├── enhanced_service_detector.py\n    ├── ip_info.py\n    ├── os_detection.py\n    ├── parser.py\n    ├── reporter.py\n    ├── scanner.py\n    ├── shodan_client.py\n    ├── vuln_checks.py\n    └── web_dashboard.py\n```\n\n## Examples\n\n### Sample Scan Results\n\n```json\n{\n  \"scan_info\": {\n    \"target\": \"192.168.1.1\",\n    \"start_time\": \"2024-01-01T10:00:00Z\",\n    \"duration\": 45.2\n  },\n  \"hosts\": [\n    {\n      \"ip\": \"192.168.1.1\",\n      \"hostname\": \"router.local\",\n      \"ports\": [\n        {\n          \"port\": 22,\n          \"protocol\": \"tcp\",\n          \"state\": \"open\",\n          \"service\": \"ssh\",\n          \"banner\": \"SSH-2.0-OpenSSH_8.2p1\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Development\n\n### Running Tests\n\n```bash\npytest tests/ -v\n```\n\n### Code Style\n\nThis project follows PEP 8 and uses:\n- Type hints for all functions\n- Black for code formatting\n- Flake8 for linting\n- MyPy for type checking\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## Connect\n\n- LinkedIn: [Mr Cherif](https://www.linkedin.com/in/mrxcherif/)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Comprehensive Service Detection\n\nThe tool features a sophisticated 6-step service detection process:\n\n1. **Banner Grab**: Simple connection and banner reading\n2. **Application Probes**: Service-specific probes (HTTP GET, SMTP EHLO, FTP USER, MySQL handshake, Redis PING, etc.)\n3. **TLS Detection**: SSL/TLS certificate analysis and cipher identification\n4. **Nmap Analysis**: Industry-standard `nmap -sV` version detection\n5. **Protocol Fingerprinting**: Response pattern analysis and binary protocol detection\n6. **NSE Scripts**: Nmap Scripting Engine for vulnerability detection\n\n**Requirements for Full Functionality**:\n```bash\n# Install Nmap for best results\nsudo apt-get install nmap  # Ubuntu/Debian\nsudo yum install nmap      # CentOS/RHEL\nbrew install nmap         # macOS\n```\n\n**Service Detection Results**:\n- **High Confidence (0.8-1.0)**: SSH, HTTP, HTTPS, FTP, SMTP, MySQL, etc.\n- **Medium Confidence (0.5-0.7)**: Custom applications with clear patterns\n- **Unknown Services (0.1-0.4)**: Ports requiring manual investigation (711, 982, 1337, etc.)\n\n## Roadmap\n\n- [x] Comprehensive service detection with Nmap integration\n- [x] Sequential multi-host scanning\n- [x] Priority-based scan management\n- [x] Professional web dashboard\n- [x] Enhanced reporting with host information\n- [x] Graceful scan cancellation\n- [ ] Additional vulnerability checks\n- [ ] Integration with more security APIs\n- [ ] Advanced reporting features\n- [ ] Mobile app for scan monitoring\n- [ ] Cloud deployment templates\n\n## Security Notice\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrxcherif%2Fgingerscan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrxcherif%2Fgingerscan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrxcherif%2Fgingerscan/lists"}