# justin-io/q-safe architecture

> Architecture diagram of the GitHub repository justin-io/q-safe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justin-io/q-safe
- Repository: https://github.com/justin-io/q-safe

## Overview

1. This repository is a hybrid security-scan proof of concept centered on a native “sentinel” binary and a Python triage agent. The main architecture is a two-stage pipeline: a low-level scanning/enforcement core, and a higher-level path-based decision layer.

2. The primary runtime entry point is the assembly-led `guardian.asm`, which is compiled into the `guardian` executable. This core is responsible for filesystem discovery, reading file contents, checking basic CPU/register integrity, and performing file deletion when a target is deemed malicious. The compiled object files in the tree (`deep_core.o`, `qsafe_driver.o`, `qsafe_monitor.o`) suggest the low-level logic is split across assembly/C build units rather than living in one script.

3. `agent_triage.py` is the main intelligence layer. It does not inspect file bytes directly; instead, it consumes a large list of discovered files, collapses them into directory-level “zones,” and chooses which folders are suspicious enough to inspect further. Its key boundary is that it turns a noisy global file inventory into a small target set for the native scanner.

4. The architecture includes an optional cloud-AI decision service through OpenRouter. The README names two model roles: one for triage and one for deeper analysis. This means the Python layer can either use remote semantic scoring or fall back to local heuristics when the API is unavailable, so the triage subsystem has both online and offline paths.

5. The central data flow is: filesystem discovery list -> folder clustering/triage -> suspicious target list -> deep content scan -> optional deletion. In the file tree, artifacts like `folder_list.txt`, `target_scan_list.txt`, `sus_folders.txt`, `allowlist.bin`, `triage_req.json`, and `llm_response.txt` look like the intermediate inputs/outputs that move between those stages.

6. `dashboard.py` and `start_ui.sh` appear to provide a presentation layer over the scanning pipeline. They are not the core enforcement path; rather, they likely visualize scan state, triage results, or request/response artifacts for the operator. That makes them a thin UI boundary on top of the scan engine.

7. The repo also contains a set of demo payloads and targets used to exercise the system’s detection logic: `attack.txt`, `innocent_script.py`, `protected_app.c`, `protected_app`, `payload.elf`, `rootkit_installer.sh`, `kernel_hook.asm`, and `qsafe_demo`. These look like test corpus and adversarial examples rather than production components, and they likely feed the sentinel’s “suspicious vs safe” classification path.

8. Build and orchestration are handled by `Makefile`, `run.sh`, and the dependency stack called out in the README: `nasm`, `gcc`, `python3`, and `curl`. The assembly binary is compiled natively, while the Python agent and any cloud calls are handled separately, reinforcing the split between enforcement and reasoning.

9. The important architectural boundary is between local authority and remote intelligence. Local code in the native core can enumerate, inspect, and delete files directly on the host, while the Python/LLM layer only influences which paths are selected for deeper inspection. That separation is what an architecture diagram should emphasize: native filesystem/control plane at the bottom, agentic triage in the middle, and optional cloud inference on the side.

