From af90159888b1f874567a58b0b04df0e656b894cb Mon Sep 17 00:00:00 2001 From: Henry Foster Date: Fri, 3 Aug 2018 09:28:48 -0700 Subject: [PATCH] add encode.py to docs --- docs/add_technique.rst | 11 +++++--- docs/commands.rst | 2 -- docs/encoding_external_files.rst | 44 ++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/installation.rst | 4 +-- docs/techniques.rst | 3 ++- 6 files changed, 56 insertions(+), 9 deletions(-) create mode 100644 docs/encoding_external_files.rst diff --git a/docs/add_technique.rst b/docs/add_technique.rst index caef7ee73..b72186fb0 100644 --- a/docs/add_technique.rst +++ b/docs/add_technique.rst @@ -105,7 +105,9 @@ Here is the second precondition: The first item names the precondition: :code:`'host'`. The second item starts with :code:`OPHost`, specifying that this precondition refers to objects that are `Hosts`. The next part of the expression denotes conditions on the :code:`OPHost`. :code:`OPVar` is a special keyword which matches to a previously defined -precondition. The entire expression, :code:`OPVar("rat.host")`, matches to the `host` field of the previously defined `rat` precondition. In plain terms, the precondition :code:`OPHost(OPVar("rat.host"))` matches to an of object of type :code:`OPHost` that is the same object as the :code'`host` field of the :code:`rat` precondition. +precondition. The entire expression, :code:`OPVar("rat.host")`, matches to the `host` field of the previously defined +`rat` precondition. In plain terms, the precondition :code:`OPHost(OPVar("rat.host"))` matches to an of object of +type :code:`OPHost` that is the same object as the :code:`host` field of the :code:`rat` precondition. In psuedocode this would look something like this: @@ -119,7 +121,7 @@ Now that you understand these preconditions, we're going to jump down a bit to a :pyobject: DirListCollection :lines: 28 -This defines the Step's :code:`action` function. The action function is called when CALERA decides to +This defines the Step's :code:`action` function. The action function is called when CALDERA decides to execute the Step. Notice the parameters :code:`rat` and :code:`host` these match the preconditions that are defined above (because they match the precondition's names). When the Step is called, objects that match the :code:`rat` and :code:`host` preconditions will be passed into the :code:`action` function. @@ -160,7 +162,8 @@ The class variable :code:`significant_parameters` allows the user to specify whi :pyobject: DirListCollection :lines: 19 -By default CALDERA will not re-run an action if all of the parameters are the same as an action that has previously been executed. +By default CALDERA will not re-run an action if all of the parameters are the same as an action that has previously +been executed. However, this behavior can be overridden using the :code:`significant_parameters` class variable. Here we set the significant_parameter as "host" because we want this Step to only be performed once per host. If we had left @@ -275,7 +278,7 @@ computer. We only want this to be run once per host, so we'd like to set the significant parameters to be -the host that the Step is being exceuted on, which is the Rat's host (that is, :code:`rat.host`), +the host that the Step is being exceuted on, which is the Rat's host (that is, :code:`rat.host`), however we need to have the host as a named precondition in order to do this, so we will also have to modify our preconditions to create a new precondition to refer to the Rat's host. diff --git a/docs/commands.rst b/docs/commands.rst index 113d48180..6576ae184 100644 --- a/docs/commands.rst +++ b/docs/commands.rst @@ -19,8 +19,6 @@ CommandLine generators .. automodule:: caldera.app.commands.cmd :members: -.. automodule:: caldera.app.commands.footprint - :members: .. automodule:: caldera.app.commands.mimikatz :members: .. automodule:: caldera.app.commands.nbtstat diff --git a/docs/encoding_external_files.rst b/docs/encoding_external_files.rst new file mode 100644 index 000000000..8cb21f0a6 --- /dev/null +++ b/docs/encoding_external_files.rst @@ -0,0 +1,44 @@ +======================= +Encoding External Files +======================= + +CALDERA uses a simple encoding scheme to disguise some of the external +scripts and tools used by the project. This can be useful in preventing +AV software from interfering with the operation +of the CALDERA server. + + +Using the script editor +----------------------- + +Small changes to external scripts can be made via the +CALDERA web application via the built-in Script Editor. + +Manually with encode.py +----------------------- + +For larger changes and encoding binary files ``scripts/encode.py`` can be +used. This script will read in a file specified with the ``-i`` option +and output an encoded file to a path specified with the ``-o`` option. + + +Example +^^^^^^^ + +The following series of commands are an example of downloading and encoding +a new version of powerview using the ``encode.py`` script. + + .. code-block:: bash + + cd scripts/ + + # Download a version of powerview from Empire's dev branch + curl -L -o powerview.ps1 https://github.com/EmpireProject/Empire/raw/dev/data/module_source/situational_awareness/network/powerview.ps1 + + # Encode the powershell script + python encode.py -i powerview.ps1 -o powerview-ps1 + + mv powervew-ps1 ../caldera/files + + # remove the downloaded file + rm powerview.ps1 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f5b1e4d6b..f79ece017 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ CALDERA User Documentation :caption: Developer Information techniques + encoding_external_files legal developer build diff --git a/docs/installation.rst b/docs/installation.rst index 36a1c1dd0..d16308d8a 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -174,7 +174,7 @@ If you would like to install without docker, please follow the below instruction #. *Install CraterMain.exe* The `CraterMain.exe` binary needs to be accessible to CALDERA. It should be placed in: `caldera/dep/crater/crater/CraterMain.exe` on the computer that the CALDERA server is installed on. - Pre-built copies of CraterMain.exe are available `here `_. + Pre-built copies of CraterMain.exe are available `here `__. #. *Start the CALDERA server* The Caldera server can now be started by navigating to the `caldera/caldera` directory and running @@ -212,7 +212,7 @@ CALDERA Agent Installation The CALDERA Agent or cagent, is installed on every computer participating in the Adversary Emulation. It should be accessible over the network to the CALDERA server. Once configured, each cagent will register with the CALDERA server making its computer available as an option in an operation. Pre-built cagent binaries are available -`here `_. +`here `__. Operating System Support ------------------------ diff --git a/docs/techniques.rst b/docs/techniques.rst index 25775ea46..b2aed7d1e 100644 --- a/docs/techniques.rst +++ b/docs/techniques.rst @@ -3,4 +3,5 @@ Techniques ========== .. automodule:: caldera.app.operation.operation_steps - :members: \ No newline at end of file + :members: +