one_gadget 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cce7f8fbd56224d205d4dc7fdd08f8d642ff586da671574ae44f29f4c1fd63d3
-  data.tar.gz: edb152ef2e3a2cad812a4eb2561854552a40e826ceb770d5aa04d7003d2e20d6
+  metadata.gz: db6b57fdce4468596a6c52c7af146c6dafce4d98c2cc0e887f7e9cafee8ddb32
+  data.tar.gz: 6fce268e224fd67920694a1fd1ac2ae16f337f10abb3f3206bace11126a1abb7
 SHA512:
-  metadata.gz: 10ec07de38a263a7ff7035e6ec97d47b111a12e344d54fef3fa8aa0f41d3cff29e59d688a180e97a1b10eb5f610d24d51a889967299445134785ec631d7274c5
-  data.tar.gz: 0adecd70607f6054831c155c3ac7f64e19a97db8a772f8265cb0d35b0bedc620d9fb8c5371ceaf5c6f804249c2381ca7dac74eaf6aa5f29f661266fc548d319e
+  metadata.gz: cac3e425c402f1f4fc5c1c685f61118492d2a9bd358d2bad56962836d849b077bc70b2781f20b4fe9624e1a532ec4e07803a141667cbc43709d1d9ad84dee766
+  data.tar.gz: 0a51d45298fba885dda209ab236c2dac350d6f7abce5dc7137e5fb8994f6ffe2d0a253d835627412c3fd642b46880ce087470bcb098459b65cb9f38041b2bb4d

data/CHANGELOG.md

@@ -7,6 +7,59 @@ Notable changes to one_gadget, newest first. The format follows
 A change worth a user's attention lands with its entry under *Unreleased*;
 releases are cut by giving that section a version and a date.
 
