# ravichandran3/cxploit-framework architecture

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

- Interactive diagram: https://gitdiagram.com/ravichandran3/cxploit-framework
- Repository: https://github.com/ravichandran3/cxploit-framework

## Overview

#### Purpose and Entry Points
CXploit is a Python 3.10+ modular framework for authorized security assessment workflows: reconnaissance, vulnerability assessment, controlled exploitation modules, payload/session handling, post-assessment collection, reporting, and optional remote control. The primary launcher is `main.py`, which initializes the central framework and starts the interactive CLI; it can also enable the Flask API. Primary user-facing surfaces are `exploit_framework/cli/console.py`, `exploit_framework/api/server.py`, and `exploit_framework/api/dashboard.py`.

#### Core Orchestration
`Framework` is the central, thread-safe application coordinator: it initializes configuration, persistence, events, module discovery, sessions, and shutdown behavior. Dynamic discovery makes category modules and custom plugins available through a common module interface (`MODULE_INFO`, options, `run`, and `check`).
- `exploit_framework/core/framework.py`
- `exploit_framework/core/module_loader.py`
- `exploit_framework/exploits/base.py`

#### Control Plane: CLI, API, and Plugins
The CLI parses Metasploit-style commands, selects modules, applies option values, launches foreground/background work, and exposes sessions, reports, and attack-chain commands. The API presents analogous framework state and module-execution capabilities over HTTP. Plugins extend the same loader-driven module ecosystem and are a boundary for third-party code.
- `exploit_framework/cli/commands.py`
- `exploit_framework/api/server.py`
- `exploit_framework/plugins/plugin_manager.py`

#### Persistent State, Events, and Sessions
SQLite/SQLAlchemy persistence is the system-of-record boundary for targets, discovered services/vulnerabilities, credentials, events, and sessions. The event subsystem distributes operational logging/events; session management represents active connections and their lifecycle. Configuration is JSON-backed and governs runtime defaults, safety settings, concurrency, and output locations.
- `exploit_framework/core/database.py`
- `exploit_framework/core/events.py`
- `exploit_framework/core/session.py`
- `exploit_framework/core/config.py`

#### Assessment and AutoPwn Pipeline
Reconnaissance modules produce host, port, service, OS, web, and vulnerability findings. The AutoPwn coordinator composes scan/service results with offline CVE matching and selected exploitation modules; this is the major automated control flow and should remain gated by authorization and emergency-stop/rate-limit controls in the framework layer.
- `exploit_framework/core/autopwn.py`
- `exploit_framework/recon/port_scanner.py`
- `exploit_framework/recon/vuln_scanner.py`
- `exploit_framework/recon/cve_db.py`

#### Execution Stages and Module Families
Loaded modules are organized as independently selectable stages: exploits act on identified targets; payload generators/handlers establish or manage connections; post modules operate through sessions; evasion modules transform payloads or traffic; auxiliary modules provide scanning and credential/testing support. These modules depend on shared framework state rather than owning persistence directly.
- `exploit_framework/exploits/web/sqli.py`
- `exploit_framework/payloads/generator.py`
- `exploit_framework/post/sys_enum.py`
- `exploit_framework/evasion/waf_bypass.py`
- `exploit_framework/auxiliary/cred_sprayer.py`

#### C2, Reporting, and Runtime Dependencies
C2 is a distinct network boundary: a server and generated agent use encrypted TCP/HTTP channels. Reporting reads persisted assessment data to create HTML, JSON, PDF, and compliance outputs. Material dependencies include Flask (API/dashboard), SQLAlchemy with SQLite, Scapy and python-nmap for network operations, Paramiko for SSH, Requests/aiohttp for HTTP, PyCryptodome for cryptography, and Jinja2/ReportLab for reports.
- `exploit_framework/c2/c2_server.py`
- `exploit_framework/c2/c2_agent.py`
- `exploit_framework/reporting/report_gen.py`
- `exploit_framework/reporting/compliance_report.py`

