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 +![terminal demo: modelhawk samples --no-color](docs/assets/demo.svg) + +_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 @@ + + + + +$ modelhawk samples --no-color + __ __ _ _ _ _ _ + | \/ |___ __| |___| | || |__ ___ __ __| |__ + | |\/| / _ \/ _` / -_) | __ / _` \ V V / / / + |_| |_\___/\__,_\___|_|_||_\__,_|\_/\_/|_\_\ + static pickle-RCE scanner for ML models + +[ OK ] SAFE samples/benign_config.yaml +[ OK ] SAFE samples/benign_float_array.npy +[ OK ] SAFE samples/benign_state_dict.pkl +[!!!!] CRITICAL samples/malicious_config.yaml + |- !!python/object/apply executes arbitrary Python callable on yaml.load() + opcodes [<yaml>]: YAML_TAGx1 +[!!!!] CRITICAL samples/malicious_exec.p2.pkl + |- REDUCE -> __builtin__.exec (invokes dangerous callable __builtin__.exec()) + opcodes: GLOBALx1 REDUCEx1 +[!!!!] CRITICAL samples/malicious_exec.p5.pkl + |- REDUCE -> builtins.exec (invokes dangerous callable builtins.exec()) + opcodes: STACK_GLOBALx1 REDUCEx1 +[!!!!] CRITICAL samples/malicious_object_array.npy + |- REDUCE -> posix.system (imports posix.system from 'posix' (code / process / file execution)) + opcodes [<npy>[object-array]]: GLOBALx1 REDUCEx1 +[!!!!] CRITICAL samples/malicious_os_system.p2.pkl + |- REDUCE -> posix.system (imports posix.system from 'posix' (code / process / file execution)) + opcodes: GLOBALx1 REDUCEx1 +[!!!!] CRITICAL samples/malicious_os_system.p5.pkl + |- REDUCE -> posix.system (imports posix.system from 'posix' (code / process / file execution)) + opcodes: STACK_GLOBALx1 REDUCEx1 +[!!!!] CRITICAL samples/malicious_pytorch_model.pt + |- REDUCE -> posix.system (imports posix.system from 'posix' (code / process / file execution)) + opcodes [archive/data.pkl]: GLOBALx1 REDUCEx1 +[ OK ] SAFE samples/safe_model.safetensors + |- safetensors format — no pickle, no code-execution path + +scanned 11 file(s) -> CRITICAL:7 SAFE:4 +