Elengenix is a true autonomous AI agent for security research. It doesn't follow checklists or script chains — it reasons about targets, chooses its own tools, pivots when stuck, and writes new tools when existing ones aren't enough.
User: "Find vulnerabilities in example.com"
│
▼
┌──────────────────────────────────────────────────────────────┐
│ VulnAgent — True AI Agent (free will, 25 tools) │
│ ├── Reasons about target and builds strategy │
│ ├── Selects tools from AVAILABLE_TOOLS (freedom to skip) │
│ ├── Creates new tools on the fly (edit_own_tool) │
│ ├── Learns from cross-session memory (ChromaDB + Skills) │
│ └── Pivots freely — no locked phases or forced ordering │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Governance Layer │
│ ├── SAFE → Execute immediately │
│ ├── PRIVILEGED → Ask user approval │
│ └── DESTRUCTIVE → Block with popup │
└──────────────────────────────────────────────────────────────┘
│
▼
Reports: findings, CVSS scores, AI analysis
Unlike "script chaining with an AI on top", Elengenix gives the AI genuine autonomy — it decides what to do, in what order, and how to adapt when a path fails.
Quick Start
Prerequisites
Python 3.10 or newer (python3 --version to check) and pip
An AI provider key — at least one of: OPENAI_API_KEY, ANTHROPIC_API_KEY,
GEMINI_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY… or a local
Ollama install (no key needed)
Optional:Node.js ≥ 18 if you want the default
npm-based MCP servers (Elengenix works fine without them)
Install
pip install elengenix # from PyPI
# or, from a source checkout:
pip install .
That's it. The install takes a few minutes (ChromaDB + sentence-transformers
are the heavy parts). User config, memory, and reports all live under
~/.elengenix/.
Scan a target in 3 lines
elengenix configure # one-line setup: pick a provider, paste your key
elengenix doctor # sanity-check the installation
elengenix scan example.com # autonomous AI vulnerability hunt
Skip the wizard entirely by exporting a key instead:
Only scan targets you own or have written permission to test.
Every potentially intrusive action is gated by the Governance layer and
asks for your approval first (--mode strict blocks it outright).
(Illustrative session; your output depends on the target.)
Try it without a real target
A deliberately vulnerable test app ships with the repo. Point Elengenix at
localhost, or run the offline benchmark (real precision/recall/F1 numbers
against 10 planted vulnerabilities — no external target needed):
python3 benchmark/run_benchmark.py --json # single benchmark run
python3 benchmark/run_benchmark.py --history # past results
Features
True AI Agent Architecture
Elengenix uses VulnAgent — a genuine autonomous AI agent with free will over tool selection and execution flow:
The old script-driven pipeline (pipeline/phase_registry, pipeline/unified, core/brain.py) has been fully removed. Elengenix now runs on a pure AI agent architecture.
Auto-copied from mcp.json.example on first run. User config overrides project config.
AI Providers
Supported: OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Ollama (local), and more.
elengenix configure # Interactive setup wizard
Or set the key directly and skip the wizard: export OPENAI_API_KEY=sk-...
(any of ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY,
DEEPSEEK_API_KEY works too). Put keys in ~/.elengenix/.env for
persistence — never commit them.
Common Issues
No AI provider configured / scan exits immediately.
Run elengenix configure or export a key (export OPENAI_API_KEY=...).
No key at all? Use local models: install Ollama,
ollama pull qwen2.5-coder, then select Ollama in the wizard.
429 / provider rate-limit errors.
The provider is throttling you. Lower the request rate
(elengenix scan example.com --rate-limit 2), wait for the quota window to
reset, or switch providers with elengenix configure.
Target not reachable / every probe times out.
Check the hostname resolves (ping -c1 example.com), try the full URL
(elengenix scan https://example.com), and confirm you're not behind a
proxy/VPN blocking outbound traffic. Host-only scopes mean the target must
pass elengenix doctor's network check.
MCP servers fail to start (npx: command not found).
Optional. Install Node.js ≥ 18, or edit ~/.elengenix/mcp.json and remove
the npm-based entries — Elengenix runs fine with MCP disabled.
First run hangs on a welcome wizard / download.
The wizard only runs once; answer it or press Ctrl-C and run
elengenix configure manually. Model downloads (sentence-transformers,
~100 MB) happen once and are cached.
pip install elengenix fails to build a dependency.
Use Python 3.10–3.13 and a venv:
python3 -m venv .venv && . .venv/bin/activate && pip install elengenix.
Very new interpreters (3.14+) work but some wheels build from source —
install your distro's python3-dev / build tools if so.
Reports or memory missing.
Everything lives under ~/.elengenix/ (reports/, data/memory.json,
data/skills.json) — check there, not the source checkout.
Testing
# Full test suite (3,150+ tests, ~5 min)
python3 -m pytest tests/ -v
# Brutal integration/security/stress suite
python3 -m pytest tests/brutal/ -v
# Skip network-dependent integration tests
python3 -m pytest tests/ -m "not integration" -v
3,150+ tests covering: governance, shell execution, target validation, MCP protocol, VulnAgent tools, agent memory, agent skills, report generation (Markdown/HTML/PDF with CVSS v3.1 scoring), and the brutal integration/security/stress suite.
