METATRON

Asistente de pruebas de penetración impulsado por IA que usa un LLM local en Linux (Parrot OS)

🔱 METATRON

Asistente de Pruebas de Penetración Impulsado por IA

📌 ¿Qué es Metatron?

Metatron es un asistente de pruebas de penetración basado en CLI que se ejecuta completamente en tu máquina local: sin nube, sin claves de API, sin suscripciones.

Le das una IP o dominio objetivo. Ejecuta herramientas reales de reconocimiento (nmap, whois, whatweb, curl, dig, nikto), envía todos los resultados a un modelo de IA que se ejecuta localmente, y la IA analiza el objetivo, identifica vulnerabilidades, sugiere exploits y recomienda soluciones. Todo se guarda en una base de datos MariaDB con el historial completo de escaneos.

✨ Características

• 🤖 Análisis de IA local — impulsado por metatron-qwen mediante Ollama, funciona 100% sin conexión
• 🔍 Reconocimiento automatizado — nmap, whois, whatweb, curl headers, dig DNS, nikto
• 🌐 Búsqueda web — búsqueda en DuckDuckGo + consulta de CVE (sin necesidad de clave de API)
• 🗄️ Backend MariaDB — historial completo de escaneos con 5 tablas vinculadas
• ✏️ Editar / Eliminar — modifica cualquier resultado guardado directamente desde la CLI
• 🔁 Bucle agéntico — la IA puede solicitar más ejecuciones de herramientas durante el análisis
• 🚫 Sin claves de API — todo es gratuito y local -📤 Exportar informes

Metatron te permite exportar los resultados del escaneo a formatos de informe limpios y compartibles seleccionando '2.view history'->selecciona slno y exporta

📄 PDF — informes profesionales de vulnerabilidades 🌐 HTML — informes visualizables en el navegador

🖥️ Capturas de pantalla

Menú Principal

Herramientas de reconocimiento ejecutándose sobre el objetivo

metatron-qwen analizando los resultados del escaneo

Vulnerabilidades guardadas en la base de datos

Exportar resultados del escaneo como PDF y/o HTML

🧱 Stack Tecnológico

⚙️ Instalación

1. Clonar el repositorio

git clone https://github.com/sooryathejas/METATRON.git
cd METATRON

2. Crear y activar el entorno virtual

python3 -m venv venv
source venv/bin/activate

3. Instalar las dependencias de Python

pip install -r requirements.txt

4. Instalar las herramientas del sistema

sudo apt install nmap whois whatweb curl dnsutils nikto

🤖 Configuración del Modelo de IA

Paso 1 — Instalar Ollama

curl -fsSL https://ollama.com/install.sh | sh

Paso 2 — Descargar el modelo base

ollama pull huihui_ai/qwen3.5-abliterated:9b

⚠️ Este modelo requiere al menos 8.4 GB de RAM. Si tu sistema tiene menos, usa la variante 4b:

root@kitploit:~

ollama pull huihui_ai/qwen3.5-abliterated:4b

Luego edita Modelfile y cambia la línea FROM al modelo 4b.

Paso 3 — Crear el modelo personalizado metatron-qwen

El repositorio incluye un Modelfile que afina el modelo base con parámetros específicos de pentest:

ollama create metatron-qwen -f Modelfile

Esto crea tu modelo metatron-qwen local con:

• Ventana de contexto de 16,384 tokens
• Temperatura: 0.7
• Top-k: 10
• Top-p: 0.9

Paso 4 — Verificar que el modelo existe

ollama list

Deberías ver metatron-qwen en la lista.

🗄️ Configuración de la Base de Datos

Paso 1 — Asegúrate de que MariaDB esté en ejecución

sudo systemctl start mariadb
sudo systemctl enable mariadb

Paso 2 — Crear la base de datos y el usuario

mysql -u root

CREATE DATABASE metatron;
CREATE USER 'metatron'@'localhost' IDENTIFIED BY '123';
GRANT ALL PRIVILEGES ON metatron.* TO 'metatron'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Paso 3 — Crear las tablas

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)
);

🚀 Uso

Metatron necesita dos pestañas de terminal para ejecutarse.

Terminal 1 — Cargar el modelo de IA

ollama run metatron-qwen

Espera hasta que veas el indicador >>>. Esto significa que el modelo está cargado en memoria y listo. Puedes dejar esta terminal ejecutándose en segundo plano.

Terminal 2 — Iniciar Metatron

cd ~/METATRON
source venv/bin/activate
python metatron.py

Guía paso a paso

1. Aparece el menú principal:

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

2. Selecciona [1] New Scan → introduce tu objetivo:

[?] Enter target IP or domain: 192.168.1.1

o

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

3. Selecciona las herramientas de reconocimiento a ejecutar:

  [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 ejecuta las herramientas, envía los resultados a la IA e imprime el análisis.

5. Todo se guarda automáticamente en MariaDB.

6. Después del escaneo, puedes editar o eliminar cualquier resultado.

📁 Estructura del Proyecto

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

🗃️ Esquema de la Base de Datos

Las 5 tablas están vinculadas por sl_no (número de sesión) de la tabla history:

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

⚠️ Descargo de responsabilidad

Esta herramienta está destinada solo a fines educativos y pruebas de penetración autorizadas.

• Usa Metatron únicamente en sistemas que poseas o para los que tengas permiso explícito por escrito para realizar pruebas.
• El escaneo o la explotación no autorizada de sistemas es ilegal.
• El autor no es responsable del mal uso de esta herramienta.

👤 Autor

Soorya Thejas

• GitHub: @sooryathejas

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para obtener más detalles.