+## v2.1.0 - 2026-09-05
+
+Two more architectures, and a libc that ships without section headers -- as an
+embedded one usually does -- can now be searched at all.
+
+### Added
+
+- RISC-V (RV64) support, alongside i386, amd64, aarch64 and arm ([#420], [#421],
+  [#422], [#423], [#425]). Every gadget it reports has been run under a debugger and
+  seen to spawn a shell ([#424]).
+- MIPS (32-bit o32) support, in both byte orders ([#448]), verified the same way.
+- Reads a libc that ships without section headers, as OpenWrt's musl does
+  ([#432]). Every architecture reports the same gadgets as the intact file.
+- A terminal `posix_spawn` whose symbol carries no version marker, as musl's
+  does not, is no longer passed over ([#432]).
+
+### Changed
+
+- The gem no longer carries gadgets for the three glibc 2.26 builds it shipped
+  ([#443]) -- no supported Ubuntu LTS ships 2.26. Those BuildIDs now answer from
+  the remote database.
+- Searching a MIPS libc takes 0.7s, was 2.3s ([#453]).
+- Searching the same file twice in one process reuses what the first search
+  found ([#455]).
+- Further search speedups, gadgets unchanged: objdump is asked what it supports
+  once per binary rather than once per command ([#454]), the scan locating calls
+  decodes far fewer words ([#456]), and a quarter as much is disassembled around
+  each call ([#457]).
+- Requires elftools >= 2.2.0 ([#442], [#465]), which reads a symbol table without
+  building an object per symbol. A libc with no section headers searches in 0.24s,
+  was 0.44s; one with its sections intact is unchanged.
+
+### Fixed
+
+- 67 more gadgets across the test corpus ([#460]): a backward walk threw away any
+  path that hit its length limit, so what a libc reported depended on how far
+  back it had been disassembled. Every new gadget was run under a debugger.
+- MIPS gadgets that could not work are no longer reported ([#460]). Entering at a
+  call leaves the callee without the address o32 requires in `t9`, and six such
+  gadgets were verified not to spawn a shell.
+- arm found nothing at all in a libc with no section headers ([#441]): Thumb code
+  was read as A32, symbol addresses were off by one, and literal-pool loads went
+  unresolved.
+- A libc with no section headers lost the calls at an address its symbol table
+  gives more than one name, such as `sigaction`/`__sigaction` -- 20 aarch64
+  gadgets ([#440]).
+- A libc with no section headers reported fewer gadgets on aarch64 and RISC-V
+  than the same libc intact -- 84 across the corpus ([#439]).
+- amd64 discarded every `execl` candidate before emulating it ([#434]). No fixture
+  reports a new gadget as a result, but one could.
+- A search could abort with `TypeError` where it should have dropped the
+  candidate ([#434]).
+
 ## v2.0.0 - 2026-08-29
 
 Reported gadgets are not offset-for-offset comparable with 1.x: constraints are
@@ -15,145 +68,140 @@ test corpus reports has been run under a debugger and seen to spawn a shell.
 
 ### Added
 
-- ARM32 support, alongside the existing amd64, i386 and aarch64 (#316).
+- ARM32 support, alongside the existing amd64, i386 and aarch64 ([#316]).
 - Output level 2, which lists every gadget including the ones lower levels drop
-  as duplicate or harder-to-satisfy (#350). `--level` is documented in the
-  README with what each level shows (#397).
+  as duplicate or harder-to-satisfy ([#350]). `--level` is documented in the
+  README with what each level shows ([#397]).
 - Aletheia, a verification harness that loads a libc under gdb (natively or
   through qemu-user), applies a constraint-satisfying plan, and requires a real
-  shell to run `ls /` before a gadget counts as real (#399). Run it with
+  shell to run `ls /` before a gadget counts as real ([#399]). Run it with
   `rake "aletheia:verify[level, target]"`. Every gadget the fixtures report is
   verified this way.
 - Gadgets say which file descriptors they close on the way to the exec, so a
-  reader knows when the spawned shell would lose its I/O (#371).
+  reader knows when the spawned shell would lose its I/O ([#371]).
 - `rake builds:refresh` rebuilds the shipped gadget database from what the
   Ubuntu archive publishes now, and `rake builds:check` fails when a shipped
-  entry has gone stale -- at most once a week, never on CI (#405, #406).
-- posix_spawn gadgets on aarch64 (#317), and the string a gadget reaches
-  through the GOT is shown rather than left opaque (#372).
+  entry has gone stale -- at most once a week, never on CI ([#405], [#406]).
+- posix_spawn gadgets on aarch64 ([#317]), and the string a gadget reaches
+  through the GOT is shown rather than left opaque ([#372]).
 
 ### Changed
 
-- **The gem ships a curated gadget database.** It carries the glibc of every
-  Ubuntu LTS in standard support plus every libc the tests cover -- 33 entries,
-  taking the packaged gem from 3.4MB to 112KB. Any other BuildID is fetched from
-  this repository on demand, as before, so nothing is unreachable; but an
-  offline `-b` for an arbitrary libc no longer answers from the gem alone
-  (#405).
+- **The gem ships a curated gadget database** -- 33 entries, taking the packaged
+  gem from 3.4MB to 112KB ([#405]). Any other BuildID is fetched on demand as
+  before, so an offline `-b` for an arbitrary libc no longer answers from the gem
+  alone.
 - **An output level means the same thing however a libc is looked up.** `-b`
   now honours `--level`, where it previously handed back whatever the database
   stored, and level 1 picks the same gadget however the emulator happened to
-  find it (#402).
+  find it ([#402]).
 - The database was regenerated; entries had been built before a year of
-  constraint work and reported gadgets their libc no longer produces (#405).
+  constraint work and reported gadgets their libc no longer produces ([#405]).
 - Constraints read consistently: pointers compare to `NULL` and values to hex,
-  never a bare `0` (#334), and readability is stated as `readable: <reg>`
-  (#344). A mask a gadget applies is named rather than given up on (#370), and
-  a value required to be zero scores the same however it is spelled (#377,
-  #401).
+  never a bare `0` ([#334]), and readability is stated as `readable: <reg>`
+  ([#344]). A mask a gadget applies is named rather than given up on ([#370]), and
+  a value required to be zero scores the same however it is spelled ([#377],
+  [#401]).
 - Emulation stops at the terminal `exec*` call instead of running past it
-  (#325), and a candidate whose path cannot hold is rejected (#359, #360).
+  ([#325]), and a candidate whose path cannot hold is rejected ([#359], [#360]).
 - Searching a libc got roughly five times faster: the test corpus at level 0
-  went from 42.5s to 8.6s (#388, #389, #390, #393, #394, #395, #396).
-- Requires Ruby >= 3.3 (#293) and elftools >= 2.0.0.
+  went from 42.5s to 8.6s ([#388], [#389], [#390], [#393], [#394], [#395], [#396]).
+- Requires Ruby >= 3.3 ([#293]) and elftools >= 2.0.0.
 
 ### Fixed
 
 - Gadgets that could not actually spawn a shell, each found by running them:
   a dereferenced pointer argument of a "safe" libc call went unconstrained
-  (#323, #340), a writable constraint was lost when its base was reassigned
-  (#341), frame-pointer stores did not require the frame be writable (#345),
-  an argv that disables shell execution was reported as usable (#348), an
-  uncontrolled dereference was not required to be readable (#354), and a slot
+  ([#323], [#340]), a writable constraint was lost when its base was reassigned
+  ([#341]), frame-pointer stores did not require the frame be writable ([#345]),
+  an argv that disables shell execution was reported as usable ([#348]), an
+  uncontrolled dereference was not required to be readable ([#354]), and a slot
   was read back as its entry value rather than what the gadget had put there
-  (#364).
+  ([#364]).
 - A GOT-base register the window establishes itself was seeded as a
-  precondition (#385), and the GOT-base constraint is now only stated where a
-  caller can actually put it -- in a register (#404).
+  precondition ([#385]), and the GOT-base constraint is now only stated where a
+  caller can actually put it -- in a register ([#404]).
 - Windowed disassembly lost gadgets whose branch predecessor sits after the
-  call, and could invent gadgets by falling through a window boundary (#391,
-  #392).
-- The "not glibc" check did not fire for aarch64 files (#311).
+  call, and could invent gadgets by falling through a window boundary ([#391],
+  [#392]).
+- The "not glibc" check did not fire for aarch64 files ([#311]).
 - **Certificates are verified again when fetching a gadget database entry.**
-  Verification had been switched off, and what comes back from that request is
-  written to a file and required as Ruby, so anyone able to answer it could run
-  code as the user.
-- Shipped entries reported fewer gadgets than reading the same libc as a file,
-  having been generated before the emulator learned to run `xchg`. They are
-  regenerated, and `rake builds:audit` now fails when an entry stops matching
+  Verification had been off, and the response is written to a file and required
+  as Ruby -- so anyone able to answer that request could run code as the user.
+- Shipped entries reported fewer gadgets than reading the same libc as a file.
+  They are regenerated, and `rake builds:audit` now fails when one stops matching
   its libc.
 - An architecture is recognised by the machine type its ELF header states, not
-  by the name the reader library prints for it -- the latter is that library's
-  wording and changed in elftools 2.0.0, which left every aarch64 and amd64 file
-  reading as an unknown architecture.
+  by the name elftools prints for it, whose wording changed in 2.0.0 and left
+  every aarch64 and amd64 file reading as unknown.
 
 ## v1.10.0 - 2024-10-04
 
-- Added JSON output, `--output-format json` (#225).
-- Requires Ruby >= 3.1 (#216).
+- Added JSON output, `--output-format json` ([#225]).
+- Requires Ruby >= 3.1 ([#216]).
 
 ## v1.9.0 - 2023-11-30
 
-- Sharper constraints for `argv` and `envp` (#206).
-- Added `--dwarf-start=0` so the output carries no local file path (#205).
+- Sharper constraints for `argv` and `envp` ([#206]).
+- Added `--dwarf-start=0` so the output carries no local file path ([#205]).
 
 ## v1.8.1 - 2022-03-25
 
 - Stack registers score higher on writable constraints, so easier gadgets rank
-  first (#190).
+  first ([#190]).
 
 ## v1.8.0 - 2022-03-20
 
-- posix_spawn call sites are treated as one-gadgets (#183).
-- amd64: loosened the restriction on gadgets reached by `jmp` (#178).
+- posix_spawn call sites are treated as one-gadgets ([#183]).
+- amd64: loosened the restriction on gadgets reached by `jmp` ([#178]).
 
 ## v1.7.4 - 2021-01-13
 
-- Writable constraints on the x86 architectures (#156).
+- Writable constraints on the x86 architectures ([#156]).
 
 ## v1.7.3 - 2019-10-25
 
-- Added the `--base` option (#100).
-- Constraints for XMM alignment, and stack alignment scores higher (#87).
+- Added the `--base` option ([#100]).
+- Constraints for XMM alignment, and stack alignment scores higher ([#87]).
 
 ## v1.7.2 - 2019-05-05
 
-- Added `--near`, ordering gadgets by distance from given functions (#76).
-- Introduced the CLI module (#81).
+- Added `--near`, ordering gadgets by distance from given functions ([#76]).
+- Introduced the CLI module ([#81]).
 
 ## v1.7.1 - 2019-04-19
 
-- Added gemspec metadata (#75).
+- Added gemspec metadata ([#75]).
 
 ## v1.7.0 - 2019-03-07
 
-- AArch64 support (#64).
-- Constraints are scored, so the easiest gadgets are reported first (#67).
+- AArch64 support ([#64]).
+- Constraints are scored, so the easiest gadgets are reported first ([#67]).
 
 ## v1.6.2 - 2018-10-25
 
-- one_gadget is usable as a library (#47).
+- one_gadget is usable as a library ([#47]).
 
 ## v1.6.1 - 2018-09-13
 
-- Improved update checking (#43) and custom error classes (#40).
+- Improved update checking ([#43]) and custom error classes ([#40]).
 
 ## v1.6.0 - 2018-04-28
 
-- Added the xmm instructions and glibc 2.27 builds (#27).
-- Added `--info`, showing what is known about a BuildID (#25).
+- Added the xmm instructions and glibc 2.27 builds ([#27]).
+- Added `--info`, showing what is known about a BuildID ([#25]).
 
 ## v1.5.0 - 2017-11-06
 
-- Emulator rework, and the build database is generated from libc files (#15).
+- Emulator rework, and the build database is generated from libc files ([#15]).
 
 ## v1.4.1 - 2017-11-01
 
-- Checks for a newer version automatically (#13).
+- Checks for a newer version automatically ([#13]).
 
 ## v1.4.0 - 2017-06-23
 
-- Warns when a BuildID is not found, and added Ubuntu 16.04/17.04 libcs (#9).
+- Warns when a BuildID is not found, and added Ubuntu 16.04/17.04 libcs ([#9]).
 
 ## v1.3.8 - 2017-05-26
 
@@ -166,7 +214,7 @@ test corpus reports has been run under a debugger and seen to spawn a shell.
 ## v1.3.6 - 2017-04-01
 
 - Added builds for glibc >= 2.19; a given libc file is no longer looked up
-  remotely (#6).
+  remotely ([#6]).
 
 ## v1.3.5 - 2017-03-27
 
@@ -215,3 +263,87 @@ test corpus reports has been run under a debugger and seen to spawn a shell.
 ## v0.1.0 - 2017-02-11
 
 - First release.
+
+[#6]: https://github.com/david942j/one_gadget/pull/6
+[#9]: https://github.com/david942j/one_gadget/pull/9
+[#13]: https://github.com/david942j/one_gadget/pull/13
+[#15]: https://github.com/david942j/one_gadget/pull/15
+[#25]: https://github.com/david942j/one_gadget/pull/25
+[#27]: https://github.com/david942j/one_gadget/pull/27
+[#40]: https://github.com/david942j/one_gadget/pull/40
+[#43]: https://github.com/david942j/one_gadget/pull/43
+[#47]: https://github.com/david942j/one_gadget/pull/47
+[#64]: https://github.com/david942j/one_gadget/pull/64
+[#67]: https://github.com/david942j/one_gadget/pull/67
+[#75]: https://github.com/david942j/one_gadget/pull/75
+[#76]: https://github.com/david942j/one_gadget/pull/76
+[#81]: https://github.com/david942j/one_gadget/pull/81
+[#87]: https://github.com/david942j/one_gadget/pull/87
+[#100]: https://github.com/david942j/one_gadget/pull/100
+[#156]: https://github.com/david942j/one_gadget/pull/156
+[#178]: https://github.com/david942j/one_gadget/pull/178
+[#183]: https://github.com/david942j/one_gadget/pull/183
+[#190]: https://github.com/david942j/one_gadget/pull/190
+[#205]: https://github.com/david942j/one_gadget/pull/205
+[#206]: https://github.com/david942j/one_gadget/pull/206
+[#216]: https://github.com/david942j/one_gadget/pull/216
+[#225]: https://github.com/david942j/one_gadget/pull/225
+[#293]: https://github.com/david942j/one_gadget/pull/293
+[#311]: https://github.com/david942j/one_gadget/pull/311
+[#316]: https://github.com/david942j/one_gadget/pull/316
+[#317]: https://github.com/david942j/one_gadget/pull/317
+[#323]: https://github.com/david942j/one_gadget/pull/323
+[#325]: https://github.com/david942j/one_gadget/pull/325
+[#334]: https://github.com/david942j/one_gadget/pull/334
+[#340]: https://github.com/david942j/one_gadget/pull/340
+[#341]: https://github.com/david942j/one_gadget/pull/341
+[#344]: https://github.com/david942j/one_gadget/pull/344
+[#345]: https://github.com/david942j/one_gadget/pull/345
+[#348]: https://github.com/david942j/one_gadget/pull/348
+[#350]: https://github.com/david942j/one_gadget/pull/350
+[#354]: https://github.com/david942j/one_gadget/pull/354
+[#359]: https://github.com/david942j/one_gadget/pull/359
+[#360]: https://github.com/david942j/one_gadget/pull/360
+[#364]: https://github.com/david942j/one_gadget/pull/364
+[#370]: https://github.com/david942j/one_gadget/pull/370
+[#371]: https://github.com/david942j/one_gadget/pull/371
+[#372]: https://github.com/david942j/one_gadget/pull/372
+[#377]: https://github.com/david942j/one_gadget/pull/377
+[#385]: https://github.com/david942j/one_gadget/pull/385
+[#388]: https://github.com/david942j/one_gadget/pull/388
+[#389]: https://github.com/david942j/one_gadget/pull/389
+[#390]: https://github.com/david942j/one_gadget/pull/390
+[#391]: https://github.com/david942j/one_gadget/pull/391
+[#392]: https://github.com/david942j/one_gadget/pull/392
+[#393]: https://github.com/david942j/one_gadget/pull/393
+[#394]: https://github.com/david942j/one_gadget/pull/394
+[#395]: https://github.com/david942j/one_gadget/pull/395
+[#396]: https://github.com/david942j/one_gadget/pull/396
+[#397]: https://github.com/david942j/one_gadget/pull/397
+[#399]: https://github.com/david942j/one_gadget/pull/399
+[#401]: https://github.com/david942j/one_gadget/pull/401
+[#402]: https://github.com/david942j/one_gadget/pull/402
+[#404]: https://github.com/david942j/one_gadget/pull/404
+[#405]: https://github.com/david942j/one_gadget/pull/405
+[#406]: https://github.com/david942j/one_gadget/pull/406
+[#420]: https://github.com/david942j/one_gadget/pull/420
+[#421]: https://github.com/david942j/one_gadget/pull/421
+[#422]: https://github.com/david942j/one_gadget/pull/422
+[#423]: https://github.com/david942j/one_gadget/pull/423
+[#424]: https://github.com/david942j/one_gadget/pull/424
+[#425]: https://github.com/david942j/one_gadget/pull/425
+[#432]: https://github.com/david942j/one_gadget/pull/432
+[#434]: https://github.com/david942j/one_gadget/pull/434
+[#439]: https://github.com/david942j/one_gadget/pull/439
+[#440]: https://github.com/david942j/one_gadget/pull/440
+[#441]: https://github.com/david942j/one_gadget/pull/441
+[#442]: https://github.com/david942j/one_gadget/pull/442
+[#443]: https://github.com/david942j/one_gadget/pull/443
+[#448]: https://github.com/david942j/one_gadget/pull/448
+[#453]: https://github.com/david942j/one_gadget/pull/453
+[#454]: https://github.com/david942j/one_gadget/pull/454
+[#455]: https://github.com/david942j/one_gadget/pull/455
+[#456]: https://github.com/david942j/one_gadget/pull/456
+[#457]: https://github.com/david942j/one_gadget/pull/457
+[#460]: https://github.com/david942j/one_gadget/pull/460
+[#465]: https://github.com/david942j/one_gadget/pull/465

data/README.md

@@ -11,12 +11,13 @@
 
 ## OneGadget
 
-When playing ctf pwn challenges we usually need the one-gadget RCE (remote code execution),
-which leads to call `execve('/bin/sh', NULL, NULL)`.
+When solving CTF pwn challenges we usually want a one-gadget RCE: a single address in
+libc that, jumped to, calls `execve("/bin/sh", NULL, NULL)`.
 
-This gem provides such gadgets finder, no need to use objdump or IDA-pro every time like a fool :wink:
+This gem finds them for you, so you don't have to dig through objdump or IDA Pro every
+time :wink:
 
-To use this tool, type `one_gadget /path/to/libc` in command line and enjoy the magic :laughing:
+Point it at a libc -- `one_gadget /path/to/libc` -- and enjoy the magic :laughing:
 
 ## Installation
 
@@ -25,18 +26,19 @@ Available on RubyGems.org!
 $ gem install one_gadget
 ```
 
-Note: requires ruby version >= 2.1.0, you can use `ruby --version` to check.
-
 ## Supported Architectures
 
 - [x] i386
 - [x] amd64 (x86-64)
 - [x] aarch64 (ARMv8)
 - [x] arm (ARMv7, A32/Thumb-2)
+- [x] riscv64 (RV64GC)
+- [x] mips (MIPS32 o32, big- and little-endian)
 
 ## Implementation
 
-OneGadget uses symbolic execution to find the constraints of gadgets to be successful.
+OneGadget symbolically executes the code around each candidate address to work out what
+has to hold for the gadget to work.
 
 Gadgets are found by walking the control-flow graph backward from each `exec`/`posix_spawn`
 call, following conditional branches both ways. When a gadget is only reachable if a branch is
@@ -144,17 +146,17 @@ BuildID is fetched from this repository, which keeps them all.
 
 ##### Why
 
-Consider this scenario when exploiting:
-1. Able to write on GOT (Global Offset Table)
-2. Base address of libc is *unknown*
+Consider this situation while exploiting:
+1. You can write to the GOT (Global Offset Table).
+2. The base address of libc is *unknown*.
 
-In this scenario you can choose to write two low-byte on a GOT entry with one-gadget's two low-byte.
-If the function offset on GOT is close enough with the one-gadget,
-you will have at least 1/16 chance of success.
+Here you can overwrite the low two bytes of a GOT entry with the low two bytes of a
+one-gadget. If the function sits close enough to the gadget, only one nibble is left to
+guess -- at least a 1 in 16 chance of success.
 
 ##### Usage
 
-Reorder gadgets according to the distance of given functions.
+Sorts the gadgets by how far they are from the functions you name.
 
 ```bash
 $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so --near exit,mkdir
@@ -204,7 +206,7 @@ $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so --n
 ```
 ![near](https://github.com/david942j/one_gadget/blob/master/examples/near.png?raw=true)
 
-Regular expression is acceptable.
+Regular expressions work too.
 ```bash
 $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so --near 'write.*' --raw
 # [OneGadget] Gadgets near writev(0x1144a0):
@@ -216,7 +218,7 @@ $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so --n
 
 ```
 
-Pass an ELF file as the argument, OneGadget will take all GOT functions for processing.
+Pass an ELF file instead, and OneGadget uses every function in its GOT.
 ```bash
 $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so --near spec/data/test_near_file.elf --raw
 # [OneGadget] Gadgets near exit(0x46a70):
@@ -573,9 +575,81 @@ $ one_gadget spec/data/arm-libc-2.39.so
 
 ```
 
+##### RISC-V (RV64)
+
+```bash
+$ one_gadget spec/data/riscv64-libc-2.39.so
+# 0x9f73a execve("/bin/sh", s1, a2)
+# constraints:
+#   [s1] == NULL || s1 == NULL || s1 is a valid argv
+#   [a2] == NULL || a2 == NULL || a2 is a valid envp
+#
+# 0x9f73c execve("/bin/sh", a1, a2)
+# constraints:
+#   [a1] == NULL || a1 == NULL || a1 is a valid argv
+#   [a2] == NULL || a2 == NULL || a2 is a valid envp
+#
+# 0x9f778 execve("/bin/sh", s1, s2)
+# constraints:
+#   [s1] == NULL || s1 == NULL || s1 is a valid argv
+#   [s2] == NULL || s2 == NULL || s2 is a valid envp
+#
+# 0xb5adc posix_spawn(sp+0x44, "/bin/sh", [sp+0x30], 0, sp+0x50, environ)
+# constraints:
+#   [sp+0x50] == NULL || {[sp+0x50], [sp+0x58], [sp+0x60], [sp+0x68], ...} is a valid argv
+#   [sp+0x30] == NULL || (s32)[[sp+0x30]+0x4] <= 0x0
+
+```
+
+##### MIPS
+
+Big-endian is as common as little-endian here, and both are read. This one is
+OpenWrt's musl for ath79, which ships with no section headers -- the shape a
+router's libc usually arrives in.
+
+```bash
+$ one_gadget spec/data/mips-musl-1.2.4.so
+# 0x668e8 posix_spawn(sp+0x20, "/bin/sh", 0, s0, sp+0x28, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   {"sh", "-c", s1, NULL} is a valid argv
+#   s0 == NULL || (u16)[s0] == 0x0
+#
+# 0x668ec posix_spawn(sp+0x20, "/bin/sh", 0, s0, sp+0x28, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   {"sh", "-c", [sp+0x30], NULL} is a valid argv
+#   s0 == NULL || (u16)[s0] == 0x0
+#
+# 0x668f0 posix_spawn(sp+0x20, "/bin/sh", 0, a3, sp+0x28, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   {"sh", "-c", [sp+0x30], NULL} is a valid argv
+#   a3 == NULL || (u16)[a3] == 0x0
+#
+# 0x668f4 posix_spawn(sp+0x20, "/bin/sh", 0, a3, sp+0x28, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   v0-0x7c70 == NULL || {v0-0x7c70, "-c", [sp+0x30], NULL} is a valid argv
+#   a3 == NULL || (u16)[a3] == 0x0
+#
+# 0x77b44 posix_spawn(sp+0x20, "/bin/sh", s2, 0, sp+0x2c, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   {"sh", "-c", s7, NULL} is a valid argv
+#   s2 == NULL || (s32)[s2+0x4] <= 0x0
+#
+# 0x77b48 posix_spawn(sp+0x20, "/bin/sh", s2, 0, sp+0x2c, environ)
+# constraints:
+#   gp is the GOT address of libc
+#   v0-0x7c70 == NULL || {v0-0x7c70, "-c", s7, NULL} is a valid argv
+#   s2 == NULL || (s32)[s2+0x4] <= 0x0
+
+```
+
 #### Combine with Script
-Pass your exploit script as `one_gadget`'s arguments, it can
-try all gadgets one by one, so you don't need to try every possible gadgets manually.
+Pass your exploit script to `one_gadget` and it runs the script once per gadget, so you
+don't have to work through them by hand.
 
 ```bash
 $ one_gadget spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so -s 'echo "offset ->"'
@@ -589,7 +663,7 @@ require 'one_gadget'
 OneGadget.gadgets(file: 'spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so')
 #=> [932657, 932660, 932896, 1080554]
 
-# or in shorter way
+# or, more briefly
 one_gadget('spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so', level: 1)
 #=> [335352, 335403, 335410, 335417, 335424, 335429, 335445, 335450, 541029, 541036, 541043, 541046, 541051, 541056, 541068, 541074, 541081, 541088, 932657, 932660, 932896, 933158, 933256, 933264, 933266, 933273, 933280, 933335, 933345, 1078759, 1078769, 1080554]
 
@@ -611,7 +685,7 @@ one_gadget('spec/data/libc-2.31-9fdb74e7b217d06c93172a8243f8547f947ee6d1.so')
 ```
 
 ## Make OneGadget Better
-Any suggestion or feature request is welcome! Feel free to send a pull request.
+Any suggestion or feature request is welcome, and pull requests even more so!
 
-Please let me know if you find any libc that make OneGadget fail to find gadgets.
-And, if you like this work, I'll be happy to be [starred](https://github.com/david942j/one_gadget/stargazers) :grimacing:
+Please let me know if you come across a libc OneGadget finds nothing in. And if you like
+this work, I'd be happy to be [starred](https://github.com/david942j/one_gadget/stargazers) :grimacing:

data/lib/one_gadget/abi.rb

@@ -14,6 +14,17 @@ module OneGadget
     # Registers of AArch64.
     AARCH64 = %w[xzr wzr sp] + 0.upto(30).map { |i| ["x#{i}", "w#{i}"] }.flatten
 
+    # Registers of RISC-V (RV64), by the ABI names objdump prints: it emits neither
+    # the numbered +x0+-+x15+ names nor +fp+ for +s0+, so neither is listed.
+    RISCV64 = %w[zero ra sp gp tp] + 0.upto(6).map { |i| "t#{i}" } +
+              0.upto(11).map { |i| "s#{i}" } + 0.upto(7).map { |i| "a#{i}" }
+
+    # Registers of MIPS (32-bit), by the names objdump prints: it emits the ABI
+    # names rather than the numbered +$0+-+$31+, and +fp+ rather than +s8+.
+    MIPS = %w[zero at v0 v1 gp sp fp ra] +
+           0.upto(3).map { |i| "a#{i}" } + 0.upto(9).map { |i| "t#{i}" } +
+           0.upto(7).map { |i| "s#{i}" } + 0.upto(1).map { |i| "k#{i}" }
+
     # Registers of ARM (32-bit).
     # objdump never prints the numbered name of a register that has a role name:
     # +r10+-+r15+ always appear as +sl+/+fp+/+ip+/+sp+/+lr+/+pc+, so those are
@@ -31,7 +42,12 @@ module OneGadget
               8.upto(15).map { |i| ["r#{i}d", "r#{i}"] }).to_h,
       i386: {},
       aarch64: 0.upto(30).to_h { |i| ["w#{i}", "x#{i}"] }.merge('wzr' => 'xzr'),
-      arm: {}
+      arm: {},
+      # RISC-V names no part of a register: its 32-bit operations are instructions
+      # of their own (+addiw+, +sext.w+), each writing the whole register.
+      riscv64: {},
+      # MIPS names no part of a register either.
+      mips: {}
     }.freeze
 
     # Registers a call may destroy, per each ABI's calling convention: the return
@@ -49,11 +65,19 @@ module OneGadget
       aarch64: (0.upto(7).to_a + 9.upto(18).to_a).map { |i| "x#{i}" },
       # AAPCS: r0-r3 arguments and return, ip (r12) the intra-procedure scratch,
       # and lr, which the call itself overwrites with the return address.
-      arm: %w[r0 r1 r2 r3 ip lr]
+      arm: %w[r0 r1 r2 r3 ip lr],
+      # RISC-V LP64: a0-a7 arguments (a0/a1 also the return), t0-t6 temporaries,
+      # and ra, which the call itself overwrites with the return address.
+      riscv64: %w[ra] + 0.upto(7).map { |i| "a#{i}" } + 0.upto(6).map { |i| "t#{i}" },
+      # o32: v0/v1 the return, a0-a3 arguments, t0-t9 temporaries, at the
+      # assembler's scratch, and ra, which the call itself overwrites. gp goes
+      # with them: PIC code reloads it from the stack after every call, because
+      # the callee establishes its own.
+      mips: %w[at v0 v1 gp ra] + 0.upto(3).map { |i| "a#{i}" } + 0.upto(9).map { |i| "t#{i}" }
     }.freeze
 
     # The register each ABI leaves an integer return value in.
-    RETURN_REGISTER = { amd64: 'rax', i386: 'eax', aarch64: 'x0', arm: 'r0' }.freeze
+    RETURN_REGISTER = { amd64: 'rax', i386: 'eax', aarch64: 'x0', arm: 'r0', riscv64: 'a0' }.freeze
 
     module_function
 
@@ -81,10 +105,22 @@ module OneGadget
       ARM
     end
 
+    # Registers' name of RISC-V (RV64).
+    # @return [Array<String>] List of registers.
+    def riscv64
+      RISCV64
+    end
+
+    # Registers' name of MIPS (32-bit).
+    # @return [Array<String>] List of registers.
+    def mips
+      MIPS
+    end
+
     # Returns all names of registers.
     # @return [Array<String>] List of registers.
     def all
-      amd64 + aarch64 + arm
+      amd64 + aarch64 + arm + riscv64 + mips
     end
 
     # Checks if the register is a stack-related pointer.
@@ -92,7 +128,7 @@ module OneGadget
     #   Register's name.
     # @return [Boolean] +true+ if +reg+ is a stack or frame pointer (e.g. +rsp+, +rbp+, +sp+).
     def stack_register?(reg)
-      %w[esp ebp rsp rbp sp x29].include?(reg)
+      %w[esp ebp rsp rbp sp x29 s0].include?(reg)
     end
   end
 end