Skip to content

Latest commit

 

History

History
254 lines (163 loc) · 11.6 KB

installation.rst

File metadata and controls

254 lines (163 loc) · 11.6 KB
Raw

Installation

This contains the installation instructions for CALDERA. CALDERA consists of three separate pieces of software:

CALDERA server

The server controls the execution of CALDERA and contains a web interface for administration

CALDERA agent

A Windows service that communicates to the CALDERA server, the CALDERA Agent is installed on every computer partaking in adversary emulation activities.

Crater

A Windows executable that is used as an implant for Adversary Emulation exercises

These instructions have two sections: the first section dictates how to install the CALDERA Server along with Crater. The second section details how to install the CALDERA Agent on each system taking part in the red team.

CALDERA Server Installation

The CALDERA server is installed on a single central server. It should be accessible over the network to all computers that are taking part in the emulated adversary operation. Both Windows and Linux are supported, however installation on Windows requires extra installation steps.

Several options exist for installing the server.

Option 1: Install with Docker Compose

The easiest way to install CALDERA is with Docker Compose. After installing Docker and Docker Compose, from the top-level directory simply run the following:

docker-compose up

This will start the Caldera server and an instance of MongoDB. Follow the Post-install steps to login to the Caldera server and change the Administrator password.

For advanced options, customize the docker-compose.yml file. If you are behind a proxy, uncomment three lines in the build section and edit the lines to include the correct information for your proxy. If you need to specify a different version of Crater (for example, if you need the Windows 7 version), you can specify it with another item under `args`: "crater=https://github.com/mitre/caldera-crater/releases/download/v0.1.0/CraterMain7.exe". Other configuration options can be set in the command section under server.

Option 2: Building the Docker Container By Itself

Alternatively, if you want to connect to an already existing MongoDB instance, you can build the server container by itself:

docker build . -t caldera

If you are behind a proxy, provide proxy information to the build process:

docker build . -t caldera --build-arg http_proxy=http://proxy.example:80 --build-arg https_proxy=http://proxy.example:80

If you need to specify a different version of Crater (for example, if you need the Windows 7 version), you can specify it with another `--build-arg`:

docker build . -t caldera --build-arg http_proxy=http://proxy.example:80 --build-arg https_proxy=http://proxy.example:80 --build-arg crater=https://github.com/mitre/caldera-crater/releases/download/v0.1.0/CraterMain7.exe

Then follow the instructions above regarding MongoDB.

Next run the container:

docker run --net=host caldera

If you need to change any configuration parameters, for example to use a different port for MongoDB, you can do the following:

docker run --net=host caldera --database.port 27020

After installation, follow the Post-install steps to login to the Caldera server and change the Administrator password.

Option 3: Installing Without Docker

