# kuray12/soc-tools-extention architecture

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

- Interactive diagram: https://gitdiagram.com/kuray12/soc-tools-extention
- Repository: https://github.com/kuray12/soc-tools-extention

## Overview

SOC·TOOLS is a Manifest V3 Chrome extension for IOC triage. Analysts enter one or many indicators in the popup, which identifies their type, gathers intelligence, and presents enrichment and pivot results; analysts can also launch enrichment from selected text or detected page indicators. The README documents MITRE mapping, geolocation, exports, notes, and false-positive tags. Source excerpts confirm popup fetching and storage, plus content-script highlighting and background message/context-menu handling; some feature wiring is documented but not visible in the sampled code.

Main entry points: [`js/popup.js`](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js) (Lookup Controller), [`js/content.js`](https://github.com/kuray12/soc-tools-extention/blob/main/js/content.js) (Page IOC Highlighter), [`js/background.js`](https://github.com/kuray12/soc-tools-extention/blob/main/js/background.js) (Background Worker), [`popup.html`](https://github.com/kuray12/soc-tools-extention/blob/main/popup.html) (Popup UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_triage["IOC Triage"]
  node_popup_ui["Popup UI<br/>[popup.html]"]
  node_popup_logic["Lookup Controller<br/>[popup.js]"]
  node_ioc_types["IOC Detection<br/>[popup.js]"]
  node_bulk["Bulk Lookup<br/>[popup.js]"]
end

subgraph group_intel["Enrichment"]
  node_intel_fetch["Source Fetchers<br/>[popup.js]"]
  node_virustotal{{"VirusTotal"}}
  node_abuseipdb{{"AbuseIPDB"}}
  node_shodan{{"Shodan"}}
  node_otx{{"AlienVault OTX"}}
  node_urlscan{{"URLScan.io"}}
  node_geo["Geo / Whois<br/>[popup.js]"]
  node_dns_pivot["DNS / Pivot<br/>[popup.js]"]
  node_dns_services{{"DNS Services"}}
  node_hackertarget{{"HackerTarget"}}
  node_mitre["MITRE Mapping<br/>[popup.js]"]
  node_results["Results View<br/>[popup.js]"]
end

subgraph group_analyst["Analyst Tools"]
  node_local_storage[("Local Storage")]
  node_notes_fp["Notes &amp; FP Tags<br/>[popup.js]"]
  node_export["CSV / JSON Export<br/>[popup.js]"]
end

subgraph group_extension["Extension Runtime"]
  node_content_script["Page IOC Highlighter<br/>[content.js]"]
  node_background["Background Worker<br/>[background.js]"]
end

node_analyst_user(("SOC Analyst"))
node_current_page["Web Page"]
node_chrome_context["Chrome Context Menu"]

node_analyst_user -->|"enters IOCs"| node_popup_ui
node_popup_ui -->|"submits lookup"| node_popup_logic
node_popup_logic -->|"detects type"| node_ioc_types
node_popup_logic -->|"requests enrichment"| node_intel_fetch
node_popup_logic -->|"runs batch"| node_bulk
node_bulk -->|"fetches each IOC"| node_intel_fetch
node_intel_fetch -->|"queries"| node_virustotal
node_intel_fetch -->|"queries"| node_abuseipdb
node_intel_fetch -->|"queries"| node_shodan
node_intel_fetch -->|"queries"| node_otx
node_intel_fetch -->|"queries"| node_urlscan
node_popup_logic -->|"looks up location"| node_geo
node_popup_logic -->|"loads pivots"| node_dns_pivot
node_dns_pivot -->|"queries records"| node_dns_services
node_dns_pivot -->|"queries reverse IP"| node_hackertarget
node_popup_logic -->|"maps intel"| node_mitre
node_popup_logic -->|"renders results"| node_results
node_analyst_user -->|"manages annotations"| node_notes_fp
node_notes_fp -->|"reads and writes"| node_local_storage
node_popup_logic -->|"loads API keys"| node_local_storage
node_popup_logic -->|"exports results"| node_export
node_analyst_user -->|"toggles highlight"| node_content_script
node_current_page -->|"provides page text"| node_content_script
node_content_script -->|"highlights IOCs"| node_current_page
node_content_script -->|"sends IOC message"| node_background
node_content_script -->|"stores pending IOC"| node_local_storage
node_analyst_user -->|"selects text"| node_chrome_context
node_chrome_context -->|"dispatches selection"| node_background
node_background -->|"stores pending IOC"| node_local_storage
node_background -->|"opens enrichment"| node_popup_ui
node_background -->|"forwards highlight toggle"| node_content_script

click node_popup_ui "https://github.com/kuray12/soc-tools-extention/blob/main/popup.html"
click node_popup_logic "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_ioc_types "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_bulk "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_intel_fetch "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_geo "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_dns_pivot "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_mitre "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_results "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_notes_fp "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_export "https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js"
click node_content_script "https://github.com/kuray12/soc-tools-extention/blob/main/js/content.js"
click node_background "https://github.com/kuray12/soc-tools-extention/blob/main/js/background.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_popup_ui,node_popup_logic,node_ioc_types,node_bulk toneBlue
class node_intel_fetch,node_virustotal,node_abuseipdb,node_shodan,node_otx,node_urlscan,node_geo,node_dns_pivot,node_dns_services,node_hackertarget,node_mitre,node_results toneAmber
class node_local_storage,node_notes_fp,node_export toneMint
class node_content_script,node_background toneRose
class node_analyst_user,node_current_page,node_chrome_context toneIndigo
```

## Components

### IOC Triage

- [Popup UI](https://github.com/kuray12/soc-tools-extention/blob/main/popup.html): `popup.html`
- [Lookup Controller](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- [IOC Detection](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- [Bulk Lookup](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`

### Enrichment

- [Source Fetchers](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- **VirusTotal**
- **AbuseIPDB**
- **Shodan**
- **AlienVault OTX**
- **URLScan.io**
- [Geo / Whois](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- [DNS / Pivot](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- **DNS Services**
- **HackerTarget**
- [MITRE Mapping](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- [Results View](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`

### Analyst Tools

- **Local Storage**
- [Notes & FP Tags](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`
- [CSV / JSON Export](https://github.com/kuray12/soc-tools-extention/blob/main/js/popup.js): `js/popup.js`

### Extension Runtime

- [Page IOC Highlighter](https://github.com/kuray12/soc-tools-extention/blob/main/js/content.js): `js/content.js`
- [Background Worker](https://github.com/kuray12/soc-tools-extention/blob/main/js/background.js): `js/background.js`

### Other components

- **SOC Analyst**
- **Web Page**
- **Chrome Context Menu**

## Connections

- SOC Analyst → Popup UI: enters IOCs
- Popup UI → Lookup Controller: submits lookup
- Lookup Controller → IOC Detection: detects type
- Lookup Controller → Source Fetchers: requests enrichment
- Lookup Controller → Bulk Lookup: runs batch
- Bulk Lookup → Source Fetchers: fetches each IOC
- Source Fetchers → VirusTotal: queries
- Source Fetchers → AbuseIPDB: queries
- Source Fetchers → Shodan: queries
- Source Fetchers → AlienVault OTX: queries
- Source Fetchers → URLScan.io: queries
- Lookup Controller → Geo / Whois: looks up location
- Lookup Controller → DNS / Pivot: loads pivots
- DNS / Pivot → DNS Services: queries records
- DNS / Pivot → HackerTarget: queries reverse IP
- Lookup Controller → MITRE Mapping: maps intel
- Lookup Controller → Results View: renders results
- SOC Analyst → Notes & FP Tags: manages annotations
- Notes & FP Tags → Local Storage: reads and writes
- Lookup Controller → Local Storage: loads API keys
- Lookup Controller → CSV / JSON Export: exports results
- SOC Analyst → Page IOC Highlighter: toggles highlight
- Web Page → Page IOC Highlighter: provides page text
- Page IOC Highlighter → Web Page: highlights IOCs
- Page IOC Highlighter → Background Worker: sends IOC message
- Page IOC Highlighter → Local Storage: stores pending IOC
- SOC Analyst → Chrome Context Menu: selects text
- Chrome Context Menu → Background Worker: dispatches selection
- Background Worker → Local Storage: stores pending IOC
- Background Worker → Popup UI: opens enrichment
- Background Worker → Page IOC Highlighter: forwards highlight toggle