pyprobe-scan 0.1.0__py3-none-any.whl

pyprobe/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyprobe/cli.py

@@ -0,0 +1,31 @@
+import asyncio
+import time
+
+from rich import print as rich_print
+
+from .scanner import scan
+from .cli_args import get_args
+from .output import print_results, save_json
+
+
+def main():
+    start_time = time.perf_counter()
+
+    target, json_export, timeout, verbose_status = get_args()
+
+    df = asyncio.run(scan(target,timeout,verbose_status))
+
+    if type(df) == str:
+        rich_print(f"[red]{df}[/red]")
+    else:
+        print_results(df)
+
+    elapsed_time = time.perf_counter() - start_time
+    rich_print(f"Completed in {elapsed_time:.3f}s\n")
+
+    if json_export:
+        save_json(df)
+
+
+if __name__ == "__main__":
+    main()

pyprobe/cli_args.py

@@ -0,0 +1,20 @@
+import argparse
+
+def get_args():
+
+    parser = argparse.ArgumentParser(
+        prog = "pyprobe",
+        description="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.",
+        epilog="Placeholder"
+    )
+
+    parser.add_argument("target")
+
+    parser.add_argument("-j", "--json", action="store_true",help="Export discovered ports to a JSON file in the same directory")
+
+    parser.add_argument("-t", "--timeout", type=int, help="Set time duration before connection timeouts, default is 3s.")
+
+    parser.add_argument("-v", "--verbose", action="store_true", help='Enable verbose logging.')
+    args = parser.parse_args()
+
+    return args.target, args.json, args.timeout, args.verbose

pyprobe/output.py

@@ -0,0 +1,24 @@
+
+import json
+from pathlib import Path
+from datetime import datetime
+
+from rich import print as rich_print
+from rich_tools import df_to_table
+
+
+def print_results(df):
+    """Display scan results in a formatted table."""
+    rich_print(df_to_table(df))
+    rich_print(f"\nNumber of ports open: {df.shape[0]}")
+
+
+def save_json(df):
+    """Export scan results to a JSON file."""
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    file_name = f"PYPROBE-{timestamp}.json"
+
+    df.to_json(file_name, orient="records", indent=4)
+
+    rich_print(f"Saved to [green]{file_name}[/green]")
+    return Path(file_name)

pyprobe/scanner.py

@@ -0,0 +1,41 @@
+import pandas as pd
+from rich import print as rich_print
+from datetime import datetime
+import asyncio
+from .services.find_service import find_service_from_port
+from .services.scan_port import scan_port
+from .services.commonly_used_ports import ports
+
+ascii_art = r"""
+ ________  ___    ___ ________  ________  ________  ________  _______      
+|\   __  \|\  \  /  /|\   __  \|\   __  \|\   __  \|\   __  \|\  ___ \     
+\ \  \|\  \ \  \/  / | \  \|\  \ \  \|\  \ \  \|\  \ \  \|\ /\ \   __/|    
+ \ \   ____\ \    / / \ \   ____\ \   _  _\ \  \\\  \ \   __  \ \  \_|/__  
+  \ \  \___|\/   / /   \ \  \___|\ \  \\  \\ \  \\\  \ \  \|\  \ \  \_|\ \ 
+   \ \__\ __/   / /     \ \__\    \ \__\\ _\\ \_______\ \_______\ \_______\
+    \|__||\____/ /       \|__|     \|__|\|__|\|_______|\|_______|\|_______|
+         \|____|/                                                                                                              
+"""
+
+async def scan(IP,timeout,verbose_status):
+    rich_print(ascii_art)
+    current_clock_time = datetime.now().strftime("%H:%M:%S")
+
+    if verbose_status:
+        rich_print(f"Starting async port scan against [yellow]{IP}[/yellow] at {current_clock_time} with verbose logging. \n")
+    else:
+        rich_print(f"Starting async port scan against [yellow]{IP}[/yellow] at {current_clock_time}\n")
+
+    tasks = [asyncio.to_thread(scan_port,IP,port,timeout,verbose_status) for port in ports] # list of tasks to be run asynchronously
+
+    try:
+        result = await asyncio.gather(*tasks) # fire all tasks
+    except Exception as e:
+        return "An error occured. Provide a valid IPv4 target address."
+
+    open_ports = [port for port in result if port is not None]
+
+    service_tasks = [asyncio.to_thread(find_service_from_port, IP, port) for port in open_ports]
+    services = await asyncio.gather(*service_tasks)
+    
+    return pd.DataFrame({"Port":open_ports, "Service":services})

