# seraphimhub/aegisrecon architecture

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

- Interactive diagram: https://gitdiagram.com/seraphimhub/aegisrecon
- Repository: https://github.com/seraphimhub/aegisrecon

## Overview

AegisRecon is a safe-by-default reconnaissance and crawling framework. Its primary workflow starts at the CLI: settings configure a scan or crawl, the engine validates scope and orchestrates discovery, and results are serialized to reports. Separate CLI commands provide screenshots, path discovery, API mapping, and JavaScript analysis. The README also documents plugin support and multiple report formats. The tree and sampled source establish the main scan and crawl calls; some subsystem wiring is documented but not shown in source excerpts.

Main entry points: [`aegis/cli/main.py`](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/cli/main.py) (Command interface), [`aegis/core/engine.py`](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/core/engine.py) (Recon engine), [`aegis/crawler/crawler.py`](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/crawler.py) (Async crawler), [`aegis/models/results.py`](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/models/results.py) (Scan results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["Command interface<br/>[main.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_engine["Recon engine<br/>[engine.py]"]
end

subgraph group_recon["Asset reconnaissance"]
  node_subdomains["Subdomain enumeration<br/>[subdomains.py]"]
  node_dns["DNS resolution<br/>[dns.py]"]
  node_http["HTTP probing<br/>[http_probe.py]"]
end

subgraph group_crawl["Web crawling"]
  node_scope["Scope controls<br/>[scope.py]"]
  node_crawler["Async crawler<br/>[crawler.py]"]
  node_crawlcontrols["Queue and scheduling<br/>[queue.py]"]
  node_robots["Robots and sitemap<br/>[robots.py]"]
  node_parser["Page parsing<br/>[parser.py]"]
  node_extractor["Page extraction<br/>[extractor.py]"]
end

subgraph group_analysis["Analysis and browser"]
  node_analyzers["Recon analyzers"]
  node_javascript["JavaScript analysis<br/>[javascript.py]"]
  node_browser["Browser rendering<br/>[rendering.py]"]
  node_screenshots["Screenshot capture<br/>[screenshot.py]"]
end

subgraph group_outputs["Results and extensions"]
  node_result["Scan results<br/>[results.py]"]
  node_exporters["Report exporters"]
  node_repository["Scan repository<br/>[repository.py]"]
  node_database[("SQL database<br/>[database.py]")]
  node_plugins["Plugin registry<br/>[loader.py]"]
end

node_user(("Assessment user"))
node_passive(("Public recon sources"))
node_artifacts["Report files"]

node_user -->|"runs commands"| node_cli
node_cli -->|"loads configuration"| node_settings
node_cli -->|"starts scan or crawl"| node_engine
node_engine -->|"validates target"| node_scope
node_engine -->|"enumerates assets"| node_subdomains
node_subdomains -.->|"queries sources"| node_passive
node_engine -->|"resolves assets"| node_dns
node_engine -->|"probes assets"| node_http
node_engine -->|"starts crawl"| node_crawler
node_crawler -->|"uses queue strategy"| node_crawlcontrols
node_crawler -->|"checks crawl rules"| node_robots
node_crawler -->|"parses responses"| node_parser
node_parser -->|"extracts page data"| node_extractor
node_cli -->|"probes discovery paths"| node_http
node_cli -->|"maps API routes"| node_analyzers
node_cli -->|"analyzes script"| node_javascript
node_cli -->|"captures screenshots"| node_screenshots
node_screenshots -->|"renders pages"| node_browser
node_engine -->|"populates results"| node_result
node_cli -->|"validates report input"| node_result
node_cli -->|"selects report formats"| node_exporters
node_exporters -->|"writes reports"| node_artifacts
node_result -->|"provides scan data"| node_repository
node_repository -->|"persists records"| node_database
node_plugins -.->|"can extend results"| node_result

click node_cli "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/cli/main.py"
click node_settings "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/config/settings.py"
click node_engine "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/core/engine.py"
click node_scope "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/scope.py"
click node_subdomains "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/subdomains.py"
click node_dns "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/dns.py"
click node_http "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/http_probe.py"
click node_crawler "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/crawler.py"
click node_crawlcontrols "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/core/queue.py"
click node_robots "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/robots.py"
click node_parser "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/parser.py"
click node_extractor "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/extractor.py"
click node_analyzers "https://github.com/seraphimhub/aegisrecon/tree/main/aegis/analyzers"
click node_javascript "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/analyzers/javascript.py"
click node_browser "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/browser/rendering.py"
click node_screenshots "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/browser/screenshot.py"
click node_result "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/models/results.py"
click node_exporters "https://github.com/seraphimhub/aegisrecon/tree/main/aegis/exporters"
click node_repository "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/storage/repository.py"
click node_database "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/storage/database.py"
click node_plugins "https://github.com/seraphimhub/aegisrecon/blob/main/aegis/plugins/loader.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_settings,node_engine,node_user toneBlue
class node_subdomains,node_dns,node_http toneAmber
class node_scope,node_crawler,node_crawlcontrols,node_robots,node_parser,node_extractor toneMint
class node_analyzers,node_javascript,node_browser,node_screenshots toneRose
class node_result,node_exporters,node_repository,node_database,node_plugins,node_passive,node_artifacts toneIndigo
```

## Components

### CLI and orchestration

- [Command interface](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/cli/main.py): `aegis/cli/main.py`
- [Settings](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/config/settings.py): `aegis/config/settings.py`
- [Recon engine](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/core/engine.py): `aegis/core/engine.py`

### Asset reconnaissance

- [Subdomain enumeration](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/subdomains.py): `aegis/recon/subdomains.py`
- [DNS resolution](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/dns.py): `aegis/recon/dns.py`
- [HTTP probing](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/recon/http_probe.py): `aegis/recon/http_probe.py`

### Web crawling

- [Scope controls](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/scope.py): `aegis/crawler/scope.py`
- [Async crawler](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/crawler.py): `aegis/crawler/crawler.py`
- [Queue and scheduling](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/core/queue.py): `aegis/core/queue.py`
- [Robots and sitemap](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/robots.py): `aegis/crawler/robots.py`
- [Page parsing](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/parser.py): `aegis/crawler/parser.py`
- [Page extraction](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/crawler/extractor.py): `aegis/crawler/extractor.py`

### Analysis and browser

- [Recon analyzers](https://github.com/seraphimhub/aegisrecon/tree/main/aegis/analyzers): `aegis/analyzers`
- [JavaScript analysis](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/analyzers/javascript.py): `aegis/analyzers/javascript.py`
- [Browser rendering](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/browser/rendering.py): `aegis/browser/rendering.py`
- [Screenshot capture](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/browser/screenshot.py): `aegis/browser/screenshot.py`

### Results and extensions

- [Scan results](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/models/results.py): `aegis/models/results.py`
- [Report exporters](https://github.com/seraphimhub/aegisrecon/tree/main/aegis/exporters): `aegis/exporters`
- [Scan repository](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/storage/repository.py): `aegis/storage/repository.py`
- [SQL database](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/storage/database.py): `aegis/storage/database.py`
- [Plugin registry](https://github.com/seraphimhub/aegisrecon/blob/main/aegis/plugins/loader.py): `aegis/plugins/loader.py`

### Other components

- **Assessment user**
- **Public recon sources**
- **Report files**

## Connections

- Assessment user → Command interface: runs commands
- Command interface → Settings: loads configuration
- Command interface → Recon engine: starts scan or crawl
- Recon engine → Scope controls: validates target
- Recon engine → Subdomain enumeration: enumerates assets
- Subdomain enumeration → Public recon sources: queries sources
- Recon engine → DNS resolution: resolves assets
- Recon engine → HTTP probing: probes assets
- Recon engine → Async crawler: starts crawl
- Async crawler → Queue and scheduling: uses queue strategy
- Async crawler → Robots and sitemap: checks crawl rules
- Async crawler → Page parsing: parses responses
- Page parsing → Page extraction: extracts page data
- Command interface → HTTP probing: probes discovery paths
- Command interface → Recon analyzers: maps API routes
- Command interface → JavaScript analysis: analyzes script
- Command interface → Screenshot capture: captures screenshots
- Screenshot capture → Browser rendering: renders pages
- Recon engine → Scan results: populates results
- Command interface → Scan results: validates report input
- Command interface → Report exporters: selects report formats
- Report exporters → Report files: writes reports
- Scan results → Scan repository: provides scan data
- Scan repository → SQL database: persists records
- Plugin registry → Scan results: can extend results