Main entry points: [`exploit_framework/core/framework.py`](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/framework.py) (Framework), [`exploit_framework/core/autopwn.py`](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/autopwn.py) (AutoPwn Coordinator), [`main.py`](https://github.com/ravichandran3/cxploit-framework/blob/main/main.py) (Launcher), [`exploit_framework/api/server.py`](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/api/server.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Control Surfaces"]
  node_launcher["Launcher<br/>Python entry point<br/>[main.py]"]
  node_cli["Interactive CLI<br/>command console<br/>[console.py]"]
  node_api["Flask API<br/>HTTP control plane<br/>[server.py]"]
  node_dashboard["Dashboard<br/>web UI<br/>[dashboard.py]"]
end

subgraph group_core["Core Runtime"]
  node_framework{{"Framework<br/>application coordinator<br/>[framework.py]"}}
  node_module_loader["Module Loader<br/>dynamic discovery<br/>[module_loader.py]"]
  node_config["Configuration<br/>JSON runtime settings<br/>[config.py]"]
  node_database[("Assessment Store<br/>SQLite / SQLAlchemy<br/>[database.py]")]
  node_events["Event Subsystem<br/>operational events<br/>[events.py]"]
  node_sessions["Session Manager<br/>connection lifecycle<br/>[session.py]"]
end

subgraph group_assessment["Assessment Pipeline"]
  node_autopwn{{"AutoPwn Coordinator<br/>automated workflow<br/>[autopwn.py]"}}
  node_recon["Recon &amp; Vulnerability Scan<br/>finding producers<br/>[port_scanner.py]"]
  node_cve_db[("Offline CVE Matcher<br/>CVE database<br/>[cve_db.py]")]
end

subgraph group_modules["Module Families"]
  node_modules["Loaded Assessment Modules<br/>common module interface<br/>[base.py]"]
  node_execution["Execution Families<br/>[sqli.py]"]
  node_plugins["Third-Party Plugins<br/>extension boundary<br/>[plugin_manager.py]"]
end

subgraph group_outputs["External Boundaries"]
  node_c2_server["C2 Server<br/>encrypted network control<br/>[c2_server.py]"]
  node_c2_agent["Generated C2 Agent<br/>remote agent<br/>[c2_agent.py]"]
  node_reporting["Reporting<br/>[report_gen.py]"]
end

node_launcher -->|"initializes"| node_framework
node_launcher -->|"starts"| node_cli
node_launcher -.->|"optionally enables"| node_api
node_dashboard -->|"uses"| node_api
node_cli -->|"commands"| node_framework
node_api -->|"controls"| node_framework
node_framework -->|"loads"| node_config
node_framework -->|"persists state"| node_database
node_framework -->|"publishes"| node_events
node_framework -->|"manages"| node_sessions
node_framework -->|"discovers modules"| node_module_loader
node_module_loader -->|"loads"| node_modules
node_plugins -->|"extends"| node_module_loader
node_modules -->|"includes"| node_execution
node_framework -->|"safety-gated execution"| node_autopwn
node_autopwn -->|"uses findings"| node_recon
node_recon -->|"stores findings"| node_database
node_autopwn -->|"matches CVEs"| node_cve_db
node_autopwn -->|"selects modules"| node_execution
node_execution -->|"creates and uses"| node_sessions
node_c2_server -->|"encrypted TCP/HTTP"| node_c2_agent
node_c2_server -->|"remote connections"| node_sessions
node_reporting -->|"reads assessment data"| node_database

click node_launcher "https://github.com/ravichandran3/cxploit-framework/blob/main/main.py"
click node_cli "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/cli/console.py"
click node_api "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/api/server.py"
click node_dashboard "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/api/dashboard.py"
click node_framework "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/framework.py"
click node_module_loader "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/module_loader.py"
click node_config "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/config.py"
click node_database "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/database.py"
click node_events "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/events.py"
click node_sessions "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/session.py"
click node_autopwn "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/autopwn.py"
click node_recon "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/recon/port_scanner.py"
click node_cve_db "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/recon/cve_db.py"
click node_modules "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/exploits/base.py"
click node_execution "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/exploits/web/sqli.py"
click node_plugins "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/plugins/plugin_manager.py"
click node_c2_server "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/c2/c2_server.py"
click node_c2_agent "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/c2/c2_agent.py"
click node_reporting "https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/reporting/report_gen.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_launcher,node_cli,node_api,node_dashboard toneBlue
class node_framework,node_module_loader,node_config,node_database,node_events,node_sessions toneAmber
class node_autopwn,node_recon,node_cve_db toneMint
class node_modules,node_execution,node_plugins toneRose
class node_c2_server,node_c2_agent,node_reporting toneIndigo
```

## Components

### Control Surfaces

- [Launcher](https://github.com/ravichandran3/cxploit-framework/blob/main/main.py): Python entry point · Initializes the framework and interactive runtime. · `main.py`
- [Interactive CLI](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/cli/console.py): command console · `exploit_framework/cli/console.py`
- [Flask API](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/api/server.py): HTTP control plane · `exploit_framework/api/server.py`
- [Dashboard](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/api/dashboard.py): web UI · `exploit_framework/api/dashboard.py`

### Core Runtime

- [Framework](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/framework.py): application coordinator · Thread-safe lifecycle, safety, concurrency, and shutdown coordinator. · `exploit_framework/core/framework.py`
- [Module Loader](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/module_loader.py): dynamic discovery · Loads built-in categories and custom plugins through a common interface. · `exploit_framework/core/module_loader.py`
- [Configuration](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/config.py): JSON runtime settings · `exploit_framework/core/config.py`
- [Assessment Store](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/database.py): SQLite / SQLAlchemy · System of record for targets, findings, credentials, events, and sessions. · `exploit_framework/core/database.py`
- [Event Subsystem](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/events.py): operational events · `exploit_framework/core/events.py`
- [Session Manager](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/session.py): connection lifecycle · `exploit_framework/core/session.py`

### Assessment Pipeline

- [AutoPwn Coordinator](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/core/autopwn.py): automated workflow · Composes findings, offline CVE matching, and selected modules under framework safety gates. · `exploit_framework/core/autopwn.py`
- [Recon & Vulnerability Scan](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/recon/port_scanner.py): finding producers · Discovers hosts, ports, services, OS, web, and vulnerability findings. · `exploit_framework/recon/port_scanner.py`
- [Offline CVE Matcher](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/recon/cve_db.py): CVE database · `exploit_framework/recon/cve_db.py`

### Module Families

- [Loaded Assessment Modules](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/exploits/base.py): common module interface · Selectable modules expose MODULE_INFO, options, check, and run. · `exploit_framework/exploits/base.py`
- [Execution Families](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/exploits/web/sqli.py): exploit / payload / post / evasion / auxiliary · Acts on targets and sessions using shared framework state. · `exploit_framework/exploits/web/sqli.py`
- [Third-Party Plugins](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/plugins/plugin_manager.py): extension boundary · `exploit_framework/plugins/plugin_manager.py`

### External Boundaries

- [C2 Server](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/c2/c2_server.py): encrypted network control · `exploit_framework/c2/c2_server.py`
- [Generated C2 Agent](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/c2/c2_agent.py): remote agent · Communicates with C2 over encrypted TCP/HTTP. · `exploit_framework/c2/c2_agent.py`
- [Reporting](https://github.com/ravichandran3/cxploit-framework/blob/main/exploit_framework/reporting/report_gen.py): HTML / JSON / PDF / compliance · `exploit_framework/reporting/report_gen.py`

## Connections

- Launcher → Framework: initializes
- Launcher → Interactive CLI: starts
- Launcher → Flask API: optionally enables
- Dashboard → Flask API: uses
- Interactive CLI → Framework: commands
- Flask API → Framework: controls
- Framework → Configuration: loads
- Framework → Assessment Store: persists state
- Framework → Event Subsystem: publishes
- Framework → Session Manager: manages
- Framework → Module Loader: discovers modules
- Module Loader → Loaded Assessment Modules: loads
- Third-Party Plugins → Module Loader: extends
- Loaded Assessment Modules → Execution Families: includes
- Framework → AutoPwn Coordinator: safety-gated execution
- AutoPwn Coordinator → Recon & Vulnerability Scan: uses findings
- Recon & Vulnerability Scan → Assessment Store: stores findings
- AutoPwn Coordinator → Offline CVE Matcher: matches CVEs
- AutoPwn Coordinator → Execution Families: selects modules
- Execution Families → Session Manager: creates and uses
- C2 Server → Generated C2 Agent: encrypted TCP/HTTP
- C2 Server → Session Manager: remote connections
- Reporting → Assessment Store: reads assessment data