# rapabru/terminal-ephemeral-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/rapabru/terminal-ephemeral-analyzer
- Repository: https://github.com/rapabru/terminal-ephemeral-analyzer

## Overview

Terminal Ephemeral Analyzer is a Windows process-monitoring and review tool focused on capturing short-lived processes without polling. Its workflow is Security Event Log capture, lifecycle pairing, risk scoring, secret redaction, persistence and alerting, followed by background signature/hash enrichment and dashboard review. The dashboard is static and offline; management CLIs update live-read configuration and whitelist files. Relationships reflect README documentation and sampled code; some monitor and dashboard internals were only partially excerpted, so uncertain wiring is omitted.

Main entry points: [`monitor.py`](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/monitor.py) (Lifecycle monitor), [`enrichment.py`](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/enrichment.py) (Enrichment worker), [`heuristics.py`](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/heuristics.py) (Risk heuristics), [`db.py`](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/db.py) (SQLite persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and scoring"]
  node_monitor["Lifecycle monitor<br/>[monitor.py]"]
  node_heuristics["Risk heuristics<br/>[heuristics.py]"]
  node_redact["Secret redaction<br/>[redact.py]"]
end

subgraph group_enrich["Enrichment and alerts"]
  node_enrichment["Enrichment worker<br/>[enrichment.py]"]
  node_vt_client["VirusTotal client<br/>[vt_client.py]"]
  node_alerts["Alert delivery<br/>[alerts.py]"]
end

subgraph group_state["Local state"]
  node_db[("SQLite persistence<br/>[db.py]")]
  node_config["Configuration<br/>[config.py]"]
  node_whitelist["Whitelist rules<br/>[whitelist.py]"]
end

subgraph group_review["Review and management"]
  node_config_manage["Config manager<br/>[config_manage.py]"]
  node_whitelist_manage["Whitelist manager"]
  node_dashboard["Static dashboard<br/>[dashboard.py]"]
end

subgraph group_integrations["System integrations"]
  node_windows_events["Windows Security Events"]
  node_codesign["Signature verification<br/>[codesign.py]"]
  node_powershell["PowerShell"]
  node_virustotal["VirusTotal API"]
  node_windows_alerts["Windows notifications and Event Log"]
end

node_operator(("Operator"))
node_browser(("Browser"))

node_windows_events -->|"pushes events"| node_monitor
node_monitor -->|"classifies processes"| node_whitelist
node_monitor -->|"reads settings"| node_config
node_monitor -->|"scores events"| node_heuristics
node_heuristics -->|"reads thresholds"| node_config
node_heuristics -->|"checks activity"| node_db
node_heuristics -->|"checks signature"| node_codesign
node_codesign -->|"runs verification"| node_powershell
node_monitor -->|"redacts for storage"| node_redact
node_monitor -->|"stores events"| node_db
node_monitor -->|"triggers alerts"| node_alerts
node_monitor -->|"queues event"| node_enrichment
node_enrichment -->|"checks signature"| node_heuristics
node_enrichment -->|"reads settings"| node_config
node_enrichment -->|"requests lookup"| node_vt_client
node_vt_client -->|"reads and writes cache"| node_db
node_vt_client -.->|"queries hash"| node_virustotal
node_enrichment -->|"updates verdict"| node_db
node_enrichment -->|"alerts on escalation"| node_alerts
node_alerts -->|"notifies and logs"| node_windows_alerts
node_dashboard -->|"reads events"| node_db
node_dashboard -->|"labels LOLBins"| node_heuristics
node_operator -->|"runs monitor"| node_monitor
node_operator -->|"manages settings"| node_config_manage
node_config_manage -->|"updates settings"| node_config
node_operator -->|"manages whitelist"| node_whitelist_manage
node_whitelist_manage -->|"updates rules"| node_whitelist
node_operator -->|"generates dashboard"| node_dashboard
node_dashboard -->|"opens report"| node_browser

click node_monitor "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/monitor.py"
click node_heuristics "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/heuristics.py"
click node_redact "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/redact.py"
click node_enrichment "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/enrichment.py"
click node_codesign "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/codesign.py"
click node_vt_client "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/vt_client.py"
click node_alerts "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/alerts.py"
click node_db "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/db.py"
click node_config "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/config.py"
click node_config_manage "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/config_manage.py"
click node_whitelist "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/whitelist.py"
click node_whitelist_manage "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/whitelist_manage.py"
click node_dashboard "https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/dashboard.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_monitor,node_heuristics,node_redact,node_browser toneBlue
class node_enrichment,node_vt_client,node_alerts toneAmber
class node_db,node_config,node_whitelist toneMint
class node_config_manage,node_whitelist_manage,node_dashboard toneRose
class node_windows_events,node_codesign,node_powershell,node_virustotal,node_windows_alerts,node_operator toneIndigo
```

## Components

### Capture and scoring

- [Lifecycle monitor](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/monitor.py): `monitor.py`
- [Risk heuristics](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/heuristics.py): `heuristics.py`
- [Secret redaction](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/redact.py): `redact.py`

### Enrichment and alerts

- [Enrichment worker](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/enrichment.py): `enrichment.py`
- [VirusTotal client](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/vt_client.py): `vt_client.py`
- [Alert delivery](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/alerts.py): `alerts.py`

### Local state

- [SQLite persistence](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/db.py): `db.py`
- [Configuration](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/config.py): `config.py`
- [Whitelist rules](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/whitelist.py): `whitelist.py`

### Review and management

- [Config manager](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/config_manage.py): `config_manage.py`
- [Whitelist manager](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/whitelist_manage.py): `whitelist_manage.py`
- [Static dashboard](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/dashboard.py): `dashboard.py`

### System integrations

- **Windows Security Events**
- [Signature verification](https://github.com/rapabru/terminal-ephemeral-analyzer/blob/master/codesign.py): `codesign.py`
- **PowerShell**
- **VirusTotal API**
- **Windows notifications and Event Log**

### Other components

- **Operator**
- **Browser**

## Connections

- Windows Security Events → Lifecycle monitor: pushes events
- Lifecycle monitor → Whitelist rules: classifies processes
- Lifecycle monitor → Configuration: reads settings
- Lifecycle monitor → Risk heuristics: scores events
- Risk heuristics → Configuration: reads thresholds
- Risk heuristics → SQLite persistence: checks activity
- Risk heuristics → Signature verification: checks signature
- Signature verification → PowerShell: runs verification
- Lifecycle monitor → Secret redaction: redacts for storage
- Lifecycle monitor → SQLite persistence: stores events
- Lifecycle monitor → Alert delivery: triggers alerts
- Lifecycle monitor → Enrichment worker: queues event
- Enrichment worker → Risk heuristics: checks signature
- Enrichment worker → Configuration: reads settings
- Enrichment worker → VirusTotal client: requests lookup
- VirusTotal client → SQLite persistence: reads and writes cache
- VirusTotal client → VirusTotal API: queries hash
- Enrichment worker → SQLite persistence: updates verdict
- Enrichment worker → Alert delivery: alerts on escalation
- Alert delivery → Windows notifications and Event Log: notifies and logs
- Static dashboard → SQLite persistence: reads events
- Static dashboard → Risk heuristics: labels LOLBins
- Operator → Lifecycle monitor: runs monitor
- Operator → Config manager: manages settings
- Config manager → Configuration: updates settings
- Operator → Whitelist manager: manages whitelist
- Whitelist manager → Whitelist rules: updates rules
- Operator → Static dashboard: generates dashboard
- Static dashboard → Browser: opens report