AI-powered penetration testing assistant using local LLM on linux (Parrot OS)
AI-Powered Penetration Testing Assistant
Metatron is a CLI-based AI penetration testing assistant that runs entirely on your local machine — no cloud, no API keys, no subscriptions.
You give it a target IP or domain. It runs real recon tools (nmap, whois, whatweb, curl, dig, nikto), feeds all results to a locally running AI model, and the AI analyzes the target, identifies vulnerabilities, suggests exploits, and recommends fixes. Everything gets saved to a MariaDB database with full scan history.
✨ Features
- 🤖 Local AI Analysis — powered by
metatron-qwen via Ollama, runs 100% offline
- 🔍 Automated Recon — nmap, whois, whatweb, curl headers, dig DNS, nikto
- 🌐 Web Search — DuckDuckGo search + CVE lookup (no API key needed)
- 🗄️ MariaDB Backend — full scan history with 5 linked tables
- ✏️ Edit / Delete — modify any saved result directly from the CLI
- 🔁 Agentic Loop — AI can request more tool runs mid-analysis
- 🚫 No API Keys — everything is free and local
-📤 Export Reports
Metatron allows you to export scan results into clean, shareable report formats by selecting '2.view history'->select slno and export
📄 PDF — professional vulnerability reports
🌐 HTML — browser-viewable reports
🖥️ Screenshots
Main Menu
Recon tools running on target
metatron-qwen analyzing scan results
Vulnerabilities saved to database
Export scan results as PDF and or HTML
---
🧱 Tech Stack
| Component |
Technology |
| Language |
Python 3 |
| AI Model |
metatron-qwen (fine-tuned Qwen 3.5) |
| Base Model |
huihui_ai/qwen3.5-abliterated:9b |
| LLM Runner |
Ollama |
| Database |
MariaDB |
| OS |
Parrot OS (Debian-based) |
| Search |
DuckDuckGo (free, no key) |
⚙️ Installation
1. Clone the repository
git clone https://github.com/sooryathejas/METATRON.git
cd METATRON
2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
3. Install Python dependencies
pip install -r requirements.txt
sudo apt install nmap whois whatweb curl dnsutils nikto
🤖 AI Model Setup
Step 1 — Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
Step 2 — Download the base model
ollama pull huihui_ai/qwen3.5-abliterated:9b
⚠️ This model requires at least 8.4 GB of RAM. If your system has less, use the 4b variant:
ollama pull huihui_ai/qwen3.5-abliterated:4b
Then edit Modelfile and change the FROM line to the 4b model.
The repo includes a Modelfile that fine-tunes the base model with pentest-specific parameters:
ollama create metatron-qwen -f Modelfile
This creates your local metatron-qwen model with:
- 16,384 token context window
- Temperature: 0.7
- Top-k: 10
- Top-p: 0.9
Step 4 — Verify the model exists
ollama list
You should see metatron-qwen in the list.
🗄️ Database Setup
Step 1 — Make sure MariaDB is running
sudo systemctl start mariadb
sudo systemctl enable mariadb
Step 2 — Create the database and user
mysql -u root
CREATE DATABASE metatron;
CREATE USER 'metatron'@'localhost' IDENTIFIED BY '123';
GRANT ALL PRIVILEGES ON metatron.* TO 'metatron'@'localhost';
FLUSH PRIVILEGES;
EXIT;
Step 3 — Create the tables
mysql -u metatron -p123 metatron
CREATE TABLE history (
sl_no INT AUTO_INCREMENT PRIMARY KEY,
target VARCHAR(255) NOT NULL,
scan_date DATETIME NOT NULL,
status VARCHAR(50) DEFAULT 'active'
);
CREATE TABLE vulnerabilities (
id INT AUTO_INCREMENT PRIMARY KEY,
sl_no INT,
vuln_name TEXT,
severity VARCHAR(50),
port VARCHAR(20),
service VARCHAR(100),
description TEXT,
FOREIGN KEY (sl_no) REFERENCES history(sl_no)
);
CREATE TABLE fixes (
id INT AUTO_INCREMENT PRIMARY KEY,
sl_no INT,
vuln_id INT,
fix_text TEXT,
source VARCHAR(50),
FOREIGN KEY (sl_no) REFERENCES history(sl_no),
FOREIGN KEY (vuln_id) REFERENCES vulnerabilities(id)
);
CREATE TABLE exploits_attempted (
id INT AUTO_INCREMENT PRIMARY KEY,
sl_no INT,
exploit_name TEXT,
tool_used TEXT,
payload LONGTEXT,
result TEXT,
notes TEXT,
FOREIGN KEY (sl_no) REFERENCES history(sl_no)
);
CREATE TABLE summary (
id INT AUTO_INCREMENT PRIMARY KEY,
sl_no INT,
raw_scan LONGTEXT,
ai_analysis LONGTEXT,
risk_level VARCHAR(50),
generated_at DATETIME,
FOREIGN KEY (sl_no) REFERENCES history(sl_no)
);
🚀 Usage
Metatron needs two terminal tabs to run.
Terminal 1 — Load the AI model
ollama run metatron-qwen
Wait until you see the >>> prompt. This means the model is loaded into memory and ready. You can leave this terminal running in the background.
cd ~/METATRON
source venv/bin/activate
python metatron.py
Walkthrough
1. Main menu appears:
[1] New Scan
[2] View History
[3] Exit
2. Select [1] New Scan → enter your target:
[?] Enter target IP or domain: 192.168.1.1
or
[?] Enter target IP or domain: example.com
3. Select recon tools to run:
[1] nmap
[2] whois
[3] whatweb
[4] curl headers
[5] dig DNS
[6] nikto
[a] Run all (except nikto)
[n] Run all + nikto (slow)
4. Metatron runs the tools, feeds results to the AI, and prints the analysis.
5. Everything is saved to MariaDB automatically.
6. After the scan you can edit or delete any result.
📁 Project Structure
METATRON/
├── metatron.py ← main CLI entry point
├── db.py ← MariaDB connection and all CRUD operations
├── tools.py ← recon tool runners (nmap, whois, etc.)
├── llm.py ← Ollama interface and AI tool dispatch loop
├── search.py ← DuckDuckGo web search and CVE lookup
├── Modelfile ← custom model config for metatron-qwen
├── requirements.txt ← Python dependencies
├── .gitignore ← excludes venv, pycache, db files
├── LICENSE ← MIT License
├── README.md ← this file
└── screenshots/ ← terminal screenshots for documentation
🗃️ Database Schema
All 5 tables are linked by sl_no (session number) from the history table:
history ← one row per scan session (sl_no is the spine)
│
├── vulnerabilities ← vulns found, linked by sl_no
│ │
│ └── fixes ← fixes per vuln, linked by vuln_id + sl_no
│
├── exploits_attempted ← exploits tried, linked by sl_no
│
└── summary ← full AI analysis dump, linked by sl_no
⚠️ Disclaimer
This tool is intended for educational purposes and authorized penetration testing only.
- Only use Metatron on systems you own or have explicit written permission to test.
- Unauthorized scanning or exploitation of systems is illegal.
- The author is not responsible for any misuse of this tool.
👤 Author
Soorya Thejas
📄 License
This project is licensed under the MIT License — see the LICENSE file for details.
Metatron 是一个基于 CLI 的 AI 渗透测试助手，它对目标运行真实的侦察工具，并让本地部署的 LLM 分析结果、提出可能的漏洞利用建议并推荐修复方案，全程不涉及云端或 API 密钥。