Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/riboseinc/retrace
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).
https://github.com/riboseinc/retrace
Last synced: 3 months ago
JSON representation
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).
- Host: GitHub
- URL: https://github.com/riboseinc/retrace
- Owner: riboseinc
- License: other
- Created: 2017-05-31T08:44:14.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2022-02-14T08:16:21.000Z (about 3 years ago)
- Last Synced: 2024-03-24T20:36:46.289Z (11 months ago)
- Language: C
- Homepage:
- Size: 1.07 MB
- Stars: 60
- Watchers: 14
- Forks: 19
- Open Issues: 50
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE.md
Awesome Lists containing this project
- AwesomeCompiler - retrace
README
= Retrace
image:https://github.com/riboseinc/retrace/actions/workflows/ubuntu.yml/badge.svg[Ubuntu, link=https://github.com/riboseinc/retrace/actions/workflows/ubuntu.yml]
image:https://github.com/riboseinc/retrace/actions/workflows/macos.yml/badge.svg[macOS, link=https://github.com/riboseinc/retrace/actions/workflows/macos.yml]
image:https://github.com/riboseinc/retrace/actions/workflows/windows.yml/badge.svg[Windows, link=https://github.com/riboseinc/retrace/actions/workflows/windows.yml]
image:https://img.shields.io/cirrus/github/riboseinc/retrace?label=freebsd&logo=cirrus%20ci["FreeBSD", link="https://cirrus-ci.com/github/riboseinc/retrace"]
image:https://github.com/riboseinc/retrace/actions/workflows/nix.yml/badge.svg[nix, link=https://github.com/riboseinc/retrace/actions/workflows/nix.yml]
image:https://github.com/riboseinc/retrace/actions/workflows/checkpatch.yml/badge.svg[checkpatch, link=https://github.com/riboseinc/retrace/actions/workflows/checkpatch.yml]
image:https://img.shields.io/coverity/scan/12840.svg[Coverity Scan, link=https://scan.coverity.com/projects/riboseinc-retrace]
`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).
`retrace` can be used to assist reverse engineering / debugging
dynamically-linked ELF (Linux/OpenBSD/FreeBSD/NetBSD) and
Mach-O (macOS) binary executables.
== Retrace v2
Work in a new version of `retrace` is ongoing, all the documentation is only about `retrace` v1, early documentation for
`retrace` v2 is link:READMEv2.adoc[here].
If you want to give it a go despiste the lack of documentation you can enable it in the build using `./configure --enable-v2`.
== Who is Ribose?
We are https://www.ribose.com[Ribose], the secure sharing company. We believe privacy and security form the foundation of liberty.
Our 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.
We created `retrace` to aid developers and security researchers to develop better code that leads the world to a better place.
== Contacting The Organizer
The Ribose `retrace` team can be reached at [email protected]. We will answer questions to the best of our efforts.
= Building retrace
For platforms with Autotools, the generic way to build and install
`retrace` is:
[source,console]
----
$ sh autogen.sh
$ ./configure --enable-tests
$ make
$ make check
$ sudo make install
----
You need Autotools installed in your system (`autoconf`, `automake`,
`libtool`, `make`, `gcc` packages).
OpenSSL library and headers are automatically detected, you can specify
an optional flag `--with-openssl=[PATH]` (to use a non-standard OpenSSL
installation root).
In order to build tests: run configure script with `--enable-tests`
flag. To build cmocka tests you can specify an optional flag
`--with-cmocka=[PATH]` (to use a non-standard cmocka installation root).
By the default `retrace` is installed in `/usr/bin` directory.
= Running retrace
[source,console]
----
$ retrace [-f configuration file location]
----
Configuration file path can be set either in `RETRACE_CONFIG`
environment variable or by specifying `-f [path]` command line argument.
= Interactive user interface
Interactive control over retrace can be exercised using cli control feature
over pseudo terminal (currently available on Linux platforms only).
In order to enable the feature, export `RETRACE_CLI=1` environment variable.
When enabled, the name of the pseudo device will be printed with a 3 seconds delay during the start up:
[source,console]
----
RETRACE-INIT [INFO]: cli pts is at: /dev/pts/1
----
After that, a terminal emulator can be connected to that device:
[source,console]
----
minicom -p /dev/pts/1
----
Hit the main Enter key, and the command menu with prompt will appear:
[source,console]
----
Welcome to minicom 2.7.1
OPTIONS: I18n
Compiled on Aug 13 2017, 15:25:34.
Port /dev/tty8, 13:10:04
Press CTRL-A Z for help on special keys
Failed to get command id, retry
Retrace command menu
\--------------------
[0] Say Hi
[1] Terminate process
Enter command id>>
----
The following are the characteristics of the terminal:
* Raw mode - no line processing will be performed on the input.
* Characters are echoed back.
* Main enter key is used to mark the end of input.
== Note to developers
In order to expose interactive commands from your module, use API defined in retrace_cli.h.
To register commads use cli_register_command_blk(). To interact with the user use cli_printf() and cli_scanf().
Refer to retrace_main.c for reference.
= Examples
== Trace usage example
In its most basic form `retrace` will just print all calls that are made
(and that are supported by retrace):
[source,console]
----
$ retrace /usr/bin/id
(2051) geteuid();
(2051) getuid();
(2051) getegid();
(2051) getgid();
(2051) fopen("/etc/passwd", "rce"); [3]
(2051) fclose(3);
(2051) fopen("/etc/group", "rce"); [3]
(2051) fclose(3);
(2051) fopen("/etc/group", "rce"); [3]
(2051) fclose(3);
(2051) fopen("/etc/group", "rce"); [3]
(2051) fclose(3);
uid=1000(test) gid=1000(test) groups=1000(test),10(wheel)
(2051) exit(0);
(2051) fileno(1);
(2051) fclose(1);
(2051) fileno(2);
(2051) fclose(2);
----
== Redirect usage example
The power of `retrace` lies in its ability to modify the behavior of
the standard system calls in a number of different ways.
This is done using a config file.
An easy example is redirecting the output of the `getuid()` call:
[source,console]
----
$ cat retrace.conf
getuid,0
geteuid,0
getegid,0
getgid,0
$ retrace -f retrace.conf /usr/bin/id
(4982) geteuid(); [redirection in effect: '0']
(4982) getuid(); [redirection in effect: '0']
(4982) getegid(); [redirection in effect: '0']
(4982) getgid(); [redirection in effect: '0']
(4982) fopen("/etc/passwd", "rce"); [3]
(4982) fclose(3);
(4982) fopen("/etc/group", "rce"); [3]
(4982) fclose(3);
(4982) fopen("/etc/group", "rce"); [3]
(4982) fclose(3);
(4982) fopen("/etc/group", "rce"); [3]
(4982) fclose(3);
uid=0(root) gid=0(root) groups=0(root)
(4982) exit(0);
(4982) fileno(1);
(4982) fclose(1);
(4982) fileno(2);
(4982) fclose(2);
----
= Config Options
Other useful config file options are listed below.
== Connect
[source,sh]
----
connect,127.0.0.1,8080,192.168.1.110,9090
----
Will redirect a `connect()` call from `127.0.0.1:8080` to
`192.168.1.110:9090`.
== File-related
[source,sh]
----
fopen,/etc/passwd,/tmp/passwd
----
Will redirect a `fopen()` call from `/etc/passwd` to `/tmp/passwd`.
== Logging
[source,sh]
----
logtofile,retrace.log
----
Will send the log file to a file rather than `stderr`. You can configure
log output to write to `/dev/null` disable logging completely.
== OpenSSL
[source,sh]
----
SSL_get_verify_result,10
----
Will cause the OpenSSL function `SSL_get_verify_result` to return any
desired value.
== Memory Fuzzing
[source,sh]
----
memoryfuzzing,0.05
----
This option will cause a percentage of `malloc()`, `realloc()` and
`calloc()` calls to fail.
The percentage is specified in a number (`float`) from `0` (no fail) to
`1` (all fail). This is useful to discover places in your code where you
are not checking the return value of allocators.
The seed of the random generator can be controlled with the
`fuzzingseed,1498729252` option, so that the results are repeatable.
== Incomplete I/O
[source,sh]
----
incompleteio,10
----
This option will cause the `read()` / `write()` calls to randomly
write/read less bytes than was asked. A common scenario that people
forget to check.
== Time tracking
[source,sh]
----
showtimestamp
showcalltime,0.0001
----
These two options will cause a timestamp (since the beginning of the
tracing) to be shown and the time a call took if it's larger than
the specified time in float seconds.
== Logging
[source,sh]
----
logging-global,LOG_GROUP_FILE|LOG_GROUP_MEM,RTR_LOG_LEVEL_ALL
logging-excluded-funcs,free|memcpy|malloc
logging-allowed-funcs,strlen
stacktrace-groups,LOG_GROUP_MEM
stacktrace-disabled-funcs,calloc
----
These options will enable or disable logging options by group or level.
The each group, level or function may be combined by `|` character.
[source,sh]
----
logging-global,[logging group],[logging level]
groups: LOG_GROUP_ALL,LOG_GROUP_MEM,LOG_GROUP_FILE,LOG_GROUP_NET,LOG_GROUP_SYS,
LOG_GROUP_STR,LOG_GROUP_SSL,LOG_GROUP_PROC
levels: LOG_LEVEL_ALL,LOG_LEVEL_NOR,LOG_LEVEL_ERR,LOG_LEVEL_FUZZ,LOG_LEVEL_REDIRECT
logging-excluded-funcs,[functions list]
logging-allowed-funcs,[functions list]
stacktrace-groups,[logging groups]
stacktrace-disabled-funcs,[functions list]
----
= Notes
== macOS System Integrity Protection
We use the DYLD_INSERT_LIBRARIES environment variable to insert `retrace` into binaries.
Starting on Mac OS X El Capitan Apple removes the DYLD_INSERT_LIBRARIES variable for
the environment for binaries in system directories. This means you can't trace system binaries
using `retrace` by default.
You can disable this behaviour by running `csrutil disable` and rebooting.
= Feedback
`retrace` is under heavy development and we are always looking to implement new
and useful features that allows debugging and reverse engineering programs in
new and interesting ways.
Please send feedback and improvement suggestions either as GitHub issues or to
[email protected].