# brooklynkray/in-the-dark architecture

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

- Interactive diagram: https://gitdiagram.com/brooklynkray/in-the-dark
- Repository: https://github.com/brooklynkray/in-the-dark

## Overview

In the Dark is a guided, terminal-based reconnaissance and enumeration tool for authorised security learning. The main workflow validates and enriches a target, gathers scan choices, previews the exact Nmap command for consent, runs it, parses and displays the result, saves a JSON record, and offers per-port next-step guidance. The graph includes the DNS and environment layers that support this flow. README capabilities such as notes, findings, and reporting are described as goals or later stages; no implementation paths for them appear in the supplied tree. Some orchestration details come from README documentation because main.py was sampled only in excerpts.

Main entry points: [`main.py`](https://github.com/brooklynkray/in-the-dark/blob/main/main.py) (CLI orchestrator), [`executor.py`](https://github.com/brooklynkray/in-the-dark/blob/main/executor.py) (Process execution), [`storage.py`](https://github.com/brooklynkray/in-the-dark/blob/main/storage.py) (Scan record writer), [`target.py`](https://github.com/brooklynkray/in-the-dark/blob/main/target.py) (Target validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Guided workflow"]
  node_main["CLI orchestrator<br/>[main.py]"]
  node_cli["Terminal presentation<br/>[cli.py]"]
  node_ports["Port validation<br/>[ports.py]"]
end

subgraph group_scan["Scan execution"]
  node_scan_config["Scan configuration<br/>[scan.py]"]
  node_executor["Process execution<br/>[executor.py]"]
end

subgraph group_results["Results and guidance"]
  node_xml_results["XML result parser<br/>[results.py]"]
  node_guidance["Service guidance<br/>[guidance.py]"]
  node_storage["Scan record writer<br/>[storage.py]"]
  node_result_files[("Saved scan JSON<br/>[storage.py]")]
end

subgraph group_support["Target and environment"]
  node_target["Target validation<br/>[target.py]"]
  node_dns["DNS enrichment<br/>[dns.py]"]
  node_environment["Environment checks<br/>[environment.py]"]
end

node_learner(("Learner"))
node_nmap["Nmap"]
node_sudo["Sudo"]
node_dns_service["System DNS"]

node_learner -->|"enters choices"| node_main
node_main -->|"validates target"| node_target
node_target -->|"enriches target"| node_dns
node_dns -->|"resolves names"| node_dns_service
node_main -->|"checks environment"| node_environment
node_main -->|"validates ports"| node_ports
node_main -->|"builds scan"| node_scan_config
node_main -->|"presents preview"| node_cli
node_main -->|"runs approved scan"| node_executor
node_executor -->|"executes argv"| node_nmap
node_executor -.->|"authenticates"| node_sudo
node_main -->|"parses XML"| node_xml_results
node_main -->|"requests guidance"| node_guidance
node_main -->|"saves scan record"| node_storage
node_storage -->|"writes JSON"| node_result_files
node_main -->|"displays results"| node_cli

click node_main "https://github.com/brooklynkray/in-the-dark/blob/main/main.py"
click node_cli "https://github.com/brooklynkray/in-the-dark/blob/main/cli.py"
click node_target "https://github.com/brooklynkray/in-the-dark/blob/main/target.py"
click node_dns "https://github.com/brooklynkray/in-the-dark/blob/main/dns.py"
click node_environment "https://github.com/brooklynkray/in-the-dark/blob/main/environment.py"
click node_ports "https://github.com/brooklynkray/in-the-dark/blob/main/ports.py"
click node_scan_config "https://github.com/brooklynkray/in-the-dark/blob/main/scan.py"
click node_executor "https://github.com/brooklynkray/in-the-dark/blob/main/executor.py"
click node_xml_results "https://github.com/brooklynkray/in-the-dark/blob/main/results.py"
click node_guidance "https://github.com/brooklynkray/in-the-dark/blob/main/guidance.py"
click node_storage "https://github.com/brooklynkray/in-the-dark/blob/main/storage.py"
click node_result_files "https://github.com/brooklynkray/in-the-dark/blob/main/storage.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,node_cli,node_ports toneBlue
class node_scan_config,node_executor toneAmber
class node_xml_results,node_guidance,node_storage,node_result_files toneMint
class node_target,node_dns,node_environment toneRose
class node_learner,node_nmap,node_sudo,node_dns_service toneIndigo
```

## Components

### Guided workflow

- [CLI orchestrator](https://github.com/brooklynkray/in-the-dark/blob/main/main.py): `main.py`
- [Terminal presentation](https://github.com/brooklynkray/in-the-dark/blob/main/cli.py): `cli.py`
- [Port validation](https://github.com/brooklynkray/in-the-dark/blob/main/ports.py): `ports.py`

### Scan execution

- [Scan configuration](https://github.com/brooklynkray/in-the-dark/blob/main/scan.py): `scan.py`
- [Process execution](https://github.com/brooklynkray/in-the-dark/blob/main/executor.py): `executor.py`

### Results and guidance

- [XML result parser](https://github.com/brooklynkray/in-the-dark/blob/main/results.py): `results.py`
- [Service guidance](https://github.com/brooklynkray/in-the-dark/blob/main/guidance.py): `guidance.py`
- [Scan record writer](https://github.com/brooklynkray/in-the-dark/blob/main/storage.py): `storage.py`
- [Saved scan JSON](https://github.com/brooklynkray/in-the-dark/blob/main/storage.py): `storage.py`

### Target and environment

- [Target validation](https://github.com/brooklynkray/in-the-dark/blob/main/target.py): `target.py`
- [DNS enrichment](https://github.com/brooklynkray/in-the-dark/blob/main/dns.py): `dns.py`
- [Environment checks](https://github.com/brooklynkray/in-the-dark/blob/main/environment.py): `environment.py`

### Other components

- **Learner**
- **Nmap**
- **Sudo**
- **System DNS**

## Connections

- Learner → CLI orchestrator: enters choices
- CLI orchestrator → Target validation: validates target
- Target validation → DNS enrichment: enriches target
- DNS enrichment → System DNS: resolves names
- CLI orchestrator → Environment checks: checks environment
- CLI orchestrator → Port validation: validates ports
- CLI orchestrator → Scan configuration: builds scan
- CLI orchestrator → Terminal presentation: presents preview
- CLI orchestrator → Process execution: runs approved scan
- Process execution → Nmap: executes argv
- Process execution → Sudo: authenticates
- CLI orchestrator → XML result parser: parses XML
- CLI orchestrator → Service guidance: requests guidance
- CLI orchestrator → Scan record writer: saves scan record
- Scan record writer → Saved scan JSON: writes JSON
- CLI orchestrator → Terminal presentation: displays results