Magic-Mirror/radare2
1
0
Fork 0
mirror of https://github.com/radareorg/radare2.git synced 2024-10-06 18:13:46 +00:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

Rewrite user-facing documentation (#19543)

Browse Source
This commit is contained in:
Lazula 2022-01-01 06:11:46 -06:00 committed by GitHub
parent b4195becaa
commit 2470a6c284
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 704 additions and 520 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

269
CONTRIBUTING.md
View File

@ -1,129 +1,226 @@
# How to report issues # How to report issues
Before reporting an issue with GitHub, be sure that: Before reporting an issue on GitHub, please check that:
* you are using the git version of radare2 * You are using the most recent git version of radare2
* you are using a clean installation * You are using a clean installation of radare2
* the issue was not already reported * The issue has not already been reported (search
[here](https://github.com/radareorg/radare2/issues))
When the above conditions are satisfied, feel free to submit an issue When the above conditions are satisfied, feel free to submit an issue. Please
while trying to be as precise as possible. If you can, provide the problematic provide a precise description, and as many of the following as possible:
binary, the steps to reproduce the error and a backtrace in case of SEGFAULTs.
Any information will help to fix the problem. * Your operating system and architecture; e.g. "Windows 10 32-bit", "Debian 11
64-bit".
* The file in use when the issue was encountered (we may add the file or a
section of it to our test suite to avoid regressions).
* A backtrace, if the issue is a segmentation fault. You can compile with ASan
on Linux using `sys/sanitize.sh` to allow easier diagnosis of such issues.
* Detailed steps to reproduce the issue, including a list of commands and
expected and/or actual output.
# How to contribute # How to contribute
There are a few guidelines that we need contributors to follow so that we can There are a few guidelines that we ask contributors to follow to ensure that
try to keep the codebase consistent and clean. the codebase is clean and consistent.
## Getting Started ## Getting Started
* Make sure you have a GitHub account and solid ability to use `git`. * Make sure you have a GitHub account and a basic understanding of `git`. If
* Fork the repository on GitHub. you don't know how to use `git`, there is a useful guide
* Create a topic branch from master. Please avoid working directly on the `master` branch. [here](https://learnxinyminutes.com/docs/git).
* Make commits of logical units. * Fork the repository on GitHub (there should be a "Fork" button on the top
right of the repository home page).
* Create a branch on your fork based off of `master`. Please avoid working
directly on the `master` branch. This will make it easier to prepare your
changes for merging when it's ready.
```sh
git checkout master
git checkout -b mybranch
```
* Make commits of logical units. Try not to make several unrelated changes in
the same commit, but don't feel obligated to split them up too much either.
Ideally, r2 should successfully compile at each commit. This simplifies the
debugging process, as it allows easier use of tools such as `git bisect`
alongside the `r2r` testing suite to identify when a bug is introduced.
* Check for coding style issues with: * Check for coding style issues with:
git diff master..mybranch | ./sys/clang-format-diff.py -p1 ```sh
git diff master..mybranch | sys/clang-format-diff.py -p1
```
and be sure to follow the CODINGSTYLE (more on this in [DEVELOPERS.md][]). For more on the coding style, see [DEVELOPERS.md](DEVELOPERS.md).
* Submit the Pull Request(PR) on Github. * Open a [pull request](https://github.com/radareorg/radare2/pulls) (PR) on
* Prefix the PR title with `WIP:` if it's not yet ready to be merged Github.
* When relevant, write a test in [test/](test). * Prefix the PR title with `WIP:` and mark it as a draft if you aren't ready to
merge.
* When relevant, add or modify tests in [test/](test).
## Rebasing onto updated master ## Rebasing onto updated master
Every so often, your PR will lag behind `master` and get conflicts. New changes are frequently pushed to the `master` branch. Before your branch
can be merged, you must resolve any conflicts with new commits made to
`master`.
To "update" your branch `my-awesome-feature`, you *rebase* it onto To prepare your branch for merging onto `master`, you must first `rebase` it
the latest `radareorg/master`, and *force-push* the result into your fork. onto the most recent commit on `radareorg/master`, then, if you already pushed
to your remote, force-`push` it to overwrite the previous commits after any
conflict resolution.
#### Step 1: Switch to `master` branch. #### Step 0: Configuring git
$ git checkout master You may wish to change default git settings to ensure you don't need to always
provide specific options. These do not need to be set again after initial
configuration unless your git settings are lost, e.g. if you delete the
repository folder and then clone it again.
#### Step 2: Pull new commits published to radareorg repo. If you cloned from your fork, you can add a new remote for upstream. The
commands here will assume that `origin` is your fork and `radareorg` is
upstream, but you can name them as you choose.
$ git pull https://github.com/radareorg/radare2 ```sh
# Use SSH
git remote add radareorg git@github.com:radareorg/radare2.git
#### Step 3: Switch back to `my-awesome-feature` branch. # Use HTTPS
git remote add radareorg https://github.com/radareorg/radare2
```
$ git checkout my-awesome-feature radare2 uses a `fast-forward` merging style. This means that instead of taking
the new commits you make and adding them to `master` in a single "merge
commit", the commits are directly copied and applied to `master`, "replaying"
them to bring `master` up to date with your branch.
#### Step 4: Rebase the `my-awesome-feature` branch. Default settings may create these "merge commits", which are undesirable and
make the commit history harder to read and interpret. You can set `merge` and
`pull` to fast-forward only to avoid this.
$ git rebase master ```sh
git config merge.ff only
git config pull.ff only
```
Optionally, use the alternative mode "interactive rebase". It allows #### Step 1: Pull new commits to `master` from upstream
to `squash` your commits all into one, reorder, reword them, etc.
$ git rebase -i master ```sh
git checkout master
git pull radareorg master
```
Follow git instructions when conflicts arise. You may need to add the `-f` flag to force the pull if it is rejected. If you
have made commits to your local `master` branch (not recommended!), this may
overwrite them.
#### Step 5: publish your updated local branch. If there are new commits to master, you will see the list of changed files. If
there are no updates, you will see `Already up to date.`.
$ git push -f #### Step 2: Rebase `mybranch` onto master
This `-f` *force-flag* is needed because git commits are immutable: rebasing ```sh
creates newer versions of them. git needs to confirm the destruction of git checkout mybranch
previous incarnations. git rebase master
```
When afraid to touch force and risk losing your work (do backups!..), You may optionally use the interactive mode. This allows you to reorder,
try *merging master into your branch* instead of rebasing onto it. `reword`, `edit`, or `squash` your commits into fewer individual commits.
This is discouraged, as it produces ugly hard-to-maintain commit history.
## Commit message rules ```sh
git rebase -i master
```
When commiting your changes into the repository you may want to follow some Again, you must resolve any conflicts that occur before you can merge.
rules to make the git history more readable and consistent:
If you are concerned about potential loss of work, you can back up your code by
creating a new branch using your feature branch as a base before rebasing.
```sh
git checkout mybranch
git branch backup
git rebase master
```
#### Step 3: Publish your updated local branch
If you have not pushed this branch before:
```sh
git push -u origin mybranch
```
If you are updating an existing branch:
```sh
git push -f
```
The `-f` flag may be needed to `force` the push onto the remote if you are
replacing existing commits on the remote because git commits are immutable -
this discards the old commits on your remote, and git won't take potentially
destructive actions without confirmation.
## Commit message guidelines
When committing changes, we ask that you follow some guidelines to keep the
history readable and consistent:
* Start the message capitalized (only the first character must be in uppercase) * Start the message capitalized (only the first character must be in uppercase)
* Be short and concise, the whole concept must fit one line * Be concise. A descriptive message under 100 characters is preferred, but may
* If a command is inlined, use backticks not be possible in all situations. For large commits, it is acceptable to use
* Add a double-hashtag if the change matters for the changelog (See below) a summary line, followed by an empty line, then an asterisk item list of
* If the commit fixes a bug start with 'Fix #number - ' changes.
* For extra details, add an empty line and use asterisk item list below * If a command is inlined, use backticks, e.g.:
* Use present simple grammar tense (Add vs Added, Fix vs Fixed/Fixes)
### Commit message hashtag list: ```sh
git commit -m 'Modify output of `ls`'
```
* ##anal - analysis related * Add a tag if the change falls into a relevant category (see below)
* ##asm - assembler * If the commit fixes an issue, you may optionally start the message with
* ##bin - binary parsing `Fix #number - `
* ##build - build fixes/changes * Use present simple tense and avoid past tense. Use "add", "fix", or "change"
* ##config - config var changes/additions/renamings instead of "added", "fixed", or "changed".
* ##cons - console/terminal-related
* ##crypto - cryptography ### Commit message tag list
* ##debug - debugger stuff
* ##diff - diffing code, strings, basic blocks, ... | Tag | Relevant changes |
* ##disasm - disassembler |------------------|------------------|
* ##doc - documentation | `##analysis` | Analysis |
* ##egg - the `r_lang` compiler | `##arch` | Architecture |
* ##emu - emulation, including esil | `##asm` | Assembly (not disassembly) |
* ##graph - basic block graph, callgraph, ... | `##bin` | Binary parsing |
* ##io - related to the `r_io` library | `##build` | Build system |
* ##json - json fixes/changes | `##config` | Configuration variables |
* ##lang - bindings | `##cons` | Console/terminal |
* ##meta - metadata handling other than printing | `##crypto` | Cryptography |
* ##optimization-space/time optimizations | `##debug` | Debugger |
* ##port - portability (new OS/archs) | `##diff` | Diffing code, strings, basic blocks, etc. |
* ##print - printing data, structures, strings, tables, types .. | `##disasm` | Disassembler |
* ##projects - saving/loading state | `##doc` | Documentation |
* ##refactor - improve code quality | `##egg` | The `r_lang` compiler |
* ##remote - r2 over tcp, http, rap, serial .. including collaboration | `##emu` | Emulation, including esil |
* ##search - rafind2, / command, .. | `##graph` | Basic block graph, callgraph, etc. |
* ##shell - command-line, argument parsing, new commands, .. | `##io` | The `r_io` library |
* ##signatures-searching/generating them | `##json` | JSON |
* ##test - testing infrastructure fixes/changes | `##lang` | Language bindings |
* ##tools - r2pm, rarun2, rax2 ... that don't fit in other categories | `##meta` | Metadata handling, excluding printing |
* ##util - core apis | `##optimization` | Space/time optimizations |
* ##visual - visual ui, including panels | `##platform` | Platform-specific code |
| `##port` | Portability - new OS or architectures |
| `##print` | Printing data, structures, strings, tables, types, etc. |
| `##projects` | Saving and loading state |
| `##refactor` | Code quality improvements |
| `##remote` | Usage over a remote connection (TCP, HTTP, RAP, etc.), collaboration |
| `##search` | `rafind2`, `/` command, etc. |
| `##shell` | Command-line, argument parsing, new commands, etc. |
| `##signatures` | Searching for or generating signatures |
| `##test` | Testing infrastructure, including `r2r` |
| `##tools` | `r2pm`, `rarun2`, `rax2` changes that don't fit in another category |
| `##util` | Core APIs |
| `##visual` | Visual UI, including panels |
# Additional resources # Additional resources
* [README.md](README.md) * [README.md](README.md)
* [DEVELOPERS.md](DEVELOPERS.md) * [DEVELOPERS.md](DEVELOPERS.md)
* [USAGE.md](USAGE.md) * [USAGE.md](USAGE.md)
If you need more confidence in your git skills, check out this quick guide:
<https://learnxinyminutes.com/docs/git/>

696
DEVELOPERS.md
View File

@ -1,171 +1,222 @@
# DEVELOPERS # Development information
This file aims to describe an introduction for developers to work This file aims to introduce developers to conventions for working on the code
on the code base of radare2 project. base of radare2.
The GitHub issues page contains a list of all the bugs that have been reported,
with labels to classify them by difficulty, type, milestone, etc. It is a good
place to start if you are looking to contribute.
For information about the git process, see
[CONTRIBUTING.md](CONTRIBUTING.md#How_to_contribute).
## Documentation ## Documentation
There is support for Doxygen document generation in this repo. Functions should have descriptive names and parameters. It should be clear what
By running `doxygen` in the root of this repository, it will autodetect the the function and its arguments do from the declaration. Comments should be used
Doxyfile and generate HTML documentation into to explain purpose or clarify something that may not be immediately apparent or
[doc/doxygen/html/index.html](./doc/doxygen/html/index.html) relatively complicated.
If you're contributing code or willing to update existing code, you can use the
doxygen C-style comments to improve documentation and comments in code.
See the [Doxygen Manual](http://www.doxygen.nl/manual/index.html)
for more info. Example usage can be found [here](http://www.doxygen.nl/manual/docblocks.html)
```c ```c
/** /* Find the min and max addresses in an RList of maps. Returns (max-min)/width. */
* \brief Find the min and max addresses in an RList of maps.
* \param maps RList of maps that will be searched through
* \param min Pointer to a ut64 that the min will be stored in
* \param max Pointer to a ut64 that the max will be stored in
* \param skip How many maps to skip at the start of an iteration
* \param width Divisor for the return value
* \return (max-min)/width
*
* Used to determine the min & max addresses of maps and
* scale the ascii bar to the width of the terminal
*/
static int findMinMax(RList *maps, ut64 *min, ut64 *max, int skip, int width); static int findMinMax(RList *maps, ut64 *min, ut64 *max, int skip, int width);
``` ```
## Error diagnosis
There are several utilities that can be used to diagnose errors in r2, whether
they are related to memory (segfaults, uninitialized read, etc.) or problems
with features.
### Compilation options
* `sys/sanitize.sh`: Compile with ASan, the address sanitizer. Provides
detailed backtraces for memory errors.
* `R2_DEBUG_ASSERT=1`: Provides a backtrace when a debug assert (typically a
`r_return_` macro) fails.
* `R2_DEBUG=1`: Show error messages and crash signal. Used for debugging plugin
loading issues.
### Useful macros from [r\_types.h](libr/include/r_types.h)
* `EPRINT_*`: Allows you to quickly add or remove a debug print without
worrying about format specifiers.
#### Parameter marking
r2 provides several empty macros to make function signatures more informative.
* `R_OUT`: Parameter is output - written to instead of read.
* `R_INOUT`: Parameter is read/write.
* `R_OWN`: Pointer ownership is transferred from the caller.
* `R_BORROW`: The caller retains ownership of the pointer - the reciever must
not free it.
* `R_NONNULL`: Pointer must not be null.
* `R_NULLABLE`: Pointer may ne null.
* `R_DEPRECATE`: Do not use in new code and will be removed in the future.
* `R_IFNULL(x)`: Default value for a pointer when null.
* `R_UNUSED`: Not used.
## Code style ## Code style
### C ### C
In order to contribute with patches or plugins, we encourage you to In order to contribute patches or plugins, we encourage you to use the same
use the same coding style as the rest of the code base. coding style as the rest of the code base.
Please use `./sys/clang-format-diff.py` before submitting a PR to be sure you * Please use `./sys/clang-format-diff.py` before submitting a PR to be sure you
are following the coding style. If you find a bug in this script, please create are following the coding style, as described in
an issue on GitHub. You can also install the pre-commit hook [CONTRIBUTING.md](CONTRIBUTING.md#Getting Started). If you find a bug in this
`./sys/pre-commit-indent.sh` by copying it in `.git/hooks/pre-commit` which script, please submit a bug report issue. A detailed style guide can be found
will check the coding style of the modified lines before committing them. below.
You may find some additional notes on this topic in doc/vim. * See `sys/indent.sh` for indenting your code automatically.
* Tabs are used for indentation. In a switch statement, the * A pre-commit hook to check coding style is located at
cases are indented at the switch level. `sys/pre-commit-indent.sh`. You can install it by copying it to
`.git/hooks/pre-commit`. To preserve your existing pre-commit hook, use
`cat sys/pre-commit-indent.sh >> .git/hooks/pre-commit` instead.
* For a premade `.vimrc`, see `doc/vim`.
* See `.clang-format` for work-in-progress support for automated indentation.
#### Guidelines
The following guidelines apply to code that we must maintain. Generally, they
will not apply to copy-paste external code that will not be touched.
* Tabs are used for indentation. In a switch statement, the cases are indented
at the switch level.
* Switch-cases where local variables are needed should be refactored into * Switch-cases where local variables are needed should be refactored into
separate functions instead of using braces. Even so, if braced scope syntax separate functions instead of using braces. If braced scope syntax is used,
is used, put `break;` statement inside the scope. put `break;` statements inside the scope.
```c ```c
switch (n) { switch (n) {
case 1: case 1:
break; break;
case 2: { case 2: {
break; break;
} }
default: default:
} }
``` ```
* Lines should be at most 78 chars. A tab is considered as 8 chars. * Lines should be at most 78 characters in length. A tab is considered 8
characters.
* Braces open on the same line as the for/while/if/else/function/etc. Closing * Braces open on the same line as the for/while/if/else/function/etc. Closing
braces are put on a line of their own, except in the else of an if statement braces are put on a line of their own, except in the else of an if statement
or in a while of a do-while statement. Always use braces for if and while. or in the while of a do-while statement.
```c ```c
if (a == b) { if (a == b) {
... ...
} }
if (a == b) { if (a == b) {
... ...
} else if (a > b) { } else if (a > b) {
... ...
} }
if (a == b) { if (a == b) {
... ...
} else { } else {
do_something_else (); do_something_else ();
} }
do { do {
do_something (); do_something ();
} while (cond); } while (cond);
if (a == b) { if (a == b) {
b = 3; b = 3;
} }
``` ```
* In general, don't use goto. The goto statement only comes in handy when a * Always use braces for if and while.
```diff
-if (a == b)
- return;
+if (a == b) {
+ return;
+}
```
* In general, avoid `goto`. The `goto` statement only comes in handy when a
function exits from multiple locations and some common work such as cleanup function exits from multiple locations and some common work such as cleanup
has to be done. If there is no cleanup needed, then just return directly. has to be done. If there is no cleanup needed, then just return directly.
Choose label names which say what the goto does or why the goto exists. An Choose label names which say what the `goto` does or why it exists. An
example of a good name could be "out_buffer:" if the goto frees "buffer". example of a good name could be `out_buffer:` if the `goto` frees `buffer`.
Avoid using GW-BASIC names like "err1:" and "err2:". Avoid using GW-BASIC names like `err1:` and `err2:`.
* Use `r_return_*` macros to check preconditions that are caused by * Use `r_return_*` macros to check for conditions that are caused by
programmers' errors. Please, keep in mind: programming errors or bugs; i.e.: conditions that should **never** happen. Do
* conditions that should never happen should be handled through not use them when checking for runtime error conditions, such as a `NULL`
`r_return_*` macros; value being returned from `malloc()`. Use a standard if statement for these
* runtime conditions (e.g. malloc returns NULL, input coming from user, cases.
etc.) should be handled in the usual way through if-else.
```c ```c
int check(RCore *c, int a, int b) { int check(RCore *c, int a, int b) {
r_return_val_if_fail (c, false); /* check for programming errors */
r_return_val_if_fail (a >= 0, b >= 1, false); r_return_val_if_fail (c, false);
r_return_val_if_fail (a >= 0, b >= 1, false);
if (a == 0) { /* check for runtime errors */
/* do something */ ut8 *buf = calloc (b, sizeof (a));
... if (!buf) {
} return -1;
... /* do something else */ }
/* continue... */
} }
``` ```
* Use a space after most of the keyword and around operators. * Use spaces after keywords and around operators.
```c ```c
a = b + 3; a = b + 3;
a = (b << 3) * 5; a = (b << 3) * 5;
a = sizeof (b) * 4;
``` ```
* Multiline ternary operator conditionals must be indented a-la JS way: * Multiline ternary operator conditionals are indented in JavaScript style:
```diff ```diff
- ret = over ? -ret = over ?
- r_debug_step_over (dbg, 1) : - r_debug_step_over (dbg, 1) :
- r_debug_step (dbg, 1); - r_debug_step (dbg, 1);
+ ret = over +ret = over
+ ? r_debug_step_over (dbg, 1) + ? r_debug_step_over (dbg, 1)
+ : r_debug_step (dbg, 1); + : r_debug_step (dbg, 1);
``` ```
* When breaking up a long line, use a single additional tab if the current and * When breaking up a long line, use a single additional tab if the current and
next lines are aligned. Do not align start of line using spaces. next lines are aligned. Do not align start of line using spaces.
```diff ```diff
- x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5, -x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
- arg6, arg7, arg8); - arg6, arg7, arg8);
- y = z; -y = z;
+ x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5, +x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
+ arg6, arg7, arg8); + arg6, arg7, arg8);
+ y = z; +y = z;
``` ```
* Use two additional tabs if the next line is indented to avoid confusion with * Use two additional tabs if the next line is indented to avoid confusion with
control flow. control flow.
```diff ```diff
- if (function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5, if (function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
- arg6, arg7, arg8)) { - arg6, arg7, arg8)) {
- do_stuff (); + arg6, arg7, arg8)) {
- } do_stuff ();
+ if (function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5, }
+ arg6, arg7, arg8)) {
+ do_stuff ();
+ }
``` ```
* When following the above guideline, if additional indentation is needed on * When following the above guideline, if additional indentation is needed on
@ -173,65 +224,62 @@ a = (b << 3) * 5;
nesting in this manner. nesting in this manner.
```diff ```diff
- if (condition_1 if (condition_1 && condition_2 && condition_3
- && condition_2 && (condition_4
- && condition_3 - || condition_5)) {
- && (condition_4 + || condition_5)) {
- || condition_5)) { do_stuff ();
- do_stuff ();
- }
+ if (condition_1
+ && condition_2
+ && condition_3
+ && (condition_4
+ || condition_5)) {
+ do_stuff ();
+ }
```
* Split long conditional expressions into small `static inline` functions to make them more readable:
```diff
+static inline bool inRange(RBreakpointItem *b, ut64 addr) {
+ return (addr >= b->addr && addr < (b->addr + b->size));
+}
+
+static inline bool matchProt(RBreakpointItem *b, int rwx) {
+ return (!rwx || (rwx && b->rwx));
+}
+
R_API RBreakpointItem *r_bp_get_in(RBreakpoint *bp, ut64 addr, int rwx) {
RBreakpointItem *b;
RListIter *iter;
r_list_foreach (bp->bps, iter, b) {
- if (addr >= b->addr && addr < (b->addr+b->size) && \
- (!rwx || rwx&b->rwx))
+ if (inRange (b, addr) && matchProt (b, rwx)) {
return b;
+ }
}
return NULL;
} }
``` ```
* Structure in the C files * Split long conditional expressions into small `static inline` functions to
make them more readable.
The structure of the C files in r2 must be like this:
```c
/* Copyright ... */ ## copyright
#include <r_core.h> ## includes
static int globals ## const, define, global variables
static void helper(void) {} ## static functions
R_IPI void internal(void) {} ## internal apis (used only inside the library)
R_API void public(void) {} ## public apis starting with constructor/destructor
```diff
+static inline bool inRange(RBreakpointItem *b, ut64 addr) {
+ return (addr >= b->addr && addr < (b->addr + b->size));
+}
+
+static inline bool matchProt(RBreakpointItem *b, int rwx) {
+ return (!rwx || (rwx && b->rwx));
+}
+
R_API RBreakpointItem *r_bp_get_in(RBreakpoint *bp, ut64 addr, int rwx) {
RBreakpointItem *b;
RListIter *iter;
r_list_foreach (bp->bps, iter, b) {
- if (addr >= b->addr && addr < (b->addr+b->size) && \
- (!rwx || rwx&b->rwx)) {
+ if (inRange (b, addr) && matchProt (b, rwx)) {
return b;
}
}
return NULL;
}
``` ```
* Use `R_API` to mark exportable (public) methods for module APIs.
* Why return int vs enum * Use `R_IPI` to mark functions internal to a library.
The reason why many places in r2land functions return int instead of an enum type is because enums can't be OR'ed; otherwise, it breaks the usage within a switch statement and swig can't handle that stuff. * Other functions should be `static` to avoid polluting the global namespace.
* The structure of C files in r2 should be as follows:
```c
/* Copyright ... */ // copyright
#include <r_core.h> // includes
static int globals // const, define, global variables
static void helper(void) {} // static functions
R_IPI void internal(void) {} // internal apis (used only inside the library)
R_API void public(void) {} // public apis starting with constructor/destructor
```
* Why do we return `int` instead of `enum`?
The reason why many r2 functions return int instead of an enum type is
because enums can't be OR'ed; additionally, it breaks the usage within a
switch statement and swig can't handle it.
``` ```
r_core_wrap.cxx:28612:60: error: assigning to 'RRegisterType' from incompatible type 'long' r_core_wrap.cxx:28612:60: error: assigning to 'RRegisterType' from incompatible type 'long'
@ -240,110 +288,116 @@ r_core_wrap.cxx:28612:60: error: assigning to 'RRegisterType' from incompatible
r_core_wrap.cxx:32103:61: error: assigning to 'RDebugReasonType' from incompatible type 'int' r_core_wrap.cxx:32103:61: error: assigning to 'RDebugReasonType' from incompatible type 'int'
arg2 = static_cast< int >(val2); if (arg1) (arg1)->type = arg2; resultobj = SWIG_Py_Void(); return resultobj; fail: arg2 = static_cast< int >(val2); if (arg1) (arg1)->type = arg2; resultobj = SWIG_Py_Void(); return resultobj; fail:
^ ~~~~ ^ ~~~~
3 warnings and 2 errors generated. ```
````
* Do not leave trailing whitespaces at the end of line * Do not leave trailing whitespaces at end-of-line.
* Do not use assert.h, use r_util/r_assert.h instead. * Do not use `<assert.h>`. Use `"r_util/r_assert.h"` instead.
* You can use `export R2_DEBUG_ASSERT=1` to set a breakpoint when hitting an assert. * You can use `export R2_DEBUG_ASSERT=1` to set a breakpoint when hitting an assert.
* Do not use C99 variable declaration * Declare variables at the beginning of code blocks - use C89 declaration
- This way we reduce the number of local variables per function instead of C99. In other words, do not mix declarations and code. This helps
and it's easier to find which variables are used, where and so on. reduce the number of local variables per function and makes it easier to find
which variables are used where.
* Always put a space before every parenthesis (function calls, conditionals, * Always put a space before an opening parenthesis (function calls, conditionals,
fors, etc, ...) except when defining the function signature. This is for loops, etc.) except when defining a function signature. This is useful
useful for grepping. for searching the code base with `grep`.
* Function names should be explicit enough to not require a comment ```c
explaining what it does when seen elsewhere in code. -if(a == b){
+if (a == b) {
```
* Use 'R_API' define to mark exportable (public) methods only for module APIs ```c
-static int check(RCore *core, int a);
+static int check (RCore *core, int a);
```
* The rest of functions must be static, to avoid polluting the global space. * Where is `function_name()` defined?
* Avoid using global variables, they are evil. Only use them for singletons ```sh
and WIP code, placing a comment explaining the reason for them to stay there. grep -R 'function_name(' libr
```
* If you *really* need to comment out some code, use #if 0 (...) #endif. In * Where is `function_name()` used?
general, don't comment out code because it makes the code less readable.
* Do not write ultra-large functions: split them into multiple or simplify ```sh
the algorithm, only external-copy-pasted-not-going-to-be-maintained code grep -R 'function_name (' libr
can be accepted in this way (gnu code, external disassemblers, etc..) ```
* See sys/indent.sh for indenting your code automatically * Function names should be explicit enough to not require a comment explaining
what it does when seen elsewhere in code.
* See doc/vim for vimrc * **Do not use global variables**. The only acceptable time to use them is for
singletons and WIP code. Make a comment explaining why it is needed.
* See .clang-format for work-in-progress support for automated indentation * Commenting out code should be avoided because it reduces readability. If you
*really* need to comment out code, use `#if 0` and `#endif`.
* Use the r2 types instead of the ones in stdint, which are known to cause some * Avoid very long functions; split it into multiple sub-functions or simplify
portability issues. So, instead of uint8_t, use ut8, etc.. your approach.
* Never ever use %lld or %llx. This is not portable. Always use the PFMT64x * Use types from `<r_types.h>` instead of the ones in `<stdint.h>`, which are
macros. Those are similar to the ones in GLIB. known to cause some portability issues. Replace `uint8_t` with `ut8`, etc.
### Shell Scripts * Never use `%lld` or `%llx`, which are not portable. Use the `PFMT64` macros
from `<r_types.h>`.
* Use `#!/bin/sh` ### Shell scripts
* Do not use bashisms `[[`, `$'...'` etc. * Use `#!/bin/sh`.
* Use our [shellcheck.sh](https://github.com/radareorg/radare2/blob/master/sys/shellcheck.sh) script to check for problems and for bashisms * Do not use BASH-only features; `[[`, `$'...'`, etc.
# Manage Endianness * Use `sys/shellcheck.sh` to check for problems and BASH-only features.
As hackers, we need to be aware of endianness. ## Managing endianness
Endianness can become a problem when you try to process buffers or streams Endianness is a common stumbling block when processing buffers or streams and
of bytes and store intermediate values as integers with width larger than storing intermediate values as integers larger than one byte.
a single byte.
It can seem very easy to write the following code: ### Problem
The following code may seem intuitively correct:
```c ```c
ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40}; ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40};
ut32 value = *(ut32*)opcode; ut32 value = *(ut32*)opcode;
``` ```
... and then continue to use "value" in the code to represent the opcode. However, when `opcode` is cast to `ut32`, the compiler interprets the memory
layout based on the host CPU's endianness. On little-endian architectures such
as x86, the least-signficiant byte comes first, so `value` contains
`0x40302010`. On a big-endian architecture, the most-significant byte comes
first, so `value` contains `0x10203040`. This implementation-defined behavior
is inherently unstable and should be avoided.
This needs to be avoided! ### Solution
Why? What is actually happening? To avoid dependency on endianness, use bit-shifting and bitwise OR
instructions. Instead of casting streams of bytes to larger width integers, do
When you cast the opcode stream to a unsigned int, the compiler uses the endianness the following for little endian:
of the host to interpret the bytes and stores it in host endianness. This leads to
very unportable code, because if you compile on a different endian machine, the
value stored in "value" might be 0x40302010 instead of 0x10203040.
## Solution
Use bitshifts and OR instructions to interpret bytes in a known endian.
Instead of casting streams of bytes to larger width integers, do the following:
```c ```c
ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40}; ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40};
ut32 value = opcode[0] | opcode[1] << 8 | opcode[2] << 16 | opcode[3] << 24; ut32 value = opcode[0] | opcode[1] << 8 | opcode[2] << 16 | opcode[3] << 24;
``` ```
or if you prefer the other endian: And do the following for big endian:
```c ```c
ut32 value = opcode[3] | opcode[2] << 8 | opcode[1] << 16 | opcode[0] << 24; ut32 value = opcode[3] | opcode[2] << 8 | opcode[1] << 16 | opcode[0] << 24;
``` ```
This is much better because you actually know which endian your bytes are stored in This behavior is not dependent on architecture, and will act consistently
within the integer value, REGARDLESS of the host endian of the machine. between any standard compilers regardless of host endianness.
## Endian helper functions ### Endian helper functions
Radare2 now uses helper functions to interpret all byte streams in a known endian. The above is not very easy to read. Within radare2, use endianness helper
functions to interpret byte streams in a given endianness.
Please use these at all times, eg:
```c ```c
val32 = r_read_be32(buffer) // reads 4 bytes from a stream in BE val32 = r_read_be32(buffer) // reads 4 bytes from a stream in BE
@ -353,12 +407,12 @@ val32 = r_read_ble32(buffer, isbig) // reads 4 bytes from a stream:
// otherwise reads in LE // otherwise reads in LE
``` ```
There are a number of helper functions for 64, 32, 16, and 8 bit reads and writes. Such helper functions exist for 64, 32, 16, and 8 bit reads and writes.
(Note that 8 bit reads are equivalent to casting a single byte of the buffer * Note that 8 bit reads are equivalent to casting a single byte of the buffer
to a ut8 value, ie endian is irrelevant). to a `ut8` value, i.e.: endian is irrelevant.
### Editor configuration ## Editor configuration
Vim/Neovim: Vim/Neovim:
@ -386,175 +440,179 @@ Emacs:
))) )))
``` ```
You may use directory-local variables by putting You may use directory-local variables by adding the following to
`.dir-locals.el`.
```elisp ```elisp
((c-mode . ((c-file-style . "radare2")))) ((c-mode . ((c-file-style . "radare2"))))
``` ```
into `.dir-locals.el`.
## Packed structures ## Packed structures
Due to the various differences between platforms and compilers radare2 Due to standards differing between compilers, radare2 provides a portable
has a special helper macro - `R_PACKED()`. Instead of non-portable helper macro for packed structures: `R_PACKED()`, which will automatically
`#pragma pack` or `__attribute__((packed))` it is advised to use this macro utilize the correct compiler-dependent macro. Do not use `#pragma pack` or
instead. To wrap the code inside of it you just need to write: `__attribute__((packed))`. Place the packed structure inside `R_PACKED()` like
so:
```c ```c
R_PACKED (union mystruct { R_PACKED (struct mystruct {
int a; int a;
char b; char b;
}) });
``` ```
or in case of typedef:
If you are using `typedef`, do not encapsulate the type name.
```c ```c
R_PACKED (typedef structmystruct { R_PACKED (typedef struct mystruct_t {
int a; int a;
char b; char b;
}) }) mystruct;
``` ```
## Modules ## Modules
The radare2 code base is modularized into different libraries that are radare2 is split into modular libraries in the `libr/` directory. The `binr/`
found in libr/ directory. The binr/ directory contains the programs directory contains programs which use these libraries.
which use the libraries.
It is possible to generate PIC/nonPIC builds of the libraries and also The libraries can be built individually, PIC or non-PIC. You can also create a
to create a single static library so you can use a single library single static library archive (`.a`) which you can link your own programs
archive (.a) to link your programs and get your programs using radare against to use radare2's libraries without depending on an existing system
framework libraries without depending on them. See doc/static for more info. installation. See [doc/static.md](doc/static.md) for more info.
The following presentation gives a good overview of the libraries: [This presentation](http://radare.org/get/lacon-radare-2009/) gives a good
overview of the libraries.
http://radare.org/get/lacon-radare-2009/
## API ## API
As mentioned in README.md, the API itself is maintained in a different The external API is maintained in a different repository. The API function
repository. The API function definitions in C header files are derived definitions in C header files are derived from and documented in the
from and documented in the radare2-bindings repository, found at: `radare2-bindings` repository, found
[here](https://github.com/radareorg/radare2-bindings).
Currently, the process of updating the header files from changed API bindings
requires human intervention, to ensure that proper review occurs. Incorrect
definitions in the C header files will trigger a build failure in the bindings
repository.
If you are able to write a plugin for various IDE that can associate the
bindings with the header files, such a contribution would be very welcome.
## Dependencies and installation
radare2 does not require external dependencies. On \*nix-like systems, it
requires only a standard C compiler and GNU `make`. For compiling on Windows,
see [doc/windows.md](doc/windows.md). Browse the [doc/](doc/) folder for other
architectures. For cross-compilation, see
[doc/cross-compile.md](doc/cross-compile.md).
## Recompiling and Outdated Dependencies
When recompiling code, ensure that you recompile all dependent modules (or
simply recompile the entire project). If a module's dependency is not
recompiled and relinked, it may cause segmentation faults due to outdated
structures and libraries. Such errors are not handles automatically, so if you
are not sure, recompile all modules.
To speed up frequent recompilation, you can use `ccache` like so:
```sh ```sh
git clone git://github.com/radareorg/radare2-bindings export CC="ccache gcc"
``` ```
Currently the process of updating the header files from changed API This will automatically detect when files do not need to recompiled and avoid
bindings requires human intervention, to ensure that proper review unnecessary work.
occurs. Incorrect definitions in the C header files will trigger
a build failure in the bindings repository.
If you are able to write a plugin for various IDE that can associate ## Repeated installation
the bindings with the header files, such a contribution would be
very welcome.
## Dependencies There is an alternative installation method for radare2 to make it easier to
repeatedly install while making changes. The `symstall` target creates a single
system-wide installation using symlinks instead of copies, making repeated
builds faster.
radare2 can be built without any special dependency. It just requires ```sh
a C compiler, a GNU make and a unix-like system. sudo make symstall
```
## Cross compilation
The instructions to crosscompile r2 to Windows are in doc/windows.
You may find other documents in doc/ explaining how to build it on iOS,
linux-arm and others, but the procedure is like this:
- define `CC`
- use a different compiler profile with `--with-compiler`
- use a different OS with `--with-ostype`
- type `make`
- install in `DESTDIR`
## Source repository ## Source repository
The source of radare2 can be found in the following GitHub repository. The source for radare2 can be found in the following GitHub repository:
```sh ```sh
git clone git://github.com/radareorg/radare2 git clone https://github.com/radareorg/radare2
``` ```
Other packages radare2 depends on, such as Capstone, are pulled from Other packages radare2 depends on, such as Capstone, are pulled from
their git repository as required. their git repository as required.
To get an up-to-date copy of the repository, you should perform the To get an up-to-date copy of the repository, you should perform the
following steps: following while on the `master` branch:
```sh ```sh
git pull git pull
``` ```
If you have conflicts in your local copy, it's because you have modified If your local git repository is not tracking upstream, you may need to use the
files which are conflicting with the incoming patchsets. To get a clean following:
source directory, type the following command:
```sh
git pull https://github.com:radareorg/radare2 master
```
The installation scripts `sys/user.sh`, `sys/install.sh`, `sys/meson.py`, and
`sys/termux.sh` will automatically identify and update using an existing
upstream remote, if one exists. If not, it will pull using a direct URL.
If you have modified files on the `master` branch, you may encounter conflicts
that must be resolved manually. To save your changes, work on a different
branch as described in [CONTRIBUTING.md](CONTRIBUTING.md). If you wish to
discard your current work, use the following commands:
```sh ```sh
git clean -xdf git clean -xdf
git reset --hard git reset --hard
``` ```
## Compilation
Inter-module rebuild dependencies are not handled automatically and
require human interaction to recompile the affected modules.
This is a common issue and can end up having outdated libraries trying
to use deprecated structures which may result into segfaults.
You have to make clean on the affected modules. If you are not
sure enough that everything is OK, just make clean the whole project.
If you want to accelerate the build process after full make cleans,
you should use ccache in this way:
```
export CC="ccache gcc"
```
## Installation
Developers use to modify the code, type make and then try.
radare2 has a specific makefile target that allows you to install
system wide but using symlinks instead of hard copies.
```sh
sudo make symstall
```
This kind of installation is really helpful if you do lot of changes
in the code for various reasons.
- only one install is required across multiple builds
- installation time is much faster
## Regression testing ## Regression testing
The source of the radare2 regression test suite can be found in the Use `r2r` to run the radare2 regression test suite, e.g.:
`test/` directory, while binaries for this test are located in the
following GitHub repository.
```sh ```sh
git clone git://github.com/radareorg/radare2-testbins sys/install.sh
r2r
``` ```
See the `README.md` file in that repository for further information. r2r's source can be found in the `test/` directory, while binaries used for
tests are located in the following GitHub repository:
The existing test coverage can always do with improvement. So if you can ```sh
contribute additional tests, that would be gratefully accepted. git clone https://github.com/radareorg/radare2-testbins
```
These can be found in `test/bins/` after being downloaded by r2r.
For more information, see [r2r's
README](https://github.com/radareorg/radare2-testbins/blob/master/README).
The test files can be found in `test/db/`. Each test consists of a unique name,
an input file, a list of input commands, and the expected output. The test must
be terminated with a line consisting only of `RUN`.
Testing can always be improved. If you can contribute additional tests or fix
existing tests, it is greatly appreciated.
## Reporting bugs ## Reporting bugs
If you notice any misfeature, issue, error, problem or you just If you encounter a broken feature, issue, error, problem, or it is unclear how
don't know how to do something which is supposed to be covered to do something that should be covered by radare2's functionality, report an
by this framework. issue on the GitHub repository
[here](https://github.com/radareorg/radare2/issues).
You should report it into the GitHub issues page. If you are looking for feedback, check out the [Community section in the
https://github.com/radareorg/radare2/issues README](README.md#Community) for places where you can contact other r2 devs.
Otherwise, if you are looking for some more feedback, I will # HOW TO RELEASE
encourage you to send an email to any of the emails enumerated
in the AUTHORS file.
Anyway, if you want to get even more feedback and discuss this
in a public place: join the #radare channel on irc.freenode.net.
The issues page of GitHub contains a list of all the bugs that
have been reported classified with labels by difficulty, type,
milestone, etc. It is a good place to start if you are looking
to contribute.
## HOW TO RELEASE
- Set `RELEASE=1` in global.mk and r2-bindings/config.mk.acr. - Set `RELEASE=1` in global.mk and r2-bindings/config.mk.acr.
- Use `bsdtar` from libarchive package. GNU tar is broken. - Use `bsdtar` from libarchive package. GNU tar is broken.
@ -573,8 +631,8 @@ to contribute.
- Update the [paths on the website](https://github.com/radareorg/radareorg/blob/master/source/download_paths.rst) - Update the [paths on the website](https://github.com/radareorg/radareorg/blob/master/source/download_paths.rst)
## Additional resources # Additional resources
* [CONTRIBUTING.md](https://github.com/radareorg/radare2/blob/master/CONTRIBUTING.md) * [CONTRIBUTING.md](CONTRIBUTING.md)
* [README.md](https://github.com/radareorg/radare2/blob/master/README.md) * [README.md](README.md)
* [USAGE.md](https://github.com/radareorg/radare2/blob/master/USAGE.md) * [USAGE.md](USAGE.md)

43
INSTALL.md
View File

@ -1,43 +1,46 @@
# Installation # Installation
The [GHA CI](https://github.com/radareorg/radare2/actions) builds the packages for every commit and those are also You can find the most recent packaged versions on the
available in the [release](https://github.com/radareorg/radare2/releases) page. But it is always recommended to [Releases](https://github.com/radareorg/radare2/releases) page. However,
install r2 from git. installing from git is recommended whenever possible.
The most used and recommended way is by running this script which will build The most used and recommended way is by running `sys/install.sh` which will
and install r2 from sources and install it **system wide** with **symlinks**. build and install r2 from sources and install it **system-wide** using
**symlinks**.
``` ```sh
git clone https://github.com/radareorg/radare2 git clone https://github.com/radareorg/radare2
radare2/sys/install.sh radare2/sys/install.sh
``` ```
If you need to install it in your user's home or switch between multiple r2 To install in your user's home directory, use `sys/user.sh`. To manage multiple
builds you may checkout the `meson` build and the [r2env](https://github.com/radareorg/r2env) Python tool. installations on the same system, use
[r2env](https://github.com/radareorg/r2env).
The focus on portability enables r2 to be built in many different ways for multiple The focus on portability enables r2 to be built in many different ways for
operating systems easily by using the `./configure;make` or `meson` build systems. multiple operating systems easily by using the `./configure && make` or `meson`
build systems.
r2env allows to build and install different versions of r2 in your home r2env allows you to build and install different versions of r2 in your home or
or system and it is available via Python's PIP tool. system and it is available via Python's `pip` tool.
``` ```sh
pip install r2env pip install r2env
r2env init r2env init
r2env install radare2@latest r2env install radare2@latest
``` ```
## Uninstall ## Uninstallation
In case of a polluted filesystem, you can uninstall the current version In case of a polluted filesystem, you can uninstall the current version
or remove all previous installations with one or more of those commands: or remove all previous installations with one or more of those commands:
``` ```sh
make uninstall make uninstall # Remove the current installation
make system-purge make purge # Remove all files from all installations
make purge make system-purge # Remove all installed packages
git clean -xdf git clean -xdf # Remove any files not tracked by git
rm -rf shlr/capstone rm -rf shlr/capstone # Remove the current version of capstone
``` ```
# Packaging status # Packaging status

130
README.md
View File

@ -2,54 +2,103 @@
## Radare2: Unix-Like Reverse Engineering Framework ## Radare2: Unix-Like Reverse Engineering Framework
[![Tests Status](https://github.com/radareorg/radare2/workflows/CI/badge.svg?branch=master)](https://github.com/radareorg/radare2/actions/workflows/ci.yml?query=branch%3Amaster) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/741/badge)](https://bestpractices.coreinfrastructure.org/projects/741) [![Build Status](https://scan.coverity.com/projects/416/badge.svg)](https://scan.coverity.com/projects/416) [![Total alerts](https://img.shields.io/lgtm/alerts/g/radareorg/radare2.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/radareorg/radare2/alerts/) [![TODO counter](https://img.shields.io/github/search/radareorg/radare2/TODO.svg)](https://github.com/radareorg/radare2/search?q=TODO) [![XXX counter](https://img.shields.io/github/search/radareorg/radare2/XXX.svg)](https://github.com/radareorg/radare2/search?q=XXX) [![Latest packaged version](https://repology.org/badge/latest-versions/radare2.svg)](https://repology.org/project/radare2/versions) [![Tests Status](https://github.com/radareorg/radare2/workflows/CI/badge.svg?branch=master)](https://github.com/radareorg/radare2/actions/workflows/ci.yml?query=branch%3Amaster) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/741/badge)](https://bestpractices.coreinfrastructure.org/projects/741) [![Build Status](https://scan.coverity.com/projects/416/badge.svg)](https://scan.coverity.com/projects/416) [![Total alerts](https://img.shields.io/lgtm/alerts/g/radareorg/radare2.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/radareorg/radare2/alerts/)
Next release will be 5.6.0, current git is 5.5.5 and the [![latest packaged version(s)](https://repology.org/badge/latest-versions/radare2.svg)](https://repology.org/project/radare2/versions) See the [Release](https://github.com/radareorg/radare2/releases) downloads page. The current packaged version is `5.5.4`. See the
[Releases](https://github.com/radareorg/radare2/releases) page for binary
downloads. The current git `master` branch is `5.5.5`, and the next release will
be `5.6.0`.
r2 is a rewrite from scratch of radare. It provies a set of libraries, tools and r2 is a complete rewrite of radare. It provides a set of libraries, tools and
plugins to ease reverse engineering tasks. plugins to ease reverse engineering tasks.
The radare project started as a simple command-line hexadecimal editor focused on The radare project started as a simple command-line hexadecimal editor focused
forensics, over time more features were added to support a scriptable command-line on forensics. Today, r2 is a featureful low-level command-line tool with
low level tool to edit from local hard drives, kernel memory, programs, remote gdb support for scripting. r2 can edit files on local hard drives, view kernel
servers and be able to analyze, emulate, debug, modify and disassemble any binary. memory, and debug programs locally or via a remote gdb server. r2's wide
architecture support allows you to analyze, emulate, debug, modify, and
disassemble any binary.
<p align="center"> <p align="center">
<a href="https://www.radare.org/"><img src="doc/images/shot.png" alt="screenshot" align="center" border=0 width="600px"></a> <a href="https://www.radare.org/"><img src="doc/images/shot.png" alt="screenshot" align="center" border=0 width="600px"></a>
</p> </p>
* Install r2 from **Git** (Clone the repo and run `sys/install.sh`) or use `pip install r2env` ## Installation
* Read the [Official radare2 book](https://book.rada.re)
* [COMMUNITY.md](COMMUNITY.md) engagement
* [CONTRIBUTING.md](CONTRIBUTING.md) general rules
* [DEVELOPERS.md](DEVELOPERS.md) to improve r2 for your needs
* [SECURITY.md](SECURITY.md) on vulnerability report instructions
* [USAGE.md](USAGE.md) for an introductory session
* [INSTALL.md](INSTALL.md) instructions
``` r2 can be installed via `git` or `pip`.
```sh
git clone https://github.com/radareorg/radare2 git clone https://github.com/radareorg/radare2
radare2/sys/install.sh radare2/sys/install.sh
``` ```
# Plugins ```sh
pip install r2env
Most of the plugins you need may be available in the stock r2 installation,
but you can find more in the [r2pm](https://github.com/radareorg/radare2-pm) package manager.
``` ```
r2pm update # initialize and update the package database
r2pm install [pkg] # installs the package ## Resources
* [Official radare2 book](https://book.rada.re): Read about r2 usage.
* [COMMUNITY.md](COMMUNITY.md): Community engagement and loose guidelines.
* [CONTRIBUTING.md](CONTRIBUTING.md): Information about reporting issues and
contributing. See also the [Contributing](#Contributing) section below.
* [DEVELOPERS.md](DEVELOPERS.md): Development guidelines for r2.
* [SECURITY.md](SECURITY.md): Instructions for reporting vulnerabilities.
* [USAGE.md](USAGE.md): Some example commands.
* [INSTALL.md](INSTALL.md): Full instructions for different installation
methods.
## Plugins
Many plugins are included with r2 by default. You can find more plugins using
the [r2pm](https://github.com/radareorg/radare2-pm) package manager.
```sh
r2pm update # update (or initialize) the package database
r2pm install <pkg> # install a package
``` ```
Some of the most installed packages are: Some of the most installed packages are:
* [radius](https://github.com/aemmitt-ns/radius) fast symbolic execution engine based on boolector and r2 * [esilsolve](https://github.com/radareorg/esilsolve): The symbolic execution plugin, based on esil and z3.
* [r2ghidra](https://github.com/radareorg/r2ghidra) the native ghidra decompiler plugin: `pdg` command * [iaito](https://github.com/radareorg/iaito): The official Qt graphical interface.
* [esilsolve](https://github.com/radareorg/esilsolve) symbolic execution r2 plugin based on esil and z3 * [radius](https://github.com/aemmitt-ns/radius): A fast symbolic execution engine based on boolector and r2.
* [r2dec](https://github.com/wargio/r2dec-js) decompiler based on r2 written in js `pdd` * [r2dec](https://github.com/wargio/r2dec-js): A decompiler based on r2 written in JS, accessed with the `pdd` command.
* [r2frida](https://github.com/nowsecure/r2frida) the frida io plugin `r2 frida://0` * [r2ghidra](https://github.com/radareorg/r2ghidra): The native ghidra decompiler plugin, accessed with the `pdg` command.
* [iaito](https://github.com/radareorg/iaito) - official graphical interface (Qt) * [r2frida](https://github.com/nowsecure/r2frida): The frida io plugin. Start r2 with `r2 frida://0` to use it.
# Contributing
There are many ways to contribute to the project. Contact the
[community](#Community), check out the github issues, or grep for
TODO/FIXME/XXX comments in the source.
To contribute code, push your changes to a branch on your fork of the
repository. Please ensure that you follow the coding and style guidelines and
that your changes pass the testing suite, which you can run with the `r2r`
tool. If you are adding significant code, it may be necessary to modify or add
additional tests in the `test/` directory.
For more details, see [CONTRIBUTING.md](CONTRIBUTING.md) and
[DEVELOPERS.md](DEVELOPERS.md).
## Documentation
To learn more about r2 we encourage you to watch [youtube
talks](https://www.youtube.com/c/r2con) from [r2con](https://rada.re/con). In
addition to reading blogposts, slides or the [official radare2
book](https://book.rada.re), here are some methods to contact us:
## Community
* [irc.libera.chat](https://libera.chat): `#radare`, `#radare_side`
* [Matrix](https://matrix.to/#/#radare:matrix.org): `#radare:matrix.org`
* Telegram: [Main Channel](https://t.me/radare) and [Side Channel](https://t.me/radare_side)
* [Discord server](https://discord.gg/MgEdxrMnqx)
* Twitter: [@radareorg](https://twitter.com/radareorg)
* Website: [https://www.radare.org/](https://www.radare.org/)
# Supported Platforms
## Operating Systems ## Operating Systems
@ -74,29 +123,6 @@ ZIMG, MBN/SBL bootloader, ELF coredump, MDMP (Windows minidump),
WASM (WebAssembly binary), Commodore VICE emulator, QNX, WAD, OFF, TIC-80 WASM (WebAssembly binary), Commodore VICE emulator, QNX, WAD, OFF, TIC-80
Game Boy (Advance), Nintendo DS ROMs and Nintendo 3DS FIRMs, various filesystems. Game Boy (Advance), Nintendo DS ROMs and Nintendo 3DS FIRMs, various filesystems.
# Contributing
There are many ways to contribute to the project, join the IRC/Matrix/Telegram
channels, check out the github issues or grep for the TODO comments in the source.
To contribute with code, create a branch in your forked repository and push
a pull request, follow the coding style and ensure it passes the tests with
the `r2r` tool to run the tests that are under the `tests/` subdirectory.
For more details read the [CONTRIBUTING.md](CONTRIBUTING.md) file.
## Community and Documentation
To learn more about r2 we encourage you to watch youtube talks from
[r2con](https://www.youtube.com/c/r2con) [conference](https://rada.re/con). As well as reading blogposts,
slides or read the [Official radare2 book](https://book.rada.re), You can reach us in the following chats:
* irc.libera.chat `#radare` `#radare_side`
* [Matrix](https://matrix.org/) `#radare:matrix.org`
* [Telegram](https://t.me/radare) and the [Side Channel](https://t.me/radare_side)
* [Discord](https://discord.gg/MgEdxrMnqx) server
* Twitter: [@radareorg](https://twitter.com/radareorg)
* Website: [https://www.radare.org/](https://www.radare.org/)
## Packaging Status ## Packaging Status
* [![Termux package](https://repology.org/badge/version-for-repo/termux/radare2.svg)](https://repology.org/project/radare2/versions) * [![Termux package](https://repology.org/badge/version-for-repo/termux/radare2.svg)](https://repology.org/project/radare2/versions)

46
SECURITY.md
View File

@ -1,40 +1,39 @@
Security Policies and Procedures # Security Policies and Procedures
================================
We take security seriously, and encourage everyone to use the last version of We take security seriously, and encourage everyone to use the last version of
radare2 from git if possible. We do not backport security fixes to old releases. radare2 from git if possible. We do not backport security fixes to old
releases.
Security bugs are max priority and they all must be fixed in less than a day. Security bugs are considered top priority and a fix is required within 24 hours
of disclosure.
Reporting a vulnerability ## Reporting a vulnerability
-------------------------
If you discover a security issue in radare2 (or any related project under the If you discover a security issue in radare2 (or any related project under the
radareorg umbrella), please submit a public issue in the [GitHub](https://github.com/radareorg/radare2/issues) repository for that project. radareorg umbrella), please submit a public issue in the [GitHub issue
section](https://github.com/radareorg/radare2/issues) repository for that
project.
If you are able to do so, we would appreciate a pull request with your suggested If possible, we would appreciate a pull request with your suggested fix
fix instead of the reproducer, which is usually faster than reporting and instead of leaving it to a reproducer. This is typically faster than reporting
explaining it. the error and explaining it for someone who can fix it.
See `DEVELOPERS.md` for technical details, but in short you may want to try See [Error diagnosis](DEVELOPERS.md#Error_diagnosis) for details.
`sys/sanitize.sh` (ASAN) builds and set `R2_DEBUG_ASSERT=1` to get to the point
of failure.
Disclosure policy ## Disclosure policy
-----------------
We don't believe in secrecy when security matters, keeping the bugs for We don't believe in secrecy when security matters. Keeping the bugs for
yourself or for a limited amount of people results in a false sense of yourself or for a limited amount of people results in a false sense of
security for the community. security for the community.
We encourage full disclosure of any and all security bugs in radare2's codebase. We encourage full disclosure of any and all security bugs in radare2's codebase.
Please see the "Reporting a Bug" section for information on how to report a bug. Please see the "Reporting a vulnerability" section above for information on how
If you do not or can not create a GitHub account, you may email the bug details to report a bug. If you do not have or can not create a GitHub account, you may
to `pancake@nopcode.org` and we will create the issue / fix on your behalf. email the bug details to `pancake@nopcode.org` and we will create the issue and
fix on your behalf.
Privacy ## Privacy
-------
While we are able to publicly acknowledge you for your contribution to radare2 While we are able to publicly acknowledge you for your contribution to radare2
for helping us keep our software secure for users, if you so choose we will for helping us keep our software secure for users, if you so choose we will
@ -43,7 +42,6 @@ keep your contribution anonymous.
To cover those situations we recommend you to create a GitHub, Telegram or IRC To cover those situations we recommend you to create a GitHub, Telegram or IRC
accounts and report it in the public channel, DMs to the author are also fine. accounts and report it in the public channel, DMs to the author are also fine.
Bounties ## Bounties
--------
No bounty programs are available right now. There is currently no bug bounty program for r2.

40
USAGE.md
View File

@ -1,8 +1,3 @@
# Usage
All r2 tools and commands support printing the output in different formats
by appending a char at the end or using the `-r`(\*r2) and `-j`(json) flags.
``` ```
___ __ ___ __ ___ ___ ____ ___ __ ___ __ ___ ___ ____
| _ \/ \| \/ \ _ \/ _ \ (__ \ | _ \/ \| \/ \ _ \/ _ \ (__ \
@ -14,40 +9,47 @@ by appending a char at the end or using the `-r`(\*r2) and `-j`(json) flags.
--pancake --pancake
``` ```
# Usage
All r2 tools and commands support printing the output in different formats by
appending a character at the end or using the `-r` (\*r2) and `-j` (json)
flags.
### radare2 ### radare2
``` ```
r2 - # same as r2 malloc://4096 the playground r2 - # same as r2 malloc://4096; "the playground"
r2 /bin/ls # standard way to run r2 r2 /bin/ls # standard way to run r2
r2 -w ls # open in read-write r2 -w ls # open in read-write
r2 -d ls # start debugging the ls in PATH r2 -d ls # start debugging the ls in PATH
``` ```
### rasm2 ### rasm2
``` ```
rasm2 -L # list all supported assembler/disassembler/emulator plugins rasm2 -L # list all supported assembler/disassembler/emulator plugins
rasm2 -a arm -b 64 'nop' rasm2 -a arm -b 64 'nop' # assemble a nop in 64-bit ARM
rasm2 -d 90 # disassembles a nop asuming local x86 rasm2 -d 90 # disassemble 0x90; nop, if you're using x86
``` ```
### rabin2 ### rabin2
``` ```
rabin2 -s /bin/ls # list symbols of binary rabin2 -s /bin/ls # list symbols in a binary
rabin2 -z /bin/ls # find strings rabin2 -z /bin/ls # find strings
``` ```
### rax2 ### rax2
``` ```
rax2 '10+0x20' # compute the result rax2 '10+0x20' # compute the result
rax2 -k 10+32 # keep the same base as input (10) rax2 -k 10+32 # keep the same base as input (10)
rax2 -h # convert between (hex, octal, decimal.. bases) rax2 -h # convert between (hex, octal, decimal.. bases)
``` ```
### Other tools... ### Other tools
Checkout the [manpages](https://github.com/radareorg/radare2/blob/master/man) and help messages for more details Check out the [manpages](https://github.com/radareorg/radare2/blob/master/man)
and help messages for more information.
## Scripting ## Scripting

0
doc/statis.md → doc/static.md
View File