阿尔夫

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

按目标选择切入点

目标 · 入口点 对单个崩溃进行事后分析 · 崩溃分类 LLM 驱动的模糊测试活动 · 模糊测试 内核/远程存根调试(VZ、QEMU、KDP) · 内核调试 让代理自由探索实时目标 · 交互式探索

事故分类

使用时机:用户有一个二进制文件和一个崩溃的输入(来自 libFuzzer、AFL++、Jackalope 等),并且想要了解根本原因、对其进行分类和/或生成最小化/扩展的语料库。三个级别,根据代理应拥有的自主权进行选择:级别·命令·何时完全脚本化管道·uv run alf analyze --pipeline --binary <bin> --crash <input>·每次运行相同的输出;对 CI 有好处

模糊测试

使用时间:用户希望运行一个活动,而不仅仅是分析现有的崩溃。模式·命令·适用于auto·alf fuzz auto <bin> --corpus <seeds>·LLM 选择函数、安装停止钩子、实时突变。适用于任何 Mach-O。 hybrid · alf fuzz hybrid <bin> --corpus <seeds> --max-time 3600 · libFuzzer 负责体积,alf 负责冷启动+分类。 libFuzzer 安全带上性价比最高的产品。

内核调试

在以下情况下使用:调试目标不是本地进程 - Virtualization.framework 下的 macOS 来宾内核、QEMU gdbstub、JTAG 桥接器、KDP 上的 iOS 设备。从内核调试更新开始,这是 alf 中的一流路径。不要尝试对内核使用lldb_launch/lldb_attach;它们用于本地用户空间进程。代理配方:关键规则:static_addr + module 是破解 IDA 地址的正确方法。 lldb_set_breakpoint(address=...) 用于运行时地址,并且在 KASLR 下会丢失。

互动探索

使用时间:代理应该在没有固定工作流程的情况下自由地刺探实时目标 - 回答“这是如何工作的?”或“这个函数对此输入做什么?”服务器自动生成 lldb-dap — 无需手动调整端口。它还运行就绪探针并显示可操作的生成错误(缺少二进制文件、端口正在使用、代码签名拒绝)。如果您看到“lldb-dap 在绑定前退出,代码为 0”,则安装的适配器不接受 --port;由于这个原因,alf 已经转移到了--connection listen://host:port。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
需要 · Vendor-specific
兼容的系统
macOS
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# alf — Agentic LLDB Fuzzer

alf lets an AI agent drive LLDB over MCP to analyze crashes, fuzz targets, and debug kernels. **Target: Apple Mach-O, arm64(e).** Agent-first design: every capability is an MCP tool call.

## Choose the entry point by goal

