Docker Environment Setup

Prerequisites

# Install pre-reqs
sudo apt install git maven docker docker-compose openjdk-8-jdk

# Clone the github repository
git clone https://github.com/OWASP/SecurityShepherd.git

# Change directory into the local copy of the repository
cd SecurityShepherd

Docker (Running on Ubuntu)

Initial Setup

# Add current user to the docker group (don't have to run docker with sudo)
sudo gpasswd -a $USER docker

# Run maven to generate the WAR and HTTPS Cert.
mvn -Pdocker clean install -DskipTests

# Build the docker images, docker network and bring up the environment
docker-compose up

Update the web application

# When you have code changes you can view them by updating the web app
mvn -Pdocker clean install -DskipTests

docker rm -f secshep_tomcat

docker-compose build web

docker-compose up -d

Use the Application

Open up an Internet Browser & type in the address bar;

• localhost

To login use the following credentials (you will be asked to update after login);

• username: admin
• password: password

The environment

The project contains a .env file. This file contains environment variables that you can set for the docker-compose set up.

docker-compose creates

• x3 images

1. owasp/security-shepherd_mariadb (database)
2. owasp/security-shepherd (application)
3. owasp/security-shepherd_mongo (for the NoSQL levels)

• x3 containers

1. secshep_mariadb (database)
2. secshep_tomcat (application)
3. secshep_mongo (for the NoSQL levels)

• x4 volumes

1. securityshepherd_conf (application configuration for tomcat)
2. securityshepherd_data (the database data i.e. user progress etc.)
3. securityshepherd_mongoconfig (created by base image - not used)
4. securityshepherd_mongodata (created by base image -not used)

Modifying the environment

Running the database on a different port

Change the value DB_PORT in the .env file to whatever you want e.g. DB_PORT=3312 Once you issue docker-compose up it'll expose the database on port 3312.

Example when running docker ps

CONTAINER ID   IMAGE                             COMMAND                  CREATED         STATUS         PORTS                       NAMES

ebc53c7fc3b0   owasp/security-shepherd_mariadb   "docker-entrypoint.s…"   6 seconds ago   Up 5 seconds 127.0.0.1:3312->3306/tcp     secshep_mariadb

Test login with mysql client mysql -u root -pCowSaysMoo -P 3312

Accessing the database running on a VM

For developers on Windows or Mac they'll need to run docker on a VM. In this case you may want to expose the database when developing to your local environment.

You should change the values DB_SERVER_IP and DB_BIND_ADDRESS to 0.0.0.0 e.g.

DB_SERVER_IP=0.0.0.0
DB_BIND_ADDRESS=0.0.0.0

Then issue docker-compose up

Additional Notes

• To get your terminal back when running docker-compose (don't tail the logs) issue a -d

docker-compose up -d

Security Shepherd through docker-compose

Shutdown Containers

# The web app
docker-compose stop web

# The db
docker-compose stop db

# Everything
docker-compose stop

Start Containers

# The web app
docker-compose start web

# The db
docker-compose start db

# Everything
docker-compose start

Rebuild Web App

# When you have code changes you can view them by updating the web app
mvn -Pdocker clean install -DskipTests

docker rm -f secshep_tomcat

docker-compose build web

docker-compose up -d

Rebuild everything

# Build the WAR & generate the TLS cert
mvn -Pdocker clean install -DskipTests

# WARNING - All data will be lost from the database
# remove all docker containers
docker-compose down

# build the environment
docker-compose build

# bring the environment up
docker-compose up

List the volumes

docker volume ls

Remove the Containers

# Remove the web container
docker rm -f secshep_tomcat

# WARNING - All data will be lost from the database
# Remove the database container
docker rm -f secshep_mysql

# Remove all containers
docker-compose down

Wipe everything

# WARNING - All data will be lost from database
# All Security Shepherd images will be wiped
docker-compose down --rmi all