Metadata-Version: 2.1
Name: portfinder
Version: 0.1.5
Summary: port scanner
Home-page: https://github.com/stanley0707/portfinder
License: MIT
Keywords: port,scanner,network,security
Author: Stanislav Shilov
Author-email: s.shilow@lynkey.io
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: aiohttp (>=3.12.14,<4.0.0)
Requires-Dist: ipaddress (>=1.0.23,<2.0.0)
Requires-Dist: rich (>=14.0.0,<15.0.0)
Requires-Dist: structlog (>=25.4.0,<26.0.0)
Requires-Dist: typer (>=0.16.0,<0.17.0)
Project-URL: Repository, https://github.com/stanley0707/portfinder
Description-Content-Type: text/markdown

# PORTFINDER

[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![PyPI Version](https://img.shields.io/pypi/v/portfinder)](https://pypi.org/project/portfinder/)

Portfinder is a powerful asynchronous port scanner for Python that allows you to quickly scan multiple targets with flexible configuration options.

## Navigation
- [Features](#features)
- [Installation](#installation-as-python-library)
- [Command Line Usage](#command-line-usage)
  - [Basic Scan](#run-basic-scan)
  - [Advanced Scan](#advanced-scan)
  - [Arguments](#arguments)
- [Python API](#basic-python-usage)
- [Output Formats](#output-files-format)
- [License](#license)

## Features
- Scan multiple IPs, CIDR ranges or domains
- Custom port ranges support (e.g., `1-1000,3389,8080`)
- Protocol-specific scanning (TCP, UDP, HTTP, HTTPS)
- High-performance async I/O implementation
- Multiple output formats (JSON, JSON Lines, plain text)
- Quiet mode for scripting

## Installation as Python Library [![PyPI](https://img.shields.io/pypi/v/portfinder)](https://pypi.org/project/portfinder/)
```commandline
pip install portfinder
```

### run basic scan
```commandline
portfinder -t example.com
```

### advanced scan
```commandline
portfinder -t 192.168.1.1,10.0.0.0/24,example.com -p 1-1024,3389,8080 -P http -T 1.5 -c 500 -tps 300 -o scan_results -j
```

| Argument                | Description                                             |
|-------------------------|---------------------------------------------------------|
| `-t`, `--target`        | Target IP/CIDR/domain (comma-separated) (required)      |
| `-p`, `--ports`         | Ports to scan (default: `80,443,53`)                    |
| `-P`, `--protocol`      | Protocol to check (tcp, udp, http, https)               |
| `-T`, `--timeout`       | Timeout in seconds (default: 2.0)                       |
| `-c`, `--concurrency`   | Maximum concurrent connections per host (default: 300) no more than ~500-1000 on CPU cores |
| `-o`, `--outfile`       | Output file path (without extension)                    |
| `-j`, `--js`            | Output in JSON format                                   |
| `-jl`, `--jsl`          | Output in JSON Lines format                             |
| `-q`, `--quiet`         | Disable all stdout output                               |


### usage with docker
```commandline
docker run --rm stanley0507/portfinder:latest -t 192.168.1.1 -p 1-1000
```

### basic python usage

```python
from portfinder.scanner import Scanner
from portfinder.dto import Protocol, Result

async def run_scan():
    ...
    scanner = Scanner(
        target="0.0.0.0",
        ports="80-23000",
        protocol=Protocol.HTTP,
        timeout=4.0,
        concurrency=400,
        ip_pool_size=200,
    )
    results: list[Result] = await scanner.run()
    ...
```
* `Result` is a active port item (dataclass) with attributes:
  * host: str
  * port: int
  * ip_version: IpVersion
  * protocols: list[Protocol]
* `Protocol` enum:
   * HTTP,
   * HTTPS,
   * TCP,
   * UDP

## output files format:
* txt file
```txt
0.0.0.0:21 [ipv4] (tcp)
```
* json file
```json
[
  {
    "host": "0.0.0.0",
    "port": 21,
    "ip_version": "ipv4",
    "protocols": [
      [
        "tcp"
      ]
    ]
  }
]
```
* jsonl file
```json lines
{"host": "0.0.0.0", "port": 53, "ip_version": "ipv4", "protocols": [["tcp"]]}
```
### powered by lynkey.io
License
MIT



