# ScanHero
A modern, lightweight, and modular Python package for basic port and service scanning in cybersecurity contexts. ScanHero provides fast asynchronous port scanning capabilities with service detection, multiple output formats, and both CLI and Python API interfaces.
## Features
- **Fast Asynchronous Scanning**: Built on asyncio for high-performance concurrent port scanning
- **Service Detection**: Automatically detects common services (HTTP, HTTPS, SSH, FTP, SMTP, DNS, etc.)
- **Multiple Output Formats**: Console (with colors), JSON, and CSV output formats
- **Command-Line Interface**: Easy-to-use CLI with comprehensive options
- **Python API**: Clean, type-hinted API for integration into other projects
- **Modern Error Handling**: Comprehensive error handling with custom exceptions
- **Extensible Design**: Ready for future AI-powered features like anomaly detection
## Installation
### From PyPI (when published)
```bash
pip install scanhero
```
### From Source
```bash
git clone https://github.com/ahmetxhero/scanhero.git
cd scanhero
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/ahmetxhero/scanhero.git
cd scanhero
pip install -e ".[dev]"
```
## Quick Start
### Command Line Usage
```bash
# Basic scan
scanhero scan 192.168.1.1 --ports 80,443,22
# Scan port range
scanhero scan example.com --ports 1-1000
# JSON output
scanhero scan 10.0.0.1 --ports 80,443 --format json --output results.json
# Verbose output with service detection
scanhero scan target.com --ports 1-1000 --verbose --show-closed
```
### Python API Usage
```python
import asyncio
from scanhero import PortScanner, ScanConfig
async def main():
# Create scanner with custom configuration
config = ScanConfig(
timeout=3.0,
max_concurrent=100,
service_detection=True
)
scanner = PortScanner(config)
# Scan target
result = await scanner.scan("192.168.1.1", [80, 443, 22])
# Print results
print(f"Scanned {result.target}")
print(f"Found {result.open_count} open ports")
print(f"Scan completed in {result.scan_duration:.2f}s")
# Access individual port results
for port_result in result.open_ports:
print(f"Port {port_result.port}: {port_result.status.value}")
if port_result.service:
print(f" Service: {port_result.service.name}")
if port_result.service.version:
print(f" Version: {port_result.service.version}")
if __name__ == "__main__":
asyncio.run(main())
```
## Command Line Interface
### Scan Command
```bash
scanhero scan <target> [options]
```
#### Required Arguments
- `target`: Target host or IP address to scan
#### Optional Arguments
- `--ports, -p`: Ports to scan (default: 1-1000)
- Single port: `80`
- Multiple ports: `80,443,22`
- Port range: `1-1000`
- Mixed: `80,443,8080-8082`
- `--format, -f`: Output format (`console`, `json`, `csv`)
- `--output, -o`: Output file path (default: stdout)
#### Scan Options
- `--timeout, -t`: Connection timeout in seconds (default: 3.0)
- `--max-concurrent, -c`: Maximum concurrent connections (default: 100)
- `--retry-count, -r`: Number of retries for failed connections (default: 1)
- `--no-service-detection`: Disable service detection
- `--no-banner-grab`: Disable banner grabbing
- `--scan-delay`: Delay between scans in seconds (default: 0.0)
#### Display Options
- `--show-closed`: Show closed ports in console output
- `--show-filtered`: Show filtered ports in console output
- `--verbose, -v`: Enable verbose logging
## Python API Reference
### PortScanner
The main scanner class for performing port scans.
```python
from scanhero import PortScanner, ScanConfig
scanner = PortScanner(config=ScanConfig())
result = await scanner.scan(target, ports, service_detection=True)
```
#### Methods
- `scan(target, ports, service_detection=None)`: Perform port scan
- `target`: Target host or IP address
- `ports`: Port(s) to scan (int, list, or range string)
- `service_detection`: Override service detection setting
- Returns: `ScanResult` object
### ScanConfig
Configuration class for scanner behavior.
```python
config = ScanConfig(
timeout=3.0, # Connection timeout
max_concurrent=100, # Max concurrent connections
retry_count=1, # Retry attempts
service_detection=True, # Enable service detection
banner_grab=True, # Enable banner grabbing
scan_delay=0.0 # Delay between scans
)
```
### ScanResult
Result object containing scan information.
```python
result = await scanner.scan("192.168.1.1", [80, 443])
# Properties
result.target # Target that was scanned
result.scan_duration # Scan duration in seconds
result.timestamp # Scan timestamp
result.total_ports # Total ports scanned
result.open_count # Number of open ports
result.closed_count # Number of closed ports
result.filtered_count # Number of filtered ports
# Collections
result.open_ports # List of open PortResult objects
result.closed_ports # List of closed PortResult objects
result.filtered_ports # List of filtered PortResult objects
result.errors # List of error messages
# Methods
result.get_port_result(port) # Get result for specific port
result.get_services() # Get all detected services
```
### PortResult
Individual port scan result.
```python
port_result = result.open_ports[0]
port_result.port # Port number
port_result.status # PortStatus enum (OPEN, CLOSED, FILTERED, UNKNOWN)
port_result.service # ServiceInfo object (if detected)
port_result.response_time # Response time in milliseconds
port_result.error # Error message (if any)
```
### ServiceInfo
Service detection information.
```python
service = port_result.service
service.service_type # ServiceType enum
service.name # Human-readable service name
service.version # Service version (if detected)
service.banner # Raw banner information
service.confidence # Detection confidence (0.0 to 1.0)
```
## Output Formats
### Console Format
Rich, colored console output with tables and panels:
```
┌─ ScanHero Port Scanner Results ─┐
│ Target: 192.168.1.1 │
│ Scan Duration: 2.34s │
│ Timestamp: 2024-01-15T10:30:00 │
└─────────────────────────────────┘
┌─ Scan Summary ─┐
│ Metric │ Count │
├──────────────────┼───────┤
│ Total Ports │ 100 │
│ Open Ports │ 3 │
│ Closed Ports │ 95 │
│ Filtered Ports │ 2 │
└──────────────────┴───────┘
```
### JSON Format
Machine-readable JSON output:
```json
{
"target": "192.168.1.1",
"scan_duration": 2.34,
"timestamp": "2024-01-15T10:30:00",
"summary": {
"total_ports": 100,
"open_ports": 3,
"closed_ports": 95,
"filtered_ports": 2
},
"ports": {
"open": [
{
"port": 80,
"status": "open",
"response_time": 15.5,
"service": {
"type": "http",
"name": "HTTP",
"version": "2.4.41",
"banner": "Apache/2.4.41 (Ubuntu)",
"confidence": 0.9
}
}
]
}
}
```
### CSV Format
Spreadsheet-compatible CSV output:
```csv
Target,Port,Status,Service,Version,Response Time (ms),Confidence,Banner,Error
192.168.1.1,80,open,HTTP,2.4.41,15.5,0.90,Apache/2.4.41 (Ubuntu),
192.168.1.1,443,closed,,,,,,
```
## Supported Services
ScanHero can detect the following services:
- **Web Services**: HTTP, HTTPS
- **Remote Access**: SSH, Telnet
- **File Transfer**: FTP
- **Email**: SMTP, POP3, IMAP
- **Network Services**: DNS, SNMP, LDAP
- **Databases**: MySQL, PostgreSQL, Redis, MongoDB
- **Search**: Elasticsearch
## Error Handling
ScanHero provides comprehensive error handling with custom exceptions:
```python
from scanhero.exceptions import (
ScanHeroError,
ScanTimeoutError,
InvalidTargetError,
ServiceDetectionError,
ConfigurationError
)
try:
result = await scanner.scan("invalid-target", [80])
except InvalidTargetError as e:
print(f"Invalid target: {e.message}")
except ScanTimeoutError as e:
print(f"Scan timed out: {e.message}")
```
## Development
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=scanhero --cov-report=html
# Run specific test file
pytest tests/test_scanner.py
```
### Code Quality
```bash
# Format code
black src/ tests/
# Sort imports
isort src/ tests/
# Lint code
flake8 src/ tests/
# Type checking
mypy src/
```
### Pre-commit Hooks
```bash
# Install pre-commit hooks
pre-commit install
# Run hooks manually
pre-commit run --all-files
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Roadmap
- [ ] AI-powered anomaly detection
- [ ] Adaptive scanning strategies
- [ ] Vulnerability assessment integration
- [ ] Network topology mapping
- [ ] Performance optimization
- [ ] Additional service detection
- [ ] Plugin system for custom detectors
## Support
- **Documentation**: [https://scanhero.readthedocs.io](https://scanhero.readthedocs.io)
- **Issues**: [GitHub Issues](https://github.com/ahmetxhero/scanhero/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ahmetxhero/scanhero/discussions)
## Acknowledgments
- Built with modern Python async/await patterns
- Inspired by nmap and other network scanning tools
- Designed for cybersecurity professionals and developers
Raw data
{
"_id": null,
"home_page": null,
"name": "scanhero",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Ahmet Hero <ahmet@example.com>",
"keywords": "port-scanning, network-security, cybersecurity, asyncio, socket",
"author": null,
"author_email": "Ahmet Hero <ahmet@example.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/55/9534106d86cc3bab1f22d8e6c855a68beb4ce870868bd0a253a1db76fe09/scanhero-1.0.0.tar.gz",
"platform": null,
"description": "# ScanHero\n\nA modern, lightweight, and modular Python package for basic port and service scanning in cybersecurity contexts. ScanHero provides fast asynchronous port scanning capabilities with service detection, multiple output formats, and both CLI and Python API interfaces.\n\n## Features\n\n- **Fast Asynchronous Scanning**: Built on asyncio for high-performance concurrent port scanning\n- **Service Detection**: Automatically detects common services (HTTP, HTTPS, SSH, FTP, SMTP, DNS, etc.)\n- **Multiple Output Formats**: Console (with colors), JSON, and CSV output formats\n- **Command-Line Interface**: Easy-to-use CLI with comprehensive options\n- **Python API**: Clean, type-hinted API for integration into other projects\n- **Modern Error Handling**: Comprehensive error handling with custom exceptions\n- **Extensible Design**: Ready for future AI-powered features like anomaly detection\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\npip install scanhero\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/ahmetxhero/scanhero.git\ncd scanhero\npip install -e .\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/ahmetxhero/scanhero.git\ncd scanhero\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Command Line Usage\n\n```bash\n# Basic scan\nscanhero scan 192.168.1.1 --ports 80,443,22\n\n# Scan port range\nscanhero scan example.com --ports 1-1000\n\n# JSON output\nscanhero scan 10.0.0.1 --ports 80,443 --format json --output results.json\n\n# Verbose output with service detection\nscanhero scan target.com --ports 1-1000 --verbose --show-closed\n```\n\n### Python API Usage\n\n```python\nimport asyncio\nfrom scanhero import PortScanner, ScanConfig\n\nasync def main():\n # Create scanner with custom configuration\n config = ScanConfig(\n timeout=3.0,\n max_concurrent=100,\n service_detection=True\n )\n scanner = PortScanner(config)\n \n # Scan target\n result = await scanner.scan(\"192.168.1.1\", [80, 443, 22])\n \n # Print results\n print(f\"Scanned {result.target}\")\n print(f\"Found {result.open_count} open ports\")\n print(f\"Scan completed in {result.scan_duration:.2f}s\")\n \n # Access individual port results\n for port_result in result.open_ports:\n print(f\"Port {port_result.port}: {port_result.status.value}\")\n if port_result.service:\n print(f\" Service: {port_result.service.name}\")\n if port_result.service.version:\n print(f\" Version: {port_result.service.version}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Command Line Interface\n\n### Scan Command\n\n```bash\nscanhero scan <target> [options]\n```\n\n#### Required Arguments\n\n- `target`: Target host or IP address to scan\n\n#### Optional Arguments\n\n- `--ports, -p`: Ports to scan (default: 1-1000)\n - Single port: `80`\n - Multiple ports: `80,443,22`\n - Port range: `1-1000`\n - Mixed: `80,443,8080-8082`\n\n- `--format, -f`: Output format (`console`, `json`, `csv`)\n- `--output, -o`: Output file path (default: stdout)\n\n#### Scan Options\n\n- `--timeout, -t`: Connection timeout in seconds (default: 3.0)\n- `--max-concurrent, -c`: Maximum concurrent connections (default: 100)\n- `--retry-count, -r`: Number of retries for failed connections (default: 1)\n- `--no-service-detection`: Disable service detection\n- `--no-banner-grab`: Disable banner grabbing\n- `--scan-delay`: Delay between scans in seconds (default: 0.0)\n\n#### Display Options\n\n- `--show-closed`: Show closed ports in console output\n- `--show-filtered`: Show filtered ports in console output\n- `--verbose, -v`: Enable verbose logging\n\n## Python API Reference\n\n### PortScanner\n\nThe main scanner class for performing port scans.\n\n```python\nfrom scanhero import PortScanner, ScanConfig\n\nscanner = PortScanner(config=ScanConfig())\nresult = await scanner.scan(target, ports, service_detection=True)\n```\n\n#### Methods\n\n- `scan(target, ports, service_detection=None)`: Perform port scan\n - `target`: Target host or IP address\n - `ports`: Port(s) to scan (int, list, or range string)\n - `service_detection`: Override service detection setting\n - Returns: `ScanResult` object\n\n### ScanConfig\n\nConfiguration class for scanner behavior.\n\n```python\nconfig = ScanConfig(\n timeout=3.0, # Connection timeout\n max_concurrent=100, # Max concurrent connections\n retry_count=1, # Retry attempts\n service_detection=True, # Enable service detection\n banner_grab=True, # Enable banner grabbing\n scan_delay=0.0 # Delay between scans\n)\n```\n\n### ScanResult\n\nResult object containing scan information.\n\n```python\nresult = await scanner.scan(\"192.168.1.1\", [80, 443])\n\n# Properties\nresult.target # Target that was scanned\nresult.scan_duration # Scan duration in seconds\nresult.timestamp # Scan timestamp\nresult.total_ports # Total ports scanned\nresult.open_count # Number of open ports\nresult.closed_count # Number of closed ports\nresult.filtered_count # Number of filtered ports\n\n# Collections\nresult.open_ports # List of open PortResult objects\nresult.closed_ports # List of closed PortResult objects\nresult.filtered_ports # List of filtered PortResult objects\nresult.errors # List of error messages\n\n# Methods\nresult.get_port_result(port) # Get result for specific port\nresult.get_services() # Get all detected services\n```\n\n### PortResult\n\nIndividual port scan result.\n\n```python\nport_result = result.open_ports[0]\n\nport_result.port # Port number\nport_result.status # PortStatus enum (OPEN, CLOSED, FILTERED, UNKNOWN)\nport_result.service # ServiceInfo object (if detected)\nport_result.response_time # Response time in milliseconds\nport_result.error # Error message (if any)\n```\n\n### ServiceInfo\n\nService detection information.\n\n```python\nservice = port_result.service\n\nservice.service_type # ServiceType enum\nservice.name # Human-readable service name\nservice.version # Service version (if detected)\nservice.banner # Raw banner information\nservice.confidence # Detection confidence (0.0 to 1.0)\n```\n\n## Output Formats\n\n### Console Format\n\nRich, colored console output with tables and panels:\n\n```\n\u250c\u2500 ScanHero Port Scanner Results \u2500\u2510\n\u2502 Target: 192.168.1.1 \u2502\n\u2502 Scan Duration: 2.34s \u2502\n\u2502 Timestamp: 2024-01-15T10:30:00 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\u250c\u2500 Scan Summary \u2500\u2510\n\u2502 Metric \u2502 Count \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Total Ports \u2502 100 \u2502\n\u2502 Open Ports \u2502 3 \u2502\n\u2502 Closed Ports \u2502 95 \u2502\n\u2502 Filtered Ports \u2502 2 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### JSON Format\n\nMachine-readable JSON output:\n\n```json\n{\n \"target\": \"192.168.1.1\",\n \"scan_duration\": 2.34,\n \"timestamp\": \"2024-01-15T10:30:00\",\n \"summary\": {\n \"total_ports\": 100,\n \"open_ports\": 3,\n \"closed_ports\": 95,\n \"filtered_ports\": 2\n },\n \"ports\": {\n \"open\": [\n {\n \"port\": 80,\n \"status\": \"open\",\n \"response_time\": 15.5,\n \"service\": {\n \"type\": \"http\",\n \"name\": \"HTTP\",\n \"version\": \"2.4.41\",\n \"banner\": \"Apache/2.4.41 (Ubuntu)\",\n \"confidence\": 0.9\n }\n }\n ]\n }\n}\n```\n\n### CSV Format\n\nSpreadsheet-compatible CSV output:\n\n```csv\nTarget,Port,Status,Service,Version,Response Time (ms),Confidence,Banner,Error\n192.168.1.1,80,open,HTTP,2.4.41,15.5,0.90,Apache/2.4.41 (Ubuntu),\n192.168.1.1,443,closed,,,,,,\n```\n\n## Supported Services\n\nScanHero can detect the following services:\n\n- **Web Services**: HTTP, HTTPS\n- **Remote Access**: SSH, Telnet\n- **File Transfer**: FTP\n- **Email**: SMTP, POP3, IMAP\n- **Network Services**: DNS, SNMP, LDAP\n- **Databases**: MySQL, PostgreSQL, Redis, MongoDB\n- **Search**: Elasticsearch\n\n## Error Handling\n\nScanHero provides comprehensive error handling with custom exceptions:\n\n```python\nfrom scanhero.exceptions import (\n ScanHeroError,\n ScanTimeoutError,\n InvalidTargetError,\n ServiceDetectionError,\n ConfigurationError\n)\n\ntry:\n result = await scanner.scan(\"invalid-target\", [80])\nexcept InvalidTargetError as e:\n print(f\"Invalid target: {e.message}\")\nexcept ScanTimeoutError as e:\n print(f\"Scan timed out: {e.message}\")\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=scanhero --cov-report=html\n\n# Run specific test file\npytest tests/test_scanner.py\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Lint code\nflake8 src/ tests/\n\n# Type checking\nmypy src/\n```\n\n### Pre-commit Hooks\n\n```bash\n# Install pre-commit hooks\npre-commit install\n\n# Run hooks manually\npre-commit run --all-files\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Roadmap\n\n- [ ] AI-powered anomaly detection\n- [ ] Adaptive scanning strategies\n- [ ] Vulnerability assessment integration\n- [ ] Network topology mapping\n- [ ] Performance optimization\n- [ ] Additional service detection\n- [ ] Plugin system for custom detectors\n\n## Support\n\n- **Documentation**: [https://scanhero.readthedocs.io](https://scanhero.readthedocs.io)\n- **Issues**: [GitHub Issues](https://github.com/ahmetxhero/scanhero/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/ahmetxhero/scanhero/discussions)\n\n## Acknowledgments\n\n- Built with modern Python async/await patterns\n- Inspired by nmap and other network scanning tools\n- Designed for cybersecurity professionals and developers\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, lightweight, and modular Python package for basic port and service scanning in cybersecurity contexts",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ahmetxhero/scanhero/issues",
"Documentation": "https://scanhero.readthedocs.io",
"Homepage": "https://github.com/ahmetxhero/scanhero",
"Repository": "https://github.com/ahmetxhero/scanhero"
},
"split_keywords": [
"port-scanning",
" network-security",
" cybersecurity",
" asyncio",
" socket"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "47804e9fff8bb4f80651cf47afd82f9b5f679aecfdb42e67e91a8371aa38149f",
"md5": "8087b326a0897d320b97b4a15e8780e8",
"sha256": "b9fdbd2b8b46e5d27f293210b84a16f91bbf89c68a96a1cdd89bb67ca8e33177"
},
"downloads": -1,
"filename": "scanhero-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8087b326a0897d320b97b4a15e8780e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19089,
"upload_time": "2025-09-07T21:16:30",
"upload_time_iso_8601": "2025-09-07T21:16:30.858454Z",
"url": "https://files.pythonhosted.org/packages/47/80/4e9fff8bb4f80651cf47afd82f9b5f679aecfdb42e67e91a8371aa38149f/scanhero-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d559534106d86cc3bab1f22d8e6c855a68beb4ce870868bd0a253a1db76fe09",
"md5": "ce99ab136c0ad3646f15aa4c50bbfeaf",
"sha256": "3f5879f749dd0e57fd35468da3429fe9acc13f8da52b31766b0b127d34ee6233"
},
"downloads": -1,
"filename": "scanhero-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ce99ab136c0ad3646f15aa4c50bbfeaf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24268,
"upload_time": "2025-09-07T21:16:32",
"upload_time_iso_8601": "2025-09-07T21:16:32.038682Z",
"url": "https://files.pythonhosted.org/packages/7d/55/9534106d86cc3bab1f22d8e6c855a68beb4ce870868bd0a253a1db76fe09/scanhero-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 21:16:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ahmetxhero",
"github_project": "scanhero",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "scanhero"
}
JSON