pyprobe/services/common_service_signatures.py

@@ -0,0 +1,7 @@
+service_signatures = {
+b'\x01\x01\x00\x18': "Nping Echo Protocol",
+b'E\x00\x00\x00': "PostgreSQL Database Server",
+b'-ERR': "Redis In-Memory Database",
+b'\x03\x00\x00': "Remote Desktop Protocol (RDP)",
+b'\x16\x03\x01': "TLS/SSL Handshake"
+}

pyprobe/services/commonly_used_ports.py

@@ -0,0 +1,26 @@
+ports = [1,3,4,6,7,9,13,17,19,20,21,22,23,24,25,26,30,32,33,37,42,43,49,50,53,70,79,80,81,82,83,84,85,88,89,90,99,100,106,109,110,111,113,119,125,135,139,143,144,146,161,163,179,199,211,212,222,254,255,256,259,264,280,301,306,311,340,366,389,406,407,416,417,425,427,443,444,445,458,464,465,481,497,500,512,513,514,515,524,541,543,544,545,548,554,555,563,587,593,616,617,625,631,636,646,648,666,667,668,683,687,691,700,705,711,714,720,722,726,749,765,777,783,787,800,801,808,843,873,880,888,898,900,901,902,903,911,912,981,987,990,992,993,995,999,1000,1001,1002,1007,1009,1010,1011,1021,1022,1023,1024,1025,1026,1027,1028,1029,1030,1031,1032,1033,1034,1035,1036,1037,1038,1039,1040,1041,1042,1043,1044,1045,1046,1047,1048,1049,1050,1051,1052,1053,1054,1055,1056,1057,1058,1059,1060,1061,1062,1063,1064,1065,1066,1067,1068,1069,1070,1071,1072,1073,1074,1075,1076,1077,1078,1079,1080,1081,1082,1083,1084,1085,1086,1087,1088,1089,1090,1091,1092,1093,1094,1095,1096,1097,1098,1099,1100,1102,1104,1105,1106,1107,1108,1110,1111,1112,1113,1114,1117,1119,1121,1122,1123,1124,1126,1130,1131,1132,1137,1138,1141,1145,1147,1148,1149,1151,1152,1154,1163,1164,1165,1166,1169,1174,1175,1183,1185,1186,1187,1192,1198,1199,1201,1213,1216,1217,1218,1233,1234,1236,1244,1247,1248,1259,1271,1272,1277,1287,1296,1300,1301,1309,1310,1311,1322,1328,1334,1352,1417,1433,1434,1443,1455,1461,1494,1500,1501,1503,1521,1524,1533,1556,1580,1583,1594,1600,1641,1658,1666,1687,1688,1700,1717,1718,1719,1720,1721,1723,1755,1761,1782,1783,1801,1805,1812,1839,1840,1862,1863,1864,1875,1900,1914,1935,1947,1971,1972,1974,1984,1998,1999,2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2013,2020,2021,2022,2030,2033,2034,2035,2038,2040,2041,2042,2043,2045,2046,2047,2048,2049,2065,2068,2099,2100,2103,2105,2106,2107,2111,2119,2121,2126,2135,2144,2160,2161,2170,2179,2190,2191,2196,2200,2222,2251,2260,2288,2301,2323,2366,2381,2382,2383,2393,2394,2399,2401,2492,2500,2522,2525,2557,2601,2602,2604,2605,2607,2608,2638,2701,2702,2710,2717,2718,2725,2800,2809,2811,2869,2875,2909,2910,2920,2967,2968,2998,3000,3001,3003,3005,3006,3007,3011,3013,3017,3030,3031,3052,3071,3077,3128,3168,3211,3221,3260,3261,3268,3269,3283,3300,3301,3306,3322,3323,3324,3325,3333,3351,3367,3369,3370,3371,3372,3389,3390,3404,3476,3493,3517,3527,3546,3551,3580,3659,3689,3690,3703,3737,3766,3784,3800,3801,3809,3814,3826,3827,3828,3851,3869,3871,3878,3880,3889,3905,3914,3918,3920,3945,3971,3986,3995,3998,4000,4001,4002,4003,4004,4005,4006,4045,4111,4125,4126,4129,4224,4242,4279,4321,4343,4443,4444,4445,4446,4449,4550,4567,4662,4848,4899,4900,4998,5000,5001,5002,5003,5004,5009,5030,5033,5050,5051,5054,5060,5061,5080,5087,5100,5101,5102,5120,5190,5200,5214,5221,5222,5225,5226,5269,5280,5298,5357,5405,5414,5431,5432,5440,5500,5510,5544,5550,5555,5560,5566,5631,5633,5666,5678,5679,5718,5730,5800,5801,5802,5810,5811,5815,5822,5825,5850,5859,5862,5877,5900,5901,5902,5903,5904,5906,5907,5910,5911,5915,5922,5925,5950,5952,5959,5960,5961,5962,5963,5987,5988,5989,5998,5999,6000,6001,6002,6003,6004,6005,6006,6007,6009,6025,6059,6100,6101,6106,6112,6123,6129,6156,6346,6389,6502,6510,6543,6547,6565,6566,6567,6580,6646,6666,6667,6668,6669,6689,6692,6699,6779,6788,6789,6792,6839,6881,6901,6969,7000,7001,7002,7004,7007,7019,7025,7070,7100,7103,7106,7200,7201,7402,7435,7443,7496,7512,7625,7627,7676,7741,7777,7778,7800,7911,7920,7921,7937,7938,7999,8000,8001,8002,8007,8008,8009,8010,8011,8021,8022,8031,8042,8045,8080,8081,8082,8083,8084,8085,8086,8087,8088,8089,8090,8093,8099,8100,8180,8181,8192,8193,8194,8200,8222,8254,8290,8291,8292,8300,8333,8383,8400,8402,8443,8500,8600,8649,8651,8652,8654,8701,8800,8873,8888,8899,8994,9000,9001,9002,9003,9009,9010,9011,9040,9050,9071,9080,9081,9090,9091,9099,9100,9101,9102,9103,9110,9111,9200,9207,9220,9290,9415,9418,9485,9500,9502,9503,9535,9575,9593,9594,9595,9618,9666,9876,9877,9878,9898,9900,9917,9929,9943,9944,9968,9998,9999,10000,10001,10002,10003,10004,10009,10010,10012,10024,10025,10082,10180,10215,10243,10566,10616,10617,10621,10626,10628,10629,10778,11110,11111,11967,12000,12174,12265,12345,13456,13722,13782,13783,14000,14238,14441,14442,15000,15002,15003,15004,15660,15742,16000,16001,16012,16016,16018,16080,16113,16992,16993,17877,17988,18040,18101,18988,19101,19283,19315,19350,19780,19801,19842,20000,20005,20031,20221,20222,20828,21571,22939,23502,24444,24800,25734,25735,26214,27000,27352,27353,27355,27356,27715,28201,30000,30718,30951,31038,31337,32768,32769,32770,32771,32772,32773,32774,32775,32776,32777,32778,32779,32780,32781,32782,32783,32784,32785,33354,33899,34571,34572,34573,35500,38292,40193,40911,41511,42510,44176,44442,44443,44501,45100,48080,49152,49153,49154,49155,49156,49157,49158,49159,49160,49161,49163,49165,49167,49175,49176,49400,49999,50000,50001,50002,50003,50006,50300,50389,50500,50636,50800,51103,51493,52673,52822,52848,52869,54045,54328,55055,55056,55555,55600,56737,56738,57294,57797,58080,60020,60443,61532,61900,62078,63331,64623,64680,65000,65129,65389]
+popular_http_ports = [
+    80,      # Default HTTP (unencrypted web traffic)
+    443,     # Default HTTPS (encrypted web traffic over SSL/TLS)
+    3000,    # Common dev servers (Node.js, Express, React, Next.js)
+    5000,    # Default Flask & ASP.NET Core port
+    8000,    # Default Python http.server, Django runserver, FastAPI/Uvicorn
+    8080,    # Alternative HTTP / Tomcat / Jenkins / Proxies
+    8443,    # HTTPS alternative / Java admin consoles
+    8888,    # Jupyter Notebook default
+]
+# Common Port to Service Mapping
+popular_services_on_port = {
+    21: "FTP (File Transfer Protocol)",
+    22: "SSH (Secure Shell)",
+    23: "Telnet",
+    25: "SMTP (Simple Mail Transfer Protocol)",
+    53: "DNS (Domain Name System)",
+    80: "HTTP (Hypertext Transfer Protocol)",
+    443: "HTTPS (HTTP Secure / TLS)",
+    6379: "Redis In-Memory Database",
+    3389: "Remote Desktop Protocol (RDP)",
+    5432: "PostgreSQL Database Server",
+    9929: "Nping Echo Protocol",
+    8021: "FTP Proxy on MacOS"
+}

