advanced-port-scanner 0.3.0__tar.gz

advanced_port_scanner-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hack2ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

advanced_port_scanner-0.3.0/PKG-INFO

@@ -0,0 +1,503 @@
+Metadata-Version: 2.4
+Name: advanced-port-scanner
+Version: 0.3.0
+Summary: Professional defensive network discovery scanner
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask<4,>=3.0
+Requires-Dist: gunicorn<24,>=22
+Requires-Dist: rich<15,>=13.7
+Requires-Dist: tqdm<5,>=4.66
+Provides-Extra: syn
+Requires-Dist: scapy<3,>=2.5; extra == "syn"
+Dynamic: license-file
+
+# Advanced Port Scanner
+
+<p align="center">
+  <strong>Professional defensive network discovery for authorized security testing.</strong><br>
+  Fast local CLI • Flask dashboard • Versioned API • Persistent history • Reports • Analytics • Operational metrics • Controlled CVE enrichment
+</p>
+
+<p align="center">
+  <a href="https://github.com/hack2ai/advanced-port-scanner/actions/workflows/ci.yml"><img src="https://github.com/hack2ai/advanced-port-scanner/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/hack2ai/advanced-port-scanner/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/release-0.3.0-informational.svg" alt="v0.3.0">
+</p>
+
+> **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
+
+```text
+                    ┌─────────────────────┐
+                    │     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
+
+```text
+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
+
+```bash
+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:
+
+```bash
+python -m pip install -e .
+```
+
+Optional SYN support:
+
+```bash
+python -m pip install -e '.[syn]'
+```
+
+Verify the installation:
+
+```bash
+aps --version
+aps --help
+```
+
+## CLI usage
+
+List available profiles:
+
+```bash
+aps profiles
+```
+
+Run a small authorized local/lab scan:
+
+```bash
+aps scan 127.0.0.1 --profile quick
+```
+
+Use the standard profile:
+
+```bash
+aps scan 127.0.0.1 --profile standard
+```
+
+Specify an explicit range:
+
+```bash
+aps scan 127.0.0.1 --ports 1-1024
+```
+
+Disable banner collection:
+
+```bash
+aps scan 127.0.0.1 --profile standard --no-banner
+```
+
+Save reports:
+
+```bash
+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:
+
+```bash
+python web/app.py
+```
+
+Open:
+
+```text
+http://127.0.0.1:5000
+```
+
+For a production-style process, use Gunicorn as described in [`docs/installation.md`](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:
+
+```json
+{
+  "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:
+
+```text
+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:
+
+```json
+{
+  "data": {},
+  "request_id": "..."
+}
+```
+
+Errors use a structured form:
+
+```json
+{
+  "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`](docs/configuration.md) for authentication, password hashing, rate limits, CVE enrichment, and deployment guidance.
+
+## Docker
+
+Build and start the stack:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+python -m pytest -q
+```
+
+The repository CI validates the project across Python 3.11, 3.12, and 3.13.
+
+Recommended development loop:
+
+```bash
+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`](CHANGELOG.md) and [`docs/v0.3-release.md`](docs/v0.3-release.md) for release details.
+
+## License
+
+This project is licensed under the MIT License. See [`LICENSE`](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.