# duty1g/subcat architecture

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

- Interactive diagram: https://gitdiagram.com/duty1g/subcat
- Repository: https://github.com/duty1g/subcat

## Overview

SubCat is a subdomain discovery and triage tool: users run passive enumeration, DNS brute force, or monitoring, then optionally probe hosts, capture screenshots, export results, or serve a web report. The CLI coordinates these modes; passive providers use shared HTTP and configuration support, while screenshots and report browsing form a distinct workflow. The README documents the broad mode flow; edges based on unsampled implementation are omitted or marked unverified.

Main entry points: [`subcat/subcat.py`](https://github.com/duty1g/subcat/blob/main/subcat/subcat.py) (CLI coordinator), [`subcat/screenshot.py`](https://github.com/duty1g/subcat/blob/main/subcat/screenshot.py) (Screenshot capture), [`subcat/passive.py`](https://github.com/duty1g/subcat/blob/main/subcat/passive.py) (Passive scan), [`subcat/modules`](https://github.com/duty1g/subcat/tree/main/subcat/modules) (Source modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_cli["CLI coordinator<br/>[subcat.py]"]
end

subgraph group_discovery["Discovery"]
  node_passive["Passive scan<br/>[passive.py]"]
  node_providers["Source modules"]
  node_brute["DNS brute force<br/>[bruteforce.py]"]
  node_monitor["Continuous monitor<br/>[monitor.py]"]
end

subgraph group_shared["Shared services"]
  node_config["API configuration<br/>[config.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_navigator["HTTP navigator<br/>[navigator.py]"]
  node_display["Terminal display<br/>[display.py]"]
  node_output["Result export<br/>[output.py]"]
end

subgraph group_triage["Host triage"]
  node_detector["Host detection<br/>[detector.py]"]
  node_screenshot["Screenshot capture<br/>[screenshot.py]"]
end

subgraph group_reporting["Reports"]
  node_scanfiles[("Scan files<br/>[screenshot.py]")]
  node_report["Report server<br/>[report.py]"]
  node_webui["Report interface<br/>[App.tsx]"]
  node_gallery["Screenshot gallery<br/>[Gallery.tsx]"]
  node_shotcard["Screenshot card<br/>[ShotCard.tsx]"]
  node_toolbar["Gallery filters<br/>[Toolbar.tsx]"]
  node_techicon["Technology icons<br/>[TechIcon.tsx]"]
end

node_user(("Operator"))

node_user -->|"runs mode"| node_cli
node_cli -->|"dispatches scan"| node_passive
node_cli -->|"dispatches scan"| node_brute
node_cli -->|"dispatches scan"| node_monitor
node_cli -->|"serves report"| node_report
node_passive -.->|"queries sources"| node_providers
node_providers -->|"sends requests"| node_navigator
node_providers -->|"reads keys"| node_config
node_passive -->|"uses cache"| node_cache
node_cli -->|"runs detection"| node_detector
node_cli -->|"captures hosts"| node_screenshot
node_screenshot -->|"browses hosts"| node_navigator
node_screenshot -->|"fingerprints pages"| node_detector
node_screenshot -->|"writes scan data"| node_scanfiles
node_report -->|"reads scan data"| node_scanfiles
node_cli -->|"exports results"| node_output
node_cli -.->|"updates progress"| node_display
node_webui -->|"renders gallery"| node_gallery
node_gallery -->|"renders shots"| node_shotcard
node_gallery -->|"renders filters"| node_toolbar
node_shotcard -->|"shows technologies"| node_techicon

click node_cli "https://github.com/duty1g/subcat/blob/main/subcat/subcat.py"
click node_passive "https://github.com/duty1g/subcat/blob/main/subcat/passive.py"
click node_providers "https://github.com/duty1g/subcat/tree/main/subcat/modules"
click node_brute "https://github.com/duty1g/subcat/blob/main/subcat/bruteforce.py"
click node_monitor "https://github.com/duty1g/subcat/blob/main/subcat/monitor.py"
click node_config "https://github.com/duty1g/subcat/blob/main/subcat/config.py"
click node_cache "https://github.com/duty1g/subcat/blob/main/subcat/cache.py"
click node_navigator "https://github.com/duty1g/subcat/blob/main/subcat/navigator.py"
click node_display "https://github.com/duty1g/subcat/blob/main/subcat/display.py"
click node_output "https://github.com/duty1g/subcat/blob/main/subcat/output.py"
click node_detector "https://github.com/duty1g/subcat/blob/main/subcat/detector.py"
click node_screenshot "https://github.com/duty1g/subcat/blob/main/subcat/screenshot.py"
click node_scanfiles "https://github.com/duty1g/subcat/blob/main/subcat/screenshot.py"
click node_report "https://github.com/duty1g/subcat/blob/main/subcat/report.py"
click node_webui "https://github.com/duty1g/subcat/blob/main/subcat/ui/App.tsx"
click node_gallery "https://github.com/duty1g/subcat/blob/main/subcat/ui/components/Gallery.tsx"
click node_shotcard "https://github.com/duty1g/subcat/blob/main/subcat/ui/components/ShotCard.tsx"
click node_toolbar "https://github.com/duty1g/subcat/blob/main/subcat/ui/components/Toolbar.tsx"
click node_techicon "https://github.com/duty1g/subcat/blob/main/subcat/ui/components/TechIcon.tsx"

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 toneBlue
class node_passive,node_providers,node_brute,node_monitor toneAmber
class node_config,node_cache,node_navigator,node_display,node_output toneMint
class node_detector,node_screenshot toneRose
class node_scanfiles,node_report,node_webui,node_gallery,node_shotcard,node_toolbar,node_techicon,node_user toneIndigo
```

## Components

### CLI workflow

- [CLI coordinator](https://github.com/duty1g/subcat/blob/main/subcat/subcat.py): `subcat/subcat.py`

### Discovery

- [Passive scan](https://github.com/duty1g/subcat/blob/main/subcat/passive.py): `subcat/passive.py`
- [Source modules](https://github.com/duty1g/subcat/tree/main/subcat/modules): `subcat/modules`
- [DNS brute force](https://github.com/duty1g/subcat/blob/main/subcat/bruteforce.py): `subcat/bruteforce.py`
- [Continuous monitor](https://github.com/duty1g/subcat/blob/main/subcat/monitor.py): `subcat/monitor.py`

### Shared services

- [API configuration](https://github.com/duty1g/subcat/blob/main/subcat/config.py): `subcat/config.py`
- [Response cache](https://github.com/duty1g/subcat/blob/main/subcat/cache.py): `subcat/cache.py`
- [HTTP navigator](https://github.com/duty1g/subcat/blob/main/subcat/navigator.py): `subcat/navigator.py`
- [Terminal display](https://github.com/duty1g/subcat/blob/main/subcat/display.py): `subcat/display.py`
- [Result export](https://github.com/duty1g/subcat/blob/main/subcat/output.py): `subcat/output.py`

### Host triage

- [Host detection](https://github.com/duty1g/subcat/blob/main/subcat/detector.py): `subcat/detector.py`
- [Screenshot capture](https://github.com/duty1g/subcat/blob/main/subcat/screenshot.py): `subcat/screenshot.py`

### Reports

- [Scan files](https://github.com/duty1g/subcat/blob/main/subcat/screenshot.py): `subcat/screenshot.py`
- [Report server](https://github.com/duty1g/subcat/blob/main/subcat/report.py): `subcat/report.py`
- [Report interface](https://github.com/duty1g/subcat/blob/main/subcat/ui/App.tsx): `subcat/ui/App.tsx`
- [Screenshot gallery](https://github.com/duty1g/subcat/blob/main/subcat/ui/components/Gallery.tsx): `subcat/ui/components/Gallery.tsx`
- [Screenshot card](https://github.com/duty1g/subcat/blob/main/subcat/ui/components/ShotCard.tsx): `subcat/ui/components/ShotCard.tsx`
- [Gallery filters](https://github.com/duty1g/subcat/blob/main/subcat/ui/components/Toolbar.tsx): `subcat/ui/components/Toolbar.tsx`
- [Technology icons](https://github.com/duty1g/subcat/blob/main/subcat/ui/components/TechIcon.tsx): `subcat/ui/components/TechIcon.tsx`

### Other components

- **Operator**

## Connections

- Operator → CLI coordinator: runs mode
- CLI coordinator → Passive scan: dispatches scan (evidence: `subcat/subcat.py`)
- CLI coordinator → DNS brute force: dispatches scan (evidence: `subcat/subcat.py`)
- CLI coordinator → Continuous monitor: dispatches scan (evidence: `subcat/subcat.py`)
- CLI coordinator → Report server: serves report (evidence: `subcat/subcat.py`)
- Passive scan → Source modules: queries sources
- Source modules → HTTP navigator: sends requests (evidence: `subcat/modules/alienvault.py`)
- Source modules → API configuration: reads keys (evidence: `subcat/modules/binaryedge.py`)
- Passive scan → Response cache: uses cache (evidence: `subcat/passive.py`)
- CLI coordinator → Host detection: runs detection (evidence: `subcat/subcat.py`)
- CLI coordinator → Screenshot capture: captures hosts (evidence: `subcat/subcat.py`)
- Screenshot capture → HTTP navigator: browses hosts (evidence: `subcat/screenshot.py`)
- Screenshot capture → Host detection: fingerprints pages (evidence: `subcat/screenshot.py`)
- Screenshot capture → Scan files: writes scan data (evidence: `subcat/screenshot.py`)
- Report server → Scan files: reads scan data (evidence: `subcat/report.py`)
- CLI coordinator → Result export: exports results (evidence: `subcat/subcat.py`)
- CLI coordinator → Terminal display: updates progress (evidence: `subcat/subcat.py`)
- Report interface → Screenshot gallery: renders gallery (evidence: `subcat/ui/App.tsx`)
- Screenshot gallery → Screenshot card: renders shots (evidence: `subcat/ui/components/Gallery.tsx`)
- Screenshot gallery → Gallery filters: renders filters (evidence: `subcat/ui/components/Gallery.tsx`)
- Screenshot card → Technology icons: shows technologies (evidence: `subcat/ui/components/ShotCard.tsx`)
