The OWASP Security Shepherd Project is a web and mobile application security training platform. Security Shepherd has been designed to foster and improve security awareness among a varied skill-set demographic. The aim of this project is to take AppSec novices or experienced engineers and sharpen their penetration testing skill set to security expert status.
You can download Security Shepherd VM's or Manual Installation Packs from GitHub
# Install pre-reqs
sudo apt install git maven docker docker-compose openjdk-17-jdk
# Clone the github repository
git clone https://github.com/OWASP/SecurityShepherd.git
# Change directory into the local copy of the repository
cd SecurityShepherd
# Adds 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 upOpen up an Internet Browser & type in the address bar;
To login use the following credentials (you will be asked to update after login);
- username:
admin - password:
password
Note: Environment variables can be configured in dotenv .env file in the root dir.
Security Shepherd now runs on Tomcat 11. Tomcat's conf directory lives in the conf Docker volume, and Docker only copies the image's files into a volume when the volume is first created. An existing environment would therefore start Tomcat 11 with its old Tomcat 9/10.1 server.xml and web.xml. That volume has to be recreated. Database data is in the separate data and mongodata volumes, so it is kept.
The conf volume also holds the TLS keystore and the database.properties / mongo.properties connection settings, so back it up first:
docker-compose down
# The volume is named <project>_conf; check with: docker volume ls
# The archive holds the TLS private key and database password. Keep it outside the repository
# (the repository root is the Docker build context) and readable by you only
BACKUP_DIR="$HOME/shepherd-conf-backup"
mkdir -p "$BACKUP_DIR" && chmod 700 "$BACKUP_DIR"
docker run --rm -v securityshepherd_conf:/conf -v "$BACKUP_DIR":/backup alpine sh -c \
'umask 077 && touch /backup/shepherd-conf-backup.tgz && chmod 600 /backup/shepherd-conf-backup.tgz \
&& tar czf /backup/shepherd-conf-backup.tgz -C /conf .'
docker volume rm securityshepherd_conf
mvn -Pdocker clean install -DskipTests
# Detached, so the databases keep running while you restore files below
docker-compose up -d --buildThe new volume starts from the image: a freshly built keystore, and connection settings taken from .env. If you had customised either, copy just those files back from the backup. Leave server.xml and web.xml alone, because they are the Tomcat 11 versions.
BACKUP_DIR="$HOME/shepherd-conf-backup"
# Connection settings changed through the setup page:
docker run --rm -v securityshepherd_conf:/conf -v "$BACKUP_DIR":/backup alpine \
tar xzf /backup/shepherd-conf-backup.tgz -C /conf ./database.properties ./mongo.properties
# Your own TLS certificate: restore the keystore file named by TLS_KEYSTORE_FILE, and make sure
# TLS_KEYSTORE_PASS and ALIAS in .env match it before building
docker run --rm -v securityshepherd_conf:/conf -v "$BACKUP_DIR":/backup alpine \
tar xzf /backup/shepherd-conf-backup.tgz -C /conf ./<your keystore file>
docker-compose restart webDelete $BACKUP_DIR (or move it somewhere safe) once the upgrade is working. On Linux hosts the archive is owned by root, but you can still delete it because you own the directory.
If you had hand-edited the old server.xml or web.xml (custom connectors, ports, ciphers and so on), re-apply those edits to the new Tomcat 11 files, using the backup as a reference. Don't copy the old files back.
The database image now runs MariaDB 12.3 (long-term support) instead of 10.6, which is no longer supported. The data volume is kept. On its first start, MARIADB_AUTO_UPGRADE=1 in docker-compose.yml upgrades the volume's system tables, after taking a backup of them inside the volume. Back up your data before rebuilding anyway, because a volume can't be moved back to 10.6 once 12.3 has opened it. Run this while the old container is still up. The dump holds every user's password hash, so like the conf backup above it goes outside the repository and is readable by you only:
BACKUP_DIR="$HOME/shepherd-db-backup"
mkdir -p "$BACKUP_DIR" && chmod 700 "$BACKUP_DIR"
(umask 077 && docker exec secshep_mariadb sh -c \
'export MYSQL_PWD="$MYSQL_ROOT_PASSWORD"; exec mysqldump -uroot --all-databases --routines --events' \
> "$BACKUP_DIR/shepherd-db-backup.sql")Delete $BACKUP_DIR (or move it somewhere safe) once the upgrade is working.
We've got fully automated and step by step walkthroughs on our wiki page to help you get Security Shepherd up and running.
Security Shepherd can be used as a;
- Teaching Tool for All Application Security
- Web Application Pen Testing Training Platform
- Mobile Application Pen Testing Training
- Safe Playground to Practise AppSec Techniques
- Platform to demonstrate real Security Risk examples
There are a lot of purposefully vulnerable applications available in the OWASP Project Inventory, and even more across the internet. Why should you use Security Shepherd? Here are a few reasons;
- Wide Topic Coverage
Shepherd includes over sixty levels across the entire spectrum of Web and Mobile application security under a single project. - Gentle Learning Curve
Shepherd is a perfect for users completely new to security with levels increasing in difficulty at a pleasant pace. - Layman Write Ups
When each security concept is first presented in Shepherd, it is done so in layman terms so that anyone (even beginners) can absorb them. - Real World Examples
The security risks in Shepherd are real vulnerabilities that have had their exploit impact dampened to protect the application, users, and environment. There are no simulated security risks which require an expected, specific attack vector in order to pass a level. Attack vectors when used on Shepherd are how they would behave in the real world. - Scalability
Shepherd can be used locally by a single user or easily as a server for a high amount of users. - Highly Customisable
Shepherd enables admins to set what levels are available to their users and in what way they are presented (Open, CTF and Tournament Layouts) - Perfect for Classrooms
Shepherd gives it's players user specific solution keys to prevent students from sharing keys, rather than going through the steps required to complete a level. - Scoreboard
Security Shepherd has a configurable scoreboard to encourage a competitive learning environment. Users that complete levels first, second and third get medals on their scoreboard entry and bonus points to keep things entertaining on the scoreboard. - User Management
Security Shepherd admins can create users, create admins, suspend, unsuspend, add bonus points, or take penalty points away from users' accounts with the admin user management controls. Admins can also segment their students into specific class groups. Admins can view the progress a class has made to identify struggling participants. An admin can even close public registration and manually create users if they wish for a private experience. - Robust Service
Shepherd has been used to run online CTFs such as the OWASP Global CTF and OWASP LATAM Tour CTF 2015, both surpassing 200 active users and running with no down time, bar planned maintenance periods. - Configurable Feedback
An administrator can enable a feedback process, which must be completed by users before a level is marked as complete. This is used both to facilitate project improvements based on feedback submitted and for system administrators to collect "Reports of Understanding" from their students. - Granular Logging
The logs reported by Security Shepherd are highly detailed and descriptive, but not screen blinding. If a user is misbehaving, you will know.