Skip to main content

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

CI MIT License Python 3.11+ v0.3.0

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, and online
  • 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/v1 endpoints
  • Request IDs for API responses
  • Session authentication with viewer, operator, and admin roles
  • 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 aps console command
  • Gunicorn-compatible web deployment
  • Non-root Docker execution
  • no-new-privileges and 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)

Source distribution for advanced-port-scanner 0.3.0
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)

Table of built distributions (wheels) for advanced-port-scanner 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page