# almadadali/scoutx architecture

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

- Interactive diagram: https://gitdiagram.com/almadadali/scoutx
- Repository: https://github.com/almadadali/scoutx

## Overview

ScoutX is an async reconnaissance framework for security researchers. A user starts a scan through the CLI or Python API; the scan engine coordinates plugin execution, persists scan state, and can notify configured channels. Results support reporting and scan comparison, while a separate attack-chain engine turns reconnaissance data into scored exploitation playbooks. The README also documents methodology-driven scanning, AI analysis, stealth, cloud and API discovery, and tool management. Some of these modules were not sampled, so their connections are shown only where documented or omitted when uncertain.

Main entry points: [`scoutx/core/engine.py`](https://github.com/almadadali/scoutx/blob/main/scoutx/core/engine.py) (Scan Engine), [`scoutx/plugins/manager.py`](https://github.com/almadadali/scoutx/blob/main/scoutx/plugins/manager.py) (Plugin Manager), [`scoutx/cli/app.py`](https://github.com/almadadali/scoutx/blob/main/scoutx/cli/app.py) (CLI), [`scoutx/api.py`](https://github.com/almadadali/scoutx/blob/main/scoutx/api.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI<br/>[app.py]"]
  node_api["Python API<br/>[api.py]"]
end

subgraph group_orchestration["Scan Orchestration"]
  node_config["Configuration<br/>[config.py]"]
  node_scope["Scope Control<br/>[scope.py]"]
  node_engine["Scan Engine<br/>[engine.py]"]
  node_events["Event Bus<br/>[events.py]"]
  node_methodology["Methodology<br/>[runner.py]"]
end

subgraph group_recon["Reconnaissance"]
  node_plugins["Plugin Manager<br/>[manager.py]"]
  node_pluginbase["Plugin Interface<br/>[base.py]"]
  node_builtin["Recon Plugins"]
  node_stealth["Stealth Controls"]
  node_tools["Tool Registry<br/>[registry.py]"]
end

subgraph group_analysis["Analysis"]
  node_chains["Attack Chains<br/>[engine.py]"]
  node_checklist["Vulnerability Checklist<br/>[checklist.py]"]
  node_patterns["Chain Patterns<br/>[patterns.py]"]
  node_ai["AI Providers<br/>[client.py]"]
end

subgraph group_outputs["Results and Integrations"]
  node_repository[("Scan Repository<br/>[repository.py]")]
  node_reporting["Report Aggregator<br/>[aggregator.py]"]
  node_html["HTML Report<br/>[html.py]"]
  node_diff["Scan Diff<br/>[diff.py]"]
  node_notifications["Notifications<br/>[engine.py]"]
  node_channels["Alert Channels<br/>[webhook.py]"]
end

node_user(("Researcher"))

node_user -->|"runs commands"| node_cli
node_user -->|"calls API"| node_api
node_cli -->|"starts scan"| node_engine
node_api -->|"creates scope"| node_scope
node_api -->|"discovers plugins"| node_plugins
node_api -->|"runs scan"| node_engine
node_engine -->|"persists scan"| node_repository
node_engine -->|"emits events"| node_events
node_engine -->|"dispatches alerts"| node_notifications
node_plugins -->|"registers plugins"| node_pluginbase
node_engine -.->|"runs plugins"| node_plugins
node_plugins -.->|"loads built-ins"| node_builtin
node_engine -.->|"follows phases"| node_methodology
node_engine -.->|"uses controls"| node_stealth
node_plugins -.->|"uses tools"| node_tools
node_chains -->|"maps findings"| node_checklist
node_chains -->|"correlates patterns"| node_patterns
node_chains -->|"uses scan data"| node_engine
node_engine -.->|"AI analysis"| node_ai
node_cli -->|"generates reports"| node_reporting
node_reporting -->|"renders HTML"| node_html
node_cli -.->|"compares scans"| node_diff
node_notifications -.->|"sends alerts"| node_channels

click node_cli "https://github.com/almadadali/scoutx/blob/main/scoutx/cli/app.py"
click node_api "https://github.com/almadadali/scoutx/blob/main/scoutx/api.py"
click node_config "https://github.com/almadadali/scoutx/blob/main/scoutx/core/config.py"
click node_scope "https://github.com/almadadali/scoutx/blob/main/scoutx/core/scope.py"
click node_engine "https://github.com/almadadali/scoutx/blob/main/scoutx/core/engine.py"
click node_events "https://github.com/almadadali/scoutx/blob/main/scoutx/core/events.py"
click node_methodology "https://github.com/almadadali/scoutx/blob/main/scoutx/methodology/runner.py"
click node_plugins "https://github.com/almadadali/scoutx/blob/main/scoutx/plugins/manager.py"
click node_pluginbase "https://github.com/almadadali/scoutx/blob/main/scoutx/plugins/base.py"
click node_builtin "https://github.com/almadadali/scoutx/tree/main/scoutx/plugins/builtin"
click node_stealth "https://github.com/almadadali/scoutx/tree/main/scoutx/stealth"
click node_tools "https://github.com/almadadali/scoutx/blob/main/scoutx/tools/registry.py"
click node_chains "https://github.com/almadadali/scoutx/blob/main/scoutx/chains/engine.py"
click node_checklist "https://github.com/almadadali/scoutx/blob/main/scoutx/chains/checklist.py"
click node_patterns "https://github.com/almadadali/scoutx/blob/main/scoutx/chains/patterns.py"
click node_ai "https://github.com/almadadali/scoutx/blob/main/scoutx/ai/client.py"
click node_repository "https://github.com/almadadali/scoutx/blob/main/scoutx/database/repository.py"
click node_reporting "https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/aggregator.py"
click node_html "https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/html.py"
click node_diff "https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/diff.py"
click node_notifications "https://github.com/almadadali/scoutx/blob/main/scoutx/notifications/engine.py"
click node_channels "https://github.com/almadadali/scoutx/blob/main/scoutx/notifications/webhook.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_cli,node_api toneBlue
class node_config,node_scope,node_engine,node_events,node_methodology toneAmber
class node_plugins,node_pluginbase,node_builtin,node_stealth,node_tools toneMint
class node_chains,node_checklist,node_patterns,node_ai toneRose
class node_repository,node_reporting,node_html,node_diff,node_notifications,node_channels,node_user toneIndigo
```

## Components

### User Entry

- [CLI](https://github.com/almadadali/scoutx/blob/main/scoutx/cli/app.py): `scoutx/cli/app.py`
- [Python API](https://github.com/almadadali/scoutx/blob/main/scoutx/api.py): `scoutx/api.py`

### Scan Orchestration

- [Configuration](https://github.com/almadadali/scoutx/blob/main/scoutx/core/config.py): `scoutx/core/config.py`
- [Scope Control](https://github.com/almadadali/scoutx/blob/main/scoutx/core/scope.py): `scoutx/core/scope.py`
- [Scan Engine](https://github.com/almadadali/scoutx/blob/main/scoutx/core/engine.py): `scoutx/core/engine.py`
- [Event Bus](https://github.com/almadadali/scoutx/blob/main/scoutx/core/events.py): `scoutx/core/events.py`
- [Methodology](https://github.com/almadadali/scoutx/blob/main/scoutx/methodology/runner.py): `scoutx/methodology/runner.py`

### Reconnaissance

- [Plugin Manager](https://github.com/almadadali/scoutx/blob/main/scoutx/plugins/manager.py): `scoutx/plugins/manager.py`
- [Plugin Interface](https://github.com/almadadali/scoutx/blob/main/scoutx/plugins/base.py): `scoutx/plugins/base.py`
- [Recon Plugins](https://github.com/almadadali/scoutx/tree/main/scoutx/plugins/builtin): `scoutx/plugins/builtin`
- [Stealth Controls](https://github.com/almadadali/scoutx/tree/main/scoutx/stealth): `scoutx/stealth`
- [Tool Registry](https://github.com/almadadali/scoutx/blob/main/scoutx/tools/registry.py): `scoutx/tools/registry.py`

### Analysis

- [Attack Chains](https://github.com/almadadali/scoutx/blob/main/scoutx/chains/engine.py): `scoutx/chains/engine.py`
- [Vulnerability Checklist](https://github.com/almadadali/scoutx/blob/main/scoutx/chains/checklist.py): `scoutx/chains/checklist.py`
- [Chain Patterns](https://github.com/almadadali/scoutx/blob/main/scoutx/chains/patterns.py): `scoutx/chains/patterns.py`
- [AI Providers](https://github.com/almadadali/scoutx/blob/main/scoutx/ai/client.py): `scoutx/ai/client.py`

### Results and Integrations

- [Scan Repository](https://github.com/almadadali/scoutx/blob/main/scoutx/database/repository.py): `scoutx/database/repository.py`
- [Report Aggregator](https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/aggregator.py): `scoutx/reporting/aggregator.py`
- [HTML Report](https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/html.py): `scoutx/reporting/html.py`
- [Scan Diff](https://github.com/almadadali/scoutx/blob/main/scoutx/reporting/diff.py): `scoutx/reporting/diff.py`
- [Notifications](https://github.com/almadadali/scoutx/blob/main/scoutx/notifications/engine.py): `scoutx/notifications/engine.py`
- [Alert Channels](https://github.com/almadadali/scoutx/blob/main/scoutx/notifications/webhook.py): `scoutx/notifications/webhook.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: runs commands (evidence: `README.md`)
- Researcher → Python API: calls API (evidence: `README.md`)
- CLI → Scan Engine: starts scan
- Python API → Scope Control: creates scope (evidence: `scoutx/api.py`)
- Python API → Plugin Manager: discovers plugins (evidence: `scoutx/api.py`)
- Python API → Scan Engine: runs scan (evidence: `scoutx/api.py`)
- Scan Engine → Scan Repository: persists scan (evidence: `scoutx/core/engine.py`)
- Scan Engine → Event Bus: emits events (evidence: `scoutx/core/engine.py`)
- Scan Engine → Notifications: dispatches alerts (evidence: `scoutx/core/engine.py`)
- Plugin Manager → Plugin Interface: registers plugins (evidence: `scoutx/plugins/manager.py`)
- Scan Engine → Plugin Manager: runs plugins
- Plugin Manager → Recon Plugins: loads built-ins (evidence: `scoutx/plugins/manager.py`)
- Scan Engine → Methodology: follows phases
- Scan Engine → Stealth Controls: uses controls
- Plugin Manager → Tool Registry: uses tools
- Attack Chains → Vulnerability Checklist: maps findings (evidence: `scoutx/chains/engine.py`)
- Attack Chains → Chain Patterns: correlates patterns (evidence: `scoutx/chains/engine.py`)
- Attack Chains → Scan Engine: uses scan data (evidence: `scoutx/chains/engine.py`)
- Scan Engine → AI Providers: AI analysis
- CLI → Report Aggregator: generates reports
- Report Aggregator → HTML Report: renders HTML (evidence: `scoutx/reporting/html.py`)
- CLI → Scan Diff: compares scans
- Notifications → Alert Channels: sends alerts (evidence: `scoutx/notifications/engine.py`)