pyprobe/services/find_service.py

@@ -0,0 +1,64 @@
+import requests
+import socket
+
+from .commonly_used_ports import (popular_http_ports,popular_services_on_port)
+from .common_service_signatures import service_signatures
+
+
+def find_service_from_port(IP, PORT):
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.settimeout(3)
+
+            result = sock.connect_ex((IP, PORT))
+
+            if result != 0:
+                return "Port closed or connection failed"
+
+            # Try to read a banner first
+            try:
+                banner = sock.recv(1024)
+            except socket.timeout:
+                banner = b""
+
+        if banner.startswith(b"220") and b"FTP" in banner.upper():
+            return "Likely FTP"
+        
+        if banner:
+            for signature, service in service_signatures.items():
+                if signature in banner:
+                    return service
+
+            return banner.decode("utf-8", errors="ignore").strip()
+
+        # Probe HTTP ports if no banner was received
+        try:
+            response = requests.get(f"http://{IP}:{PORT}/",timeout=3,)
+
+            server = response.headers.get("Server", "Unknown HTTP server")
+            content_type = response.headers.get(
+                "Content-Type", ""
+            ).split(";")[0]
+
+            return f"HTTP | {server}" # | Content-Type: {content_type}
+
+        except requests.RequestException:
+            pass
+
+        # Use the port number as a weak clue
+        if PORT in popular_services_on_port:
+            return f"Likely: {popular_services_on_port[PORT]}"
+
+        return "Open port, but no banner received"
+
+    except OSError as e:
+        return f"Socket error: {e}"
+
+
+def main():
+    result = find_service_from_port("127.0.0.1", 50)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

