{"id":29224108,"url":"https://github.com/redthing1/w1tn3ss","last_synced_at":"2026-05-17T01:39:16.996Z","repository":{"id":302516161,"uuid":"1012267654","full_name":"redthing1/w1tn3ss","owner":"redthing1","description":"dynamic binary instrumentation, analysis, and patching framework","archived":false,"fork":false,"pushed_at":"2025-07-18T10:50:28.000Z","size":1654,"stargazers_count":54,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T12:38:55.647Z","etag":null,"topics":["binary-analysis","binary-instrumentation","binary-patching","dbi","dynamic-analysis","dynamic-binary-instrumentation","function-hooking","hooking","instrumentation","llvm","patching","qbdi","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redthing1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T04:45:35.000Z","updated_at":"2025-07-18T05:02:34.000Z","dependencies_parsed_at":"2025-07-18T10:32:35.406Z","dependency_job_id":"554f7cf2-beea-415a-ba7f-0eaade17bbc3","html_url":"https://github.com/redthing1/w1tn3ss","commit_stats":null,"previous_names":["redthing1/w1tn3ss"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/redthing1/w1tn3ss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redthing1%2Fw1tn3ss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redthing1%2Fw1tn3ss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redthing1%2Fw1tn3ss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redthing1%2Fw1tn3ss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redthing1","download_url":"https://codeload.github.com/redthing1/w1tn3ss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redthing1%2Fw1tn3ss/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266764204,"owners_count":23980529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-analysis","binary-instrumentation","binary-patching","dbi","dynamic-analysis","dynamic-binary-instrumentation","function-hooking","hooking","instrumentation","llvm","patching","qbdi","reverse-engineering"],"created_at":"2025-07-03T06:00:23.391Z","updated_at":"2026-05-17T01:39:16.990Z","avatar_url":"https://github.com/redthing1.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# w1tn3ss\n\na cross-platform framework for binary analysis/instrumentation.\nfully supports **linux**, **macos**, **windows** across `x86`, `x64`, and `arm64`.\n\nbuilt to enable flexible auditing, tracing, analysis, instrumentation of binaries across platforms.\n\nhighlights:\n+ **record-and-replay** (experimental): **record** the execution of a process, and **replay** the trace on any platform; with full time-travel\n+ **code coverage**: automatic gathering of code coverage/block hits for any instrumentable binary\n+ **declarative patching**: scriptable, ergonomic, declarative binary patching\n\n## features\n\n+ dynamic instrumentation tracers\n  + code coverage: `w1cov`\n  + record and replay `w1rewind`/`w1replay`\n  + call tracing: `w1xfer`\n  + scripting: `w1script`\n  + memory: `w1mem`\n  + process dump: `w1dump`\n+ signature scanning and binary patching (`p1ll`/`p1llx`)\n+ scriptable with js/lua\n+ reusable binary instrumentation infra\n  + cross-platform library injection: `w1nj3ct`\n  + cross-platform function hooking: `w1h00k`\n  + calling convention/abi modeling for many platforms\n\n## build\n\ninitialize submodules:\n```sh\ngit submodule update --init --recursive\n```\n\nbuild:\n```sh\ncmake -G Ninja -B build-release -DCMAKE_BUILD_TYPE=Release\ncmake --build build-release --parallel\n```\n\nsee [doc/build.md](./doc/build.md) for features and platform-specific instructions.\n\n## `w1tool` guide\n\nthis is a brief guide to using `w1tool`, a ready-to-use command-line for running tracers\n\n### coverage \u0026 tracing\n\ncode coverage helps us learn what code in a program gets run and how often. the `w1cov` tracer is purpose-built to collect detailed code coverage information, with only modest performance overhead.\n\nthe drcov format is ideal for coverage tracing, as it includes metadata about loaded modules. `w1cov` also supports collecting data in a superset of the drcov format, which also records hit counts of coverage units. this can be useful to record the execution frequency of a block.\nmy other project [covtool](https://github.com/redthing1/covtool) provides a powerful tool for viewing, editing, and browsing coverage traces.\n\ncollect coverage in drcov format using `w1cov`:\n```sh\n# macos/linux\n./build-release/bin/w1tool cover -s ./build-release/bin/samples/programs/simple_demo\n# windows\n.\\build-release\\bin\\w1tool.exe cover -s .\\build-release\\bin\\samples\\programs\\simple_demo.exe\n```\n\noutput will resemble:\n```\n[w1cov.preload] [inf] coverage data export completed      output_file=simple_demo_coverage.drcov\n[w1cov.tracer] [inf] coverage collection completed       coverage_units=59 modules=50 total_hits=71\n```\n\nthe default block tracing mode is significantly more efficient than per-instruction tracing as it requires less frequent callback interruptions. however, qbdi detects basic blocks dynamically, so recorded block boundaries may differ from those detected by static analysis tools. this usually isn't an issue, as you can script your disassembler to fix any discrepancies when marking basic block coverage.\n\nyou can also trace coverage in the same drcov format by passing `--inst` to `cover`, which will use instruction callbacks.\n\nfor a more primitive form of tracing which simply records the instruction pointer, use `w1trace`:\n```sh\n# macos/linux\n./build-release/bin/w1tool tracer -n w1trace -c output=simple_demo_trace.txt -s ./build-release/bin/samples/programs/simple_demo\n# windows\n.\\build-release\\bin\\w1tool.exe tracer -n w1trace -c output=simple_demo_trace.txt -s .\\build-release\\bin\\samples\\programs\\simple_demo.exe\n```\n\n### real-time api call analysis\n\noften it is valuable to learn what system library apis a program calls. for example, we can learn a lot about the behavior of a program by observing its calls to `libc`. the `w1xfer` tracer, powered by qbdi's [`ExecBroker`](https://qbdi.readthedocs.io/en/stable/tutorial_ExecBrokerEvent.html) mechanism, can intercept and observe calls from and returns back to instrumented code.\n\nin addition to detecting calls crossing the instrumentation boundary, `w1xfer` resolves the symbols of these calls, and extracts function arguments based on platform-specific calling convention models. this allows for very rich interception and tracing of the arguments and return values of common library apis.\n\ntrace api calls in real time with `w1xfer`:\n```sh\n# macos/linux\n./build-release/bin/w1tool -v tracer -n w1xfer -c analyze_apis=true -c output=test_transfers.jsonl -s ./build-release/bin/samples/programs/simple_demo\n# windows\n.\\build-release\\bin\\w1tool.exe -v tracer -n w1xfer -c analyze_apis=true -c output=test_transfers.jsonl -s .\\build-release\\bin\\samples\\programs\\simple_demo.exe\n```\n\noutput will resemble:\n```sh\nregistered platform conventions     platform=aarch64 count=1\n...\ncall=malloc(size=64) category=Heap module=libsystem_malloc.dylib\nreturn=malloc() = 0x600003b982c0 raw_value=105553178755776 module=libsystem_malloc.dylib\n...\ncall=puts(s=\"simple demo finished\") category=I/O module=libsystem_c.dylib\nsimple demo finished\nreturn=puts() = 10 raw_value=10 module=libsystem_c.dylib\ncall=intercept_exit(?) category= module=w1xfer_qbdipreload.dylib\n```\n\nas seen above, this can successfully intercept calls to many common `libc` apis!\n\n### scripting\n\nw1tn3ss supports writing custom tracers in luajit through the `w1script` tracer.\nscripts can hook various callbacks and directly access vm state, registers, and memory.\n\nhere's a simple instruction tracer:\n```lua\nlocal instruction_count = 0\n\nlocal tracer = {}\n\nlocal function on_instruction(vm, gpr, fpr)\n    instruction_count = instruction_count + 1\n\n    local pc = w1.reg.pc(gpr) or 0\n    local disasm = w1.inst.disasm(vm) or \"\u003cunknown\u003e\"\n\n    w1.log.info(w1.util.format_address(pc) .. \": \" .. disasm)\n    return w1.enum.vm_action.CONTINUE\nend\n\nfunction tracer.init()\n    w1.on(w1.event.INSTRUCTION_PRE, on_instruction)\nend\n\nfunction tracer.shutdown()\n    w1.log.info(\"traced \" .. instruction_count .. \" instructions\")\nend\n\nreturn tracer\n```\n\nrun it:\n```sh\n# macos/linux\n./build-release/bin/w1tool tracer -n w1script -c script=./scripts/w1script/instruction_tracer.lua -s ./build-release/bin/samples/programs/simple_demo\n# windows\n.\\build-release\\bin\\w1tool.exe tracer -n w1script -c script=./scripts/w1script/instruction_tracer.lua -s .\\build-release\\bin\\samples\\programs\\simple_demo.exe\n```\n\nthis will produce a trace of disassembled instructions as they are executed.\n\nsee the [example scripts](./scripts/w1script/), which demonstrate memory tracing, coverage collection, and api interception.\n\n## record and replay\n\nthe duo `w1rewind` + `w1replay` provides record/replay functionality.\ntraces can be captured with various levels of detail, trading performance/size for fidelity.\n\nrecord a rewind trace:\n```sh\n./build-release/bin/w1tool rewind -s -o /tmp/trace.w1r -- ./build-release/bin/samples/programs/simple_demo\n```\n\ninspect:\n```sh\n./build-release/bin/w1replay inspect -t /tmp/trace.w1r --thread 1 --count 10\n```\n\ntips:\n- to increase trace detail, use `--flow instruction --reg-deltas --mem-access reads_writes --mem-values`\n- to capture stack bytes, use `--stack-window frame --stack-snapshot-interval 1`\n- run a gdb rsp server with `w1replay server -t \u003ctrace\u003e --gdb 127.0.0.1:5555`\n\n## `p1ll` guide\n\npatching binaries is an essential part of a reversing or cracking workflow. `p1ll` is a portable signature scanning and patching library that can patch binaries statically on disk or dynamically in memory.\n`p1llx` provides a nifty command line to run and inspect patches.\n\n### static patching\n\npatch a binary on disk:\n```sh\n./build-release/bin/p1llx -vv cure -c ./patch_script.lua -i ./target_binary -o ./patched_binary\n```\n\non macos, statically patched binaries require codesigning:\n```sh\ncodesign -fs - ./patched_binary\n```\n\nthe `d0ct0r.py` script provides intelligent patch development features; it automatically backs up the input file, and handles permissions and codesigning.\n\n### dynamic patching\n\npatch a running process in memory:\n```sh\n# spawn new process\n./build-release/bin/p1llx -vv poison -c ./patch_script.lua -s ./target_binary\n# attach to existing process\n./build-release/bin/p1llx -vv poison -c ./patch_script.lua -n target_binary\n```\n\n### patch scripts\n\n`p1ll` uses scripts to define signatures and patching. this is designed to be used through the declarative `auto_cure` api, which can define platform-specific signatures and patches.\n\nexample patch script:\n```lua\n-- validation signature\nlocal SIG_DEMO_NAME = p1.sig(p1.str2hex(\"Demo Program\"))\n-- unique signature for this string\nlocal SIG_ANGERY = p1.sig(p1.str2hex(\"Angery\"), {single = true})\n\n-- find a function by signature (optional module filter)\nlocal SIG_CHECK_LICENSE_WIN_X64 = p1.sig([[\n  4885c0          -- test rax, rax\n  74??            -- je \u003coffset\u003e\n  b001            -- mov al, 1\n]], {filter = \"demo_program\"})\n\n-- patch: fall through the check by nopping it\nlocal FIX_CHECK_LICENSE_WIN_X64 = [[\n  ??????\n  9090            -- nop nop\n  ????\n]]\n\nlocal meta = { -- declarative patch\n  name = \"demo_program\",\n  platforms = {\"windows:x64\"}, -- platforms supported by this patch\n  sigs = {\n    [\"*\"] = { -- wildcard signatures are checked on all platforms\n      SIG_DEMO_NAME,\n      SIG_ANGERY,\n    }\n  },\n  patches = {\n    [\"windows:x64\"] = { -- patch only on windows:x64\n        p1.patch(SIG_CHECK_LICENSE_WIN_X64, 0, FIX_CHECK_LICENSE_WIN_X64)\n    },\n    [\"*\"] = { -- wildcard patches are used on all platforms\n      p1.patch(SIG_ANGERY, 0, p1.str2hex(\"Happey\"))\n    }\n  }\n}\n\nfunction cure()\n  return p1.auto_cure(meta)\nend\n```\n\nkey concepts:\n- `p1.sig()`: define byte patterns (with `??` for wildcards)\n- `p1.patch()`: specify signature, offset, and replacement\n- `meta` table: organize sigs and patches by platform\n\noptional python bindings are available under `src/p1ll/bindings/python`. see the [python bindings guide](./doc/p1ll_python.md) and samples under `scripts/python`.\n\n`p1ll` is an excellent and powerful tool for binary modification!\nsee the [guide](./doc/p1lljs.md)\n\n## acknowledgements\n\n+ many thanks to quarkslab for [qbdi](https://github.com/QBDI/QBDI) and [lief](https://github.com/lief-project/LIEF).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredthing1%2Fw1tn3ss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredthing1%2Fw1tn3ss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredthing1%2Fw1tn3ss/lists"}