Add --arch, machine-readable output, byte bad-chars and symbol annotation (#19-#22)

[ricardojrdez]

Implements four enhancements from the backlog.

#19 — --arch slice selection for fat Mach-O

Select which slice of a fat/universal Mach-O to analyse (e.g. --arch x86_64, --arch i386). Without it, the first supported slice is used (unchanged). Clear errors for an unsupported (arm64) or absent slice. Threaded through Binary → MachO.

#20 — machine-readable output --output {text,json,csv}

Structured output for scripting/pwntools. Gadget.to_dict() provides a stable record (file, vaddr, gadget, instructions, bytes, count, symbol, op, dst, src, modifies). Works for plain gadgets, --op results and --ropchain (CSV adds a chain column). text remains the default and the non-exhaustive ropchain path stays lazy.

#21 — --badchar-bytes

Reject gadgets whose opcode bytes contain a forbidden byte (the existing --badchar still filters the address only). Useful when the payload itself travels through a byte-restricted sink.

#22 — --symbols

Annotate each gadget with the nearest symbol at or below its address (name+offset). Loaders gained get_symbols():

• ELF: .symtab / .dynsym via pyelftools.
• Mach-O: LC_SYMTAB, parsed from the file (macholib does not expand the nlist array).
• PE: export table via pefile.

All symbol addresses are rebased by the same delta as --base.

Other

• Comments/docstrings switched to American English spelling.

Testing

• 78 tests pass on Python 3.11 and 3.13.
• New coverage: byte bad-chars, symbol annotation + nearest-symbol resolution, JSON/CSV output, ELF symbol parsing (the in-memory ELF builder now emits an optional .symtab/.strtab, so no binary blobs are committed) and Mach-O slice selection (guarded to macOS / fat /bin/ls).
• End-to-end verified on /bin/ls (Mach-O) and a 32-bit busybox (ELF).
• README usage block updated.

Closes #19, closes #20, closes #21, closes #22.

Generated with Claude Code