Advanced Port Scanner
Professional defensive network discovery for authorized security testing.
Fast local CLI • Flask dashboard • Versioned API • Persistent history • Reports • Analytics • Operational metrics • Controlled CVE enrichment
Authorized use only. Scan systems you own or have explicit permission to assess.
Overview
Advanced Port Scanner is a Python-based network discovery platform designed for controlled, authorized security assessment. It combines a focused command-line interface with a Flask dashboard and versioned REST API.
The project is built around predictable resource controls, persistent scan history, cooperative job cancellation, structured reporting, operational metrics, controlled CVE enrichment, and security-conscious deployment defaults.
Why this project
- One scanner, multiple interfaces — use the CLI for focused work or the dashboard/API for repeatable operations.
- Bounded by design — target, port, concurrency, timeout, queue, and retention limits keep workloads predictable.
- Operationally useful — scans persist to SQLite, exports can be generated as JSON/CSV/TXT/HTML, analytics are derived from stored results, and operational metrics expose current workload and historical outcomes.
- Security-aware — authentication, RBAC, CSRF protection, rate limiting, security headers, non-root containers, and dropped Linux capabilities are included.
- Transparent results — service and risk metadata are presented as observations and guidance, not as proof of vulnerabilities.
Features
Scanning
- Concurrent TCP connect scanning with bounded worker usage
- Optional SYN mode for controlled lab environments
- IPv4/IPv6 connection handling
- Lightweight banner collection
- Service/product/version fingerprinting with confidence metadata
- Heuristic TTL/OS indication
- Configurable socket and banner timeouts
- Reusable scan profiles
Job management
- Bounded asynchronous scan queue
- Live progress reporting
- Cooperative cancellation
- Accurate terminal status and elapsed time
- Persistent history for completed, failed, and cancelled jobs
- Configurable history retention
Reporting, analytics & metrics
- Versioned JSON report model
- CSV and TXT exports
- HTML reports with scan metadata and findings
- Persistent scan history in SQLite
- Configurable report retention
- Analytics for scan volume, unique targets, open ports, high-risk findings, duration, risk distribution, and top services
- Operational metrics for active/queued/running jobs, retained history, completed/failed/cancelled scans, average duration, and total open ports
CVE enrichment
- Separate from heuristic port-risk hints
- Explicit modes:
off,offline, andonline - Operator-supplied offline JSON feeds
- Optional NVD API lookup in online mode
- Source-aware CVE records with severity, score, summary, and URL metadata
- Enrichment failures are non-critical to scan execution
Web & API
- Responsive Flask dashboard
- Versioned
/api/v1endpoints - Request IDs for API responses
- Session authentication with
viewer,operator, andadminroles - Login and scan rate limiting
- CSRF protection for protected mutations
- Security response headers
- Trusted-proxy support only when explicitly enabled
Deployment & distribution
- Installable Python package with an
apsconsole command - Gunicorn-compatible web deployment
- Non-root Docker execution
no-new-privilegesand dropped capabilities in Compose- Persistent Docker storage for SQLite data, reports, and logs
- CI across Python 3.11, 3.12, and 3.13
- Tag-driven PyPI publishing workflow using GitHub OIDC trusted publishing
Architecture
┌─────────────────────┐
│ CLI / Web UI │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Input validation & │
│ target resolution │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Job Manager │
│ queue • progress • │
│ cancellation │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Scan Engine │
│ TCP • SYN • banner │
│ service detection │
└───────┬─────┬───────┘
│ │
┌───────────┘ └────────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ SQLite history │ │ JSON/CSV/TXT/ │
│ + analytics │ │ HTML reports │
└────────┬────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Operational │
│ metrics + CVE │
│ enrichment │
└─────────────────┘
Project layout
advanced-port-scanner/
├── scanner/
│ ├── analytics.py
│ ├── auth.py
│ ├── config.py
│ ├── cve.py
│ ├── history.py
│ ├── jobs.py
│ ├── metrics.py
│ ├── profiles.py
│ ├── reporting.py
│ ├── retention.py
│ ├── scanner.py
│ ├── security.py
│ ├── service_detection.py
│ ├── utils.py
│ ├── version.py
│ └── vuln_hints.py
├── web/
│ ├── api_v1.py
│ ├── app.py
│ └── templates/
├── tests/
├── docs/
├── data/
├── reports/
├── logs/
├── .github/workflows/
│ ├── ci.yml
│ └── pypi.yml
├── Dockerfile
├── docker-compose.yml
├── main.py
├── pyproject.toml
├── requirements.txt
├── CHANGELOG.md
└── README.md
Requirements
- Python 3.11 or newer
- For normal TCP scanning: standard Python runtime plus project dependencies
- Optional Scapy installation for SYN mode
- Docker and Docker Compose for container deployment
Installation
From source
git clone https://github.com/hack2ai/advanced-port-scanner.git
cd advanced-port-scanner
python -m venv .venv
Activate the environment and install the project:
python -m pip install -e .
Optional SYN support:
python -m pip install -e '.[syn]'
Verify the installation:
aps --version
aps --help
CLI usage
List available profiles:
aps profiles
Run a small authorized local/lab scan:
aps scan 127.0.0.1 --profile quick
Use the standard profile:
aps scan 127.0.0.1 --profile standard
Specify an explicit range:
aps scan 127.0.0.1 --ports 1-1024
Disable banner collection:
aps scan 127.0.0.1 --profile standard --no-banner
Save reports:
aps scan 127.0.0.1 --profile standard \
--save-json --save-csv --save-txt \
--output-dir reports
The CLI and web API both enforce MAX_TARGETS and MAX_PORTS safety limits. Profiles cannot bypass those controls.
Dashboard
Start the Flask application locally:
python web/app.py
Open:
http://127.0.0.1:5000
For a production-style process, use Gunicorn as described in docs/installation.md.
API v1
The preferred machine-readable interface is /api/v1.
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/health |
Service health |
GET |
/api/v1/profiles |
Available profiles |
POST |
/api/v1/scans |
Queue an authorized scan |
GET |
/api/v1/scans/<job_id> |
Read scan status/results |
POST |
/api/v1/scans/<job_id>/cancel |
Request cancellation |
GET |
/api/v1/jobs |
List recent jobs |
GET |
/api/v1/history |
List persisted history |
GET |
/api/v1/history/<job_id> |
Read stored scan details |
GET |
/api/v1/reports/<job_id>/html |
Render an HTML report |
GET |
/api/v1/analytics |
Read persisted analytics |
GET |
/api/v1/metrics |
Read operational metrics |
GET |
/api/v1/cve/lookup |
Lookup CVE enrichment for an observed product/version |
The metrics response currently includes:
{
"data": {
"active_jobs": 0,
"queued_jobs": 0,
"running_jobs": 0,
"retained_history": 0,
"completed_scans": 0,
"failed_scans": 0,
"cancelled_scans": 0,
"average_duration_seconds": 0.0,
"total_open_ports": 0
},
"request_id": "..."
}
CVE lookup example:
GET /api/v1/cve/lookup?product=OpenSSH&version=9.8
CVE enrichment is controlled by the configured mode and is off by default.
Successful JSON responses use a request-aware envelope:
{
"data": {},
"request_id": "..."
}
Errors use a structured form:
{
"error": {
"code": "...",
"message": "..."
},
"request_id": "..."
}
Legacy /api/... endpoints remain available for compatibility.
Scan profiles
| Profile | Range | Intended use |
|---|---|---|
quick |
1-100 |
Fast first-pass discovery |
standard |
1-1024 |
General-purpose discovery |
extended |
1-10000 |
Broader service discovery |
full |
1-65535 |
Full TCP port coverage when explicitly permitted |
The effective range is always subject to the configured MAX_PORTS limit.
Configuration
Configuration is centralized in scanner/config.py and can be overridden using environment variables.
Key controls include:
| Variable | Default | Purpose |
|---|---|---|
HOST |
127.0.0.1 |
Bind address |
PORT |
5000 |
Web port |
MAX_CONCURRENT_JOBS |
2 |
Concurrent queued scans |
MAX_TARGETS |
16 |
Maximum targets per request |
MAX_PORTS |
4096 |
Maximum ports per scan |
SOCKET_TIMEOUT |
0.5 |
TCP connection timeout |
BANNER_TIMEOUT |
0.75 |
Banner probe timeout |
HISTORY_RETENTION |
100 |
Stored history records |
REPORT_RETENTION |
100 |
Stored report groups |
AUTH_ENABLED |
false |
Enable session authentication |
SECURE_COOKIES |
false |
Mark cookies Secure |
TRUST_PROXY_HEADERS |
false |
Trust X-Forwarded-For when behind a configured proxy |
CVE_MODE |
off |
CVE enrichment mode: off, offline, or online |
CVE_FEED |
empty | Operator-supplied offline CVE JSON feed |
CVE_TIMEOUT |
5.0 |
Online CVE request timeout |
CVE_API_URL |
NVD v2 API | Online CVE provider endpoint |
See docs/configuration.md for authentication, password hashing, rate limits, CVE enrichment, and deployment guidance.
Docker
Build and start the stack:
docker compose up --build
The Compose configuration:
- runs the application as a non-root user
- drops Linux capabilities
- enables
no-new-privileges - persists data, reports, and logs using Docker-managed volumes
- keeps SYN/raw-packet capability disabled by default
The container intentionally uses one Gunicorn worker with multiple threads because scan job state and rate-limit state are process-local. Multi-process scaling requires a shared job/rate-limit backend.
For authorized lab environments that require SYN mode, review the commented capability configuration in docker-compose.yml and enable it deliberately.
CVE enrichment
CVE enrichment is intentionally separate from the scanner's heuristic risk hints. A reachable port is not a CVE finding.
Modes:
- off — no external or local CVE lookup
- offline — search an operator-supplied JSON feed
- online — query the configured NVD API endpoint
Example environment configuration:
export CVE_MODE=offline
export CVE_FEED=data/cve-feed.json
The online mode must be explicitly enabled. Network errors return an empty enrichment result rather than causing an otherwise valid scan to fail.
Security model
Authentication is disabled by default for local development. For controlled deployments, enable authentication and configure a strong secret, credentials, and appropriate cookie settings.
Roles:
- viewer — read-only access to jobs, history, analytics, reports, metrics, and CVE lookup
- operator — viewer access plus scan and cancellation operations
- admin — operator access plus administrative capability reserved for future expansion
Additional protections include CSRF validation, login/scan rate limiting, response security headers, bounded workloads, and explicit trusted-proxy configuration.
Important limitations
- Open ports indicate network reachability, not vulnerability.
- Risk labels are informational guidance, not a substitute for vulnerability research.
- CVE enrichment depends on accurate product/version identification and the selected data source; a keyword match is not proof that a specific host is vulnerable.
- Service fingerprinting is heuristic and reports confidence rather than certainty.
- TTL/OS identification is heuristic and can be influenced by routing devices.
- Banner collection is intentionally lightweight.
- Operational metrics are derived from process-local jobs and retained history, not a long-term telemetry system.
- Before exposing the dashboard/API outside a trusted environment, use authentication, TLS, and network access controls.
Reports & history
A completed scan can produce a structured report with:
- schema and scanner version
- scan time and duration
- scan type and profile
- selected port range
- target-level results
- service/version/banner observations
- risk guidance
The HTML report is designed for human review, while JSON is the preferred structured format for automation.
Persisted history is stored in SQLite and is bounded by HISTORY_RETENTION. Generated report groups are bounded by REPORT_RETENTION.
Testing & development
Run the complete test suite locally:
python -m pytest -q
The repository CI validates the project across Python 3.11, 3.12, and 3.13.
Recommended development loop:
python -m pytest -q
aps --help
aps profiles
When changing API or deployment behavior, add or update regression coverage in tests/.
Release
Current application version: 0.3.0.
See CHANGELOG.md and docs/v0.3-release.md for release details.
License
This project is licensed under the MIT License. See LICENSE.
Responsible use
Use Advanced Port Scanner only on systems and networks you are authorized to assess. The project is intended for defensive discovery, validation, and security testing—not credential attacks, exploitation, stealth, or evasion.
Metadata
Release files for advanced-port-scanner 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| advanced_port_scanner-0.3.0.tar.gz | 37.9 kB | With provenance | Details for advanced_port_scanner-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| advanced_port_scanner-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for advanced_port_scanner-0.3.0-py3-none-any.whl |
Total release size: 74.5 kB
Release files / advanced_port_scanner-0.3.0.tar.gz
| Download URL | advanced_port_scanner-0.3.0.tar.gz |
|---|---|
| Size | 37.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b7008a475d8438f4de1472d497db36e5268ed6b45a96eef1f7b5c3d4db347363
|
|
BLAKE2b-256 checksum How to use checksums |
c7245e9295ca9d34967a980b212e44bdb6d4197ddb20abd6187f2a347b96e955
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / advanced_port_scanner-0.3.0-py3-none-any.whl
| Download URL | advanced_port_scanner-0.3.0-py3-none-any.whl |
|---|---|
| Size | 36.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
983bff0f939c2bee6d1a619e0b2dbea43d9fe20effa57093eb8c3dc75d50aff1
|
|
BLAKE2b-256 checksum How to use checksums |
4b139e95058acb3be834646aa0c638264e9d1edd39166097bce6278fef214614
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logSecurity for advanced-port-scanner 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for advanced_port_scanner-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.