Skip to content

Rewrite README #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Psychevus merged 1 commit into from
Jul 26, 2025
Merged

Rewrite README #24

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 66 additions & 164 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,212 +1,114 @@
<!--
_ _ _ _ _ _ _ _ _
| | | | | | | | | | | | | | (_)
| |__| | __ _ ___| | _____ ___| |_ ___ _ __ | |__| | | _| |_ _ __
| __ |/ _` |/ __| |/ / __|/ _ \ __/ _ \| '_ \| __ | |/ / | | '_ \
| | | | (_| | (__| <\__ \ __/ || (_) | |_) | | | | <| | | | | |
|_| |_|\__,_|\___|_|\_\___/\___|\__\___/| .__/|_| |_|_|\_\_|_|_| |_|
| |
|_|
-->

<h1 align="center">🛡️ Pentest-Toolkit</h1>
<p align="center">
<em>Lightning‑fast reconnaissance with subdomain discovery, HTTP probing,
port sweeps and TLS audits&mdash;all in one modern CLI.</em>
</p>

<p align="center">
<img src="https://img.shields.io/badge/licence-MIT-blue" alt="MIT licence">
<img src="https://img.shields.io/badge/python-3.11%20|%203.12-blue" alt="Python 3.11 | 3.12">
</p>

---

## 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 <role-arn>
```
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 <name>` where `<name>` 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 <http://localhost:3000> 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.