· p o r t i s ·

An adaptive TCP port scanner for high-latency and unstable networks.

Portis measures the network first, then automatically configures its scanning behavior.

Status: V0 early release and ongoing project. Portis is functional and has been tested against authorized lab targets. Short- and medium-range results are promising, while full-range accuracy remains experimental. Continued tuning and optimization are expected, and CLI behavior, calibration logic, performance characteristics, and output formats may change before V1.

Development Status

Portis V0 establishes the adaptive scanning architecture; it is not the final performance or accuracy target. Development will continue over time as more benchmark data and real-world feedback become available.

Why Portis

During penetration-testing practice, port enumeration repeatedly became a bottleneck over high-latency VPN connections.

nmap remains the standard tool for network discovery and enumeration, but full-range scans over unstable connections can take a long time. Adjusting timing and retry parameters can improve runtime, but finding suitable values for each target requires experimentation and can affect the resulting port set.

Portis explores a different approach: measure the network first, choose an initial scanning profile automatically, and recheck responses that remain uncertain.

• Calibrates before scanning — measures target responses and selects an initial timeout and worker count.
• Scans concurrently — chooses concurrency according to the requested port range and observed network behavior.
• Retries uncertain results — sends timed-out or unresolved ports through a separate retry path.
• Adjusts during the scan — increases its active timeout when slower responses are observed.
• Hands results to nmap — suggests a follow-up nmap command for service detection and deeper analysis.

Portis is not intended to replace nmap. The intended workflow is:

Portis: fast port discovery
        ↓
nmap: service detection, OS fingerprinting, scripts, and deeper analysis

Preliminary Results

Portis has been benchmarked against nmap and RustScan on authorized Hack The Box targets over high-latency VPN connections.

In the earlier controlled 20-run 0–1000 campaigns:

• Portis was 2.13–2.46× faster than nmap
• Portis returned the complete expected port set in 19/20 Windows runs
• Portis returned the complete expected port set in 20/20 Linux runs

In the latest 20-run Windows 0–1000 campaign:

• Portis completed 18/20 runs
• Portis achieved 98.6% per-port recall
• RustScan remained faster, with a median of 3.17 seconds compared with Portis at 11.68 seconds

Full-range performance remains experimental and varies significantly by target. Results should not be interpreted as universal performance guarantees.

See benchmarks.md for the methodology, network conditions, complete-run definitions, limitations, and detailed results.

Installation

Build from source

Requirements:

• Go 1.22.2 or later
• Portis currently performs TCP connect scans and does not require raw-socket or root privileges.

git clone https://github.com/Ch4os1/Portis.git
cd Portis
go build -o portis ./cmd/portis

Download a release

Prebuilt binaries and checksums are available from GitHub Releases.

Quick Start

Scan ports 1-1000:

./portis -ip 10.0.0.5 -port 1-1000

Write the full result to JSON:

./portis -ip 10.0.0.5 -port 1-1000 -o results.json

Every scan ends with a suggested nmap handoff command:

nmap -sV -p 22,80,443 10.0.0.5

How It Works

1. Portis probes the target and measures response timing.
2. It selects an initial timeout and divides workers between primary scanning and retries.
3. Primary workers scan the requested ports concurrently.
4. Uncertain responses are sent through the retry path with a more generous timeout.
5. If slower responses appear during the scan, the timeout ratchet increases the active timeout up to its configured ceiling.
6. Portis classifies the results and generates a follow-up nmap command.

Usage

portis -ip <target> [-port <spec> | -top-ports <n> | -all] [-v | -vv | -vvv] [-o <file>]

Target

Flag	Description
-ip string	IP address to scan

Port selection — pick exactly one

Flag	Description
-port string	Single port, range, or comma-separated list, such as 80, 1-1000, or 80,443,8080
-p string	Shorthand for -port
-top-ports int	Scan the N most common ports, up to 8,386
-all / -a	Scan ports 0-65535

Verbosity — pick at most one

The default verbosity level is -v.

Flag	Description
-v	Display the open, closed, and filtered summary
-vv	Also list closed and filtered ports individually
-vvv	Display internal events for debugging

Output

Flag	Description
-o string	Write the full result to a JSON file

Examples

./portis -ip 10.0.0.5 -port 80
./portis -ip 10.0.0.5 -port 80,81,82
./portis -ip 10.0.0.5 -port 1-1000 -vv
./portis -ip 10.0.0.5 -top-ports 1000 -o results.json
./portis -ip 10.0.0.5 -all -vvv

Current Scope

Portis V0 currently provides:

• TCP connect scanning
• Single-port, range, list, common-port, and full-range selection
• Automatic timeout and worker calibration
• Open, closed, and filtered classifications
• Retry handling for uncertain responses
• JSON output
• Suggested nmap handoff commands

Known Limitations

• Full-range accuracy varies significantly by target and is not yet reliable enough to claim parity with nmap.
• Short scans provide a more modest speed advantage than medium-range scans.
• Calibration and classification have been tested against a limited number of authorized lab targets and network conditions.
• Portis V0 has not yet received broad platform or real-world environment testing.
• Only IPv4 targets are supported for V0
• Currently runs on Linux systems

Testing and Feedback

Portis is an early release, and results from different authorized network conditions are valuable.

When opening a test report or bug, please include:

• Client operating system
• Authorized lab or testing environment
• Port range and exact command
• Approximate RTT, jitter, and packet loss
• Known open ports
• Ports Portis missed or misclassified
• Comparison tool, command, and result

Please submit reproducible findings through GitHub Issues.

Responsible Use

Portis is intended for authorized security testing and research. Only scan systems you own or have explicit permission to assess. You are responsible for complying with applicable laws, contracts, and acceptable-use policies.

Roadmap

Potential future work includes:

• Further calibration and retry tuning
• Worker scheduling and runtime optimization
• Improving full-range consistency
• Expanding benchmark coverage
• SYN scanning
• UDP scanning

The roadmap is directional rather than a commitment to specific release dates.

Contributing

Bug reports, documentation improvements, reproducible benchmark results, and code contributions are welcome.

See CONTRIBUTING.md for development setup, testing requirements, benchmark guidance, and pull-request expectations.

License

Portis is licensed under the GNU General Public License v3.0 only, identified by the SPDX expression GPL-3.0-only.