# Neural Security Graph — Research & Tooling

## Product Context — SnS Secure Command Center (SCC)

The SCC is a **military/defense-grade security operations platform** with 5 modules:
- **Cyber Ops** — main dashboard: terminal CLI, network traffic, tactical map, encryption status, fleet overview, threat level
- **Network Monitor** — real-time traffic, segment topology, top talkers, protocol distribution, firewall rule hits, security alerts
- **Tactical Fleet** — vehicle tracking (armored transport, executive protection), GPS map, mission/fuel/maintenance status
- **Threat Intel** — global threat landscape, IOCs, CVE tracking, threat actors, campaign progress, intelligence feeds
- **Encrypted Vault** — classified document storage, key rotation, zero-trust data flow pipeline, access control, integrity monitoring

**Visual language**: terminal-green on black, monospace fonts, panel-based layout, real-time live data, military C2 aesthetic.

The **Neural Security Graph** is a proposed addition/layer — a live force-directed visualization where infrastructure nodes pulse like neurons when accessed, and the graph grows organically as new connections form.

---

## Key Open-Source Tooling

### 1. Graphify — Knowledge Graph Engine (graph data layer)

| | |
|---|---|
| **Repo** | https://github.com/Graphify-Labs/graphify |
| **What it does** | Turns code, configs, docs, and infra-as-code into a queryable knowledge graph (JSON) |
| **Install** | `uv tool install graphifyy` |
| **Relevant extras** | `graphifyy[mcp]` (MCP server), `graphifyy[terraform]` (HCL/Terraform extraction) |
| **License** | Open source (MIT) |
| **Key feature** | Local-first AST parsing via tree-sitter — code never leaves the machine |
| **Language** | Python |

**Role in SCC:** Builds the static graph structure from infra configs (nftables, netplan, cloud-init, docker-compose, Proxmox configs). This is the "brain anatomy" — the connections that exist. Queryable via MCP server or CLI.

**Useful commands:**
```bash
graphify extract ./infra/ --code-only          # local, no API needed
graphify query "what connects br0 to the internet"
graphify path "ws-nat" "wlp2s0"
graphify watch ./dotfiles                      # auto-rebuild on change
python -m graphify.serve graph.json --transport http --port 8080 --api-key "$SECRET"
```

---

### 2. Superfile — Terminal File Manager (TUI framework reference)

