Pyprobe

Pyprobe is a command-line tool and Python package for scanning TCP ports, identifying potentially running services, and exporting scan results to JSON. Built from scratch using Python's socket and concurrency capabilities, it aims to make network reconnaissance accessible through both a CLI and a reusable Python API.

Features

Installation

Install from PyPI

install it with:

pip install pyprobe-scan

Install from source

Clone the repository:

git clone https://github.com/fourtysevencode/pyprobe.git
cd pyprobe

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install the project in editable mode:

python -m pip install -e .

Project Structure

pyprobe
├── dist/
│   ├── pyprobe_scan-0.1.6-py3-none-any.whl
│   └── pyprobe_scan-0.1.6.tar.gz
├── docs/
│   ├── demo-screenshots/
│   │   └── dummy-help-scan.png
│   └── ESP_Demo/
│       └── pic.jpeg
├── src/
│   └── pyprobe/
│       ├── services/
│       │   ├── __init__.py
│       │   ├── common_service_signatures.py
│       │   ├── commonly_used_ports.py
│       │   ├── find_service.py
│       │   ├── scan_port.py
│       │   └── syn_scan.py
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli_args.py
│       ├── cli.py
│       ├── output.py
│       └── scanner.py
├── tests/
│   ├── Dummy_ESP32_Server/
│   │   └── Dummy_ESP32_Server.ino
│   └── package_tests/
│       └── test_scan.py
├── .gitignore
├── pyproject.toml
└── README.md

Usage

Display help

pyprobe-scan --help

Scan a target

pyprobe-scan 127.0.0.1

Replace 127.0.0.1 with the IP address of a host you own or have explicit permission to test.

Export results to JSON

pyprobe-scan 127.0.0.1 --json

The short form is also available (applicable to all commands use -h to view):

pyprobe-scan 127.0.0.1 -j

The scan results are saved to a timestamped JSON file in the current working directory.

Enable verbose logging:

pyprobe-scan 127.0.0.1 -v

Set a timeout on each TCP connection:

pyprobe-scan 127.0.0.1 -t 3 # Default is 3s

Scan specific ports on the server

pyprobe-scan 127.0.0.1 -p 80 443 # Scans port 80 and 443

Use SYN scanning

pyprobe-scan 127.0.0.1 -sS

Run directly from source

If you haven't installed the package yet, run it from the repository root:

PYTHONPATH=src python -m pyprobe 127.0.0.1

Using Pyprobe in Python

Pyprobe is also designed to be imported into your own Python projects.

import asyncio
from pyprobe.scanner import scan

async def main():
    results = await scan("127.0.0.1")
    print(results)

asyncio.run(main())

The scanner returns a pandas DataFrame containing discovered ports and their detected service information.

You can process the results using pandas:

results = asyncio.run(scan("127.0.0.1"))

print(results)
print(f"Open ports found: {len(results)}")

Testing

If you don't have a server to run test scans against, you may use the ESP32 sketch in `tests/Dummy_ESP32_Server' to host one on your ESP32.

Replace the hyphens with your WiFi network's SSID and password, and get it's local IP from your serial monitor.

const char* ssid = "-";
const char* password = "-";

You will get the following output:

the tiny hair is from my dog Maple, who is snuggled up beside me as I write this

Credits

Shipped to Hack Club Crescent 2026

made with 💗 from fourtysevencode