If you would like to install without docker, please follow the below instructions.

  1. Install Python 3.5.4 or later

    Python 3.5.4 or later can be acquired from the Operating System's package manager or from https://www.python.org/ . The standard installation is straightforward.

    Note

    On Linux, the development package for Python is needed. For example (may vary based on distribution and version):

    apt-get install python3-dev
  2. Upgrade to setuptools 24.0 or later

    The python package, setuptools, version 24.0 or later must be installed. Setuptools comes with Python 3.5, but some versions may not be up to date. To update it, run

    pip install --upgrade setuptools
  3. [Windows Only] Install Visual C++ 2015 Build Tools

    Install the Visual C++ 2015 Build Tools. During install check Windows 8.1 SDK and Windows 10 SDK options.

    Note

    If Visual Studio 2015 is already installed, Visual C++ 2015 Build Tools should not need to be installed

  4. Install Python libraries

    Within a command prompt navigate to the caldera/caldera folder and run the command

    pip install -r requirements.txt

    This will download and install the Python libraries necessary to run the CALDERA server.

    Note

    When sitting behind a proxy, specific steps must be taken for pip to understand proxies. See Setting your pip configuration file. An example configuration file might look like the following:

    [global]
    proxy = http://my.proxy.name
    cert = C:\My\Path\To\SSL Certificates\chain.pem
  5. Install MongoDB

    MongoDB 3.0 and later are supported. Most Linux distributions have MongoDB in their package manager. Otherwise both Windows and Linux installers can be downloaded from https://www.mongodb.com/download-center#community

  6. MongoDB Configuration

    MongoDB must be configured to use a replication set. There are two ways to do this, either by modifying MongoDB's configuration file or by adding an additional command line flag when starting the MongoDB daemon. On Linux it is typically easier to edit the configuration file (typically located in /etc/mongodb.conf). On Windows it is typically easier to add an additional command line flag. Both methods are detailed below.

    Method 1: Edit Configuration File (Recommended for Linux)

    Depending on the version of MongoDB that you have installed, the configuration file uses two different formats. Old style formatting typically contains equal signs. If you see no equal signs you probably have a new style configuration file (See https://docs.mongodb.com/v3.2/administration/configuration/ for more information.)

    After determining what style configuration file you have, make the following modifications to it:

    Newer version of mongodb use YAML style formatting so the following lines should be added (indentation intended)

    replication:
   replSetName: caldera

    Older versions on mongodb use key value pairs. For this style the following line should be added

    replSet = caldera

    Method 2: Command Line Flag (Recommended for Windows)

    Alternatively, the replication set parameter can also be passed in through the command line if running mongodb from the command line by adding the flag --replSet caldera to the command to start mongod. This is the easiest way to configure replication sets for Windows installs.

  7. Start MongoDB

    MongoDB must be started. If MongoDB was installed using the Operating System's package manager, look for instructions on how to start the MongoDB service (typically service mongod start). On Windows, MongoDB is installed by default in C:\Program Files\MongoDB\Server\<version>\bin. Navigate to this folder on a commandline and run mongod.exe --bind_ip 127.0.0.1 --replSet caldera

  8. [Optional] Install git

    Git can be installed for version tracking information. It is available from Linux distributions package maintainers or from git

  9. 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.

  10. Start the CALDERA server

    The Caldera server can now be started by navigating to the caldera/caldera directory and running python caldera.py. The first time CALDERA is run, it will generate an OpenSSL command line which can be run to create an SSL keypair for encrypted communication. If CALDERA is installed on a Linux machine, OpenSSL is typically already installed and available. On Windows computers, OpenSSL can be installed or, this command should be executed on a Linux computer (with the appropriate hostname substituted).

See the following section for login information.

Post-install steps

After installing, perform the below steps

  1. Login to the Caldera server

    The CALDERA server exposes a web service available on https://localhost:8888. Navigate to this URL to access CALDERA's administration panel. The default username and password

    username: admin
password: caldera
  2. Change the Administrator Password

    Click on the top right button labeled "admin (Admin)" and select "Change Password" to change the default password to something unique and secret.

CALDERA is now installed. Proceed to the next section to install CALDERA Agents.

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.

Operating System Support

Windows 7, 8, 8.1 or 10, 64 bit

A 64 bit version of Windows 7, 8, 8.1 or 10 is required.

Installation Instructions

  1. If not already done, install the CALDERA server

  2. Install the Visual C++ Redistributable for Visual Studio 2015

    Note

    The Visual C++ Redistributable may fail to install if Windows is not fully updated. If you encounter problems try fully updating Windows.

  3. Download the latest release of cagent. Place cagent.exe in the desired installation location (the recommended location is C:\Program Files\cagent\cagent.exe)

  4. In the same directory, place the conf.yml file which can be downloaded from the CALDERA server by navigating to :

    https://my-caldera-server:8888/conf.yml

    Note

    The conf.yml is unique to the CALDERA server. When migrating agents to a new server, you will have to update the conf.yml file

    Warning

    To prevent unauthorized users from modifying cagent.exe or conf.yml ensure the directory that contains these files is only editable by Administrators

  5. In an Administrator command prompt install cagent with: :

    cagent.exe --startup auto install

  6. In an Administrator command prompt start cagent with: :

    cagent.exe start

Agents that are connected to the CALDERA server are visible by checking the Debug>Connected Agents tab.