GitHub - sooryathejas/METATRON: AI-powered penetration testing assistant using local LLM on linux (Parrot OS)

METATRON

AI-powered penetration testing assistant using local LLM on linux (Parrot OS)

🔱 METATRON

AI-Powered Penetration Testing Assistant

📌 What is Metatron?

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

-📤 Export Reports

• 🚫 No API Keys — everything is free and local

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

1. Create and activate virtual environment

python3 -m venv venv

source venv/bin/activate

1. Install Python dependencies

pip install -r requirements.txt

1. Install system tools

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.

Step 3 — Build the custom metatron-qwen 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.

Terminal 2 — Launch Metatron

cd ~ /METATRON

source venv/bin/activate

python metatron.py

Walkthrough

1. Main menu appears:

[1] New Scan [2] View History [3] Exit

1. Select [1] New Scan → enter your target:

[?] Enter target IP or domain: 192.168.1.1

or

[?] Enter target IP or domain: example.com

1. 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)

1. Metatron runs the tools, feeds results to the AI, and prints the analysis.

1. Everything is saved to MariaDB automatically.

1. 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

• GitHub: @sooryathejas

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。