Set-up

The following are the components you will need to set-up if you want to run the entire PurpleTeam solution locally.

If you can’t be bothered with all this work, then use the PurpleTeam-Labs cloud environment. Head to the quick-start page.

If you are using the local environment, run through all of the set-up steps in this file and the linked resources. All git repositories that you clone or fork locally should sit within the same directory level. Once you have completed the local set-up, continue to the workflow page to get all of the PurpleTeam components running locally.

The path of least resistance is to set everything up on a GNU/Linux distribution. Windows tends to yield additional obstacles.

PurpleTeam `local` Architecture

The following diagram shows how the PurpleTeam components communicate. In the local environment it’s your responsibility to follow all the directions to enable all components to interact correctly:

At this stage we’re locked to docker-compose versions before the rewrite of v2. This is mostly because we currently depend on docker-compose-ui which only supports docker-compose versions prior to version 2.

Docker Network

Before most of the supporting commands can be run, such as running docker-compose-ui (which hosts the stage two containers), and sam-cli (which hosts the purpleteam-lambda functions locally), the compose_pt-net Docker network needs to be created. You can create this bridge network manually. Alternatively once you have both purpleteam-orchestrator and purpleteam-app-scanner repository cloned and configured as per the details under Orchestrator and Application Scanner, running the following two commands from the purpleteam-orchestrator root directory will create the network:

npm run dc-build

npm run dc-up

Providing you have configured the orchestrator and Application Scanner:

dc-build will build the stage one Docker services (images).
dc-up will create the required Docker network and containers, it will then bring all containers up that are listed (stage one) in the orchestrator-testers-compose.yml file. The actual process of running the components is under the Workflow page.

Your System Under Test (SUT)

Obviously you are going to need a web application that you want to put under test. A couple of options for you to start to experiment with if you don’t yet have a SUT in a Docker container ready to be tested are:

If you want to target a local SUT, it needs to be running in a Docker container. Clone a copy of NodeGoat and make the following changes:
- Add the following docker-compose.override.yml file to the root directory
```
version: "3.7"

networks:
  compose_pt-net:
    external: true

services:
  web:
    networks:
      compose_pt-net:
    depends_on:
      - mongo
    container_name: pt-sut-cont
    environment:
      - NODE_ENV=production
  mongo:
    networks:
      compose_pt-net:
```
  This option means that NodeGoat will be running in the pt-net network created by the orchestrator’s docker-compose
- Change the passwords in the artifacts/db-reset.js file.
The PurpleTeam-labs core team usually just store these files in a sibling directory to the NodeGoat repository.

When you are ready to bring NodeGoat up, just run the following command from the NodeGoat root directory:
```
docker-compose up
```
An alternative is to spin up purpleteam-iac-sut. PurpleTeam-Labs use this for both local and cloud testing

Lambda functions

Details on installing and configuring the aws cli and aws-sam-cli in order to be able to host the purpleteam-lambda functions locally can be found here

Stage Two containers

Details on configuring and debugging (gaining insights into what is happening inside the containers) if needed can be found here

Orchestrator

To run the stage one containers (orchestrator, Testers and Redis) we use npm scripts from the purpleteam-orchestrator project to run the docker-compose files. The main docker-compose file is orchestrator-testers-compose.yml.

Environment Variables

The orchestrator-testers-compose.yml file has several bind mounts. The mounts expect the HOST_DIR and HOST_DIR_APP_SCANNER environment variables to exist and be set to host directories of your choosing. You will need source directories set-up and their respective directory paths assigned as values to the HOST_DIR and HOST_DIR_APP_SCANNER environment variables.

The directory that the HOST_DIR refers to is mounted by the orchestrator and all Testers. This directory gets written to by the Testers and orchestrator and read from by the orchestrator. This directory should have 0o770 permissions.

The directory that the HOST_DIR_APP_SCANNER refers to is mounted by both App Tester and it’s Emissary. The App Tester writes files here that it’s Emissary consumes, the App Emissary writes reports here that the App Tester consumes. This directory should have 0o770 permissions.

We have created a .env.example file in the orchestrator compose/ directory. Rename this to .env and set any values within appropriately.

Set-up for Running Emissaries

Firewall Rules

If you use a firewall, you may have to make sure that the PurpleTeam components can communicate with each other.

Testers need to communicate with the locally running Lambda service in order to start and stop stage two containers.

Communications (TCP) will need to flow from the app-scanner container (pt-app-scanner-cont) bound to the pt-net (or listed as compose_pt-net with docker network ls) Docker network IP address of 172.25.0.120 - to the IP address and port that local Lambda is listening on (172.25.0.1:3001) which can be seen in the sam local start-lambda commands (as seen in the local-workflow documentation) used to host the lambda functions

Host IP Forwarding

Make sure host IP forwarding is turned on.

Details on installing the orchestrator dependencies and configuring can be found here.

Testers

Currently PurpleTeam has the app-scanner and the tls-scanner implemented. The server-scanner is stubbed out and in the Product Backlog waiting to be implemented. Details on progress can be found here (for server-scanner).

Application Scanner

Details on installing the app-scanner dependencies and configuring can be found here

TLS Scanner

Details on installing the tls-scanner dependencies and configuring can be found here

Server Scanner

Not yet implemented.

Details on installing the server-scanner dependencies and configuring once implemented will be found here

PurpleTeam (CLI)

Details on installing the PurpleTeam CLI (purpleteam), configuring and running can be found here

Once completed the local set-up, head to the workflow page to get all of the PurpleTeam components running locally.

Last updated on May 8, 2021

Edit this page