ashveil1/elengenix

1. Repository shape

Elengenix is a Python-first autonomous security research framework with a large “core app + tools” architecture. The top level contains the user-facing entrypoints, the AI/orchestration layer, a broad tools/ library for recon and analysis, and a smaller redteam_agent/ subpackage that looks like a self-contained experimental or legacy execution path.

2. Primary entrypoints

The main runtime can be entered through main.py, run.py, cli.py, cli_textual.py, bot.py, and elengenix_launcher.py. These are different front doors into the same backend capabilities: terminal UI, command-line scanning, autonomous mode, and bot/launcher integration. setup.sh and termux_setup.sh support local and mobile deployment.

3. User interaction layer

The human-facing UI is split between a standard CLI and a Textual-based terminal UI. cli_textual.py, ui_components.py, live_display.py, and tools_menu.py suggest the app is designed for interactive operation as well as unattended runs. The README’s “CHILL” and “HUNT” modes map to a safety-vs-autonomy boundary in the interface layer.

4. Core reasoning and orchestration

agent_brain.py, orchestrator.py, and agent.py are the central control plane. They appear to turn user intent into an execution plan, coordinate tool calls, and manage state transitions across scan phases. This is the layer that likely chooses which agent persona or workflow should handle a task.

5. Multi-agent subsystem

The agents/ package contains the team-style reasoning components: strategist, specialist, critic, hybrid, universal, planner, intent, executor, and council modules. This is the collaboration boundary where multiple AI roles cross-check findings, produce plans, and arbitrate outputs before actions are taken. agents/tui_game.py suggests a test/demo or gamified interaction path, while worker_base.py and agent_dataclasses.py provide shared agent primitives.

6. Governance and safety boundary

Safety is not an afterthought; it is a dedicated layer. tools/governance.py, tools/safe_exec.py, redteam_agent/governance.py, and the README’s “SAFE / PRIVILEGED / DESTRUCTIVE” model indicate that all tool execution is supposed to pass through a policy gate. This is the main architectural boundary between reasoning and action.

7. Tooling and execution fabric

The tools/ directory is the main capability surface, with dozens of focused modules: recon (python_recon, smart_recon, subdomain_takeover, wayback_tool), application testing (xss, sqli, ssrf, graphql, auth, bola), fuzzing/mutation, WAF detection/evasion, reporting, and intelligence gathering. tool_registry.py, universal_executor.py, universal_ai_client.py, event_loop.py, and session_manager.py suggest a plug-in style execution model where the orchestrator dispatches tasks to registered tools.

8. Preflight scan pipeline

A key flow described in the README is the Phase 0 preflight path, which runs before full autonomous scanning. The pipeline is grounded in tools/python_recon.py, tools/waf_detector.py, tools/active_fuzzer.py, tools/bola_tester.py, tools/learning_engine.py, and tools/coverage_analyzer.py. This produces baseline findings even when AI access or external scanners are unavailable, then hands those findings upward to the reasoning layer.

9. Analysis, scoring, and reporting

Post-processing is handled by modules such as analysis_pipeline.py, cvss_calculator.py, exploit_chain_builder.py, reporter.py, html_reporter.py, pdf_report_generator.py, finding_dedup.py, and related research helpers. This is where raw tool output becomes triaged findings, severity scoring, exploit-chain hypotheses, and shareable reports.

10. Persistence and memory

The framework persists context across sessions through several storage layers. The repository includes SQLite databases and state files such as data/cve_database.db, data/mission_state.db, programs_cache.db, token_usage.db, and watchman_state.json, plus memory-oriented modules like vector_memory.py, memory_manager.py, memory_persistence.py, history_manager.py, and user_memory.py. The README indicates semantic memory with a ChromaDB/SQLite FTS5 fallback, so the architectural boundary is “ephemeral run state” vs “cross-session recall.”

11. Background and monitoring workflows

watchman.py, tools/watchman-related state, tools/interactive_dashboard.py, tools/dashboard_server.py, and the watchman CLI mode point to a long-running monitoring daemon separate from interactive scans. This suggests a second operating mode: persistent surveillance and periodic intelligence gathering instead of one-shot engagement.

12. Secondary package: redteam_agent/

The redteam_agent/ package is a compact standalone subsystem with its own main.py, run.py, config.py, llm.py, executor.py, state.py, and governance.py. Architecturally, it looks like a narrower red-team automation stack that mirrors the main project’s concepts but with fewer moving parts, likely used for isolated workflows or experimentation.

13. Integration points

The system is built around external AI providers and third-party security tooling rather than a single backend service. The README explicitly supports multiple LLM providers, while the requirements and setup scripts imply optional installation of Go-based and Python-based security tools. That means the main integration boundary is “provider/tool availability,” not networked microservices.

14. Quality and validation

The tests/ suite is broad and architecture-relevant: it covers governance enforcement, executor policy, agent coordination, fuzzing, configuration, CLI end-to-end behavior, and integration paths. The .github/workflows/test.yml CI file indicates the repo treats these boundaries as stable contracts, which is useful when drawing the architecture diagram: most components are validated at the seams between UI, orchestration, governance, and tools.