pyprobe/services/scan_port.py

@@ -0,0 +1,27 @@
+import socket
+from .commonly_used_ports import ports
+
+target = "127.0.0.1" # ESP32 with a webpage hosted on port 80
+
+def scan_port(target, port,timeout=3,verbose_status=False):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(timeout)
+        result = sock.connect_ex((target, port))
+    
+    if result == 0:
+        if verbose_status:
+            print(f"{port}: Open")
+        return port
+
+    return None
+
+if __name__ == "__main__":  
+    open_ports = []
+
+    for port in ports:
+        result = scan_port(target, port)
+
+        if result is not None:
+            open_ports.append(result)
+
+    print("Open ports:", open_ports)

pyprobe_scan-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: pyprobe-scan
+Version: 0.1.0
+Summary: A Python network probing and asynchronous port scanning tool
+Author: Ronak Pal
+License-Expression: MIT
+Keywords: networking,port-scanner,network-probing,service-detection,cybersecurity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: rich
+Requires-Dist: rich-tools
+
+# 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.
+
+<img src="docs/demo-screenshots/dummy-help-scan.png" style="max-width: 80%; height: auto;"></img>
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Asynchronous Scanning** | Uses `asyncio` and `asyncio.to_thread()` to scan multiple ports concurrently. |
+| **TCP Port Scanning** | Identifies accessible TCP ports on a target host. |
+| **Service Detection** | Attempts to identify services using port mappings and service signatures. |
+| **Terminal Output** | Displays scan results in a formatted table using Rich. Use `-v` for verbose logging. |
+| **JSON Export** | Saves discovered ports and service information to a JSON file. |
+| **Custom Timeouts** | Set a custom timeout for each TCP connection |
+| **CLI and Python API** | Designed for terminal use and integration into Python programs. |
+
+## Installation
+
+Install from PyPI
+
+install it with:
+
+```bash
+python -m pip install pyprobe-scan
+```
+
+Install from source
+
+Clone the repository:
+
+```bash 
+git clone https://github.com/fourtysevencode/pyprobe.git
+cd pyprobe
+```
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the project in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+## Project Structure
+```
+pyprobe
+├── docs
+│   └── demo-screenshots
+│       └── dummy-help-scan.png
+├── src
+│   └── pyprobe
+│       ├── services
+│       │   ├── __init__.py
+│       │   ├── common_service_signatures.py
+│       │   ├── commonly_used_ports.py
+│       │   ├── find_service.py
+│       │   └── scan_port.py
+│       ├── __init.py
+│       ├── __main__.py
+│       ├── cli_args.py
+│       ├── cli.py
+│       ├── output.py
+│       └── scanner.py
+├── .gitignore
+├── pyproject.toml
+└── README.md
+```
+
+## Usage
+
+Display help
+
+```bash
+pyprobe-scan --help
+```
+
+Scan a target
+
+```bash
+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
+
+```bash
+pyprobe-scan 127.0.0.1 --json
+```
+
+The short form is also available (applicable to all commands use -h to view):
+
+```bash
+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:
+
+```bash
+pyprobe-scan 127.0.0.1 -v
+```
+
+Set a timeout on each TCP connection:
+
+```bash
+pyprobe-scan 127.0.0.1 -t 3 # Default is 3s
+```
+
+### Run directly from source
+
+If you haven't installed the package yet, run it from the repository root:
+
+```bash
+PYTHONPATH=src python -m pyprobe 127.0.0.1
+```
+
+Using Pyprobe e in Python
+
+Pyprobe is also designed to be imported into your own Python projects.
+
+```python
+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:
+
+```python
+results = asyncio.run(scan("127.0.0.1"))
+
+print(results)
+print(f"Open ports found: {len(results)}")
+```
+
+## Credits
+Shipped to [Hack Club Crescent](https://crescent.hackclub.com) 2026
+
+<img src='https://hackatime.hackclub.com/api/v1/badge/U0BJ7PF47LJ/fourtysevencode/pyprobe'></img>
+
+_made with 💗 from fourtysevencode_

pyprobe_scan-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyprobe/__init.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyprobe/__main__.py,sha256=dlUlpbDREBvZ3EZbGtRNlpLJryM0RTGD3zUPraT5m3M,78
+pyprobe/cli.py,sha256=ugTByIzS7gVf36IAEI36eSL4Z5xCd0BnnTN4an7mto0,631
+pyprobe/cli_args.py,sha256=QDnMnAq-ED-g6x5uBFZlnWBJPlpD5j6aCnkzeU6uoUA,953
+pyprobe/output.py,sha256=TwMyX2tINdaP92UOGvhY2O1Jjqj8MDoLwehCDqMPy_M,618
+pyprobe/scanner.py,sha256=C-stbAlO8PLUTuTCUP67ncmNyAIVDkXeTANHBsZbRzA,1917
+pyprobe/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyprobe/services/common_service_signatures.py,sha256=VLJx7Wsft1Zn5cmf1sIb0wTUrT9UbTv1daC6YF0j6cg,240
+pyprobe/services/commonly_used_ports.py,sha256=vPBQK4tBF93jQMsc-DXaKah_IQmOJGVQvUuqYZ8JM7c,6008
+pyprobe/services/find_service.py,sha256=GmngD20sapB6K0XhV-bYyqyx1OEToRzxDEcMu1J_OEw,1808
+pyprobe/services/scan_port.py,sha256=jVJdtfSB7kHbvE2KYL5u14YySeWChiEqo7zImE4xaMY,673
+pyprobe_scan-0.1.0.dist-info/METADATA,sha256=GAygAC0AQ1ofPKCql11BfK69f9jr9INnRJxvlxFXDzs,4565
+pyprobe_scan-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyprobe_scan-0.1.0.dist-info/entry_points.txt,sha256=B5QBDTtNQTjIMzCpLpr9MCGJ3c0Ey3_l4F-GQCwC3aE,50
+pyprobe_scan-0.1.0.dist-info/top_level.txt,sha256=M_5K7kLSWGQUXKUFLZaXbRelUowqPnKhIPfTWkRbU40,8
+pyprobe_scan-0.1.0.dist-info/RECORD,,

pyprobe_scan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyprobe_scan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyprobe-scan = pyprobe.cli:main

pyprobe_scan-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyprobe