AutoPentest Lite

AI-powered pentesting assistant for non-experts. Run security scans safely, get plain-English summaries, and export reports — all from a browser UI.

---

Screenshots

See docs/screenshots/ for the full set. Run the app and follow docs/demo.md to capture your own.

---

What it does

AutoPentest Lite connects a React UI to a local Python backend. You paste a target, describe your goal in plain English, and the tool:

1. Validates the target is safe to scan
2. Uses a local LLM (Llama 3.1 via Ollama) to pick the right tool
3. Runs the tool and captures output
4. Generates a plain-English AI summary
5. Flags likely vulnerabilities with severity badges
6. Lets you export a Markdown report or save to scan history

No cloud. No API keys. Everything runs on your machine.

---

Stack

Layer	Tech
Frontend	React 18 + Vite + MUI
Backend	Python 3.12 + Flask
AI	Llama 3.1 via Ollama
Tools	nmap, gobuster, sqlmap, whatweb, dirb, nikto
Tests	pytest (backend) · Playwright (frontend)
CI	GitHub Actions
Container	Docker + docker-compose

---

Installation

Option 1 — Docker (recommended)

git clone https://github.com/Giathi-Daniel/AutoPentest-Lite.git
cd AutoPentest-Lite
cp .env.example .env
docker-compose up --build

Open http://localhost:5173.

Ollama must be running on your host machine. The backend connects to it at http://host.docker.internal:11434 by default.

Option 2 — Local (Python + Node.js)

Requirements: Python 3.12+, Node.js 18+, Ollama, and the security tools below.

# 1. Install security tools (Debian/Ubuntu)
sudo apt install nmap gobuster sqlmap whatweb dirb nikto

# 2. Start Ollama with Llama 3.1
ollama pull llama3.1
ollama serve

# 3. Start backend
cd backend
pip install -r requirements.txt
python main.py --serve

# 4. Start frontend (new terminal)
cd frontend
npm install
npm run dev

Open http://localhost:5173.

Option 3 — VS Code Extension

The vscode-extension/ folder contains a VS Code extension that runs scans directly from the editor.

cd vscode-extension
npm install
# Press F5 in VS Code to launch the extension host

---

Configuration

Copy .env.example to .env and adjust as needed:

LLM_MODEL=llama3.1
OLLAMA_URL=http://127.0.0.1:11434/api/generate

# IPs/CIDRs/hostnames always allowed (in addition to private ranges)
TARGET_WHITELIST=127.0.0.1,192.168.0.0/16

# Hard kill timeout per scan (seconds)
MAX_SCAN_DURATION=300

# Sliding-window rate limit per client IP
SCAN_RATE_LIMIT=3/hour

API_HOST=127.0.0.1
API_PORT=8000

---

Usage

Basic scan

1. Paste a target URL or IP (e.g. http://localhost:3000)
2. Pick a goal chip: Scan ports, Find subdomains, Check for SQLi, etc.
3. Check "I own this target" if the target is external
4. Click Start Scan

The UI shows a live progress indicator, then displays:

• AI summary
• Vulnerability findings with severity badges
• Raw tool output
• Export Report button (downloads .md)

CTF Mode

Switch to the CTF Mode tab and pick a chain:

Chain	Tools
Web Challenge	gobuster → whatweb → sqlmap
Network Challenge	nmap → dirb → nikto

The chain runs automatically. If any output contains flag{...}, CTF{...}, or HTB{...} it is highlighted.

Scan History

The History tab shows all past scans stored in localStorage. Each entry can be exported as a Markdown report or deleted.

---

API Reference

All endpoints accept and return JSON.

Method	Endpoint	Description
POST	/api/validate-target	Check if a target is allowed to scan
POST	/api/select-tool	LLM picks the best tool for a goal
POST	/api/run-tool	Execute a tool and return structured output
POST	/api/summarize	Generate a plain-English summary of output
POST	/api/analyze	Detect vulnerabilities in tool output
POST	/api/report	Generate a Markdown report
POST	/api/run-ctf	Run a CTF tool chain
GET	/api/logs	Tail the last N log entries

---

Running tests

# Backend unit tests
cd backend
pytest

# Frontend integration tests (Playwright)
cd frontend
npm run test:e2e

CI runs both automatically on every push and pull request.

---

Project structure

AutoPentest-Lite/
├── backend/
│   ├── tools/          # Tool wrappers (nmap.py, gobuster.py, …)
│   ├── tests/          # pytest test suite
│   ├── main.py         # Flask app + CLI entry point
│   ├── security.py     # Whitelist, rate limit, timeout guards
│   ├── logger.py       # Structured JSON logger
│   └── requirements.txt
├── frontend/
│   ├── src/            # React components
│   ├── tests/          # Playwright e2e tests
│   └── package.json
├── vscode-extension/   # VS Code extension
├── docs/               # FAQ, CONTRIBUTING, SECURITY
├── .github/workflows/  # CI pipeline
├── docker-compose.yml
└── .env.example

---

Security & ethics

• Authorized targets only. Public IPs are blocked unless you confirm ownership.
• Rate limited. Max 3 scans/hour per IP by default (configurable).
• Timeout enforced. Scans are killed after 5 minutes by default.
• All scans logged with IP and timestamp for audit.

See docs/SECURITY.md for the full policy and how to report vulnerabilities.

---

Contributing

See docs/CONTRIBUTING.md for setup instructions, code style, and how to add new tools.

---

License

MIT — see LICENSE.

Built by Giathi Daniel.