METATRON README

The project's README from github.com/sooryathejas/METATRON. As one markdown file: README.md.

METATRON

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

🔱 METATRON

AI-Powered Penetration Testing Assistant

Metatron Banner

📌 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

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
Main Menu

Scan Running
Recon tools running on target

AI Analysis
metatron-qwen analyzing scan results

Results
Vulnerabilities saved to database

Export Menu
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

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:

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:

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.

👤 Author

Soorya Thejas

📄 License

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

METATRON (sooryathejas/METATRON)

Searching Database…

4.2K ·GitHub
METATRON
What is this?Metatron is a CLI-based AI penetration testing assistant that runs real recon tools against a target and lets a locally-hosted LLM analyze the results, suggest exploits, and recommend fixes, with no cloud or API keys involved.
Is this a CLI tool or does it have a GUI?It's a terminal-based CLI app driven by a menu, run across two terminal tabs; output includes generated PDF/HTML reports rather than any graphical interface.
How do I get it running?Clone the repo, create a Python virtual environment and install the Python and system tool dependencies, then set up Ollama and MariaDB before launching it — one terminal loads the AI model and keeps it running, a second terminal launches Metatron itself.
What do I need installed before I can scan anything?You need Ollama to serve the local metatron-qwen model, a running MariaDB server for scan history, and the recon tools nmap, whois, whatweb, curl, dig and nikto on your Parrot OS/Debian-based system.
Do I need a powerful machine to run the AI model?Yes — the default metatron-qwen base model needs at least 8.4 GB of RAM; if your machine has less, you have to switch the Modelfile to the smaller 4b variant.
Does it only work on Parrot OS, or any Linux?It's built around Parrot OS, a Debian-based distro; the README doesn't confirm support on other Linux distributions, so a Debian/Parrot-style setup is the safest bet.
Does any of my scan data leave my machine?No — analysis runs on a local Ollama model and everything is stored in your own MariaDB database; the only outbound traffic is DuckDuckGo search and CVE lookups, which require no API key.
What does the AI actually do with the recon output?It analyzes the combined nmap, whois, whatweb, nikto and dig results, identifies vulnerabilities, suggests possible exploits, and recommends fixes — and can request additional tool runs mid-analysis through its agentic loop.
Can I export my scan results?Yes, from the 'view history' menu you can export any saved scan as a professional PDF report or a browser-viewable HTML report.
Is it legal to scan any target with this?No — the README states it's for educational purposes and authorized testing only; scanning systems you don't own or lack written permission for is illegal.
What AI model powers the analysis?A custom fine-tuned model called metatron-qwen, built from the huihuiai/qwen3.5-abliterated:9b base model through Ollama, using a 16,384-token context window.
What are similar projects?CVE-2026-62911, Claude-Red, Sn1per, Decepticon, evilginx2, bbot, EvilFontTool, masscan
Which topics is it in?mariadb, reconnaissance, vulnerability, local-ai, network-security, python3, red-team, pentesting, penetration-testing, hacking, qwen, local-llm
Creator
sooryathejas
Size
2.1 MB
Stars
4.2K
Updated
CommitApr 11
Age
6mo
Commits · 90 Days