How justin-io/q-safe works
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 Guardian · agent_triage.py Triage agent · run.sh Run script · neural_oracle.py Oracle
Components 23
Native sentinel
Assembly/C enforcement core that scans, validates, and can remove malicious targets.
- Guardian · Primary low-level executable; performs discovery, content checks, integrity checks, and deletion.
guardian.asm - Deep core · Compiled low-level logic supporting the sentinel pipeline.
deep_core.o - Driver · Compiled driver unit for the native scanning path.
qsafe_driver.o - Monitor · 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 · Consumes file inventories, clusters them into zones, and selects suspicious folders.
agent_triage.py - Oracle · Optional cloud-backed semantic scoring and analysis layer for triage.
neural_oracle.py
Operator UI
Presentation and launch layer for observing pipeline state.
- Dashboard · Operator-facing view over scan and triage state.
dashboard.py - UI launcher · Starts the presentation layer for the scanning pipeline.
start_ui.sh - Run script · Convenience entry for executing the repo workflow.
run.sh
Demo corpus
Sample targets and adversarial payloads used to exercise detection logic.
- Attack sample · Example malicious-looking input used to exercise detection.
attack.txt - Innocent sample · Benign script used to contrast with suspicious payloads.
innocent_script.py - Protected app · C source sample representing a protected or monitored program.
protected_app.c - App binary · Compiled protected application sample.
protected_app - Payload ELF · Executable payload sample for the sentinel to classify.
payload.elf - Installer · Shell payload representing an installation or persistence attempt.
rootkit_installer.sh - Hook sample · Assembly sample illustrating kernel-hook style behavior.
kernel_hook.asm - Demo bundle · Bundled demonstration target used to exercise the system.
qsafe_demo
Pipeline artifacts
Intermediate files exchanged between discovery, triage, and scan stages.
- Folder list · Discovered filesystem listing used as triage input.
folder_list.txt - Targets · Selected paths forwarded to deeper inspection.
target_scan_list.txt - Suspicious set · Folders marked suspicious by the decision layer.
sus_folders.txt - Allowlist · Known-safe entries used to suppress false positives.
allowlist.bin - Triage request · Structured prompt or request sent to the optional oracle.
triage_req.json - LLM response · Returned scoring or analysis from the remote decision path.
llm_response.txt
Connections 24
- 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.