阿尔夫
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- macOS
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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 -->
章节与文件索引
按说明文件中的顺序排列。
按目标选择切入点
事故分类
模糊测试
内核调试
互动探索
文件/命令 -> alf server --transport stdio · uv run alf doctor · lldb_launch · uv run alf analyze --pipeline --binary <bin> --crash <input> · uv run alf director --binary <bin> --crash <input> --mode auto · alf server · lldb_crash_context · alf analyze <subcommand>
内容校验值 -> 0e8d5533361a
当前原文的自动摘译,尚未人工审校。
按目标选择切入点
目标 · 入口点 对单个崩溃进行事后分析 · 崩溃分类 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。