Getting started

Everything you need to start using Chain Reactor.

Contents

• Contents
• Prepare your environment
• Install musl
• Install Chain Reactor
• Run a simple reaction
• Next steps

Prepare your environment

Before you start testing, make sure to have the following:

• Python 3. You can download the latest version of Python here.
• Permission to test. Always ask your environment owner for permission before executing a test.

Install musl

Chain Reactor requires musl, which is an implementation of the C standard libary. To install musl on Debian-like operating systems, run the following from the command line:

sudo apt install musl-tools

To install musl from the RPM package manager:

sudo yum install musl-tools

To build musl from source:

git clone git://git.musl-libc.org/musl
cd musl && ./configure && sudo make install

Install Chain Reactor

To install Chain Reactor, run the following from the command line:

git clone https://github.com/redcanaryco/chain-reactor.git
cd chain-reactor && make

Run a simple reaction

Test your build by creating and executing a simple reaction. Open a text editor and save the following file as reaction.json:

{
    "name": "simple_reaction",
    "atoms": [
        "HIDDEN-PROCESS-EXEC"
    ]
}

Reactions are made of objectives called "atoms." This file defines a reaction—simple_reaction—comprising a single atom called HIDDEN-PROCESS-EXEC.

Next, we need to define HIDDEN-PROCESS-EXEC. Save the following file as atoms.json:

[
    {
        "name" : "HIDDEN-PROCESS-EXEC",
        "execve" : [ "mkdir", "-p", "/tmp/.hidden" ],
        "copy" : [ "/proc/self/exe", "/tmp/.hidden/.chain_reactor_hidden" ],
        "execveat" : [ "/tmp/.hidden/.chain_reactor_hidden", "exit" ],
        "remove" : [ "/tmp/.hidden" ]
    }
]

Atoms are made of actions called "quarks." The atoms.json file defines HIDDEN-PROCESS-EXEC as a sequence of four quarks:

1. Use the execve system call to create a hidden directory.
2. Copy the current Chain Reactor process to the hidden directory.
3. Use the execveat system call to execute the hidden Chain Reactor binary and exit without doing anything else.
4. Delete the hidden directory.

To build the reaction executable, run the following from the command line:

python3 compose_reaction atoms.json reaction.json simple-reaction

You can run the output file as you would any other executable:

$ ./simple-reaction

              .S_sSSs      sSSs 
              .SS~YS%%b    d%%SP
              S%S   `S%b  d%S'  
              S%S    S%S  S%S   
              S%S    d*S  S&S   
              S&S   .S*S  S&S   
              S&S_sdSSS   S&S   
              S&S~YSY%b   S&S   
              S*S   `S%b  S*b   
              S*S    S%S  S*S.  
              S*S    S&S   SSSbs
              S*S    SSS    YSSP
              SP                
              Y                 
 `+ymmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmy+` 
:dmmhsssssssssssssssssssssssssssssssssssssssshmmd/
dmm+`                                        `+mmm
mmm:      `:+oss+:`                           :mmm
mmm:   `:oyyyyyyyys/`                         :mmm
mmm:    .:oyyyyyyyyys:`                       :mmm
mmm:      -syyyyyyyyyyo:`                     :mmm
mmm:       -yyyyyyyyyyyyy+.                   :mmm
mmm:       .syyyyyyyyyyyyyy/`                 :mmm
mmm:       `oyyyyyyyyyyyyyyys.                :mmm
mmm:        :yyyyyyyyyyyyyyyys-               :mmm
mmm:        `+yyyyyyyyyyyyyyyyy:              :mmm
mmm:         `oyyyyyyyyyyyyyyyyy-             :mmm
mmm:          `/yyyyyyyyyyyyyyyys-            :mmm
mmm:            ./yyyyyyyyyyyyyyys`          `/mmm
mmm:              `/yysyyyyyyyyyyy+`  `.:+oydmmmmm
mmm:               ç-o- ``...osyyyyyoydmmmmmmdyymmm
mmm:              ::    `-:syhdhyyyyyhyo+:.`  :mmm
mmm:            -o//+shdmmhhmdhyo/syyyo.      :mmm
mmm:     `.-/oyyyddmmmdhyo/-.`    `/yyys.     :mmm
mmm+:/oyhdmmmmmhys+/-.`             -syys-    :mmm
mmmmmmmmdhs+:-``                     .sy+-`   :mmm
dmmd+:-`                              .ss.   `+mmm
:dmmhssssssssssssssssssssssssssssssssssyssssshmmd/
 `+hmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmh+` 
chain reaction "simple_reaction" 1001 1001
atom: HIDDEN-PROCESS-EXEC
quark: execve("mkdir -p /tmp/.hidden")
quark: copy src="/proc/self/exe" dst="/tmp/.hidden/.chain_reactor_hidden"
quark: execveat("/tmp/.hidden/.chain_reactor_hidden exit")
quark: remove("/tmp/.hidden")
chain reaction complete

Next steps

Check whether your endpoint security product produced telemetry for all four quarks. Did your security product detect the execution of the hidden binary? Use this information to evaluate and improve detections.

For more information about defining reactions, see Defining custom reactions.

For a list of available quark types, see Quark types.