| | |
|---|---|
| **Repo** | https://github.com/yorukot/superfile |
| **Website** | https://superfile.dev |
| **What it does** | Modern, fancy terminal file manager with multi-panel layout |
| **Install** | `bash -c "$(curl -sLo- https://superfile.dev/install.sh)"` |
| **License** | MIT |
| **Language** | Go (built on [Bubble Tea](https://github.com/charmbracelet/bubbletea) TUI framework) |

**Features relevant to SCC:**
- **Multi-panel split view** — multiple directory panes side-by-side (maps to SCC's panel-based layout)
- **Keyboard-driven navigation** — vim-like keybindings (matches the terminal-operator UX of SCC)
- **20+ built-in themes** — Catppuccin, Nord, Tokyo Night, Dracula, Gruvbox (SCC uses its own dark/green military theme)
- **Plugin system** — extensible with git status, system monitoring, custom commands
- **Fuzzy search** — quick file/node lookup
- **Image preview** — inline terminal rendering
- **Bulk operations** — multi-select, batch actions
- **Customizable hotkeys** — every key remappable
- **Built on Bubble Tea** — the Go TUI framework (same tech could power a terminal-native SCC)

**Role in SCC:** Superfile's architecture is a **direct reference for building the Encrypted Vault module as a TUI**. Its multi-panel, theme-able, plugin-extensible design is exactly what an operator terminal for classified file management needs. The Bubble Tea framework underneath is the same one we'd use to build a terminal-native version of the full SCC dashboard.

**Specifically maps to SCC modules:**
| Superfile feature | SCC module it maps to |
|---|---|
| Multi-panel file browsing | Encrypted Vault (browse classified docs across panels) |
| Plugin system (git status, sys monitor) | Cyber Ops (live system vitals as plugins) |
| Theme engine (green-on-black) | All modules (military C2 aesthetic) |
| Fuzzy search | Network Monitor (search nodes/connections), Threat Intel (search IOCs) |
| Bulk operations | Fleet management (batch commands to vehicles) |
| Keyboard-driven | All modules (operator efficiency, no mouse needed) |

---

### 3. Bubble Tea — Go TUI Framework (the engine)

| | |
|---|---|
| **Repo** | https://github.com/charmbracelet/bubbletea |
| **What it does** | The Elm-architecture TUI framework that powers superfile |
| **Ecosystem** | [Lip Gloss](https://github.com/charmbracelet/lipgloss) (styling), [Bubbles](https://github.com/charmbracelet/bubbles) (components) |
| **License** | MIT |

If we build SCC as a terminal-native app (not browser), Bubble Tea + Lip Gloss is the stack. Gives us panels, borders, colors, responsive layouts, and keyboard handling — all in Go with no dependencies.

---

## Event Sources (the "nerve impulses")

| Source | What it catches | Tool/Command |
|--------|----------------|--------------|
| File access | Config reads/writes, vault document access | `inotifywait -m -r -e access,open,modify` |
| Network connections | New flows through NAT/firewall | `conntrack -E -e NEW` |
| SSH sessions | Remote access events | `journalctl -f -t sshd` |
| Service state | Start/stop/restart | `journalctl -f` filtered by unit |
| Security events | Sensitive file access | `auditd` with custom rules |
| Graph changes | New infra relationships | `graphify watch` / `graphify --watch` |
| Fleet telemetry | Vehicle GPS, speed, fuel | Custom feed (GPS tracker API) |
| Threat feeds | IOCs, CVEs, actor activity | OSINT feeds, honeypots, partner sharing |

---

## Visualization Approaches

### Option A — Browser-based (D3.js force graph + WebSocket)

Best for the **neural firing** effect. Rich animations, glow, particle trails along edges.

| Tool | Role | Link |
|------|------|------|
| D3.js (force layout) | Graph physics + rendering | https://github.com/d3/d3-force |
| WebSocket API | Real-time event push to browser | Native browser API |
| Graphify `graph.html` | Starting point (already force-directed) | Generated by `graphify extract` |

Extends Graphify's output with:
- WebSocket client receiving live events
- SVG glow/pulse animations on node activation (neuron firing)
- Edge particle animations (impulse traveling along connection)
- Dynamic node/edge insertion (graph grows organically)
- Decay: inactive nodes dim, active nodes brighten
- Fits into the SCC dashboard as an embedded panel (Network Monitor → Topology Map, or its own tab)

### Option B — Terminal-native (Bubble Tea / Go)

Same stack as superfile. Pure terminal, no browser. Fits the SCC aesthetic perfectly.

| Tool | Role | Link |
|------|------|------|
| Bubble Tea | TUI framework (event loop, components) | https://github.com/charmbracelet/bubbletea |
| Lip Gloss | Styling (green-on-black, borders, panels) | https://github.com/charmbracelet/lipgloss |
| Bubbles | Pre-built components (tables, spinners, viewports) | https://github.com/charmbracelet/bubbles |

Terminal approach caps at ~50-100 visible nodes but matches the operator terminal UX from the blueprints exactly. Could render a simplified topology map with ANSI color pulses.

### Option C — Hybrid (terminal panels + embedded browser graph)

The SCC shell is a terminal app (Bubble Tea) with panels for CLI, tables, status. The neural graph is a browser panel served locally (`localhost:8080`) or rendered via Sixel/Kitty graphics protocol for inline terminal display.

---

## Supporting Security Tools (complement the graph)

| Category | Tool | Link | Role in SCC |
|----------|------|------|-------------|
| HIDS/SIEM | Wazuh | https://github.com/wazuh/wazuh | Event source → feeds alerts to Cyber Ops + Threat Intel |
| Vulnerability scanning | Trivy | https://github.com/aquasecurity/trivy | Feeds Top Vulnerabilities in Threat Intel |
| Secret scanning | gitleaks | https://github.com/gitleaks/gitleaks | Vault integrity checks |
| Network IDS/IPS | Suricata | https://github.com/OISF/suricata | Feeds Network Monitor + security alerts |
| Log aggregation | Grafana Loki | https://github.com/grafana/loki | Backend for all activity logs |
| Uptime/health | Uptime Kuma | https://github.com/louislam/uptime-kuma | Node health status (already running on pve2) |
| Encryption | Age / SOPS | https://github.com/FiloSottile/age | Vault encryption layer |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                     SnS SECURE COMMAND CENTER                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  │
│  │  CYBER OPS  │  │   NETWORK    │  │  TACTICAL   │  │   THREAT     │  │
│  │  (main CLI  │  │   MONITOR    │  │   FLEET     │  │   INTEL      │  │
│  │  + status)  │  │  (topology)  │  │  (GPS map)  │  │  (IOC/CVE)   │  │
│  └──────┬──────┘  └──────┬───────┘  └──────┬──────┘  └──────┬───────┘  │
│         │                 │                  │                 │          │
│         └─────────────────┼──────────────────┼─────────────────┘         │
│                           │                  │                            │
│                    ┌──────▼──────────────────▼──────┐                    │
│                    │    NEURAL SECURITY GRAPH        │                    │
│                    │  (force-directed, live pulses)  │                    │
│                    │                                 │                    │
│                    │  Graphify (structure) ──────┐   │                    │
│                    │  Event feed (WebSocket) ────┤   │                    │
│                    │  D3.js / Bubble Tea (render)┘   │                    │
│                    └────────────────────────────────┘                    │
│                                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                      ENCRYPTED VAULT                                 │ │
│  │  (superfile-style TUI: multi-panel, classified docs, key rotation)  │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                                                           │
├─────────────────────────────────────────────────────────────────────────┤
│  EVENT SOURCES:  inotify · conntrack · auditd · journald · suricata     │
│  GRAPH ENGINE:   Graphify (graph.json) · MCP server · watch mode        │
│  TUI FRAMEWORK:  Bubble Tea + Lip Gloss (Go) — or browser (D3.js)      │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 7 Layers of Digital Security (reference)

1. **Physical Security** — hardware locks, encrypted drives, secure access
2. **Network Perimeter** — firewalls, VPN/mesh, NAT, DDoS mitigation
3. **Identity & Access Management** — SSO, MFA, least-privilege, scoped tokens
4. **Application Security** — input validation, parameterized queries, WAF
5. **Data Security** — encryption at rest/transit, tokenization, backup encryption
6. **Monitoring & Detection** — logs, SIEM, IDS, anomaly detection
7. **Recovery & Resilience** — tested backups, DR runbooks, incident response

The Neural Security Graph serves **Layer 6** but provides visibility into Layers 2–5 by mapping their configurations as queryable relationships. The Encrypted Vault covers **Layer 5**. Threat Intel feeds **Layers 2–4** with actionable intelligence.

---

## SCC Module → Open-Source Mapping

| SCC Module | Primary OSS Tool | Secondary |
|------------|-----------------|-----------|
| Cyber Ops (CLI dashboard) | Bubble Tea (TUI) | Graphify (status queries) |
| Network Monitor | Suricata + Graphify (topology) | D3.js (live graph) |
| Tactical Fleet | Custom (GPS feed) | Bubble Tea (TUI panels) |
| Threat Intel | Wazuh + OSINT feeds | Graphify (IOC relationships) |
| Encrypted Vault | Superfile (TUI file mgr pattern) + Age (encryption) | gitleaks (integrity) |
| Neural Graph (new) | Graphify + D3.js | inotify/conntrack (events) |

---

## Status

- [ ] Define scope: which SCC modules are being built vs. conceptual
- [ ] Decide: terminal-native (Bubble Tea/Go) vs. browser (D3/Electron) vs. hybrid
- [ ] Install Graphify and build initial graph from infra configs
- [ ] Prototype the neural firing visualization
- [ ] Map superfile's plugin architecture to Encrypted Vault module
- [ ] Integrate event sources (inotify, conntrack, auditd)
- [ ] Connect to real security tooling (Wazuh/Suricata as event feeders)

---

## Notes

*Waiting on Sam to define: what is this product? A real deployable tool for clients? An internal ops dashboard? A product you're selling? That determines build priority and tech choices.*