Main entry points: [`guardian.asm`](https://github.com/justin-io/q-safe/blob/main/guardian.asm) (Guardian), [`agent_triage.py`](https://github.com/justin-io/q-safe/blob/main/agent_triage.py) (Triage agent), [`run.sh`](https://github.com/justin-io/q-safe/blob/main/run.sh) (Run script), [`neural_oracle.py`](https://github.com/justin-io/q-safe/blob/main/neural_oracle.py) (Oracle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_native["Native sentinel"]
  node_n_guardian["Guardian<br/>assembly sentinel<br/>[guardian.asm]"]
  node_n_deep_core["Deep core<br/>native object<br/>[deep_core.o]"]
  node_n_qsafe_driver["Driver<br/>native object<br/>[qsafe_driver.o]"]
  node_n_qsafe_monitor["Monitor<br/>assembly module<br/>[qsafe_monitor.o]"]
end

subgraph group_grp_triage["Triage agent"]
  node_n_triage["Triage agent<br/>python decision<br/>[agent_triage.py]"]
  node_n_oracle["Oracle<br/>llm adapter<br/>[neural_oracle.py]"]
end

subgraph group_grp_ui["Operator UI"]
  node_n_dashboard["Dashboard<br/>python ui<br/>[dashboard.py]"]
  node_n_start_ui["UI launcher<br/>shell entry<br/>[start_ui.sh]"]
  node_n_run["Run script<br/>shell orchestrator<br/>[run.sh]"]
end

subgraph group_grp_demo["Demo corpus"]
  node_n_attack["Attack sample<br/>payload sample<br/>[attack.txt]"]
  node_n_innocent["Innocent sample<br/>benign sample<br/>[innocent_script.py]"]
  node_n_protected_c["Protected app<br/>demo target<br/>[protected_app.c]"]
  node_n_protected_bin["App binary<br/>demo binary"]
  node_n_payload["Payload ELF<br/>adversarial binary<br/>[payload.elf]"]
  node_n_rootkit["Installer<br/>malicious script"]
  node_n_hook["Hook sample<br/>asm payload<br/>[kernel_hook.asm]"]
  node_n_demo["Demo bundle<br/>demo executable"]
end

subgraph group_grp_artifacts["Pipeline artifacts"]
  node_n_folder_list["Folder list<br/>inventory artifact<br/>[folder_list.txt]"]
  node_n_target_list["Targets<br/>scan artifact"]
  node_n_sus_folders["Suspicious set<br/>triage artifact<br/>[sus_folders.txt]"]
  node_n_allowlist[("Allowlist<br/>policy artifact<br/>[allowlist.bin]")]
  node_n_triage_req["Triage request<br/>llm request<br/>[triage_req.json]"]
  node_n_llm_resp["LLM response<br/>llm result<br/>[llm_response.txt]"]
end

node_n_folder_list -->|"inventory"| node_n_triage
node_n_triage -->|"cluster"| node_n_sus_folders
node_n_triage -->|"select"| node_n_target_list
node_n_allowlist -.->|"suppress"| node_n_triage
node_n_triage -->|"compose"| node_n_triage_req
node_n_triage_req -.->|"request"| node_n_oracle
node_n_oracle -.->|"respond"| node_n_llm_resp
node_n_llm_resp -.->|"rank"| node_n_triage
node_n_target_list -->|"scan"| node_n_guardian
node_n_guardian -->|"uses"| node_n_deep_core
node_n_guardian -->|"coordinates"| node_n_qsafe_driver
node_n_guardian -->|"checks"| node_n_qsafe_monitor
node_n_guardian -.->|"inspects"| node_n_attack
node_n_guardian -.->|"inspects"| node_n_innocent
node_n_guardian -.->|"evaluates"| node_n_protected_c
node_n_guardian -.->|"evaluates"| node_n_protected_bin
node_n_guardian -.->|"detects"| node_n_payload
node_n_guardian -.->|"detects"| node_n_rootkit
node_n_guardian -.->|"detects"| node_n_hook
node_n_guardian -.->|"evaluates"| node_n_demo
node_n_guardian -->|"reports"| node_n_dashboard
node_n_dashboard -->|"launched by"| node_n_start_ui
node_n_run -->|"orchestrates"| node_n_guardian
node_n_run -->|"orchestrates"| node_n_triage

click node_n_guardian "https://github.com/justin-io/q-safe/blob/main/guardian.asm"
click node_n_deep_core "https://github.com/justin-io/q-safe/blob/main/deep_core.o"
click node_n_qsafe_driver "https://github.com/justin-io/q-safe/blob/main/qsafe_driver.o"
click node_n_qsafe_monitor "https://github.com/justin-io/q-safe/blob/main/qsafe_monitor.o"
click node_n_triage "https://github.com/justin-io/q-safe/blob/main/agent_triage.py"
click node_n_oracle "https://github.com/justin-io/q-safe/blob/main/neural_oracle.py"
click node_n_dashboard "https://github.com/justin-io/q-safe/blob/main/dashboard.py"
click node_n_start_ui "https://github.com/justin-io/q-safe/blob/main/start_ui.sh"
click node_n_run "https://github.com/justin-io/q-safe/blob/main/run.sh"
click node_n_folder_list "https://github.com/justin-io/q-safe/blob/main/folder_list.txt"
click node_n_target_list "https://github.com/justin-io/q-safe/blob/main/target_scan_list.txt"
click node_n_sus_folders "https://github.com/justin-io/q-safe/blob/main/sus_folders.txt"
click node_n_allowlist "https://github.com/justin-io/q-safe/blob/main/allowlist.bin"
click node_n_triage_req "https://github.com/justin-io/q-safe/blob/main/triage_req.json"
click node_n_llm_resp "https://github.com/justin-io/q-safe/blob/main/llm_response.txt"
click node_n_attack "https://github.com/justin-io/q-safe/blob/main/attack.txt"
click node_n_innocent "https://github.com/justin-io/q-safe/blob/main/innocent_script.py"
click node_n_protected_c "https://github.com/justin-io/q-safe/blob/main/protected_app.c"
click node_n_protected_bin "https://github.com/justin-io/q-safe/tree/main/protected_app"
click node_n_payload "https://github.com/justin-io/q-safe/blob/main/payload.elf"
click node_n_rootkit "https://github.com/justin-io/q-safe/blob/main/rootkit_installer.sh"
click node_n_hook "https://github.com/justin-io/q-safe/blob/main/kernel_hook.asm"
click node_n_demo "https://github.com/justin-io/q-safe/tree/main/qsafe_demo"

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_n_guardian,node_n_deep_core,node_n_qsafe_driver,node_n_qsafe_monitor toneBlue
class node_n_triage,node_n_oracle toneAmber
class node_n_dashboard,node_n_start_ui,node_n_run toneMint
class node_n_attack,node_n_innocent,node_n_protected_c,node_n_protected_bin,node_n_payload,node_n_rootkit,node_n_hook,node_n_demo toneRose
class node_n_folder_list,node_n_target_list,node_n_sus_folders,node_n_allowlist,node_n_triage_req,node_n_llm_resp toneIndigo
```

## Components

### Native sentinel

Assembly/C enforcement core that scans, validates, and can remove malicious targets.

- [Guardian](https://github.com/justin-io/q-safe/blob/main/guardian.asm): assembly sentinel · Primary low-level executable; performs discovery, content checks, integrity checks, and deletion. · `guardian.asm`
- [Deep core](https://github.com/justin-io/q-safe/blob/main/deep_core.o): native object · Compiled low-level logic supporting the sentinel pipeline. · `deep_core.o`
- [Driver](https://github.com/justin-io/q-safe/blob/main/qsafe_driver.o): native object · Compiled driver unit for the native scanning path. · `qsafe_driver.o`
- [Monitor](https://github.com/justin-io/q-safe/blob/main/qsafe_monitor.o): assembly module · Monitoring logic compiled into the native enforcement stack. · `qsafe_monitor.o`

### Triage agent

Python decision layer that clusters discovered files and selects suspicious paths.

- [Triage agent](https://github.com/justin-io/q-safe/blob/main/agent_triage.py): python decision · Consumes file inventories, clusters them into zones, and selects suspicious folders. · `agent_triage.py`
- [Oracle](https://github.com/justin-io/q-safe/blob/main/neural_oracle.py): llm adapter · Optional cloud-backed semantic scoring and analysis layer for triage. · `neural_oracle.py`

### Operator UI

Presentation and launch layer for observing pipeline state.

- [Dashboard](https://github.com/justin-io/q-safe/blob/main/dashboard.py): python ui · Operator-facing view over scan and triage state. · `dashboard.py`
- [UI launcher](https://github.com/justin-io/q-safe/blob/main/start_ui.sh): shell entry · Starts the presentation layer for the scanning pipeline. · `start_ui.sh`
- [Run script](https://github.com/justin-io/q-safe/blob/main/run.sh): shell orchestrator · Convenience entry for executing the repo workflow. · `run.sh`

### Demo corpus

Sample targets and adversarial payloads used to exercise detection logic.

- [Attack sample](https://github.com/justin-io/q-safe/blob/main/attack.txt): payload sample · Example malicious-looking input used to exercise detection. · `attack.txt`
- [Innocent sample](https://github.com/justin-io/q-safe/blob/main/innocent_script.py): benign sample · Benign script used to contrast with suspicious payloads. · `innocent_script.py`
- [Protected app](https://github.com/justin-io/q-safe/blob/main/protected_app.c): demo target · C source sample representing a protected or monitored program. · `protected_app.c`
- [App binary](https://github.com/justin-io/q-safe/tree/main/protected_app): demo binary · Compiled protected application sample. · `protected_app`
- [Payload ELF](https://github.com/justin-io/q-safe/blob/main/payload.elf): adversarial binary · Executable payload sample for the sentinel to classify. · `payload.elf`
- [Installer](https://github.com/justin-io/q-safe/blob/main/rootkit_installer.sh): malicious script · Shell payload representing an installation or persistence attempt. · `rootkit_installer.sh`
- [Hook sample](https://github.com/justin-io/q-safe/blob/main/kernel_hook.asm): asm payload · Assembly sample illustrating kernel-hook style behavior. · `kernel_hook.asm`
- [Demo bundle](https://github.com/justin-io/q-safe/tree/main/qsafe_demo): demo executable · Bundled demonstration target used to exercise the system. · `qsafe_demo`

### Pipeline artifacts

Intermediate files exchanged between discovery, triage, and scan stages.

- [Folder list](https://github.com/justin-io/q-safe/blob/main/folder_list.txt): inventory artifact · Discovered filesystem listing used as triage input. · `folder_list.txt`
- [Targets](https://github.com/justin-io/q-safe/blob/main/target_scan_list.txt): scan artifact · Selected paths forwarded to deeper inspection. · `target_scan_list.txt`
- [Suspicious set](https://github.com/justin-io/q-safe/blob/main/sus_folders.txt): triage artifact · Folders marked suspicious by the decision layer. · `sus_folders.txt`
- [Allowlist](https://github.com/justin-io/q-safe/blob/main/allowlist.bin): policy artifact · Known-safe entries used to suppress false positives. · `allowlist.bin`
- [Triage request](https://github.com/justin-io/q-safe/blob/main/triage_req.json): llm request · Structured prompt or request sent to the optional oracle. · `triage_req.json`
- [LLM response](https://github.com/justin-io/q-safe/blob/main/llm_response.txt): llm result · Returned scoring or analysis from the remote decision path. · `llm_response.txt`

## Connections

- Folder list → Triage agent: inventory · Filesystem discovery list feeds the triage agent.
- Triage agent → Suspicious set: cluster · Agent groups files into suspicious folder zones.
- Triage agent → Targets: select · Suspicious zones are collapsed into a target scan list.
- Allowlist → Triage agent: suppress · Known-safe entries reduce unnecessary escalation.
- Triage agent → Triage request: compose · Local or remote triage inputs are packaged for semantic scoring.
- Triage request → Oracle: request · Optional cloud path sends structured triage requests.
- Oracle → LLM response: respond · Remote analysis returns scored decisions or rationale.
- LLM response → Triage agent: rank · LLM output influences which paths are selected next.
- Targets → Guardian: scan · Selected targets are handed to the native sentinel.
- Guardian → Deep core: uses · Core executable delegates low-level scan logic.
- Guardian → Driver: coordinates · Driver unit participates in native enforcement flow.
- Guardian → Monitor: checks · Monitoring module supports integrity and runtime checks.
- Guardian → Attack sample: inspects · Representative malicious sample exercises the scan path.
- Guardian → Innocent sample: inspects · Benign sample contrasts against malicious inputs.
- Guardian → Protected app: evaluates · Source sample represents protected content in the corpus.
- Guardian → App binary: evaluates · Compiled protected app is a monitored target type.
- Guardian → Payload ELF: detects · Executable payload sample can be flagged and removed.
- Guardian → Installer: detects · Installer script models a malicious action path.
- Guardian → Hook sample: detects · Assembly hook sample exercises deeper content checks.
- Guardian → Demo bundle: evaluates · Bundled demo executable is part of the test corpus.
- Guardian → Dashboard: reports · Scan outcomes are surfaced to the operator UI.
- Dashboard → UI launcher: launched by · UI is started through the shell launcher.
- Run script → Guardian: orchestrates · Run script ties together the repo workflow and native core.
- Run script → Triage agent: orchestrates · Run script also invokes the Python triage stage.