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
• 🚫 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

⚙️ 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

4. 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:

root@kitploit:~

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

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

• GitHub: @sooryathejas

📄 License

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