README.md

---
license: apache-2.0
language:
- en
pipeline_tag: text-generation
library_name: llama.cpp
tags:
- gguf
- qwen
- qwen3
- qwen3.5
- cybersecurity
- malware-analysis
- reverse-engineering
- pe
- elf
- ghidra
- agent
- research
inference: false
---

<p align="center">
  <img src="assets/xref-9b-banner.svg" alt="xref-9b" width="860">
</p>

# xref-9b

`xref-9b` is a research-preview reverse-engineering assistant for static PE and ELF malware triage. It is intended to be used with a local tool wrapper that exposes static analysis tools such as `file`, `strings`, `readelf`, `objdump`, PE header/import inspection, entropy checks, and optional Ghidra headless summaries.

This release is distributed as GGUF for local inference with llama.cpp.

## What Is Included

| File | Purpose |
|---|---|
| `xref-9b-q4_k_m.gguf` | Recommended GGUF for local use. |
| `xref-9b-f16.gguf` | Full precision GGUF artifact for conversion/experimentation. |
| `agentre.py` | Interactive chat wrapper for PE/ELF reverse engineering. |
| `agentre_triage.py` | Static tool runtime and batch triage backend. |
| `reverse_engineering_spec_unified.md` | Tool-use and verdict spec given to the model. |
| `tools/ghidra_scripts/AgentRESummary.java` | Ghidra headless script used by `/ghidra` and `ghidra_summary`. |
| `scripts/` | Convenience scripts and environment template. |
| `assets/` | Release graphics and evaluation chart. |

## Intended Use

This model is for defensive research, malware triage, reverse-engineering education, and local analyst-assist workflows. It is not a production malware detector and should not be used as the only basis for blocking, attribution, incident response, or legal decisions.

The model should be treated as an assistant that proposes evidence-backed hypotheses from static tool output. It can be wrong, especially on stripped, packed, obfuscated, or sparse-string binaries.

## Training Summary

`xref-9b` was trained from a Qwen-family 9B base model using:

- supervised fine-tuning (SFT) on reverse-engineering instruction traces;
- additional PE and ELF malware/benign triage data;
- reinforcement learning / preference optimization with IPO over curated preference pairs;
- tool-use formatting for local static analysis workflows.

Training data sources are intentionally not enumerated in this public model card.

## Evaluation Snapshot

Held-out mixed PE/ELF evaluation, 40 binaries total, balanced by format and benign/malicious label. Results are research-preview numbers and should be read as directional rather than definitive.

<p align="center">
  <img src="assets/xref-9b-eval-chart.svg" alt="xref-9b evaluation chart" width="760">
</p>

| Checkpoint / workflow | Strict accuracy | Binary accuracy | Notes |
|---|---:|---:|---|
| Base model | 55.0% | 62.5% | Untuned base under the same holdout triage harness. |
| SFT | 57.5% | 57.5% | Supervised checkpoint on PE/ELF reverse-engineering tasks. |
| SFT + IPO | 67.5% | 67.5% | Preference-optimized release workflow with deeper static-analysis settings and final-answer forcing. |

Observed gains:

- strict accuracy improved from 55.0% on the base model to 67.5% with SFT + IPO in the release workflow (+12.5 percentage points);
- labeled ELF malware performance improved substantially under the deeper static workflow;
- benign ELF calibration regressed in that run, so unknown/benign decisions still need analyst review.

## Quick Start

### 1. Install Runtime Dependencies

Required:

- Python 3.10+
- llama.cpp with `llama-completion`
- common Unix tools: `file`, `strings`, `readelf`, `objdump`, `nm`, `hexdump` or `xxd`

Optional but recommended:

- Ghidra headless (`analyzeHeadless`)
- MinGW binutils for richer PE inspection on Linux (`x86_64-w64-mingw32-objdump`, `x86_64-w64-mingw32-nm`)

### 2. Download

Example with Hugging Face CLI:

```bash
hf download AgentreBench/xref-9b   xref-9b-q4_k_m.gguf agentre.py agentre_triage.py reverse_engineering_spec_unified.md   --local-dir xref-9b
```

For full local package including scripts and Ghidra helper:

```bash
hf download AgentreBench/xref-9b --local-dir xref-9b
```

### 3. Configure Environment

```bash
cd xref-9b
cp scripts/xref9b.env.example scripts/xref9b.env
$EDITOR scripts/xref9b.env
source scripts/xref9b.env
```

