# moreyash007/nerofence architecture

> Architecture diagram of the GitHub repository moreyash007/nerofence, 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/moreyash007/nerofence
- Repository: https://github.com/moreyash007/nerofence

## Overview

NeuroFence is an air-gapped desktop scanner for detecting LLM weight poisoning and backdoors. An analyst selects a local model; the worker audits and safely loads it, records baseline activations, exercises adversarial prompts, and scores anomalies before returning a report to the desktop console. A separate static viewer reads exported reports locally and presents scores, flagged neurons, integrity findings, layer profiles, and activation heatmaps. The README documents these workflows; sampled source confirms key orchestration and viewer paths, while some subsystem wiring is documented rather than directly sampled.

Main entry points: [`worker.py`](https://github.com/moreyash007/nerofence/blob/main/worker.py) (Scan worker), [`neurofence-web/app/page.tsx`](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/app/page.tsx) (Viewer page), [`app.py`](https://github.com/moreyash007/nerofence/blob/main/app.py) (Desktop console), [`sandbox_tracker.py`](https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py) (Audit and loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scanning"]
  node_audit_load["Audit and loader<br/>[sandbox_tracker.py]"]
  node_hooks["MLP hook capture<br/>[sandbox_tracker.py]"]
  node_activation_store[("Activation statistics<br/>[sandbox_tracker.py]")]
  node_fuzzer["Prompt generation<br/>[fuzzer.py]"]
  node_detector["Anomaly scoring<br/>[detector.py]"]
end

subgraph group_desktop["Desktop console"]
  node_app["Desktop console<br/>[app.py]"]
  node_worker["Scan worker<br/>[worker.py]"]
  node_report_file["Exported report"]
end

subgraph group_reports["Report viewer"]
  node_web_page["Viewer page<br/>[page.tsx]"]
  node_dropzone["Report loader<br/>[DropZone.tsx]"]
  node_decode["Heatmap decoder<br/>[decode.ts]"]
  node_score_view["Score summaries<br/>[ScoreHero.tsx]"]
  node_anomaly_view["Neuron findings<br/>[AnomalyTable.tsx]"]
  node_integrity_view["Integrity findings<br/>[IntegrityList.tsx]"]
  node_layer_view["Layer profile<br/>[LayerProfile.tsx]"]
  node_heatmap_view["Activation heatmap<br/>[Heatmap.tsx]"]
  node_colormap["Heatmap scaling<br/>[colormap.ts]"]
end

subgraph group_simulation["Poison simulation"]
  node_mock["Backdoor simulator<br/>[mock_poison.py]"]
end

node_analyst(("Analyst"))
node_model_files[("Local model files")]
node_viewer_user(("Report reader"))

node_analyst -->|"selects model"| node_app
node_app -->|"starts scan"| node_worker
node_worker -->|"audits and loads"| node_audit_load
node_audit_load -->|"reads locally"| node_model_files
node_audit_load -->|"instruments model"| node_hooks
node_worker -->|"requests prompts"| node_fuzzer
node_worker -->|"runs prompts"| node_hooks
node_hooks -->|"records activations"| node_activation_store
node_worker -->|"reads statistics"| node_activation_store
node_worker -->|"scores phases"| node_detector
node_detector -->|"returns findings"| node_worker
node_worker -->|"sends results"| node_app
node_app -->|"exports JSON"| node_report_file
node_analyst -.->|"runs simulation"| node_mock
node_mock -.->|"creates poisoned model"| node_model_files
node_viewer_user -->|"opens viewer"| node_web_page
node_viewer_user -->|"selects report"| node_dropzone
node_dropzone -->|"returns report"| node_web_page
node_report_file -->|"loads locally"| node_dropzone
node_web_page -->|"decodes heatmap"| node_decode
node_web_page -->|"renders score"| node_score_view
node_web_page -->|"renders anomalies"| node_anomaly_view
node_web_page -->|"renders integrity"| node_integrity_view
node_web_page -->|"renders layers"| node_layer_view
node_web_page -->|"renders matrix"| node_heatmap_view
node_heatmap_view -->|"scales colors"| node_colormap

click node_app "https://github.com/moreyash007/nerofence/blob/main/app.py"
click node_worker "https://github.com/moreyash007/nerofence/blob/main/worker.py"
click node_audit_load "https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py"
click node_hooks "https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py"
click node_activation_store "https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py"
click node_fuzzer "https://github.com/moreyash007/nerofence/blob/main/fuzzer.py"
click node_detector "https://github.com/moreyash007/nerofence/blob/main/detector.py"
click node_mock "https://github.com/moreyash007/nerofence/blob/main/mock_poison.py"
click node_web_page "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/app/page.tsx"
click node_dropzone "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/DropZone.tsx"
click node_decode "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/lib/decode.ts"
click node_score_view "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/ScoreHero.tsx"
click node_anomaly_view "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/AnomalyTable.tsx"
click node_integrity_view "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/IntegrityList.tsx"
click node_layer_view "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/LayerProfile.tsx"
click node_heatmap_view "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/Heatmap.tsx"
click node_colormap "https://github.com/moreyash007/nerofence/blob/main/neurofence-web/lib/colormap.ts"

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_audit_load,node_hooks,node_activation_store,node_fuzzer,node_detector toneBlue
class node_app,node_worker,node_report_file,node_model_files toneAmber
class node_web_page,node_dropzone,node_decode,node_score_view,node_anomaly_view,node_integrity_view,node_layer_view,node_heatmap_view,node_colormap toneMint
class node_mock toneRose
class node_analyst,node_viewer_user toneIndigo
```

## Components

### Scanning

- [Audit and loader](https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py): `sandbox_tracker.py`
- [MLP hook capture](https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py): `sandbox_tracker.py`
- [Activation statistics](https://github.com/moreyash007/nerofence/blob/main/sandbox_tracker.py): `sandbox_tracker.py`
- [Prompt generation](https://github.com/moreyash007/nerofence/blob/main/fuzzer.py): `fuzzer.py`
- [Anomaly scoring](https://github.com/moreyash007/nerofence/blob/main/detector.py): `detector.py`

### Desktop console

- [Desktop console](https://github.com/moreyash007/nerofence/blob/main/app.py): `app.py`
- [Scan worker](https://github.com/moreyash007/nerofence/blob/main/worker.py): `worker.py`
- **Exported report**

### Report viewer

- [Viewer page](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/app/page.tsx): `neurofence-web/app/page.tsx`
- [Report loader](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/DropZone.tsx): `neurofence-web/components/DropZone.tsx`
- [Heatmap decoder](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/lib/decode.ts): `neurofence-web/lib/decode.ts`
- [Score summaries](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/ScoreHero.tsx): `neurofence-web/components/ScoreHero.tsx`
- [Neuron findings](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/AnomalyTable.tsx): `neurofence-web/components/AnomalyTable.tsx`
- [Integrity findings](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/IntegrityList.tsx): `neurofence-web/components/IntegrityList.tsx`
- [Layer profile](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/LayerProfile.tsx): `neurofence-web/components/LayerProfile.tsx`
- [Activation heatmap](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/components/Heatmap.tsx): `neurofence-web/components/Heatmap.tsx`
- [Heatmap scaling](https://github.com/moreyash007/nerofence/blob/main/neurofence-web/lib/colormap.ts): `neurofence-web/lib/colormap.ts`

### Poison simulation

- [Backdoor simulator](https://github.com/moreyash007/nerofence/blob/main/mock_poison.py): `mock_poison.py`

### Other components

- **Analyst**
- **Local model files**
- **Report reader**

## Connections

- Analyst → Desktop console: selects model
- Desktop console → Scan worker: starts scan
- Scan worker → Audit and loader: audits and loads
- Audit and loader → Local model files: reads locally
- Audit and loader → MLP hook capture: instruments model
- Scan worker → Prompt generation: requests prompts
- Scan worker → MLP hook capture: runs prompts
- MLP hook capture → Activation statistics: records activations
- Scan worker → Activation statistics: reads statistics
- Scan worker → Anomaly scoring: scores phases
- Anomaly scoring → Scan worker: returns findings
- Scan worker → Desktop console: sends results
- Desktop console → Exported report: exports JSON
- Analyst → Backdoor simulator: runs simulation
- Backdoor simulator → Local model files: creates poisoned model
- Report reader → Viewer page: opens viewer
- Report reader → Report loader: selects report
- Report loader → Viewer page: returns report
- Exported report → Report loader: loads locally
- Viewer page → Heatmap decoder: decodes heatmap
- Viewer page → Score summaries: renders score
- Viewer page → Neuron findings: renders anomalies
- Viewer page → Integrity findings: renders integrity
- Viewer page → Layer profile: renders layers
- Viewer page → Activation heatmap: renders matrix
- Activation heatmap → Heatmap scaling: scales colors