From 7b3646f927fd7aa226059d1af5f930735c313a29 Mon Sep 17 00:00:00 2001
From: Praising Harris Ratnam <215876416+Pyhroff@users.noreply.github.com>
Date: Mon, 16 Nov 2026 18:29:09 +0000
Subject: [PATCH] docs: add real-output demo SVG and Mermaid diagram
---
README.md | 26 ++++++++++++++++++++++++++
docs/assets/demo.svg | 40 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 66 insertions(+)
create mode 100644 docs/assets/demo.svg
diff --git a/README.md b/README.md
index af8dde4..de9a731 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,28 @@ Each imported global is scored by a **severity table** (full lists in `modelhawk
> **Design note — low false positives by construction.** Real models routinely pickle references to their *own* custom classes (`GLOBAL mymodel MyNet`). Those land as **MEDIUM "manual review,"** and because the CI gate defaults to `--fail-on HIGH`, legitimate models with custom classes **pass cleanly** — you get the signal without the false alarm. Only genuine code-execution sinks (`os`/`subprocess`/`builtins.exec`/…) reach CRITICAL and fail the build.
+### Scan pipeline
+
+```mermaid
+flowchart TD
+ P["path(s)"] --> GP["gather_paths (recurse, pick model files)"]
+ GP --> SF{"scan_file by extension / magic"}
+ SF -->|".safetensors"| ST["SAFE (no pickle, no code path)"]
+ SF -->|".yaml / .yml"| Y["scan_yaml_bytes (python/* tags)"]
+ SF -->|".npy"| N["scan_npy_bytes (object arrays embed a pickle)"]
+ SF -->|"pickle / zip (.pt, .bin, .npz)"| IT["iter_pickle_streams (bounded member count and size)"]
+ IT --> SP["scan_pickle_bytes (opcode walk, never unpickles)"]
+ SP --> CG["classify_global (dangerous callables)"]
+ Y --> V["verdict per file (worst stream wins)"]
+ N --> V
+ CG --> V
+ ST --> V
+ V --> R["print_reports / --json (--disasm for opcodes)"]
+ R --> X{"--fail-on threshold"}
+ X -->|"met"| E1["exit non-zero"]
+ X -->|"not met"| E0["exit 0"]
+```
+
### Two subtleties that bite people who reason from memory
ModelHawk handles both because they were verified empirically, not assumed:
@@ -105,6 +127,10 @@ Useful flags: `--disasm` (full opcode dump for flagged files), `--json`, `--quie
## Example output
+
+
+_Real output of `modelhawk.py samples --no-color` after `python demo.py` crafted the samples (ANSI stripped; exits 1 because CRITICAL findings exist). Paths show `posix.system` because this run was on Linux._
+
Scanning the crafted corpus (`python demo.py`):
```
diff --git a/docs/assets/demo.svg b/docs/assets/demo.svg
new file mode 100644
index 0000000..d22e5cd
--- /dev/null
+++ b/docs/assets/demo.svg
@@ -0,0 +1,40 @@
+