mirror of
https://github.com/trailofbits/skills.git
synced 2026-09-14 14:28:48 +08:00
Eric Kilmer
ec2450d05e
* Trim dwarf-expert: single-file skill, effort level, contract test - Consolidate SKILL.md from four files into one (115 lines); delete reference/. Cut generic behavior rules, duplicate When-to-Use sections, a 9-line readelf reference hop, and an ASCII decision tree; fix five typos. - Fix --lookup=<offset> misuse carried over from the original: DIE at a section offset is --debug-info=<offset>; --lookup takes a program address. Verified live against llvm-dwarfdump. - Drop the invented v3-v5 version scoping from the skill, plugin.json, marketplace.json, and both READMEs. Version-specific judgment that earned its place (the -gdwarf-N pin inference, v2 surface forms) lives in the Verifying section. - Frontmatter: add effort: medium, rewrite the trigger description, extend allowed-tools with Write/Edit/WebFetch. - Add tests/test_skill_contract.py (stdlib + pytest): every dwarfdump flag documented in SKILL.md must exist in a live llvm-dwarfdump (>= 19, the verified floor for --error-display/--verify-json), plus a frontmatter contract check. Zero extracted flags or a missing tool fails rather than skips. - CI: python-tests installs llvm-19, falling back to the default llvm on future runner images. - Bump version 1.0.1 -> 1.1.0. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Address review: fence-aware extraction, capability-gated resolver - body_sections() no longer strips fenced blocks from section text: fences are ignored only for heading detection, so flags documented inside examples are extracted and verified. New unit test covers both properties; a fenced --bogus-flag mutation now goes red. - Replace the parsed-version LLVM floor with a capability gate: the resolver requires --error-display/--verify-json in --help, because Apple's LLVM numbering does not track upstream and a numeric major is not comparable across toolchains. Failure lists rejected tools with their version banners. README wording matches. - Raise the extraction floor from 10 to 15 (21 flags documented). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: kz-tob <kara.zaffarano@trailofbits.com>
52 lines
2.0 KiB
Markdown
52 lines
2.0 KiB
Markdown
# DWARF Expert
|
|
|
|
Interact with and analyze DWARF debug information: parse and search DIEs with
|
|
`dwarfdump`/`llvm-dwarfdump` and `readelf`, verify debug info integrity with
|
|
`llvm-dwarfdump --verify`, answer questions about the DWARF standard, and write
|
|
code that parses DWARF data.
|
|
|
|
**Author:** Evan Hellman
|
|
|
|
## What It Does
|
|
|
|
The skill is a single `SKILL.md` covering:
|
|
|
|
- Authoritative sources for standard questions: dwarfstd.org, LLVM's
|
|
`lib/DebugInfo/DWARF/`, and libdwarf, looked up on demand rather than answered
|
|
from memory
|
|
- An `llvm-dwarfdump` flag reference for dumping, searching (`--find`, `--name`,
|
|
`--lookup`), and displaying DIE trees
|
|
- A search-escalation strategy: accelerator-table lookup, exhaustive name search,
|
|
grep pipelines over full dumps, then a `pyelftools` script when pipelines turn
|
|
brittle
|
|
- Verification workflows: `--verify` (with `--error-display` and `--verify-json`)
|
|
and `--statistics` for comparing debug-info quality across builds
|
|
- Library recommendations for C/C++, Python, Rust, Go, and .NET, plus
|
|
DWARF-specific pitfalls (optional attributes, `DW_AT_abstract_origin` /
|
|
`DW_AT_specification` indirection, type chains)
|
|
|
|
## Testing
|
|
|
|
`tests/test_skill_contract.py` extracts every `llvm-dwarfdump` flag the skill
|
|
documents and checks it against the real tool's `--help`, and validates the
|
|
frontmatter contract (`name`, `description`, `effort`, space-delimited
|
|
`allowed-tools`). It fails if the extraction comes back empty or no LLVM
|
|
dwarfdump is on PATH — a checker that inspects zero items must not pass.
|
|
|
|
Requires an LLVM dwarfdump that supports `--error-display` and `--verify-json`
|
|
(upstream LLVM 19+; the test checks for the flags themselves rather than a
|
|
version string, since Apple's LLVM numbering differs from upstream). macOS:
|
|
current Xcode Command Line Tools qualify; Debian/Ubuntu: `apt install llvm-19`
|
|
or newer. Run with:
|
|
|
|
```sh
|
|
cd plugins/dwarf-expert/tests
|
|
uv run --no-project --with pytest python3 -m pytest -q --import-mode=importlib .
|
|
```
|
|
|
|
## Installation
|
|
|
|
```
|
|
/plugin install trailofbits/skills/plugins/dwarf-expert
|
|
```
|