# ashveil1/elengenix architecture

> Architecture diagram of the GitHub repository ashveil1/elengenix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashveil1/elengenix
- Repository: https://github.com/ashveil1/elengenix

## Overview

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.

Main entry points: [`orchestrator.py`](https://github.com/ashveil1/elengenix/blob/main/orchestrator.py) (Orchestrator), [`agent_brain.py`](https://github.com/ashveil1/elengenix/blob/main/agent_brain.py) (Brain), [`tools/universal_executor.py`](https://github.com/ashveil1/elengenix/blob/main/tools/universal_executor.py) (Executor), [`cli_textual.py`](https://github.com/ashveil1/elengenix/blob/main/cli_textual.py) (Textual UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_main_py["Main<br/>entrypoint<br/>[main.py]"]
  node_run_py["Run<br/>entrypoint<br/>[run.py]"]
  node_cli_py["CLI<br/>entrypoint<br/>[cli.py]"]
  node_bot_py["Bot<br/>entrypoint<br/>[bot.py]"]
  node_launcher_py["Launcher<br/>entrypoint"]
end

subgraph group_ui["UI layer"]
  node_cli_textual_py["Textual UI<br/>entrypoint<br/>[cli_textual.py]"]
  node_ui_components_py["UI widgets<br/>[ui_components.py]"]
  node_live_display_py["Live display<br/>ui<br/>[live_display.py]"]
  node_tools_menu_py["Tools menu<br/>ui<br/>[tools_menu.py]"]
end

subgraph group_control["Control plane"]
  node_orchestrator_py["Orchestrator<br/>control<br/>[orchestrator.py]"]
  node_agent_brain_py["Brain<br/>control<br/>[agent_brain.py]"]
  node_agent_py["Agent<br/>control<br/>[agent.py]"]
end

subgraph group_agents["Agent swarm"]
  node_agent_council_py["Council<br/>agents<br/>[agent_council.py]"]
  node_agent_planner_py["Planner<br/>agents<br/>[agent_planner.py]"]
end

subgraph group_tools["Tool fabric"]
  node_tool_registry_py["Tool registry<br/>tools<br/>[tool_registry.py]"]
  node_universal_executor_py["Executor<br/>tools"]
  node_governance_py["Governance<br/>tools<br/>[governance.py]"]
  node_analysis_pipeline_py["Analysis<br/>tools"]
  node_reporter_py["Reporter<br/>tools<br/>[reporter.py]"]
end

subgraph group_state["State & memory"]
  node_vector_memory_py[("Memory<br/>state<br/>[vector_memory.py]")]
  node_session_manager_py[("Session<br/>state<br/>[session_manager.py]")]
end

subgraph group_monitoring["Monitoring"]
  node_watchman_py(("Watchman<br/>monitoring<br/>[watchman.py]"))
  node_dashboard_py["Dashboard<br/>monitoring"]
end

subgraph group_redteam["Redteam package"]
  node_redteam_main_py["RT main<br/>redteam<br/>[main.py]"]
  node_redteam_gov_py["RT governance<br/>redteam<br/>[governance.py]"]
end

node_main_py -->|"boot"| node_orchestrator_py
node_run_py -->|"launch"| node_orchestrator_py
node_cli_py -->|"ui"| node_ui_components_py
node_cli_textual_py -->|"render"| node_live_display_py
node_cli_textual_py -->|"navigate"| node_tools_menu_py
node_bot_py -->|"dispatch"| node_orchestrator_py
node_launcher_py -->|"wrap"| node_main_py
node_orchestrator_py -->|"reason"| node_agent_brain_py
node_agent_brain_py -->|"plan"| node_agent_planner_py
node_agent_brain_py -->|"consult"| node_agent_council_py
node_agent_py -->|"host"| node_agent_brain_py
node_orchestrator_py -->|"select"| node_tool_registry_py
node_tool_registry_py -->|"run"| node_universal_executor_py
node_universal_executor_py -->|"check"| node_governance_py
node_governance_py -->|"allow"| node_analysis_pipeline_py
node_analysis_pipeline_py -->|"publish"| node_reporter_py
node_orchestrator_py -->|"state"| node_session_manager_py
node_session_manager_py -->|"remember"| node_vector_memory_py
node_watchman_py -->|"surface"| node_dashboard_py
node_watchman_py -->|"observe"| node_orchestrator_py
node_redteam_main_py -->|"gate"| node_redteam_gov_py
node_redteam_gov_py -->|"execute"| node_universal_executor_py

click node_main_py "https://github.com/ashveil1/elengenix/blob/main/main.py"
click node_run_py "https://github.com/ashveil1/elengenix/blob/main/run.py"
click node_cli_py "https://github.com/ashveil1/elengenix/blob/main/cli.py"
click node_cli_textual_py "https://github.com/ashveil1/elengenix/blob/main/cli_textual.py"
click node_ui_components_py "https://github.com/ashveil1/elengenix/blob/main/ui_components.py"
click node_live_display_py "https://github.com/ashveil1/elengenix/blob/main/live_display.py"
click node_tools_menu_py "https://github.com/ashveil1/elengenix/blob/main/tools_menu.py"
click node_bot_py "https://github.com/ashveil1/elengenix/blob/main/bot.py"
click node_launcher_py "https://github.com/ashveil1/elengenix/blob/main/elengenix_launcher.py"
click node_orchestrator_py "https://github.com/ashveil1/elengenix/blob/main/orchestrator.py"
click node_agent_brain_py "https://github.com/ashveil1/elengenix/blob/main/agent_brain.py"
click node_agent_py "https://github.com/ashveil1/elengenix/blob/main/agent.py"
click node_agent_council_py "https://github.com/ashveil1/elengenix/blob/main/agents/agent_council.py"
click node_agent_planner_py "https://github.com/ashveil1/elengenix/blob/main/agents/agent_planner.py"
click node_tool_registry_py "https://github.com/ashveil1/elengenix/blob/main/tools/tool_registry.py"
click node_universal_executor_py "https://github.com/ashveil1/elengenix/blob/main/tools/universal_executor.py"
click node_governance_py "https://github.com/ashveil1/elengenix/blob/main/tools/governance.py"
click node_analysis_pipeline_py "https://github.com/ashveil1/elengenix/blob/main/tools/analysis_pipeline.py"
click node_reporter_py "https://github.com/ashveil1/elengenix/blob/main/tools/reporter.py"
click node_vector_memory_py "https://github.com/ashveil1/elengenix/blob/main/tools/vector_memory.py"
click node_session_manager_py "https://github.com/ashveil1/elengenix/blob/main/tools/session_manager.py"
click node_watchman_py "https://github.com/ashveil1/elengenix/blob/main/watchman.py"
click node_dashboard_py "https://github.com/ashveil1/elengenix/blob/main/tools/interactive_dashboard.py"
click node_redteam_main_py "https://github.com/ashveil1/elengenix/blob/main/redteam_agent/main.py"
click node_redteam_gov_py "https://github.com/ashveil1/elengenix/blob/main/redteam_agent/governance.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_run_py,node_cli_py,node_bot_py,node_launcher_py,node_watchman_py,node_dashboard_py toneBlue
class node_cli_textual_py,node_ui_components_py,node_live_display_py,node_tools_menu_py,node_redteam_main_py,node_redteam_gov_py toneAmber
class node_orchestrator_py,node_agent_brain_py,node_agent_py toneMint
class node_agent_council_py,node_agent_planner_py toneRose
class node_tool_registry_py,node_universal_executor_py,node_governance_py,node_analysis_pipeline_py,node_reporter_py toneIndigo
class node_vector_memory_py,node_session_manager_py toneTeal
```

## Components

### Entry points

User-facing runtime fronts and launch helpers.

- [Main](https://github.com/ashveil1/elengenix/blob/main/main.py): entrypoint · Primary application entrypoint. · `main.py`
- [Run](https://github.com/ashveil1/elengenix/blob/main/run.py): entrypoint · Alternate runtime launcher. · `run.py`
- [CLI](https://github.com/ashveil1/elengenix/blob/main/cli.py): entrypoint · Standard command-line interface. · `cli.py`
- [Bot](https://github.com/ashveil1/elengenix/blob/main/bot.py): entrypoint · Bot integration entrypoint. · `bot.py`
- [Launcher](https://github.com/ashveil1/elengenix/blob/main/elengenix_launcher.py): entrypoint · External launcher wrapper. · `elengenix_launcher.py`

### UI layer

Interactive terminal and command surfaces.

- [Textual UI](https://github.com/ashveil1/elengenix/blob/main/cli_textual.py): entrypoint · Interactive terminal UI entrypoint. · `cli_textual.py`
- [UI widgets](https://github.com/ashveil1/elengenix/blob/main/ui_components.py): ui · Shared terminal UI components. · `ui_components.py`
- [Live display](https://github.com/ashveil1/elengenix/blob/main/live_display.py): ui · Live status and progress presentation. · `live_display.py`
- [Tools menu](https://github.com/ashveil1/elengenix/blob/main/tools_menu.py): ui · Interactive tool selection surface. · `tools_menu.py`

### Control plane

Core intent, planning, and orchestration logic.

- [Orchestrator](https://github.com/ashveil1/elengenix/blob/main/orchestrator.py): control · Coordinates plans, tools, and execution phases. · `orchestrator.py`
- [Brain](https://github.com/ashveil1/elengenix/blob/main/agent_brain.py): control · High-level reasoning and intent routing. · `agent_brain.py`
- [Agent](https://github.com/ashveil1/elengenix/blob/main/agent.py): control · Core agent runtime facade. · `agent.py`

### Agent swarm

Collaborative reasoning roles and shared agent primitives.

- [Council](https://github.com/ashveil1/elengenix/blob/main/agents/agent_council.py): agents · Multi-agent deliberation and arbitration. · `agents/agent_council.py`
- [Planner](https://github.com/ashveil1/elengenix/blob/main/agents/agent_planner.py): agents · Task decomposition and plan generation. · `agents/agent_planner.py`

### Tool fabric

Execution registry, policy gates, and major post-processing.

- [Tool registry](https://github.com/ashveil1/elengenix/blob/main/tools/tool_registry.py): tools · Registers and dispatches available tools. · `tools/tool_registry.py`
- [Executor](https://github.com/ashveil1/elengenix/blob/main/tools/universal_executor.py): tools · Runs tools under a shared execution model. · `tools/universal_executor.py`
- [Governance](https://github.com/ashveil1/elengenix/blob/main/tools/governance.py): tools · Policy gate for safe and privileged actions. · `tools/governance.py`
- [Analysis](https://github.com/ashveil1/elengenix/blob/main/tools/analysis_pipeline.py): tools · Post-processes findings into triage outputs. · `tools/analysis_pipeline.py`
- [Reporter](https://github.com/ashveil1/elengenix/blob/main/tools/reporter.py): tools · Generates human-readable reports. · `tools/reporter.py`

### State & memory

Cross-session state, persistence, and run coordination.

- [Memory](https://github.com/ashveil1/elengenix/blob/main/tools/vector_memory.py): state · Semantic and persistent recall layer. · `tools/vector_memory.py`
- [Session](https://github.com/ashveil1/elengenix/blob/main/tools/session_manager.py): state · Tracks run state and session coordination. · `tools/session_manager.py`

### Monitoring

Persistent watchman and dashboard workflows.

- [Watchman](https://github.com/ashveil1/elengenix/blob/main/watchman.py): monitoring · Persistent monitoring and background workflow. · `watchman.py`
- [Dashboard](https://github.com/ashveil1/elengenix/blob/main/tools/interactive_dashboard.py): monitoring · Interactive monitoring dashboard. · `tools/interactive_dashboard.py`

### Redteam package

Compact standalone automation path.

- [RT main](https://github.com/ashveil1/elengenix/blob/main/redteam_agent/main.py): redteam · Standalone red-team subsystem entrypoint. · `redteam_agent/main.py`
- [RT governance](https://github.com/ashveil1/elengenix/blob/main/redteam_agent/governance.py): redteam · Red-team policy and execution gate. · `redteam_agent/governance.py`

## Connections

- Main → Orchestrator: boot · Starts the main autonomous runtime.
- Run → Orchestrator: launch · Alternative runtime launch path.
- CLI → UI widgets: ui · Builds the standard CLI experience.
- Textual UI → Live display: render · Drives live terminal updates.
- Textual UI → Tools menu: navigate · Presents interactive tool selection.
- Bot → Orchestrator: dispatch · Routes bot-triggered tasks into the core runtime.
- Launcher → Main: wrap · Launches the primary application entrypoint.
- Orchestrator → Brain: reason · Delegates intent handling and control flow.
- Brain → Planner: plan · Turns intent into an actionable plan.
- Brain → Council: consult · Uses multi-agent deliberation for decisions.
- Agent → Brain: host · Provides the runtime shell for agent logic.
- Orchestrator → Tool registry: select · Resolves available tools for a task.
- Tool registry → Executor: run · Executes selected tools through a shared engine.
- Executor → Governance: check · Applies policy before action.
- Governance → Analysis: allow · Permits downstream analysis after policy checks.
- Analysis → Reporter: publish · Converts findings into reports.
- Orchestrator → Session: state · Persists and restores run context.
- Session → Memory: remember · Stores cross-session memory and recall data.
- Watchman → Dashboard: surface · Feeds the monitoring dashboard.
- Watchman → Orchestrator: observe · Supports ongoing surveillance workflows.
- RT main → RT governance: gate · Runs the standalone red-team path through governance.
- RT governance → Executor: execute · Uses the shared execution model for actions.