| Goal | Entry point |
|---|---|
| Post-mortem analysis of a single crash | [Crash triage](#crash-triage) |
| LLM-driven fuzzing campaign | [Fuzzing](#fuzzing) |
| Kernel / remote-stub debugging (VZ, QEMU, KDP) | [Kernel debugging](#kernel-debugging) |
| Let an agent freely explore a live target | [Interactive exploration](#interactive-exploration) |
| Plug alf into Claude Code / Codex / Gemini CLI | [ACP integration](#acp-integration) |

When in doubt: **`alf server --transport stdio`** exposes every capability as MCP tools. Everything else is a higher-level orchestrator around that same tool surface.

Before anything else, verify the host is configured: `uv run alf doctor`. A failing `lldb_launch` check almost always means macOS Developer Mode is off — see [Gotchas](#gotchas).

---

## Crash triage

**Use when:** the user has a binary and a crashing input (from libFuzzer, AFL++, Jackalope, etc.) and wants to understand the root cause, classify it, and/or generate a minimized/expanded corpus.

Three levels, pick by how much autonomy the agent should have:

| Level | Command | When |
|---|---|---|
| Fully scripted pipeline | `uv run alf analyze --pipeline --binary <bin> --crash <input>` | Same output every run; good for CI |
| LLM-in-the-loop director | `uv run alf director --binary <bin> --crash <input> --mode auto` | Need the agent to pick which commands to run |
| Raw MCP surface | `alf server` + `lldb_launch` → `lldb_crash_context` → ... | Building a custom workflow, or an outer agent already orchestrates |

Sub-commands (`alf analyze <subcommand>`):
- `triage` — capture backtrace, registers, disassembly → `logs/*.json`
- `classify` — heuristic exploitability + LLM bucketing
- `report` — render a markdown RCA from a triage JSON
- `minimize` — shrink a crash input while preserving the stack hash
- `corpus` — synthesize new seeds from a crash (add `--llm` for LLM-guided)

**Agent recipe (raw MCP):**
1. `lldb_launch(binary, crash_input=...)` — auto-runs to the stop
2. `lldb_crash_context()` — one JSON with reason, registers, top frames, disasm, stack bytes, stack hash
3. If you need more: `lldb_backtrace_json(max_frames=32)`, `lldb_read_memory("$x0", size=64)`, `lldb_disassemble("--pc", count=20)`
4. `lldb_stack_hash()` for deduplication against previous crashes

One-call-gets-most-of-it: `lldb_crash_context` is the fastest path to a full picture.

---

## Fuzzing

**Use when:** the user wants alf to run a campaign, not just analyze an existing crash.

| Mode | Command | Fits when |
|---|---|---|
| `auto` | `alf fuzz auto <bin> --corpus <seeds>` | LLM picks functions, installs stop-hooks, mutates live. Works on any Mach-O. |
| `hybrid` | `alf fuzz hybrid <bin> --corpus <seeds> --max-time 3600` | libFuzzer does the volume, alf does the cold-start + triage. Best bang-for-buck on libFuzzer harnesses. |
| `jackalope` | `alf fuzz jackalope <harness> --instrument-module <M> --target-method <m>` | macOS framework fuzzing (ImageIO, AVFoundation, etc.) via TinyInst. Requires a Jackalope build. |

**Agent recipe for in-process mutation (raw MCP, after `lldb_launch`):**
1. `lldb_lookup_symbol(query="parse_", regex_search=True, as_json=True)` — find candidate parsers
2. `lldb_install_stop_hook(function="parse_foo", ptr_reg="x0", len_reg="x1")` — mutate the buffer at entry
3. `lldb_generate_fuzz_script(function=..., skip_conditions=[...])` — scripted IOUserClient `externalMethod` filtering
4. `telemetry_rate()` / `telemetry_snapshot()` — exec/s visibility while the hook runs
5. `lldb_poll_crashes()` — deduplicated crash events surfaced by the stop hook

---

## Kernel debugging

**Use when:** the debug target is **not a local process** — a macOS guest kernel under Virtualization.framework, a QEMU gdbstub, a JTAG bridge, an iOS device over KDP.

This is a first-class path in alf as of the kernel-debug update. Do **not** try to use `lldb_launch`/`lldb_attach` for kernels; they are for local userspace processes.

**Agent recipe:**
```
# Attach to the stub (required first step)
lldb_gdb_remote(
    port=8864,                                   # VZ hypervisor default varies; whatever your stub exposes
    host="127.0.0.1",                            # default
    target="/Library/Developer/KDKs/KDK_*.kdk/System/Library/Kernels/kernel.release.vmapple",
    arch="arm64e",                               # optional; some stubs omit it
    plugin="kdp-remote",                         # "kdp-remote" for macOS; omit for QEMU/JTAG
)

# Pull in xnu's lldb macros (auto-detects KDK / ~/src/xnu / ALF_XNU_LLDBMACROS)
lldb_load_xnu_macros()

# Add a kext whose symbols aren't in the main kernel
lldb_add_module(path="/path/to/com.apple.MyKext.kext/Contents/MacOS/MyKext", dsym="...")

# Set breakpoints two ways
lldb_set_breakpoint(function="smb2_rq_decompress_read")              # by symbol (after macros loaded)
lldb_set_breakpoint(static_addr="0xfffffe000a5ec4c8",                # by link-time addr from IDA/disassembly
                    module="kernel.release.vmapple")                 # resolved against the runtime slide

# Work the stop
lldb_continue(wait=True)
lldb_register_read("x0")
lldb_read_memory("$x0+0x620", size=4)

# Poke the guest without fully halting it (single atomic pause/write/continue)
lldb_write_memory(address="_smbfs_loglevel", data="ffff0000",
                  encoding="hex", resume=True)

# Clean teardown — keeps the remote inferior running (attach/gdb_remote is detach-safe)
lldb_terminate()
```

**Key rules:**
- `static_addr` + `module` is the correct way to break on an IDA address. `lldb_set_breakpoint(address=...)` is for *runtime* addresses and will miss under KASLR.
- `lldb_write_memory(resume=True)` is the kernel-debug primitive: one round trip, guest SSH barely blips.
- `lldb_terminate` on an attach/gdb-remote session detaches (does **not** kill the inferior). Launched processes are killed. Trust it.
- `lldb_slide(module=...)` returns `None` if lldb hasn't resolved a slide yet (target not attached / unloaded module) — that is a legitimate answer, not an error; retry after attach.
- If the server says "No active session" vs "Session ended": the first means you never attached; the second means the adapter died and you should gather what you have and report.

See [references/workflows.md](references/workflows.md) for the full VZ gdbstub recipe including KDK path discovery.

---

## Interactive exploration

**Use when:** the agent should freely poke at a live target without a fixed workflow — answering "how does this work?" or "what does this function do on this input?"

```bash
uv run alf server --transport stdio     # preferred for Claude Desktop / Claude Code
uv run alf server --transport sse --listen-port 7777   # for web clients
```

The server spawns `lldb-dap` automatically — no manual port juggling. It also runs a readiness probe and surfaces actionable spawn errors (missing binary, port in use, code-signing refusal). If you see "lldb-dap exited with code 0 before binding", the installed adapter doesn't accept `--port`; alf has already moved to `--connection listen://host:port` for this reason.

Tool families the agent has access to (~50 tools):
- **Session** — `lldb_launch`, `lldb_attach`, `lldb_gdb_remote`, `lldb_load_core`, `lldb_status`, `lldb_terminate`
- **Execution** — `lldb_execute` (raw LLDB), `lldb_continue`, `lldb_step`, `lldb_set_breakpoint`, `lldb_watchpoint`
- **Inspection** — `lldb_backtrace`, `lldb_disassemble`, `lldb_read_memory`, `lldb_register_read/write`, `lldb_memory_search`, `lldb_frame_*`, `lldb_thread_*`
- **Crash** — `lldb_crash_context`, `lldb_stack_hash`, `lldb_poll_crashes`
- **Symbols** — `lldb_lookup_symbol` (with `as_json=True` for structured output), `lldb_dump_symtab`, `lldb_read_source`
- **Kernel** — `lldb_add_module`, `lldb_slide`, `lldb_load_xnu_macros`, `lldb_write_memory`
- **Instrumentation** — `lldb_install_stop_hook`, `lldb_install_fork_server`, `lldb_generate_fuzz_script`, `telemetry_rate`, `telemetry_snapshot`
- **Static analysis** (no target required) — `macho_*` for load commands, entitlements, dylibs, Swift symbols; `static_lookup`
- **ObjC runtime** — `runtime_objc_classes`, `runtime_objc_class_dump`, `runtime_objc_object_dump`
- **Capabilities** — `heap_check`, `heap_inspect`, `objc_inspect`, `monitor_trace`, `xpc_sniff`, `xpc_send`

Full one-line descriptions in [references/mcp-tool-catalog.md](references/mcp-tool-catalog.md).

---

## ACP integration

ACP (Agent Client Protocol) is how alf drives agent CLIs (Claude Code, Codex, Gemini CLI) that authenticate via a user's subscription instead of an API key. The inverse is also true: those CLIs can consume alf as an MCP server.

### Using alf from Claude Code / Codex / Gemini CLI

Add alf to the client's MCP config. For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "alf": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/alf", "alf", "server", "--transport", "stdio"]
    }
  }
}
```

Claude Code's project-local `.mcp.json` takes the same shape. Gemini CLI: pass via `--experimental-acp` with an equivalent config. The server auto-spawns `lldb-dap` — no side setup.

### Driving an agent CLI from alf

`alf`'s ACP bridge (`alf acp run`) launches an external agent with alf already attached as an MCP server. Useful when you want alf to orchestrate Claude Code (for example, to run a multi-turn triage under subscription auth). Example:

```bash
uv run alf acp run --agent claude --prompt "Triage crash at /tmp/crash_input against /tmp/fuzz_bin"
```

Agents: `claude` (via `claude-code-acp`), `codex` (via `codex-acp`), `gemini` (via `gemini --experimental-acp`). alf discovers Zed-installed agents under `~/Library/Application Support/Zed/external_agents/` automatically.

---

## Backend selection

alf supports four debugger backends. For an agent making MCP tool calls, the backend is almost always chosen by whoever started `alf server` — you don't pick it per call. But if the user asks:

| Backend | Flag | Use when |
|---|---|---|
| `dap` (default) | `--backend dap` | Anywhere. Portable. Required for `lldb_gdb_remote`. |
| `sbapi` | `--backend sbapi` | Batch crash triage, need 10-100× throughput, don't need gdb-remote |
| `lldb_mcp` | `--backend lldb_mcp` | Experimental native LLDB MCP protocol |
| `mock` | `--backend mock` | Tests/CI without an LLDB install |

Default is `dap`. If the user is doing kernel / remote work, they need `dap` (only backend with `attach_gdb_remote`).

---

## Gotchas

- **`process exited with status -1`** on launch → macOS Developer Mode is off. `uv run alf doctor` will print the fix (System Settings → Privacy & Security → Developer Mode; `DevToolsSecurity --enable`; reboot).
- **`lldb_execute` returns "No active session"** → the agent never called a session-opening tool. Tell it to call `lldb_launch`, `lldb_attach`, `lldb_load_core`, or `lldb_gdb_remote` first.
- **`lldb_execute` returns "Session ended"** → the adapter died mid-flight. Don't retry — collect what you have from `lldb_crash_context` / `lldb_status` and report.
- **`lldb-dap exited with code 0 before binding <port>`** → the installed adapter doesn't accept `--port`; you're on a build old enough that alf's `--connection listen://...` spawn still failed. Upgrade Xcode command-line tools or LLVM.
- **Breakpoint set on a kernel address never fires** → you used `address=` with a link-time address. Use `static_addr=` + `module=` instead so alf applies the runtime slide.
- **`lldb_slide` returns null** → either the target isn't attached yet, or lldb hasn't resolved the module. Both are retryable; it's not an error.
- **Symbols look wrong / macros missing** in a kernel session → call `lldb_add_module` for the KDK kernel and `lldb_load_xnu_macros` before trying to use `zprint`/`showallkmods`/etc.
- **`alf doctor` reports `xnu_lldbmacros: WARN`** → advisory only. Not needed for userspace. Install a KDK or set `ALF_XNU_LLDBMACROS` if you're doing kernel work.

---

## Reference files

- [references/mcp-tool-catalog.md](references/mcp-tool-catalog.md) — every MCP tool, one line each, grouped by category.
- [references/workflows.md](references/workflows.md) — end-to-end recipes: kernel bp-on-parser loop, crash triage from cold, stop-hook-driven fuzzing, ACP orchestration.
- [references/backends.md](references/backends.md) — detailed backend comparison and when each wins.

---
> Source: [blacktop/alf](https://github.com/blacktop/alf) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。