Magic-Mirror/radare2
1
0
Fork 0
mirror of https://github.com/radareorg/radare2.git synced 2024-11-23 05:09:43 +00:00
Code Issues Actions 6 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
Before reporting an issue with GitHub, be sure that:
* you are using the git version of radare2
* you are using a clean installation
* the issue was not already reported
Before reporting an issue on GitHub, please check that:
* You are using the most recent git version of radare2
* You are using a clean installation of radare2
* 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
while trying to be as precise as possible. If you can, provide the problematic
binary, the steps to reproduce the error and a backtrace in case of SEGFAULTs.
Any information will help to fix the problem.
When the above conditions are satisfied, feel free to submit an issue. Please
provide a precise description, and as many of the following as possible:
* 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
There are a few guidelines that we need contributors to follow so that we can
try to keep the codebase consistent and clean.
There are a few guidelines that we ask contributors to follow to ensure that
the codebase is clean and consistent.
## Getting Started
* Make sure you have a GitHub account and solid ability to use `git`.
* Fork the repository on GitHub.
* Create a topic branch from master. Please avoid working directly on the `master` branch.
* Make commits of logical units.
* Make sure you have a GitHub account and a basic understanding of `git`. If
you don't know how to use `git`, there is a useful guide
[here](https://learnxinyminutes.com/docs/git).
* 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:
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][]).
* Submit the Pull Request(PR) on Github.
* Prefix the PR title with `WIP:` if it's not yet ready to be merged
* When relevant, write a test in [test/](test).
For more on the coding style, see [DEVELOPERS.md](DEVELOPERS.md).
* Open a [pull request](https://github.com/radareorg/radare2/pulls) (PR) on
Github.
* 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
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
the latest `radareorg/master`, and *force-push* the result into your fork.
To prepare your branch for merging onto `master`, you must first `rebase` it
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
to `squash` your commits all into one, reorder, reword them, etc.
#### Step 1: Pull new commits to `master` from upstream
$ 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
creates newer versions of them. git needs to confirm the destruction of
previous incarnations.
```sh
git checkout mybranch
git rebase master
```
When afraid to touch force and risk losing your work (do backups!..),
try *merging master into your branch* instead of rebasing onto it.
This is discouraged, as it produces ugly hard-to-maintain commit history.
You may optionally use the interactive mode. This allows you to reorder,
`reword`, `edit`, or `squash` your commits into fewer individual commits.
## Commit message rules
```sh
git rebase -i master
```
When commiting your changes into the repository you may want to follow some
rules to make the git history more readable and consistent:
Again, you must resolve any conflicts that occur before you can merge.
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)
* Be short and concise, the whole concept must fit one line
* If a command is inlined, use backticks
* Add a double-hashtag if the change matters for the changelog (See below)
* If the commit fixes a bug start with 'Fix #number - '
* For extra details, add an empty line and use asterisk item list below
* Use present simple grammar tense (Add vs Added, Fix vs Fixed/Fixes)
* Be concise. A descriptive message under 100 characters is preferred, but may
not be possible in all situations. For large commits, it is acceptable to use
a summary line, followed by an empty line, then an asterisk item list of
changes.
* If a command is inlined, use backticks, e.g.:
### Commit message hashtag list:
```sh
git commit -m 'Modify output of `ls`'
```
* ##anal - analysis related
* ##asm - assembler
* ##bin - binary parsing
* ##build - build fixes/changes
* ##config - config var changes/additions/renamings
* ##cons - console/terminal-related
* ##crypto - cryptography
* ##debug - debugger stuff
* ##diff - diffing code, strings, basic blocks, ...
* ##disasm - disassembler
* ##doc - documentation
* ##egg - the `r_lang` compiler
* ##emu - emulation, including esil
* ##graph - basic block graph, callgraph, ...
* ##io - related to the `r_io` library
* ##json - json fixes/changes
* ##lang - bindings
* ##meta - metadata handling other than printing
* ##optimization-space/time optimizations
* ##port - portability (new OS/archs)
* ##print - printing data, structures, strings, tables, types ..
* ##projects - saving/loading state
* ##refactor - improve code quality
* ##remote - r2 over tcp, http, rap, serial .. including collaboration
* ##search - rafind2, / command, ..
* ##shell - command-line, argument parsing, new commands, ..
* ##signatures-searching/generating them
* ##test - testing infrastructure fixes/changes
* ##tools - r2pm, rarun2, rax2 ... that don't fit in other categories
* ##util - core apis
* ##visual - visual ui, including panels
* Add a tag if the change falls into a relevant category (see below)
* If the commit fixes an issue, you may optionally start the message with
`Fix #number - `
* Use present simple tense and avoid past tense. Use "add", "fix", or "change"
instead of "added", "fixed", or "changed".
### Commit message tag list
| Tag | Relevant changes |
|------------------|------------------|
| `##analysis` | Analysis |
| `##arch` | Architecture |
| `##asm` | Assembly (not disassembly) |
| `##bin` | Binary parsing |
| `##build` | Build system |
| `##config` | Configuration variables |
| `##cons` | Console/terminal |
| `##crypto` | Cryptography |
| `##debug` | Debugger |
| `##diff` | Diffing code, strings, basic blocks, etc. |
| `##disasm` | Disassembler |
| `##doc` | Documentation |
| `##egg` | The `r_lang` compiler |
| `##emu` | Emulation, including esil |
| `##graph` | Basic block graph, callgraph, etc. |
| `##io` | The `r_io` library |
| `##json` | JSON |
| `##lang` | Language bindings |
| `##meta` | Metadata handling, excluding printing |
| `##optimization` | Space/time optimizations |
| `##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
* [README.md](README.md)
* [DEVELOPERS.md](DEVELOPERS.md)
* [USAGE.md](USAGE.md)
If you need more confidence in your git skills, check out this quick guide:
<https://learnxinyminutes.com/docs/git/>

600
DEVELOPERS.md
View File

@ -1,56 +1,97 @@
# DEVELOPERS
# Development information
This file aims to describe an introduction for developers to work
on the code base of radare2 project.
This file aims to introduce developers to conventions for working on the code
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
There is support for Doxygen document generation in this repo.
By running `doxygen` in the root of this repository, it will autodetect the
Doxyfile and generate HTML documentation into
[doc/doxygen/html/index.html](./doc/doxygen/html/index.html)
Functions should have descriptive names and parameters. It should be clear what
the function and its arguments do from the declaration. Comments should be used
to explain purpose or clarify something that may not be immediately apparent or
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
/**
* \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
*/
/* Find the min and max addresses in an RList of maps. Returns (max-min)/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
### C
In order to contribute with patches or plugins, we encourage you to
use the same coding style as the rest of the code base.
In order to contribute patches or plugins, we encourage you to use the same
coding style as the rest of the code base.
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
an issue on GitHub. You can also install the pre-commit hook
`./sys/pre-commit-indent.sh` by copying it in `.git/hooks/pre-commit` which
will check the coding style of the modified lines before committing them.
* Please use `./sys/clang-format-diff.py` before submitting a PR to be sure you
are following the coding style, as described in
[CONTRIBUTING.md](CONTRIBUTING.md#Getting Started). If you find a bug in this
script, please submit a bug report issue. A detailed style guide can be found
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
cases are indented at the switch level.
* A pre-commit hook to check coding style is located at
`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
separate functions instead of using braces. Even so, if braced scope syntax
is used, put `break;` statement inside the scope.
separate functions instead of using braces. If braced scope syntax is used,
put `break;` statements inside the scope.
```c
switch (n) {
@ -63,11 +104,12 @@ 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 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
if (a == b) {
@ -93,51 +135,63 @@ do {
if (a == b) {
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
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
example of a good name could be "out_buffer:" if the goto frees "buffer".
Avoid using GW-BASIC names like "err1:" and "err2:".
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`.
Avoid using GW-BASIC names like `err1:` and `err2:`.
* Use `r_return_*` macros to check preconditions that are caused by
programmers' errors. Please, keep in mind:
* conditions that should never happen should be handled through
`r_return_*` macros;
* runtime conditions (e.g. malloc returns NULL, input coming from user,
etc.) should be handled in the usual way through if-else.
* Use `r_return_*` macros to check for conditions that are caused by
programming errors or bugs; i.e.: conditions that should **never** happen. Do
not use them when checking for runtime error conditions, such as a `NULL`
value being returned from `malloc()`. Use a standard if statement for these
cases.
```c
int check(RCore *c, int a, int b) {
/* check for programming errors */
r_return_val_if_fail (c, false);
r_return_val_if_fail (a >= 0, b >= 1, false);
if (a == 0) {
/* do something */
...
/* check for runtime errors */
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
a = b + 3;
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
- ret = over ?
-ret = over ?
- r_debug_step_over (dbg, 1) :
- r_debug_step (dbg, 1);
+ ret = over
+ret = over
+ ? r_debug_step_over (dbg, 1)
+ : r_debug_step (dbg, 1);
```
@ -146,26 +200,23 @@ a = (b << 3) * 5;
next lines are aligned. Do not align start of line using spaces.
```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);
- y = z;
+ x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
-y = z;
+x = function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
+ arg6, arg7, arg8);
+ y = z;
+y = z;
```
* Use two additional tabs if the next line is indented to avoid confusion with
control flow.
```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)) {
- do_stuff ();
- }
+ if (function_with_long_signature_and_many_args (arg1, arg2, arg3, arg4, arg5,
+ arg6, arg7, arg8)) {
+ do_stuff ();
+ }
do_stuff ();
}
```
* When following the above guideline, if additional indentation is needed on
@ -173,23 +224,16 @@ a = (b << 3) * 5;
nesting in this manner.
```diff
- if (condition_1
- && condition_2
- && condition_3
- && (condition_4
if (condition_1 && condition_2 && condition_3
&& (condition_4
- || condition_5)) {
- do_stuff ();
- }
+ if (condition_1
+ && condition_2
+ && condition_3
+ && (condition_4
+ || condition_5)) {
+ do_stuff ();
+ }
do_stuff ();
}
```
* Split long conditional expressions into small `static inline` functions to make them more readable:
* Split long conditional expressions into small `static inline` functions to
make them more readable.
```diff
+static inline bool inRange(RBreakpointItem *b, ut64 addr) {
@ -205,33 +249,37 @@ a = (b << 3) * 5;
RListIter *iter;
r_list_foreach (bp->bps, iter, b) {
- if (addr >= b->addr && addr < (b->addr+b->size) && \
- (!rwx || rwx&b->rwx))
- (!rwx || rwx&b->rwx)) {
+ if (inRange (b, addr) && matchProt (b, rwx)) {
return b;
+ }
}
}
return NULL;
}
```
* Structure in the C files
* Use `R_API` to mark exportable (public) methods for module APIs.
The structure of the C files in r2 must be like this:
* Use `R_IPI` to mark functions internal to a library.
* 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
/* 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`?
* Why return int vs enum
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.
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'
@ -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'
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.
* Do not use C99 variable declaration
- This way we reduce the number of local variables per function
and it's easier to find which variables are used, where and so on.
* Declare variables at the beginning of code blocks - use C89 declaration
instead of C99. In other words, do not mix declarations and code. This helps
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,
fors, etc, ...) except when defining the function signature. This is
useful for grepping.
* Always put a space before an opening parenthesis (function calls, conditionals,
for loops, etc.) except when defining a function signature. This is useful
for searching the code base with `grep`.
* Function names should be explicit enough to not require a comment
explaining what it does when seen elsewhere in code.
```c
-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
and WIP code, placing a comment explaining the reason for them to stay there.
```sh
grep -R 'function_name(' libr
```
* If you *really* need to comment out some code, use #if 0 (...) #endif. In
general, don't comment out code because it makes the code less readable.
* Where is `function_name()` used?
* Do not write ultra-large functions: split them into multiple or simplify
the algorithm, only external-copy-pasted-not-going-to-be-maintained code
can be accepted in this way (gnu code, external disassemblers, etc..)
```sh
grep -R 'function_name (' libr
```
* 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
portability issues. So, instead of uint8_t, use ut8, etc..
* Avoid very long functions; split it into multiple sub-functions or simplify
your approach.
* Never ever use %lld or %llx. This is not portable. Always use the PFMT64x
macros. Those are similar to the ones in GLIB.
* Use types from `<r_types.h>` instead of the ones in `<stdint.h>`, which are
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
of bytes and store intermediate values as integers with width larger than
a single byte.
Endianness is a common stumbling block when processing buffers or streams and
storing intermediate values as integers larger than one byte.
It can seem very easy to write the following code:
### Problem
The following code may seem intuitively correct:
```c
ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40};
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?
When you cast the opcode stream to a unsigned int, the compiler uses the endianness
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:
To avoid dependency on endianness, use bit-shifting and bitwise OR
instructions. Instead of casting streams of bytes to larger width integers, do
the following for little endian:
```c
ut8 opcode[4] = {0x10, 0x20, 0x30, 0x40};
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
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
within the integer value, REGARDLESS of the host endian of the machine.
This behavior is not dependent on architecture, and will act consistently
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.
Please use these at all times, eg:
The above is not very easy to read. Within radare2, use endianness helper
functions to interpret byte streams in a given endianness.
```c
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
```
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
to a ut8 value, ie endian is irrelevant).
* Note that 8 bit reads are equivalent to casting a single byte of the buffer
to a `ut8` value, i.e.: endian is irrelevant.
### Editor configuration
## Editor configuration
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
((c-mode . ((c-file-style . "radare2"))))
```
into `.dir-locals.el`.
## Packed structures
Due to the various differences between platforms and compilers radare2
has a special helper macro - `R_PACKED()`. Instead of non-portable
`#pragma pack` or `__attribute__((packed))` it is advised to use this macro
instead. To wrap the code inside of it you just need to write:
Due to standards differing between compilers, radare2 provides a portable
helper macro for packed structures: `R_PACKED()`, which will automatically
utilize the correct compiler-dependent macro. Do not use `#pragma pack` or
`__attribute__((packed))`. Place the packed structure inside `R_PACKED()` like
so:
```c
R_PACKED (union mystruct {
R_PACKED (struct mystruct {
int a;
char b;
})
});
```
or in case of typedef:
If you are using `typedef`, do not encapsulate the type name.
```c
R_PACKED (typedef structmystruct {
R_PACKED (typedef struct mystruct_t {
int a;
char b;
})
}) mystruct;
```
## Modules
The radare2 code base is modularized into different libraries that are
found in libr/ directory. The binr/ directory contains the programs
which use the libraries.
radare2 is split into modular libraries in the `libr/` directory. The `binr/`
directory contains programs which use these libraries.
It is possible to generate PIC/nonPIC builds of the libraries and also
to create a single static library so you can use a single library
archive (.a) to link your programs and get your programs using radare
framework libraries without depending on them. See doc/static for more info.
The libraries can be built individually, PIC or non-PIC. You can also create a
single static library archive (`.a`) which you can link your own programs
against to use radare2's libraries without depending on an existing system
installation. See [doc/static.md](doc/static.md) for more info.
The following presentation gives a good overview of the libraries:
http://radare.org/get/lacon-radare-2009/
[This presentation](http://radare.org/get/lacon-radare-2009/) gives a good
overview of the libraries.
## API
As mentioned in README.md, the API itself is maintained in a different
repository. The API function definitions in C header files are derived
from and documented in the radare2-bindings repository, found at:
The external API is maintained in a different repository. The API function
definitions in C header files are derived from and documented in the
`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
git clone git://github.com/radareorg/radare2-bindings
export CC="ccache gcc"
```
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.
This will automatically detect when files do not need to recompiled and avoid
unnecessary work.
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.
## Repeated installation
## 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
a C compiler, a GNU make and a unix-like system.
## 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`
```sh
sudo make symstall
```
## 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
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
their git repository as required.
To get an up-to-date copy of the repository, you should perform the
following steps:
following while on the `master` branch:
```sh
git pull
```
If you have conflicts in your local copy, it's because you have modified
files which are conflicting with the incoming patchsets. To get a clean
source directory, type the following command:
If your local git repository is not tracking upstream, you may need to use the
following:
```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
git clean -xdf
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
The source of the radare2 regression test suite can be found in the
`test/` directory, while binaries for this test are located in the
following GitHub repository.
Use `r2r` to run the radare2 regression test suite, e.g.:
```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
contribute additional tests, that would be gratefully accepted.
```sh
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
If you notice any misfeature, issue, error, problem or you just
don't know how to do something which is supposed to be covered
by this framework.
If you encounter a broken feature, issue, error, problem, or it is unclear how
to do something that should be covered by radare2's functionality, report an
issue on the GitHub repository
[here](https://github.com/radareorg/radare2/issues).
You should report it into the GitHub issues page.
https://github.com/radareorg/radare2/issues
If you are looking for feedback, check out the [Community section in the
README](README.md#Community) for places where you can contact other r2 devs.
Otherwise, if you are looking for some more feedback, I will
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
# HOW TO RELEASE
- Set `RELEASE=1` in global.mk and r2-bindings/config.mk.acr.
- 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)
## Additional resources
# Additional resources
* [CONTRIBUTING.md](https://github.com/radareorg/radare2/blob/master/CONTRIBUTING.md)
* [README.md](https://github.com/radareorg/radare2/blob/master/README.md)
* [USAGE.md](https://github.com/radareorg/radare2/blob/master/USAGE.md)
* [CONTRIBUTING.md](CONTRIBUTING.md)
* [README.md](README.md)
* [USAGE.md](USAGE.md)

43
INSTALL.md
View File

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

130
README.md
View File

@ -2,54 +2,103 @@
## 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.
The radare project started as a simple command-line hexadecimal editor focused on
forensics, over time more features were added to support a scriptable command-line
low level tool to edit from local hard drives, kernel memory, programs, remote gdb
servers and be able to analyze, emulate, debug, modify and disassemble any binary.
The radare project started as a simple command-line hexadecimal editor focused
on forensics. Today, r2 is a featureful low-level command-line tool with
support for scripting. r2 can edit files on local hard drives, view kernel
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">
<a href="https://www.radare.org/"><img src="doc/images/shot.png" alt="screenshot" align="center" border=0 width="600px"></a>
</p>
* Install r2 from **Git** (Clone the repo and run `sys/install.sh`) or use `pip install r2env`
* 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
## Installation
```
r2 can be installed via `git` or `pip`.
```sh
git clone https://github.com/radareorg/radare2
radare2/sys/install.sh
```
# Plugins
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.
```sh
pip install r2env
```
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:
* [radius](https://github.com/aemmitt-ns/radius) fast symbolic execution engine based on boolector and r2
* [r2ghidra](https://github.com/radareorg/r2ghidra) the native ghidra decompiler plugin: `pdg` command
* [esilsolve](https://github.com/radareorg/esilsolve) symbolic execution r2 plugin based on esil and z3
* [r2dec](https://github.com/wargio/r2dec-js) decompiler based on r2 written in js `pdd`
* [r2frida](https://github.com/nowsecure/r2frida) the frida io plugin `r2 frida://0`
* [iaito](https://github.com/radareorg/iaito) - official graphical interface (Qt)
* [esilsolve](https://github.com/radareorg/esilsolve): The symbolic execution plugin, based on esil and z3.
* [iaito](https://github.com/radareorg/iaito): The official Qt graphical interface.
* [radius](https://github.com/aemmitt-ns/radius): A fast symbolic execution engine based on boolector and r2.
* [r2dec](https://github.com/wargio/r2dec-js): A decompiler based on r2 written in JS, accessed with the `pdd` command.
* [r2ghidra](https://github.com/radareorg/r2ghidra): The native ghidra decompiler plugin, accessed with the `pdg` command.
* [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
@ -74,29 +123,6 @@ ZIMG, MBN/SBL bootloader, ELF coredump, MDMP (Windows minidump),
WASM (WebAssembly binary), Commodore VICE emulator, QNX, WAD, OFF, TIC-80
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
* [![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
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
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
fix instead of the reproducer, which is usually faster than reporting and
explaining it.
If possible, we would appreciate a pull request with your suggested fix
instead of leaving it to a reproducer. This is typically faster than reporting
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
`sys/sanitize.sh` (ASAN) builds and set `R2_DEBUG_ASSERT=1` to get to the point
of failure.
See [Error diagnosis](DEVELOPERS.md#Error_diagnosis) for details.
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
security for the community.
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.
If you do not or can not create a GitHub account, you may email the bug details
to `pancake@nopcode.org` and we will create the issue / fix on your behalf.
Please see the "Reporting a vulnerability" section above for information on how
to report a bug. If you do not have or can not create a GitHub account, you may
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
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
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.

24
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,10 +9,16 @@ by appending a char at the end or using the `-r`(\*r2) and `-j`(json) flags.
--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
```
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 -w ls # open in read-write
r2 -d ls # start debugging the ls in PATH
@ -27,14 +28,14 @@ r2 -d ls # start debugging the ls in PATH
```
rasm2 -L # list all supported assembler/disassembler/emulator plugins
rasm2 -a arm -b 64 'nop'
rasm2 -d 90 # disassembles a nop asuming local x86
rasm2 -a arm -b 64 'nop' # assemble a nop in 64-bit ARM
rasm2 -d 90 # disassemble 0x90; nop, if you're using x86
```
### rabin2
```
rabin2 -s /bin/ls # list symbols of binary
rabin2 -s /bin/ls # list symbols in a binary
rabin2 -z /bin/ls # find strings
```
@ -45,9 +46,10 @@ rax2 -k 10+32 # keep the same base as input (10)
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

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