# Simple Port Checker
A comprehensive Python tool for checking firewall ports and detecting L7 protection services (WAF, CDN, etc.).
## Features
- ✅ **Port Scanning**: Check well-known firewall ports and services
- 🛡️ **L7 Protection Detection**: Identify WAF/CDN services (F5, AWS WAF, Azure, Cloudflare, etc.)
- 🚀 **Async Support**: High-performance concurrent scanning
- 📊 **Rich Output**: Beautiful terminal output with progress bars
- 🔧 **CLI Interface**: Easy-to-use command-line interface
- 📦 **Pip Installable**: Available on PyPI
## Installation
### From PyPI (recommended)
```bash
pip install simple-port-checker
```
### From Source
```bash
git clone https://github.com/htunn/simple-port-checker.git
cd simple-port-checker
pip install -e .
```
## Quick Start
### Command Line Usage
```bash
# Basic port scan
port-checker scan example.com
# Scan specific ports
port-checker scan example.com --ports 80,443,8080
# Check L7 protection
port-checker l7-check example.com
# Full scan with L7 detection
port-checker full-scan example.com
# Scan multiple targets
port-checker scan example.com google.com --output results.json
```
### Python API Usage
```python
from simple_port_checker import PortChecker, L7Detector
# Initialize scanner
scanner = PortChecker()
# Scan ports
results = await scanner.scan_host("example.com", ports=[80, 443, 8080])
print(f"Open ports: {len([p for p in results.ports if p.is_open])}")
# Detect L7 protection
detector = L7Detector()
protection = await detector.detect("example.com")
if protection.primary_protection:
service = protection.primary_protection.service.value
confidence = protection.primary_protection.confidence
print(f"L7 Protection: {service} ({confidence:.0%})")
else:
print("No L7 protection detected")
```
## Architecture & Flow
The following sequence diagram illustrates the end-to-end flow of Simple Port Checker:
```mermaid
sequenceDiagram
participant User
participant CLI
participant PortChecker
participant L7Detector
participant Target as Target Host
participant DNS
participant HTTP as HTTP/HTTPS
%% Port Scanning Flow
rect rgb(200, 255, 200)
Note over User, HTTP: Port Scanning Phase
User->>+CLI: port-checker scan target.com
CLI->>+PortChecker: scan_host(target.com, ports)
PortChecker->>+DNS: Resolve hostname
DNS-->>-PortChecker: IP address
par Port 80
PortChecker->>+Target: TCP Connect :80
Target-->>-PortChecker: Connection response
and Port 443
PortChecker->>+Target: TCP Connect :443
Target-->>-PortChecker: Connection response
and Port 22
PortChecker->>+Target: TCP Connect :22
Target-->>-PortChecker: Connection response
end
PortChecker->>+Target: Banner grabbing
Target-->>-PortChecker: Service banners
PortChecker-->>-CLI: ScanResult
CLI-->>-User: Rich formatted output
end
%% L7 Protection Detection Flow
rect rgb(200, 200, 255)
Note over User, HTTP: L7 Protection Detection Phase
User->>+CLI: port-checker l7-check target.com
CLI->>+L7Detector: detect(target.com)
L7Detector->>+HTTP: HTTPS Request
HTTP-->>-L7Detector: Response + Headers
L7Detector->>L7Detector: Analyze Headers<br/>(CF-Ray, X-Amzn-RequestId, etc.)
L7Detector->>L7Detector: Check Response Body<br/>(WAF signatures)
L7Detector->>+DNS: CNAME Lookup
DNS-->>-L7Detector: DNS Records
L7Detector->>L7Detector: Match Signatures<br/>(Cloudflare, AWS WAF, etc.)
alt WAF/CDN Detected
L7Detector-->>CLI: L7Result (Protected)
CLI-->>User: "✓ Protection: Cloudflare (95%)"
else No Protection
L7Detector-->>CLI: L7Result (Unprotected)
CLI-->>User: "✗ No L7 Protection Detected"
end
L7Detector-->>-CLI: L7Result
CLI-->>-User: Rich formatted output
end
%% Full Scan Flow
rect rgb(255, 255, 200)
Note over User, HTTP: Full Scan (Combined)
User->>+CLI: port-checker full-scan target.com
CLI->>CLI: Execute Port Scan
CLI->>CLI: Execute L7 Detection
CLI-->>-User: Complete security assessment
end
```
### Key Components
- **CLI**: Rich command-line interface with progress bars and colored output
- **PortChecker**: Async port scanner with configurable concurrency and timeouts
- **L7Detector**: HTTP header and DNS analysis for WAF/CDN detection
- **DNS Resolution**: Hostname to IP mapping and CNAME analysis
- **Target Host**: The system being scanned for open ports and services
- **HTTP/HTTPS**: Web service detection and L7 protection analysis
### Supported Detection Methods
1. **Port Scanning**: TCP connection attempts with banner grabbing
2. **HTTP Header Analysis**: Identifying protection service signatures
3. **DNS Analysis**: CNAME records pointing to CDN/WAF providers
4. **Response Pattern Matching**: Service-specific response signatures
5. **IP Range Detection**: Known IP ranges for major providers
## Supported L7 Protection Services
- **AWS WAF** - Amazon Web Application Firewall
- **Azure WAF** - Microsoft Azure Web Application Firewall
- **F5 BIG-IP** - F5 Application Security Manager
- **Cloudflare** - Cloudflare WAF and DDoS Protection
- **Akamai** - Akamai Web Application Protector
- **Imperva** - Imperva SecureSphere WAF
- **Sucuri** - Sucuri Website Firewall
- **Fastly** - Fastly Edge Security
- **KeyCDN** - KeyCDN Security
- **MaxCDN** - MaxCDN Security
## Well-Known Ports Checked
| Port | Service | Description |
|------|---------|-------------|
| 80 | HTTP | Web traffic |
| 443 | HTTPS | Secure web traffic |
| 8080 | HTTP-ALT | Alternative HTTP |
| 8443 | HTTPS-ALT | Alternative HTTPS |
| 3389 | RDP | Remote Desktop Protocol |
| 22 | SSH | Secure Shell |
| 21 | FTP | File Transfer Protocol |
| 25 | SMTP | Simple Mail Transfer Protocol |
| 53 | DNS | Domain Name System |
| 110 | POP3 | Post Office Protocol |
| 143 | IMAP | Internet Message Access Protocol |
| 993 | IMAPS | IMAP over SSL |
| 995 | POP3S | POP3 over SSL |
| 587 | SMTP-MSA | SMTP Message Submission |
## CLI Commands
### `port-checker scan`
Scan target hosts for open ports.
```bash
port-checker scan TARGET [OPTIONS]
Options:
--ports TEXT Comma-separated list of ports (default: common ports)
--timeout INTEGER Connection timeout in seconds (default: 3)
--concurrent INTEGER Maximum concurrent connections (default: 100)
--output TEXT Output file (JSON format)
--verbose Enable verbose output
```
### `port-checker l7-check`
Check for L7 protection services.
```bash
port-checker l7-check TARGET [OPTIONS]
Options:
--timeout INTEGER Request timeout in seconds (default: 10)
--user-agent TEXT Custom User-Agent string
--output TEXT Output file (JSON format)
--verbose Enable verbose output
```
### `port-checker full-scan`
Perform both port scanning and L7 protection detection.
```bash
port-checker full-scan TARGET [OPTIONS]
Options:
--ports TEXT Comma-separated list of ports
--timeout INTEGER Connection timeout in seconds
--concurrent INTEGER Maximum concurrent connections
--output TEXT Output file (JSON format)
--verbose Enable verbose output
```
## Configuration
Create a configuration file at `~/.port-checker.yaml`:
```yaml
default_ports: [80, 443, 8080, 8443, 22, 21, 25, 53]
timeout: 5
concurrent_limit: 50
user_agent: "SimplePortChecker/1.0"
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/htunn/simple-port-checker.git
cd simple-port-checker
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest
pytest --cov=simple_port_checker # With coverage
```
### Code Formatting
```bash
black src/ tests/
isort src/ tests/
flake8 src/ tests/
mypy src/
```
### Pre-commit Hooks
```bash
pre-commit install
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.
## Changelog
### v0.1.0 (Initial Release)
- Basic port scanning functionality
- L7 protection detection
- CLI interface
- Async support
- Rich terminal output
## Security Considerations
This tool is intended for legitimate security testing and network diagnostics only. Users are responsible for ensuring they have proper authorization before scanning any networks or systems they do not own.
## Support
- 📖 [Documentation](https://github.com/htunn/simple-port-checker#readme)
- 🐛 [Issue Tracker](https://github.com/htunn/simple-port-checker/issues)
## Acknowledgments
- Thanks to the Python community for excellent libraries
- Inspired by nmap and other network scanning tools
- Built with ❤️ for the security community
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-port-checker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "htunn <htunnthuthu.linux@gmail.com>",
"keywords": "firewall, l7-protection, network, port-scanner, security, waf",
"author": null,
"author_email": "htunn <htunnthuthu.linux@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/95/b3/5cdd225871552f76b80daade1ad874435b4ceba375b5b3ac27eb1933983b/simple_port_checker-0.1.10.tar.gz",
"platform": null,
"description": "# Simple Port Checker\n\nA comprehensive Python tool for checking firewall ports and detecting L7 protection services (WAF, CDN, etc.).\n\n## Features\n\n- \u2705 **Port Scanning**: Check well-known firewall ports and services\n- \ud83d\udee1\ufe0f **L7 Protection Detection**: Identify WAF/CDN services (F5, AWS WAF, Azure, Cloudflare, etc.)\n- \ud83d\ude80 **Async Support**: High-performance concurrent scanning\n- \ud83d\udcca **Rich Output**: Beautiful terminal output with progress bars\n- \ud83d\udd27 **CLI Interface**: Easy-to-use command-line interface\n- \ud83d\udce6 **Pip Installable**: Available on PyPI\n\n## Installation\n\n### From PyPI (recommended)\n```bash\npip install simple-port-checker\n```\n\n### From Source\n```bash\ngit clone https://github.com/htunn/simple-port-checker.git\ncd simple-port-checker\npip install -e .\n```\n\n## Quick Start\n\n### Command Line Usage\n\n```bash\n# Basic port scan\nport-checker scan example.com\n\n# Scan specific ports\nport-checker scan example.com --ports 80,443,8080\n\n# Check L7 protection\nport-checker l7-check example.com\n\n# Full scan with L7 detection\nport-checker full-scan example.com\n\n# Scan multiple targets\nport-checker scan example.com google.com --output results.json\n```\n\n### Python API Usage\n\n```python\nfrom simple_port_checker import PortChecker, L7Detector\n\n# Initialize scanner\nscanner = PortChecker()\n\n# Scan ports\nresults = await scanner.scan_host(\"example.com\", ports=[80, 443, 8080])\nprint(f\"Open ports: {len([p for p in results.ports if p.is_open])}\")\n\n# Detect L7 protection\ndetector = L7Detector()\nprotection = await detector.detect(\"example.com\")\nif protection.primary_protection:\n service = protection.primary_protection.service.value\n confidence = protection.primary_protection.confidence\n print(f\"L7 Protection: {service} ({confidence:.0%})\")\nelse:\n print(\"No L7 protection detected\")\n```\n\n## Architecture & Flow\n\nThe following sequence diagram illustrates the end-to-end flow of Simple Port Checker:\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant PortChecker\n participant L7Detector\n participant Target as Target Host\n participant DNS\n participant HTTP as HTTP/HTTPS\n \n %% Port Scanning Flow\n rect rgb(200, 255, 200)\n Note over User, HTTP: Port Scanning Phase\n User->>+CLI: port-checker scan target.com\n CLI->>+PortChecker: scan_host(target.com, ports)\n \n PortChecker->>+DNS: Resolve hostname\n DNS-->>-PortChecker: IP address\n \n par Port 80\n PortChecker->>+Target: TCP Connect :80\n Target-->>-PortChecker: Connection response\n and Port 443 \n PortChecker->>+Target: TCP Connect :443\n Target-->>-PortChecker: Connection response\n and Port 22\n PortChecker->>+Target: TCP Connect :22\n Target-->>-PortChecker: Connection response\n end\n \n PortChecker->>+Target: Banner grabbing\n Target-->>-PortChecker: Service banners\n \n PortChecker-->>-CLI: ScanResult\n CLI-->>-User: Rich formatted output\n end\n \n %% L7 Protection Detection Flow \n rect rgb(200, 200, 255)\n Note over User, HTTP: L7 Protection Detection Phase\n User->>+CLI: port-checker l7-check target.com\n CLI->>+L7Detector: detect(target.com)\n \n L7Detector->>+HTTP: HTTPS Request\n HTTP-->>-L7Detector: Response + Headers\n \n L7Detector->>L7Detector: Analyze Headers<br/>(CF-Ray, X-Amzn-RequestId, etc.)\n L7Detector->>L7Detector: Check Response Body<br/>(WAF signatures)\n \n L7Detector->>+DNS: CNAME Lookup\n DNS-->>-L7Detector: DNS Records\n \n L7Detector->>L7Detector: Match Signatures<br/>(Cloudflare, AWS WAF, etc.)\n \n alt WAF/CDN Detected\n L7Detector-->>CLI: L7Result (Protected)\n CLI-->>User: \"\u2713 Protection: Cloudflare (95%)\"\n else No Protection\n L7Detector-->>CLI: L7Result (Unprotected) \n CLI-->>User: \"\u2717 No L7 Protection Detected\"\n end\n \n L7Detector-->>-CLI: L7Result\n CLI-->>-User: Rich formatted output\n end\n \n %% Full Scan Flow\n rect rgb(255, 255, 200)\n Note over User, HTTP: Full Scan (Combined)\n User->>+CLI: port-checker full-scan target.com\n CLI->>CLI: Execute Port Scan\n CLI->>CLI: Execute L7 Detection\n CLI-->>-User: Complete security assessment\n end\n```\n\n### Key Components\n\n- **CLI**: Rich command-line interface with progress bars and colored output\n- **PortChecker**: Async port scanner with configurable concurrency and timeouts\n- **L7Detector**: HTTP header and DNS analysis for WAF/CDN detection\n- **DNS Resolution**: Hostname to IP mapping and CNAME analysis\n- **Target Host**: The system being scanned for open ports and services\n- **HTTP/HTTPS**: Web service detection and L7 protection analysis\n\n### Supported Detection Methods\n\n1. **Port Scanning**: TCP connection attempts with banner grabbing\n2. **HTTP Header Analysis**: Identifying protection service signatures\n3. **DNS Analysis**: CNAME records pointing to CDN/WAF providers\n4. **Response Pattern Matching**: Service-specific response signatures\n5. **IP Range Detection**: Known IP ranges for major providers\n\n## Supported L7 Protection Services\n\n- **AWS WAF** - Amazon Web Application Firewall\n- **Azure WAF** - Microsoft Azure Web Application Firewall \n- **F5 BIG-IP** - F5 Application Security Manager\n- **Cloudflare** - Cloudflare WAF and DDoS Protection\n- **Akamai** - Akamai Web Application Protector\n- **Imperva** - Imperva SecureSphere WAF\n- **Sucuri** - Sucuri Website Firewall\n- **Fastly** - Fastly Edge Security\n- **KeyCDN** - KeyCDN Security\n- **MaxCDN** - MaxCDN Security\n\n## Well-Known Ports Checked\n\n| Port | Service | Description |\n|------|---------|-------------|\n| 80 | HTTP | Web traffic |\n| 443 | HTTPS | Secure web traffic |\n| 8080 | HTTP-ALT | Alternative HTTP |\n| 8443 | HTTPS-ALT | Alternative HTTPS |\n| 3389 | RDP | Remote Desktop Protocol |\n| 22 | SSH | Secure Shell |\n| 21 | FTP | File Transfer Protocol |\n| 25 | SMTP | Simple Mail Transfer Protocol |\n| 53 | DNS | Domain Name System |\n| 110 | POP3 | Post Office Protocol |\n| 143 | IMAP | Internet Message Access Protocol |\n| 993 | IMAPS | IMAP over SSL |\n| 995 | POP3S | POP3 over SSL |\n| 587 | SMTP-MSA | SMTP Message Submission |\n\n## CLI Commands\n\n### `port-checker scan`\nScan target hosts for open ports.\n\n```bash\nport-checker scan TARGET [OPTIONS]\n\nOptions:\n --ports TEXT Comma-separated list of ports (default: common ports)\n --timeout INTEGER Connection timeout in seconds (default: 3)\n --concurrent INTEGER Maximum concurrent connections (default: 100)\n --output TEXT Output file (JSON format)\n --verbose Enable verbose output\n```\n\n### `port-checker l7-check`\nCheck for L7 protection services.\n\n```bash\nport-checker l7-check TARGET [OPTIONS]\n\nOptions:\n --timeout INTEGER Request timeout in seconds (default: 10)\n --user-agent TEXT Custom User-Agent string\n --output TEXT Output file (JSON format)\n --verbose Enable verbose output\n```\n\n### `port-checker full-scan`\nPerform both port scanning and L7 protection detection.\n\n```bash\nport-checker full-scan TARGET [OPTIONS]\n\nOptions:\n --ports TEXT Comma-separated list of ports\n --timeout INTEGER Connection timeout in seconds\n --concurrent INTEGER Maximum concurrent connections\n --output TEXT Output file (JSON format)\n --verbose Enable verbose output\n```\n\n## Configuration\n\nCreate a configuration file at `~/.port-checker.yaml`:\n\n```yaml\ndefault_ports: [80, 443, 8080, 8443, 22, 21, 25, 53]\ntimeout: 5\nconcurrent_limit: 50\nuser_agent: \"SimplePortChecker/1.0\"\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/htunn/simple-port-checker.git\ncd simple-port-checker\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Run Tests\n\n```bash\npytest\npytest --cov=simple_port_checker # With coverage\n```\n\n### Code Formatting\n\n```bash\nblack src/ tests/\nisort src/ tests/\nflake8 src/ tests/\nmypy src/\n```\n\n### Pre-commit Hooks\n\n```bash\npre-commit install\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## Changelog\n\n### v0.1.0 (Initial Release)\n- Basic port scanning functionality\n- L7 protection detection\n- CLI interface\n- Async support\n- Rich terminal output\n\n## Security Considerations\n\nThis tool is intended for legitimate security testing and network diagnostics only. Users are responsible for ensuring they have proper authorization before scanning any networks or systems they do not own.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://github.com/htunn/simple-port-checker#readme)\n- \ud83d\udc1b [Issue Tracker](https://github.com/htunn/simple-port-checker/issues)\n\n## Acknowledgments\n\n- Thanks to the Python community for excellent libraries\n- Inspired by nmap and other network scanning tools\n- Built with \u2764\ufe0f for the security community\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive tool for checking firewall ports and L7 protection services",
"version": "0.1.10",
"project_urls": {
"Documentation": "https://github.com/htunn/simple-port-checker#readme",
"Homepage": "https://github.com/htunn/simple-port-checker",
"Issues": "https://github.com/htunn/simple-port-checker/issues",
"Repository": "https://github.com/htunn/simple-port-checker"
},
"split_keywords": [
"firewall",
" l7-protection",
" network",
" port-scanner",
" security",
" waf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f6b4d4179033b60b0df9115a20737c722351104b1254949f4b5fbe4995d91dfe",
"md5": "deaf54af2b3a6962846fe4da47ed7eb7",
"sha256": "b231c027e5430f2d766e1b2a4e5e402e38ee4dd84b572d3ce99e4a1b4dab804c"
},
"downloads": -1,
"filename": "simple_port_checker-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "deaf54af2b3a6962846fe4da47ed7eb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 30837,
"upload_time": "2025-09-14T15:42:23",
"upload_time_iso_8601": "2025-09-14T15:42:23.409965Z",
"url": "https://files.pythonhosted.org/packages/f6/b4/d4179033b60b0df9115a20737c722351104b1254949f4b5fbe4995d91dfe/simple_port_checker-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "95b35cdd225871552f76b80daade1ad874435b4ceba375b5b3ac27eb1933983b",
"md5": "1c1da075dc8daec25b3c02a8c30e2a8f",
"sha256": "6a306608921bb462c43ee453574a369ff604c0d1cc0228736240c111c37d76e7"
},
"downloads": -1,
"filename": "simple_port_checker-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "1c1da075dc8daec25b3c02a8c30e2a8f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 29698,
"upload_time": "2025-09-14T15:42:24",
"upload_time_iso_8601": "2025-09-14T15:42:24.894876Z",
"url": "https://files.pythonhosted.org/packages/95/b3/5cdd225871552f76b80daade1ad874435b4ceba375b5b3ac27eb1933983b/simple_port_checker-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 15:42:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "htunn",
"github_project": "simple-port-checker#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.9.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "dnspython",
"specs": [
[
">=",
"2.4.0"
]
]
},
{
"name": "python-nmap",
"specs": [
[
">=",
"0.7.1"
]
]
},
{
"name": "asyncio-throttle",
"specs": [
[
">=",
"1.0.2"
]
]
}
],
"lcname": "simple-port-checker"
}
JSON
