METATRON

Assistente di penetration testing basato su IA che utilizza LLM locale su Linux (Parrot OS)

🔱 METATRON

Assistente di penetration testing basato su IA

📌 Cos'è Metatron?

Metatron è un assistente di penetration testing basato su IA, eseguibile da CLI, che gira interamente sulla tua macchina locale — niente cloud, niente chiavi API, niente abbonamenti.

Gli fornisci un IP o un dominio target. Esegue strumenti di ricognizione reali (nmap, whois, whatweb, curl, dig, nikto), invia tutti i risultati a un modello IA in esecuzione locale, e l'IA analizza il target, identifica le vulnerabilità, suggerisce exploit e raccomanda le correzioni. Tutto viene salvato in un database MariaDB con la cronologia completa delle scansioni.

✨ Funzionalità

• 🤖 Analisi IA locale — basata su metatron-qwen tramite Ollama, funziona 100% offline
• 🔍 Ricognizione automatica — nmap, whois, whatweb, curl headers, dig DNS, nikto
• 🌐 Ricerca web — ricerca DuckDuckGo + lookup CVE (nessuna chiave API necessaria)
• 🗄️ Backend MariaDB — cronologia completa delle scansioni con 5 tabelle collegate
• ✏️ Modifica / Elimina — modifica qualsiasi risultato salvato direttamente dalla CLI
• 🔁 Ciclo agentico — l'IA può richiedere ulteriori esecuzioni degli strumenti durante l'analisi
• 🚫 Niente chiavi API — tutto è gratuito e locale -📤 Esportazione report

Metatron consente di esportare i risultati delle scansioni in formati di report puliti e condivisibili selezionando '2.view history'->seleziona slno ed esporta

📄 PDF — report professionali delle vulnerabilità 🌐 HTML — report visualizzabili nel browser

🖥️ Screenshot

Menu principale

Strumenti di ricognizione in esecuzione sul target

metatron-qwen analizza i risultati della scansione

Vulnerabilità salvate nel database

Esporta i risultati della scansione in PDF e/o HTML

🧱 Stack tecnologico

⚙️ Installazione

1. Clona il repository

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

2. Crea e attiva l'ambiente virtuale

python3 -m venv venv
source venv/bin/activate

3. Installa le dipendenze Python

pip install -r requirements.txt

4. Installa gli strumenti di sistema

sudo apt install nmap whois whatweb curl dnsutils nikto

🤖 Configurazione del modello IA

Passaggio 1 — Installa Ollama

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

Passaggio 2 — Scarica il modello base

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

⚠️ Questo modello richiede almeno 8,4 GB di RAM. Se il tuo sistema ne dispone di meno, usa la variante 4b:

root@kitploit:~

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

Quindi modifica Modelfile e cambia la riga FROM con il modello 4b.

Passaggio 3 — Crea il modello personalizzato metatron-qwen

Il repository include un Modelfile che esegue il fine-tuning del modello base con parametri specifici per il pentest:

ollama create metatron-qwen -f Modelfile

Questo crea il tuo modello locale metatron-qwen con:

• Finestra di contesto di 16.384 token
• Temperatura: 0.7
• Top-k: 10
• Top-p: 0.9

Passaggio 4 — Verifica che il modello esista

ollama list

Dovresti vedere metatron-qwen nell'elenco.

🗄️ Configurazione del database

Passaggio 1 — Assicurati che MariaDB sia in esecuzione

sudo systemctl start mariadb
sudo systemctl enable mariadb

Passaggio 2 — Crea il database e l'utente

mysql -u root

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

Passaggio 3 — Crea le tabelle

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

🚀 Utilizzo

Metatron richiede due schede del terminale per funzionare.

Terminale 1 — Carica il modello IA

ollama run metatron-qwen

Attendi di vedere il prompt >>>. Questo significa che il modello è caricato in memoria e pronto. Puoi lasciare questo terminale in esecuzione in background.

Terminale 2 — Avvia Metatron

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

Guida passo passo

1. Compare il menu principale:

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

2. Seleziona [1] New Scan → inserisci il tuo target:

[?] Enter target IP or domain: 192.168.1.1

oppure

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

3. Seleziona gli strumenti di ricognizione da eseguire:

  [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 esegue gli strumenti, invia i risultati all'IA e stampa l'analisi.

5. Tutto viene salvato automaticamente in MariaDB.

6. Dopo la scansione puoi modificare o eliminare qualsiasi risultato.

📁 Struttura del progetto

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

🗃️ Schema del database

Tutte e 5 le tabelle sono collegate tramite sl_no (numero di sessione) della tabella 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

⚠️ Disclaimer

Questo strumento è destinato esclusivamente a fini educativi e a penetration testing autorizzati.

• Utilizza Metatron solo su sistemi di tua proprietà o per i quali hai esplicita autorizzazione scritta a effettuare test.
• La scansione o lo sfruttamento non autorizzato di sistemi è illegale.
• L'autore non è responsabile di qualsiasi uso improprio di questo strumento.

👤 Autore

Soorya Thejas

• GitHub: @sooryathejas

📄 Licenza

Questo progetto è concesso in licenza secondo i termini della MIT License — consulta il file LICENSE per i dettagli.