At minimum set:

```bash
export XREF9B_GGUF="$PWD/xref-9b-q4_k_m.gguf"
export XREF9B_LLAMA_CLI="/path/to/llama.cpp/build/bin/llama-completion"
```

Optional Ghidra:

```bash
export GHIDRA_HEADLESS="/path/to/ghidra/support/analyzeHeadless"
```

### 4. Chat With One Binary

```bash
python3 agentre.py chat /path/to/sample   --model "$XREF9B_GGUF"   --llama-cli "$XREF9B_LLAMA_CLI"   --ctx-size 65536   --gpu-layers 99   --max-turns 8   --max-tool-calls 16   --max-tokens 1600   --obs-limit 8000
```

Inside chat:

```text
/deep      run the deeper static workflow
/ghidra    run Ghidra headless summary
/verdict   force a concise final verdict
/compact   compact long chat history
/tools     list tools used
/save      save transcript
/quit      exit
```

You can also ask naturally:

```text
is this malicious or benign?
use ghidra and explain the key functions
is this packed?
what evidence supports malicious behavior?
```

### 5. Directory Mode

Directory mode is explicit:

```bash
python3 agentre.py chat -d /path/to/binaries   --model "$XREF9B_GGUF"   --llama-cli "$XREF9B_LLAMA_CLI"   --ctx-size 65536   --gpu-layers 99
```

Use `/samples` and `/open N` inside the session.

### 6. Batch Triage

```bash
python3 agentre.py triage /path/to/binaries   --model "$XREF9B_GGUF"   --llama-cli "$XREF9B_LLAMA_CLI"   --ctx-size 65536   --gpu-layers 99   --max-tool-calls 16   --max-tokens 1600   --obs-limit 8000
```

## Ghidra Support

`xref-9b` does not run arbitrary Ghidra commands. The wrapper exposes one Ghidra tool, `ghidra_summary`, implemented with Ghidra headless and `tools/ghidra_scripts/AgentRESummary.java`.

The wrapper runs a command equivalent to:

```bash
analyzeHeadless /tmp/agentre_ghidra_xxx agentre_project   -import <staged_sample>   -overwrite   -analysisTimeoutPerFile 180   -scriptPath tools/ghidra_scripts   -postScript AgentRESummary.java /tmp/agentre_ghidra_summary.txt
```

Ghidra is used for static summaries: program metadata, memory blocks, imports/external symbols, strings, functions, and short instruction excerpts. It does not unpack malware, execute binaries, emulate payloads, or dynamically dump memory.

## Limitations

- Research preview; not production detection.
- Static-only; no execution, sandboxing, unpacking, or memory dumping.
- Stripped/static/packed binaries can require manual analyst follow-up.
- The model can overfit to tool artifacts or overclaim from weak signals.
- PE and ELF performance is uneven across families and compiler/linker settings.
- The model may classify offensive dual-use tools as `hackware` or `malicious` depending on evidence and workflow.
- Long tool histories can degrade answers; use `/compact`.

## Improving The Model

Useful next steps for contributors:

- Add more stripped ELF and statically linked ELF training traces.
- Add calibrated benign PE examples that contain network/admin APIs but no malicious behavior.
- Add preference pairs that penalize overclaiming from entropy or strings alone.
- Add tool traces that distinguish virtual addresses from file offsets.
- Improve Ghidra summaries with function call graphs, xrefs, and decompiler snippets.
- Add safer structured verdict calibration: `malicious`, `benign`, `hackware`, `unknown`.
- Evaluate with family-disjoint and compiler-disjoint splits.

## Recommended Settings

For most local analysis:

```bash
--ctx-size 65536 --max-turns 8 --max-tool-calls 16 --max-tokens 1600 --obs-limit 8000
```

Use larger `--max-tokens` for deeper explanations, and `/compact` if the session becomes repetitive or context-heavy.

## File Hashes

```text
87f320a4edda407a00ddb005774640acac4c45882a9d03674e5f2c37e9dbafd6  xref-9b-q4_k_m.gguf
2e9438786b7aed9a9314629e811900616c1b4666a2f7cffa2f537fd566f238d8  xref-9b-f16.gguf
```

## Citation

If you use this model in research, cite AgentRE-Bench / xref-9b and include the exact GGUF hash used.