# samfrieman/c2-beacon-detector architecture

> Architecture diagram of the GitHub repository samfrieman/c2-beacon-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samfrieman/c2-beacon-detector
- Repository: https://github.com/samfrieman/c2-beacon-detector

## Overview

C2 Beacon Detector is a browser-based tool for analyzing network-connection JSON and identifying possible command-and-control beaconing. The user submits a file or sample; the app validates the data, extracts behavioral features, checks threat intelligence, and produces scored findings for display and export. Historical analyses and custom rules are stored locally, while ThreatFox lookups use an external service. The README documents the analysis stages; sampled code confirms selected initialization, validation, and lookup relationships. Other runtime wiring is not shown, so those links are omitted.

Main entry points: [`js/app.js`](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/app.js) (App controller), [`js/analyzer.js`](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/analyzer.js) (Behavioral analyzer), [`js/detector.js`](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/detector.js) (Scoring engine), [`js/threat-intel.js`](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/threat-intel.js) (Threat intelligence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Input &amp; Workflow"]
  node_app["App controller<br/>[app.js]"]
  node_utils["Validation &amp; utilities<br/>[utils.js]"]
end

subgraph group_analysis["Detection Analysis"]
  node_analyzer["Behavioral analyzer<br/>[analyzer.js]"]
  node_detector["Scoring engine<br/>[detector.js]"]
end

subgraph group_enrichment["Intel &amp; Learning"]
  node_threat["Threat intelligence<br/>[threat-intel.js]"]
  node_ml["ML detector<br/>[ml-detector.js]"]
end

subgraph group_results["Results &amp; History"]
  node_ui["Results UI<br/>[ui.js]"]
  node_reports["Report generator"]
  node_history["Analysis history<br/>[history-manager.js]"]
end

node_user(("Security analyst"))
node_threatfox["ThreatFox API"]
node_localstorage[("Browser local storage")]

node_user -->|"submits traffic"| node_app
node_app -->|"validates JSON"| node_utils
node_app -->|"coordinates analysis"| node_analyzer
node_analyzer -->|"uses statistics"| node_utils
node_analyzer -->|"provides features"| node_detector
node_detector -->|"looks up IPs"| node_threat
node_app -->|"initializes"| node_threat
node_threat -->|"queries IOCs"| node_threatfox
node_app -->|"initializes"| node_ml
node_detector -.->|"combines predictions"| node_ml
node_app -->|"initializes history"| node_history
node_history -->|"reads and writes"| node_localstorage
node_app -->|"coordinates rendering"| node_ui
node_app -.->|"coordinates export"| node_reports

click node_app "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/app.js"
click node_utils "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/utils.js"
click node_analyzer "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/analyzer.js"
click node_detector "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/detector.js"
click node_threat "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/threat-intel.js"
click node_ml "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/ml-detector.js"
click node_ui "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/ui.js"
click node_reports "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/report-generator.js"
click node_history "https://github.com/samfrieman/c2-beacon-detector/blob/main/js/history-manager.js"

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_app,node_utils toneBlue
class node_analyzer,node_detector,node_localstorage toneAmber
class node_threat,node_ml,node_threatfox toneMint
class node_ui,node_reports,node_history toneRose
class node_user toneIndigo
```

## Components

### Input & Workflow

- [App controller](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/app.js): `js/app.js`
- [Validation & utilities](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/utils.js): `js/utils.js`

### Detection Analysis

- [Behavioral analyzer](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/analyzer.js): `js/analyzer.js`
- [Scoring engine](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/detector.js): `js/detector.js`

### Intel & Learning

- [Threat intelligence](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/threat-intel.js): `js/threat-intel.js`
- [ML detector](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/ml-detector.js): `js/ml-detector.js`

### Results & History

- [Results UI](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/ui.js): `js/ui.js`
- [Report generator](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/report-generator.js): `js/report-generator.js`
- [Analysis history](https://github.com/samfrieman/c2-beacon-detector/blob/main/js/history-manager.js): `js/history-manager.js`

### Other components

- **Security analyst**
- **ThreatFox API**
- **Browser local storage**

## Connections

- Security analyst → App controller: submits traffic (evidence: `README.md`)
- App controller → Validation & utilities: validates JSON (evidence: `js/app.js`)
- App controller → Behavioral analyzer: coordinates analysis (evidence: `README.md`)
- Behavioral analyzer → Validation & utilities: uses statistics (evidence: `js/analyzer.js`)
- Behavioral analyzer → Scoring engine: provides features (evidence: `README.md`)
- Scoring engine → Threat intelligence: looks up IPs (evidence: `js/detector.js`)
- App controller → Threat intelligence: initializes (evidence: `js/app.js`)
- Threat intelligence → ThreatFox API: queries IOCs (evidence: `js/threat-intel.js`)
- App controller → ML detector: initializes (evidence: `js/app.js`)
- Scoring engine → ML detector: combines predictions
- App controller → Analysis history: initializes history (evidence: `js/app.js`)
- Analysis history → Browser local storage: reads and writes (evidence: `js/history-manager.js`)
- App controller → Results UI: coordinates rendering (evidence: `README.md`)
- App controller → Report generator: coordinates export
