{"id":18375558,"url":"https://github.com/riboseinc/retrace","last_synced_at":"2025-04-06T20:31:05.313Z","repository":{"id":21501385,"uuid":"92924805","full_name":"riboseinc/retrace","owner":"riboseinc","description":"retrace is a versatile security vulnerability / bug discovery tool through monitoring and modifying the behavior of compiled binaries on Linux, OpenBSD/FreeBSD/NetBSD (shared object) and macOS (dynamic library).","archived":false,"fork":false,"pushed_at":"2022-02-14T08:16:21.000Z","size":1126,"stargazers_count":61,"open_issues_count":50,"forks_count":19,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-05T23:32:29.450Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riboseinc.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-31T08:44:14.000Z","updated_at":"2024-11-20T16:11:37.000Z","dependencies_parsed_at":"2022-08-02T22:45:25.257Z","dependency_job_id":null,"html_url":"https://github.com/riboseinc/retrace","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Fretrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Fretrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Fretrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Fretrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riboseinc","download_url":"https://codeload.github.com/riboseinc/retrace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547236,"owners_count":20956525,"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","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":[],"created_at":"2024-11-06T00:19:24.298Z","updated_at":"2025-04-06T20:31:05.002Z","avatar_url":"https://github.com/riboseinc.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"= Retrace\n\nimage:https://github.com/riboseinc/retrace/actions/workflows/ubuntu.yml/badge.svg[Ubuntu, link=https://github.com/riboseinc/retrace/actions/workflows/ubuntu.yml]\nimage:https://github.com/riboseinc/retrace/actions/workflows/macos.yml/badge.svg[macOS, link=https://github.com/riboseinc/retrace/actions/workflows/macos.yml]\nimage:https://github.com/riboseinc/retrace/actions/workflows/windows.yml/badge.svg[Windows, link=https://github.com/riboseinc/retrace/actions/workflows/windows.yml]\nimage:https://img.shields.io/cirrus/github/riboseinc/retrace?label=freebsd\u0026logo=cirrus%20ci[\"FreeBSD\", link=\"https://cirrus-ci.com/github/riboseinc/retrace\"]\nimage:https://github.com/riboseinc/retrace/actions/workflows/nix.yml/badge.svg[nix, link=https://github.com/riboseinc/retrace/actions/workflows/nix.yml]\nimage:https://github.com/riboseinc/retrace/actions/workflows/checkpatch.yml/badge.svg[checkpatch, link=https://github.com/riboseinc/retrace/actions/workflows/checkpatch.yml]\nimage:https://img.shields.io/coverity/scan/12840.svg[Coverity Scan, link=https://scan.coverity.com/projects/riboseinc-retrace]\n\n`retrace` is a versatile security vulnerability / bug discovery tool\nthrough monitoring and modifying the behavior of compiled binaries on\nLinux, OpenBSD/FreeBSD/NetBSD (shared object) and macOS (dynamic library).\n\n`retrace` can be used to assist reverse engineering / debugging\ndynamically-linked ELF (Linux/OpenBSD/FreeBSD/NetBSD) and\nMach-O (macOS) binary executables.\n\n\n== Retrace v2\n\nWork in a new version of `retrace` is ongoing, all the documentation is only about `retrace` v1, early documentation for\n`retrace` v2 is link:READMEv2.adoc[here].\n\nIf you want to give it a go despiste the lack of documentation you can enable it in the build using `./configure --enable-v2`.\n\n\n== Who is Ribose?\n\nWe are https://www.ribose.com[Ribose], the secure sharing company. We believe privacy and security form the foundation of liberty.\n\nOur goal is to empower individuals and organizations alike to freely communicate and achieve productivity for the greater good, through our deep security and technology expertise, creating highly-secure products validated to the world’s most stringent requirements and regulations.\n\nWe created `retrace` to aid developers and security researchers to develop better code that leads the world to a better place.\n\n\n== Contacting The Organizer\n\nThe Ribose `retrace` team can be reached at retrace@ribose.com. We will answer questions to the best of our efforts.\n\n\n\n\n= Building retrace\n\nFor platforms with Autotools, the generic way to build and install\n`retrace` is:\n\n[source,console]\n----\n$ sh autogen.sh\n$ ./configure --enable-tests\n$ make\n$ make check\n$ sudo make install\n----\n\nYou need Autotools installed in your system (`autoconf`, `automake`,\n`libtool`, `make`, `gcc` packages).\n\nOpenSSL library and headers are automatically detected, you can specify\nan optional flag `--with-openssl=[PATH]` (to use a non-standard OpenSSL\ninstallation root).\n\nIn order to build tests: run configure script with `--enable-tests`\nflag.  To build cmocka tests you can specify an optional flag\n`--with-cmocka=[PATH]` (to use a non-standard cmocka installation root).\n\nBy the default `retrace` is installed in `/usr/bin` directory.\n\n\n= Running retrace\n\n[source,console]\n----\n$ retrace [-f configuration file location] \u003cexecutable\u003e\n----\n\nConfiguration file path can be set either in `RETRACE_CONFIG`\nenvironment variable or by specifying `-f [path]` command line argument.\n\n= Interactive user interface\n\nInteractive control over retrace can be exercised using cli control feature\nover pseudo terminal (currently available on Linux platforms only).\nIn order to enable the feature, export `RETRACE_CLI=1` environment variable.\nWhen enabled, the name of the pseudo device will be printed with a 3 seconds delay during the start up:\n\n[source,console]\n----\nRETRACE-INIT [INFO]: cli pts is at: /dev/pts/1\n----\n\nAfter that, a terminal emulator can be connected to that device:\n\n[source,console]\n----\nminicom -p /dev/pts/1\n----\n\nHit the main Enter key, and the command menu with prompt will appear:\n\n[source,console]\n----\nWelcome to minicom 2.7.1\n\nOPTIONS: I18n\nCompiled on Aug 13 2017, 15:25:34.\nPort /dev/tty8, 13:10:04\n\nPress CTRL-A Z for help on special keys\n\n\nFailed to get command id, retry\nRetrace command menu\n\\--------------------\n[0] \u003cMain\u003e Say Hi\n[1] \u003cMain\u003e Terminate process\nEnter command id\u003e\u003e\n----\n\nThe following are the characteristics of the terminal:\n\n* Raw mode - no line processing will be performed on the input.\n* Characters are echoed back.\n* Main enter key is used to mark the end of input.\n\n== Note to developers\nIn order to expose interactive commands from your module, use API defined in retrace_cli.h.\nTo register commads use cli_register_command_blk(). To interact with the user use cli_printf() and cli_scanf().\nRefer to retrace_main.c for reference.\n\n= Examples\n\n== Trace usage example\n\nIn its most basic form `retrace` will just print all calls that are made\n(and that are supported by retrace):\n\n[source,console]\n----\n$ retrace /usr/bin/id\n(2051) geteuid();\n(2051) getuid();\n(2051) getegid();\n(2051) getgid();\n(2051) fopen(\"/etc/passwd\", \"rce\"); [3]\n(2051) fclose(3);\n(2051) fopen(\"/etc/group\", \"rce\"); [3]\n(2051) fclose(3);\n(2051) fopen(\"/etc/group\", \"rce\"); [3]\n(2051) fclose(3);\n(2051) fopen(\"/etc/group\", \"rce\"); [3]\n(2051) fclose(3);\nuid=1000(test) gid=1000(test) groups=1000(test),10(wheel)\n(2051) exit(0);\n(2051) fileno(1);\n(2051) fclose(1);\n(2051) fileno(2);\n(2051) fclose(2);\n----\n\n== Redirect usage example\n\nThe power of `retrace` lies in its ability to modify the behavior of\nthe standard system calls in a number of different ways.\nThis is done using a config file.\n\nAn easy example is redirecting the output of the `getuid()` call:\n\n[source,console]\n----\n$ cat retrace.conf\ngetuid,0\ngeteuid,0\ngetegid,0\ngetgid,0\n\n$ retrace -f retrace.conf /usr/bin/id\n(4982) geteuid(); [redirection in effect: '0']\n(4982) getuid(); [redirection in effect: '0']\n(4982) getegid(); [redirection in effect: '0']\n(4982) getgid(); [redirection in effect: '0']\n(4982) fopen(\"/etc/passwd\", \"rce\"); [3]\n(4982) fclose(3);\n(4982) fopen(\"/etc/group\", \"rce\"); [3]\n(4982) fclose(3);\n(4982) fopen(\"/etc/group\", \"rce\"); [3]\n(4982) fclose(3);\n(4982) fopen(\"/etc/group\", \"rce\"); [3]\n(4982) fclose(3);\nuid=0(root) gid=0(root) groups=0(root)\n(4982) exit(0);\n(4982) fileno(1);\n(4982) fclose(1);\n(4982) fileno(2);\n(4982) fclose(2);\n----\n\n\n= Config Options\n\nOther useful config file options are listed below.\n\n== Connect\n\n[source,sh]\n----\nconnect,127.0.0.1,8080,192.168.1.110,9090\n----\n\nWill redirect a `connect()` call from `127.0.0.1:8080` to\n`192.168.1.110:9090`.\n\n== File-related\n\n[source,sh]\n----\nfopen,/etc/passwd,/tmp/passwd\n----\n\nWill redirect a `fopen()` call from `/etc/passwd` to `/tmp/passwd`.\n\n== Logging\n\n[source,sh]\n----\nlogtofile,retrace.log\n----\n\nWill send the log file to a file rather than `stderr`. You can configure\nlog output to write to `/dev/null` disable logging completely.\n\n== OpenSSL\n\n[source,sh]\n----\nSSL_get_verify_result,10\n----\n\nWill cause the OpenSSL function `SSL_get_verify_result` to return any\ndesired value.\n\n== Memory Fuzzing\n\n[source,sh]\n----\nmemoryfuzzing,0.05\n----\n\nThis option will cause a percentage of `malloc()`, `realloc()` and\n`calloc()` calls to fail.\n\nThe percentage is specified in a number (`float`) from `0` (no fail) to\n`1` (all fail). This is useful to discover places in your code where you\nare not checking the return value of allocators.\n\nThe seed of the random generator can be controlled with the\n`fuzzingseed,1498729252` option, so that the results are repeatable.\n\n== Incomplete I/O\n\n[source,sh]\n----\nincompleteio,10\n----\n\nThis option will cause the `read()` / `write()` calls to randomly\nwrite/read less bytes than was asked. A common scenario that people\nforget to check.\n\n== Time tracking\n\n[source,sh]\n----\nshowtimestamp\nshowcalltime,0.0001\n----\n\nThese two options will cause a timestamp (since the beginning of the\ntracing) to be shown and the time a call took if it's larger than\nthe specified time in float seconds.\n\n== Logging\n\n[source,sh]\n----\nlogging-global,LOG_GROUP_FILE|LOG_GROUP_MEM,RTR_LOG_LEVEL_ALL\nlogging-excluded-funcs,free|memcpy|malloc\nlogging-allowed-funcs,strlen\nstacktrace-groups,LOG_GROUP_MEM\nstacktrace-disabled-funcs,calloc\n----\n\nThese options will enable or disable logging options by group or level.\nThe each group, level or function may be combined by `|` character.\n\n[source,sh]\n----\nlogging-global,[logging group],[logging level]\n\tgroups: LOG_GROUP_ALL,LOG_GROUP_MEM,LOG_GROUP_FILE,LOG_GROUP_NET,LOG_GROUP_SYS,\n\t\tLOG_GROUP_STR,LOG_GROUP_SSL,LOG_GROUP_PROC\n\tlevels: LOG_LEVEL_ALL,LOG_LEVEL_NOR,LOG_LEVEL_ERR,LOG_LEVEL_FUZZ,LOG_LEVEL_REDIRECT\n\nlogging-excluded-funcs,[functions list]\nlogging-allowed-funcs,[functions list]\nstacktrace-groups,[logging groups]\nstacktrace-disabled-funcs,[functions list]\n----\n\n= Notes\n\n== macOS System Integrity Protection\n\nWe use the DYLD_INSERT_LIBRARIES environment variable to insert `retrace` into binaries.\nStarting on Mac OS X El Capitan Apple removes the DYLD_INSERT_LIBRARIES variable for\nthe environment for binaries in system directories. This means you can't trace system binaries\nusing `retrace` by default.\n\nYou can disable this behaviour by running `csrutil disable` and rebooting.\n\n\n= Feedback\n\n`retrace` is under heavy development and we are always looking to implement new\nand useful features that allows debugging and reverse engineering programs in\nnew and interesting ways.\n\nPlease send feedback and improvement suggestions either as GitHub issues or to\nretrace@ribose.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friboseinc%2Fretrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friboseinc%2Fretrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friboseinc%2Fretrace/lists"}