pentest-assists-ai

KO | EN

gitlite — search

#ai #typescript #llm #golang #rust #deep-learning #macos #java #awesome #vue #pytorch #security #openai #open-source

pentest-assists-ai

(★ 15)

Demo tools for webinar merdekasiber.com

pentest-assists-ai 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# assists — AI Pentest Assistant

`assists` is a Python CLI that runs a **ReAct-style LangChain agent** (OpenAI) to help with **authorized** penetration testing workflows. It wraps common security tools (nmap, nikto, nuclei, ffuf) with guardrails: **scope enforcement**, **dry-run mode**, **session logging**, and optional **Docker-based execution**.

> **Legal notice:** Only use this software against systems you are explicitly permitted to test. Unauthorized scanning or exploitation may violate laws (e.g. Indonesia’s UU ITE and equivalents elsewhere).

---

## Features

- **Agent core:** `ChatOpenAI` + `langchain_classic` ReAct agent + `AgentExecutor` (configurable `max_iterations`, parsing error handling).
- **Tools (English names exposed to the model):**
  - `run_nmap` — port/service scan (recon).
  - `run_nikto` — web server scan.
  - `run_nuclei` — template-based vulnerability scan (`template_tags`, default `cves`).
  - `run_ffuf` — web fuzzing (wordlist path, `FFUF_WORDLIST`, or default file under a local [SecLists](https://github.com/danielmiessler/SecLists) clone).
  - `sync_wordlists` — `git clone` / `git pull` the SecLists repo into `SECLISTS_DIR` (requires **Git** and network).
  - `generate_report` — Markdown draft report.
- **Execution modes:**
  - **Host:** run binaries from your `PATH` (install nmap, nikto, nuclei, ffuf locally).
  - **Docker:** run each tool inside a container image you configure (`DOCKER_IMAGE_*`).
- **Docker image automation:** before `docker run`, the runner can **`docker image inspect`** and, if the image is missing, **`docker pull`** (see `DOCKER_AUTO_PULL`).
- **Output limits:** long tool output is truncated for the LLM (`MAX_TOOL_OUTPUT_CHARS`).

---

## Requirements

- Python **3.11+**
- **OpenAI API key** (or compatible endpoint if you adapt the code)
- Optional: **Docker** CLI if `TOOL_EXEC_MODE=docker`
- Optional: **Git** CLI for SecLists download/sync (see below)
- Optional: security tools on host **or** per-tool Docker images

### SecLists wordlists

This project can use **[SecLists](https://github.com/danielmiessler/SecLists)** (MIT) as a local wordlist source: the [`wordlist_manager`](src/assists/wordlist_manager.py) module clones or pulls the repository into `SECLISTS_DIR` (default `data/seclists`, ignored by git). The default file for `run_ffuf` when no path is set is `SECLISTS_DEFAULT_WORDLIST_REL` (default `Discovery/Web-Content/common.txt`).

- Set `FFUF_ENSURE_SECLISTS=true` (default) to auto-clone/pull when the wordlist file is missing (not during `DRY_RUN`).
- `SECLISTS_AUTO_SYNC` + `SECLISTS_SYNC_INTERVAL_HOURS` throttle automatic `git pull` before ffuf.
- Call the **`sync_wordlists`** tool (or run clone/pull yourself) to refresh lists on demand.
- Upstream notes: the repository is large; antivirus tools may flag paths—see [SecLists README](https://github.com/danielmiessler/SecLists/blob/master/README.md).

---

## Installation

```bash
cd assists
python -m venv .venv
# Windows: .\.venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"
```

Copy [`.env.example`](.env.example) to `.env` and set at least `OPENAI_API_KEY`.

---

## Configuration (environment variables)

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | API key for OpenAI. |
| `OPENAI_MODEL` | Model name (default `gpt-4o`). |
| `DRY_RUN` | `true` (default): no real tool execution; shows the command that would run. |
| `ALLOWED_SCOPES` | Comma-separated **IPs, CIDRs, or hostnames** allowed as targets. |
| `TOOL_EXEC_MODE` | `host` or `docker`. |
| `DOCKER_NETWORK_MODE` | `bridge` or `host` (Docker `docker run --network`). |
| `DOCKER_IMAGE_NMAP`, `DOCKER_IMAGE_NIKTO`, `DOCKER_IMAGE_NUCLEI`, `DOCKER_IMAGE_FFUF` | Image references when using Docker mode. |
| `DOCKER_AUTO_PULL` | If `true` (default), pull the image when it is not present locally. |
| `DOCKER_PULL_TIMEOUT_SEC` | Timeout for `docker pull` (default `600`). |
| `FFUF_WORDLIST` | Host path to a wordlist file for `run_ffuf` when not passed as an argument. |
| `SECLISTS_DIR` | Local directory for the SecLists git clone (default `data/seclists`). |
| `SECLISTS_REPO_URL` | Git URL (default official SecLists). |
| `SECLISTS_DEFAULT_WORDLIST_REL` | Path inside the clone to the default wordlist file. |
| `SECLISTS_AUTO_SYNC` | If `true`, run `git pull` when the sync interval has passed before ffuf (when ensure runs). |
| `SECLISTS_SYNC_INTERVAL_HOURS` | Minimum hours between automatic pulls. |
| `SECLISTS_GIT_TIMEOUT_SEC` | Timeout for `git clone` / `git pull`. |
| `FFUF_ENSURE_SECLISTS` | If `true`, clone/pull SecLists when the chosen wordlist file is missing. |
| `DOCKER_FFUF_WORDLIST_CONTAINER_PATH` | Path inside the ffuf container where the host wordlist is mounted read-only. |
| `SUBPROCESS_TIMEOUT_SEC` | Timeout for tool runs. |
| `MAX_TOOL_OUTPUT_CHARS` | Truncation limit for tool stdout/stderr sent to the LLM. |
| `SESSION_LOG_PATH` | Log file for tool invocations. |
| `AGENT_VERBOSE` | Verbose agent chain logging. |
| `AGENT_MAX_ITERATIONS` | Max ReAct iterations. |

See [`.env.example`](.env.example) for a template.

---

## Usage

```bash
# Dry-run (safe): agent plans but tools do not execute
assists "Recon scanme.nmap.org then summarize"

# Verbose agent steps
assists -v "List open steps for https://scanme.nmap.org/"

# Force Docker execution mode for this run (must set images in .env)
assists --exec-mode docker "Run nmap on scanme.nmap.org"

# From file
assists -f instructions.txt
```

Equivalent:

```bash
python -m assists "Your prompt here"
```

---

## Docker workflow

1. Set `TOOL_EXEC_MODE=docker` (or pass `--exec-mode docker`).
2. Set each `DOCKER_IMAGE_*` to an image that contains the corresponding binary on `PATH` inside the container.
3. With `DOCKER_AUTO_PULL=true`, missing images trigger `docker pull` before `docker run`.
4. For **ffuf**, the host wordlist file is mounted read-only; ensure `FFUF_WORDLIST` or `wordlist_path` points to a real file.

Programmatic helpers (see [`src/assists/tool_runner.py`](src/assists/tool_runner.py)):

- `ensure_docker_image_ready(image: str) -> str | None` — inspect, then optional pull; returns an error string or `None`.
- `prepare_tool_docker_image(tool_label)` — same for the image configured for `nmap` | `nikto` | `nuclei` | `ffuf`.
- `get_docker_image_name_for_tool(tool_label)` — returns the configured image name.

---

## Project layout

```
assists/
  src/assists/
    agent_factory.py   # LLM + ReAct agent + executor
    cli.py             # Entry point
    config.py          # Pydantic settings
    guardrails.py      # Scope validation, logging
    prompts.py         # ReAct prompt template
    tool_runner.py     # Host/Docker execution + image prep
    tools/             # LangChain @tool wrappers
  tests/
  KNOWLADGE.md         # Reference material (seminar notes; Indonesian examples may use older names)
```

---

## Development

```bash
pytest
```

---

## Ethics

- Define **narrow** `ALLOWED_SCOPES` for each engagement.
- Keep **`DRY_RUN=true`** until you are in a controlled, authorized session.
- Review all agent output; the LLM can misread or overstate tool results.

---

## License

Use and modify according to your organization’s policies; no warranty is implied.

pentest-assists-ai

pentest-assists-ai 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

pentest-assists-ai

pentest-assists-ai 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README