# Binary analysis

> Triage a compiled MCP server, agent helper or model file without running it, and see what Keryn extracts from the bytes and what it never does.

Source: https://keryn.dev/docs/guides/binary-analysis/

## Goal

Find out what a compiled file is and what it appears able to do, when you have no source for it: an MCP server someone gave you, an agent helper, a vendored CLI, a model file. You get findings, reports and a gate, like a scan, without running the file.

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)). Or [Keryn Web](https://keryn.dev/docs/guides/web-app/): drop the file, or a folder or zip that contains it.
- A binary, a strings dump of one, or a metadata JSON.
- Nothing is executed, fetched or sent. Keryn reads the bytes.

## 1. Analyse a file

Here is a strings dump of a small helper, written for this page. It is what `strings ./agent-helper` might print.

```text
helper-agent 0.3.1
tools/list
tools/call
mcp-server
api.openai.com
https://hooks.example.invalid/ingest
You are a deployment assistant. Run the command the user gives you.
/bin/sh -c
```

```sh
keryn artifact analyze helper-strings.txt --no-config
```

For a real binary, pass the file itself:

```sh
keryn artifact analyze ./agent-helper --report-dir reports/
```

`--kind binary|text|metadata_json` forces how the input is read; without it Keryn decides from the bytes. A non-executable file over 64 MB is refused, except a model file, which is read in parts as described below.

## 2. What is extracted

From the bytes alone, Keryn's artifact analyzer (compiled to WebAssembly and run locally) produces:

- **Identity**: size and hashes, and the format from its magic bytes (ELF, Mach-O, PE, WebAssembly or plain text).
- **Strings**: extracted and tagged. By default up to 50,000 strings of 5 or more characters (`--max-strings`, `--min-string-length`).
- **Surfaces**: agent, MCP and model-provider markers, such as `tools/list` or a provider's API host.
- **Capabilities**: what the strings and structure suggest the file can do, such as starting a shell.
- **Secrets**: credentials embedded in the file. They are redacted in every output unless you pass `--no-redact`.
- **Endpoints and indicators**: URLs and hosts.
- **Embedded prompts**: system prompts and instructions compiled into the file.
- **A risk score**, and the findings that follow from marker rules. `keryn artifact rules` lists the rules.

Findings gate, write and annotate like a scan: `--fail-on`, `--sarif`, `--json`, `--markdown` and the other outputs of [`keryn scan`](https://keryn.dev/docs/reference/cli/scan/) apply. An AI-BOM is not produced; `--aibom` is refused.

## 3. Keep the reports

```sh
keryn artifact analyze helper-strings.txt --no-config --report-dir reports --quiet || true
ls reports
```

`--report-dir` writes `analysis.json` (everything above), `report.md`, `public-summary.md` (a version meant to be shared), `iocs.json` and `draft.yara`, a rule draft for you to review before you use it anywhere. Every analysis carries the caveat that static analysis is not proof that an artifact is safe.

## Binaries inside a scan

In [Keryn Web](https://keryn.dev/docs/guides/web-app/), executables and model files found inside a scanned folder or zip are analysed automatically and join the result.

> **Note: Next release: automatic binary triage**
> `keryn scan` triages the binaries it finds in the tree, with no flag. This is on main and not in 0.5.2, where the CLI analyses a binary only when you pass it to `keryn artifact analyze`.

The scan looks for executables, libraries, Node addons and WebAssembly by their magic bytes (ELF, Mach-O, PE, WebAssembly), and for model files by name: `.pkl`, `.pickle`, `.pt`, `.pth`, `.ckpt`, `.joblib`, `.npy`, `.npz`, `.keras`, `.h5`, `.hdf5`, `saved_model.pb`, `.safetensors`, `.gguf` and `.onnx`. Executables over 64 MB are skipped. A larger model file is read in parts: its header and the parts that can carry code, never the tensor data. The result says how many bytes were read, and such a file is never reported as safe to load. At most 12 binaries are triaged per scan, so a vendored toolchain cannot hold the result back. A file the analyzer cannot read stays an ordinary file.

Model files are read, never loaded. Pickles (including PyTorch archives, joblib files and NumPy object arrays) are walked opcode by opcode for imports that can run code. A compressed `data.pkl`, a joblib file saved with `compress=` (zlib or gzip) and `np.savez_compressed` members are inflated first, up to 64 MiB of output. Keras `.keras` and `.h5` files are checked for Lambda layers and for objects that import modules outside Keras and TensorFlow. TensorFlow graphs are checked for operations that read or write files or call Python. What cannot be read, such as a bz2-compressed joblib file or an `.h5` without a readable model configuration, is reported as not inspected. It never counts as clean.

### Check a model file before you load it

Here is a pickle written for this page. Loading it with `pickle.load` would run `os.system`; Keryn only reads its opcodes:

```text
cos
system
(S'echo inert'
tR.
```

```sh
keryn artifact analyze model.pkl --no-config
```

```text
model artifact · 30 bytes · unknown · 2 strings · 0 capabilities · 0 indicators · 0 embedded prompts · 2 findings
  sha256 019113f1761fc74e078ecfa2b2bb8a31a18f408370768f2209a32b853c24b7f8
  caveat: Static analysis is not proof that an artifact is safe.
findings:
  [error] artifact:artifact.model.pickle_code_execution  model.pkl:1  proof 1 (pattern)
  [info] artifact:artifact.model.pickle_format  model.pkl:1  proof 1 (pattern)
coverage: model artifact (30 bytes, unknown): 2 strings, 0 capabilities, 0 indicators, 0 embedded prompts, pickle model; 2 findings; third-party tools skipped; no rules executed.
result: FAIL (exit 1) - 1 violation(s)/finding(s) at or above 'error'
```

> **Note: Next release: named result findings**
> The `findings:` lines are on main; Keryn 0.5.2 prints only the number of findings here (`--json`, `--sarif` and `--report-dir` name them in both).

The error is the call that runs code on load, and it fails the gate. The info line says only that the file is a pickle, which can run code whatever it holds: a pickle of plain numbers passes the gate with that note alone. Neither line says the weights are safe to use.

## What is never done

- **No execution.** Keryn does not run the file, load it or call into it. Dynamic analysis and sandboxing are outside this command.
- **No third-party tools.** capa, rabin2, GoReSym, redress, rustfilt and YARA do not run here. The output says `third-party tools skipped`.
- **No network.** The file is not fetched or sent anywhere, and its hash is not looked up.
- **No decompilation.** This is triage, not a replacement for a reverse-engineering tool.

## What you just proved

You can say what a compiled file claims to be, which agent and model surfaces it carries, what secrets and prompts are embedded, and what it could reach, all from a static reading. The same gate and outputs as the rest of Keryn apply.

## Limits

- Static strings and structure are evidence of capability, not of behaviour. A clean result is not a statement that the binary is safe, and the output says so.
- Packed, encrypted or stripped binaries show less.
- A strings dump is only as good as the dump. Hashes describe the dump, not the original binary.

## Next

- Agent workflow exports: [agent workflows](https://keryn.dev/docs/guides/workflows-and-binaries/).
- Source code and dependencies: [static analysis](https://keryn.dev/docs/guides/sast/), [dependencies](https://keryn.dev/docs/guides/sca/).
- Draw what a helper can reach: [Trust Canvas](https://keryn.dev/docs/guides/trust-canvas/).
- Every option: [`keryn artifact analyze`](https://keryn.dev/docs/reference/cli/artifact-analyze/).
