The Problem

METATRON functions as a capable local AI penetration-testing assistant, but its codebase carries measurable technical debt that increases risk for anyone relying on it for ongoing assessment work. High nesting in export.py, bare except clauses in llm.py, and duplicated 6-line logic blocks across db.py and export.py make control flow hard to follow and error-prone. Compounding this, there are no test files, no CI/CD gate, and no dependency lockfile, meaning any patch or upgrade risks breaking the recon-to-export pipeline without automated guardrails.

What This Does

METATRON is a CLI-driven tool that takes a target IP or domain, runs real network recon (nmap, whois, whatweb, curl, dig, nikto), feeds results to a locally running Ollama model (metatron-qwen), and saves findings to a MariaDB database. The repository lives in the root directory with 11 Python and Markdown files, plus a screenshots/ folder and requirements.txt. Six Python modules handle distinct roles: metatron.py orchestrates the CLI loop, llm.py handles model interaction and outbound calls, tools.py runs external commands, db.py manages persistence, export.py generates reports, and search.py performs web searches. Entry point execution flows through metatron.py into tools.py for command runs, then llm.py for model analysis, with db.py saving every step.

How It Is Wired

The internal call graph contains 123 resolved call edges between repository functions. get_connection is the most widely referenced function, called from 22 places—it defines database access used by db.py, export.py, and metatron.py. run_tool is called from 7 places and funnels into tools.py commands (run_nmap, run_whois, run_whatweb, run_curl_headers, run_default_recon). The module graph shows metatron as the central hub (Ca 0, Ce 4, instability 1), importing from llm (instability 0.67) and tools (instability 0). Functions that leave the process: 13 read/write database operations (in db.py, export.py), 3 read/write files (in export.py), 4 make outbound network calls (search.py DuckDuckGo/CVE lookups, llm.py Ollama calls), and 2 run external commands (tools.py). Changing get_connection or run_tool would ripple through the largest number of dependent paths, making them the highest-blast-radius touchpoints.

How To Use It

git clone https://github.com/moses-y/METATRON
cd METATRON
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
sudo apt install nmap whois whatweb curl dnsutils nikto

Configure Ollama and the model: curl -fsSL https://ollama.com/install.sh | sh then ollama pull huihui_ai/qwen3.5-abliterated:9b (or :4b for lower RAM). Edit Modelfile if customizing the prompt. No API keys or environment variables are required beyond Ollama’s local socket.

Real-World Use

An analyst provides a target domain; the CLI invokes new_scan, which calls divider and run_tool to execute nmap and whois. Results flow into llm.py's ask_ollama, which extracts tool calls and summarizes findings. save_vulnerability, save_exploit, and save_fix in db.py persist each finding. If the model requests more data, the loop re-runs web_search or additional run_tool commands before finalizing. The analyst can then select history entries and export via export_menu to PDF or HTML.

Code Health & Issues

  • MEDIUM - cognitive_load: export.py max indentation depth 8 - control flow is hard to follow. Flatten with early returns/guard clauses; extract inner blocks.
  • MEDIUM - resilience: llm.py bare or Exception-wide except swallows errors indiscriminately. Catch specific exceptions; re-raise or log the rest.
  • MEDIUM - clarity: 9 repeated 6-line blocks across db.py and export.py. Extract shared helpers; DRY the repeated logic.
  • MEDIUM - SDLC: No Dependabot or Renovate configured. Without a bot, published advisories sit unpatched; commit .github/dependabot.yml covering pip and github-actions ecosystems.
  • Low - reproducibility: Dependencies declared in requirements.txt without a lockfile; installs may vary across environments.

The Bottom Line

METATRON delivers a functional, offline AI pen-testing workflow with real tool integration and local database persistence, making it useful for isolated assessments on Parrot OS. However, the absence of tests, CI, and a lockfile, combined with deep nesting, broad exception handling, and duplicated logic, create maintainability and security risks for anyone modifying or extending the code. It’s suitable for researchers comfortable with local LLM setups who accept the current SDLC gaps, but not for teams requiring reproducible, auditable pipelines without manual gatekeeping.