From b5db4d36980107bb07c962d4af72e09581facc01 Mon Sep 17 00:00:00 2001 From: Psychevus Date: Sat, 26 Jul 2025 19:25:31 +0330 Subject: [PATCH] docs: rewrite README --- README.md | 230 ++++++++++++++++-------------------------------------- 1 file changed, 66 insertions(+), 164 deletions(-) diff --git a/README.md b/README.md index fbf0481..ba2931e 100644 --- a/README.md +++ b/README.md @@ -1,212 +1,114 @@ - - -

🛡️ Pentest-Toolkit

-

- Lightning‑fast reconnaissance with subdomain discovery, HTTP probing, - port sweeps and TLS audits—all in one modern CLI. -

- -

- MIT licence - Python 3.11 | 3.12 -

- ---- - -## Table of Contents - -1. [Features](#features) -2. [Quick Start](#quick-start) -3. [Architecture](#architecture) -4. [Output Example](#output-example) -5. [Plugins](#plugins) -6. [Contributing](#contributing) -7. [Licence](#licence) -8. [Maintainer](#maintainer) - -## Features - -* Wraps `subfinder`, `httpx`, `nuclei`, `nmap`, `testssl.sh`, optional modules like `dnsrecon`, `ffuf`, `screenshot`, `katana` behind one interface -* Structured JSON output with optional HTML, Markdown or PDF reports -* Docker container and AWS Lambda compatible -* Extensible plugin system for custom modules -* Opt-in pipeline mode to feed Subfinder → Httpx → Nuclei → Nmap → TestSSL -* `--parallel` flag to run independent modules concurrently for speed -* Autonomous `--agent` mode with `--watch` and `--diff-only` for stateful - differential scanning -* Distributed mode via `--distributed` to fan out scans across remote runners - ---- - -## Quick start +# 🚀 Pentest Toolkit + +[![CI](https://github.com/psychevus/pentest-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/psychevus/pentest-toolkit/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-blue)](https://pypi.org/project/pentest-toolkit/) +[![Docker](https://img.shields.io/badge/docker-image-blue)](https://hub.docker.com/r/psychevus/pentest-toolkit) +[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) + +## One-line Description + +Pentest Toolkit orchestrates leading open-source scanning utilities to automate reconnaissance and vulnerability discovery. + +## Key Features + +- ✔️ Unified CLI for Subfinder, Httpx, Nuclei, Nmap, TestSSL and more +- ✔️ JSON, HTML and PDF reporting +- ✔️ Extensible plugin system for custom tools and notifiers +- ✔️ Slack, Teams and Discord alerts +- ✔️ Docker container and AWS Lambda compatible +- ✔️ Distributed mode for horizontal scaling + +## Screenshots + +![Terminal screenshot](docs/screenshot.png) + +## Installation ### PyPI -Install the latest release from PyPI: ```bash pip install pentest-toolkit -pentest-toolkit example.com --pipeline --report markdown ``` -Run `pip install pentest-toolkit[full]` or `./install.sh` for automatic install of -Go-based tools. -### Local install +### Manual ```bash git clone https://github.com/psychevus/pentest-toolkit.git cd pentest-toolkit -python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt -r requirements-dev.txt -python main.py example.com --pipeline --report markdown ``` ### Docker ```bash -docker pull ghcr.io/psychevus/pentest-toolkit:latest -docker run --rm ghcr.io/psychevus/pentest-toolkit:latest example.com +docker run --rm psychevus/pentest-toolkit --help ``` ### AWS Lambda -```bash -zip -r function.zip . -x '*.git*' -aws lambda create-function \ - --function-name pt-toolkit \ - --runtime python3.12 \ - --handler lambda_function.lambda_handler \ - --zip-file fileb://function.zip \ - --role -``` +Deploy `lambda_function.py` with the `PentestToolkitLambda` IAM role and at least 2 minute timeout. -Make sure `subfinder`, `httpx`, `nmap`, `testssl.sh` and `nuclei` are available in your -`PATH`. Add `--auto-install` to let the toolkit attempt installation via your system -package manager. Alternatively run `./install.sh` to fetch the required Go binaries. +## Quick Start -> **Use responsibly. Run against systems you own or have explicit permission -> to test.** - ---- - -## Architecture - -```mermaid -flowchart LR - A[subfinder] --> B[httpx] - B --> C[nuclei] - C --> D[nmap] - D --> E[testssl.sh] - E --> F[[JSON artefacts]] +```bash +python main.py --target example.com --tools subfinder,httpx ``` +Generated reports appear under `output/` in JSON and optional HTML/PDF formats. -Every module subclasses a shared `Module` base class so adding new tools is -trivial. - ---- +## CLI Usage -## Distributed scanning +| Flag | Description | +| ---- | ----------- | +| `--target` | Target domain or IP | +| `--tools` | Comma separated list of modules | +| `--report` | `html`, `pdf`, `markdown` or `summary` | +| `--auto-install` | Attempt to install missing tools | +| `--notify` | Send findings via Slack, Teams or Discord | +| `--pipeline` | Feed one tool's output into the next | +| `--distributed` | Offload work to remote runners | +| `--ws-port` | WebSocket port for live results | -Launch `pentest-runner` on remote nodes (or containers) then run the main CLI -with `--distributed`: +## Architecture Overview -```bash -pentest-runner --port 9000 & -pentest-toolkit targets.txt --distributed --runners http://localhost:9000 ``` +subfinder --> httpx --> nuclei --> nmap --> testssl.sh +``` +The toolkit loads each module dynamically and passes results through the pipeline above. -Targets are automatically chunked across runners with health-checks and local -fallback if a node goes offline. +## Plugins ---- +Place Python modules inside `plugins/` or set `PENTEST_TOOLKIT_PLUGIN_DIR` to load external plugins. Each plugin subclasses `Module` or `Notifier` to register automatically. -## Output example +## Output Formats ```json [ - { "type": "subdomain", "host": "api.example.co.uk", "ip": "93.184.216.34" }, - { "type": "httpx", "url": "https://api.example.co.uk", "status": 200, "tls": true }, - { "nmap_xml": "output/nmap_api.example.co.uk_20250519-1131.xml" }, - { "testssl_json": "output/testssl_api.example.co.uk_20250519-1131.json" } + {"type": "subdomain", "host": "api.example.com", "ip": "1.2.3.4"}, + {"type": "httpx", "url": "https://api.example.com", "status": 200} ] ``` +HTML and PDF reports contain the same data in a user friendly format. See the `output/` directory for examples. -Results are stored in `output/` with timestamps. Notifications can be sent via -`--notify ` where `` is one of `slack`, `teams`, `discord`, -`telegram`, `elasticsearch` or `splunk`. - ---- - -## Real-time dashboard - -Start the CLI with a WebSocket port to stream live results: - -```bash -python main.py example.com --pipeline --ws-port 8765 -``` - -Then install and launch the React interface: +## Webhooks & Notifications -```bash -cd ui && npm install -npm start -``` +Use `--notify slack` or `--notify teams` to push findings. Payloads contain the JSON above and links to reports. -Open to view the dashboard with a live terminal feed -and 3D recon graph. +## Docker Usage ---- - -## Plugins - -Drop Python files into a `plugins/` directory or set the -`PENTEST_TOOLKIT_PLUGIN_DIR` environment variable. Each plugin defines a -`Module` or `Notifier` subclass that automatically registers when imported. -See [PLUGINS.md](PLUGINS.md) for more examples. - -```python -# plugins/dirbuster.py -from modules.base import Module, Finding - -class DirBuster(Module): - name = "dirbuster" - - def run(self, target: str): - return [Finding(tool=self.name, data={"target": target})] -``` - -Run with: ```bash -python main.py example.com --tools dirbuster -python main.py example.com --parallel +docker run --rm -e PENTEST_TOOLKIT_PLUGIN_DIR=/plugins psychevus/pentest-toolkit target.com ``` ---- +## AWS Lambda Support +Upload the repo with `lambda_function.py` as the entrypoint. Grant the function network permissions and set the timeout high enough for scanning. ## Contributing -1. Fork and create a feature branch -2. Install dependencies with `pip install -r requirements.txt -r requirements-dev.txt` -3. Run `ruff check .` and tests via `pytest -q` -4. Submit a PR describing your changes - ---- - -## Licence - -MIT © [Psychevus](https://github.com/psychevus). See [`LICENSE`](LICENSE) for -full terms. +1. Install deps with `pip install -r requirements.txt -r requirements-dev.txt` +2. Run `ruff check .` and `pytest -q` +3. Open a pull request explaining your changes ---- +## License -## Maintainer +This project is licensed under the [MIT](LICENSE) license. -**Psychevus** – Security-minded Software Developer -12+ years experience in backend, automation and security (UTC +3:30) -📧 [psychevus@gmail.com](mailto:psychevus@gmail.com) | [linkedin.com/in/mzaferanloo](https://linkedin.com/in/mzaferanloo) +## Credits / Maintainers +Maintained by [psychevus](https://github.com/psychevus). Consider sponsoring development if you find it useful.