What Is OWASP Security Shepherd?

Security Shepherd is an OWASP training project for learning manual application-security testing. A lesson introduces a weakness in accessible language; a challenge then asks the learner to recognize the trust failure, reproduce it inside the lab, and submit a user-specific result. The platform covers classic web and mobile security topics such as injection, authentication, access control, cross-site scripting, cross-site request forgery, insecure storage, and data leakage.

Blog Review: What Needed Improvement

The original guide had a useful structure and sensible safety warnings, but several points needed refinement for accuracy and search intent:

Quick Start: Build Security Shepherd with Docker

1. Verify the required tools

git --version
java -version
mvn -version
docker --version
docker compose version

Use OpenJDK 17 for the documented build workflow. The repository’s contributor notes explain that the code still targets Java 8 compatibility, while CI and local builds use Java 17.

2. Clone the active source and record the commit

git clone --depth 1 --branch dev https://github.com/OWASP/SecurityShepherd.git
cd SecurityShepherd
git rev-parse HEAD

Recording the commit gives a class or team a repeatable baseline. The dev branch is active source and may change; do not silently update it halfway through a workshop.

3. Restrict the published ports to loopback

Review docker-compose.yml. If the HTTP and HTTPS mappings publish as $HTTP_PORT:8080 and $HTTPS_PORT:8443, prefix the host side with 127.0.0.1:. The following script changes those two patterns and stops if it cannot verify them:

cp docker-compose.yml docker-compose.yml.original
python3 - <<'SHEPHERD_PORTS'
from pathlib import Path
import re

path = Path("docker-compose.yml")
original = path.read_text()
updated = original

patterns = [
    (r'(?<!127\.0\.0\.1:)(\$HTTP_PORT|\${HTTP_PORT}):8080', r'127.0.0.1:
:8080', 'HTTP_PORT'),
    (r'(?<!127\.0\.0\.1:)(\$HTTPS_PORT|\${HTTPS_PORT}):8443', r'127.0.0.1:
:8443', 'HTTPS_PORT'),
]
for pattern, replacement, label in patterns:
    updated, count = re.subn(pattern, replacement, updated)
    if count == 0:
        raise SystemExit('Could not find the ' + label + ' port mapping. Review docker-compose.yml manually.')

path.write_text(updated)
print("Updated HTTP and HTTPS mappings to bind on 127.0.0.1")
SHEPHERD_PORTS

docker compose config

Inspect the rendered Compose configuration before continuing. If your project revision uses a different structure, restore the original file and edit the published web ports manually. Do not guess.

4. Generate the application assets and start the stack

mvn -Pdocker clean install -DskipTests -B
docker compose up -d --build
docker compose ps

The Maven Docker profile runs before the Compose build because it generates the WAR, database initialization material, and TLS assets required by the containers. A first build can take longer because Maven and Docker must download dependencies and images.

Security Shepherd Requirements

Use a disposable VM when possible. This reduces conflicts with ports 80 and 443, makes cleanup easier, and keeps training traffic separate from personal or company data.

Install Security Shepherd on Ubuntu

Use Docker’s official Ubuntu repository rather than relying on an old distribution package. The commands below install the build tools and current Docker Engine packages:

sudo apt-get update
sudo apt-get install -y ca-certificates curl git maven openjdk-17-jdk python3
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${UBUNTU_CODENAME:-$VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world

You can either keep using sudo docker or deliberately add your account to the Docker group. Membership in that group is effectively root-level access, so do not treat it as an ordinary convenience permission on a shared system.

Install Security Shepherd on Red Hat Enterprise Linux

On a maintained RHEL release, install the build tools and Docker Engine from Docker’s official RHEL repository:

sudo dnf -y install dnf-plugins-core git maven java-17-openjdk-devel python3
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world

SELinux should remain enabled. If a custom bind mount fails, inspect the denial and correct the volume labeling rather than disabling SELinux for the host.

Install Security Shepherd on Windows with Docker Desktop and WSL 2

The cleanest Windows workflow is Docker Desktop using Linux containers and an Ubuntu WSL distribution. Run the first two commands in an elevated PowerShell terminal:

wsl --install -d Ubuntu
winget install -e --id Docker.DockerDesktop

Restart if Windows requests it. Open Docker Desktop, enable the WSL 2 engine and integration for Ubuntu, then open the Ubuntu terminal and install the Linux-side build tools:

sudo apt-get update
sudo apt-get install -y git maven openjdk-17-jdk python3
java -version
mvn -version
docker version
docker compose version

Keep the repository inside the WSL Linux filesystem, such as ~/SecurityShepherd, rather than under /mnt/c/. Builds and file operations are generally more reliable there.

First Run: Database Setup Wizard

After the containers start, open https://localhost/. A self-signed certificate warning is normal for this local lab. Current source builds can redirect to /setup.jsp before showing the login page. That is expected on an uninitialized database.

docker exec secshep_tomcat cat /usr/local/tomcat/conf/SecurityShepherd.auth

Security Shepherd Login and First Session

After setup, use the initial administrator credentials documented by the official README:

URL:      https://localhost/
Username: admin
Password: password

Change the password immediately when prompted. Use a unique lab-only value. Then review registration, module availability, hints, scoreboard, class settings, and layout mode before allowing other learners to connect.

A Safer Security Shepherd Learning Workflow

The guide intentionally does not publish challenge answers or exploit strings. A better learning process is to reproduce one controlled behavior, explain the broken trust assumption, identify the preventive control, and confirm the fix with a regression test.

SQL injection lessons

Use the lesson path to understand why untrusted values must not be concatenated into SQL statements. Focus on parameterized queries, allowlisted input shapes, least-privilege database accounts, predictable error handling, and regression tests. The goal is not to collect payloads; it is to recognize unsafe query construction and replace it with a safe data-access pattern.

CSRF lessons

Use the CSRF modules to study how an authenticated browser can be induced to send an unwanted state-changing request. The defensive review should cover unpredictable anti-CSRF tokens, appropriate SameSite cookie settings, Origin or Referer validation where suitable, avoidance of state changes through safe HTTP methods, and reauthentication for high-impact actions.

Use hints without turning them into answer keys

Attempt the module first, write down what you observed, and then use built-in hints progressively. Many result keys are user-specific. A copied static answer does not demonstrate that the learner can reproduce the behavior, identify its root cause, or verify remediation.

Module:
Learning objective:
Normal behavior:
Controlled change:
Observed result:
Broken trust assumption:
Preventive control:
Detection or logging signal:
Regression test:
Result key submitted:

GitHub Source, Formal Releases, and the Legacy VM

Primary sources:

• Official OWASP Security Shepherd project page
• Official GitHub repository and README
• Official GitHub Releases page
• Docker Engine on Ubuntu
• Docker Engine on RHEL
• Docker Desktop on Windows

Security Shepherd Command Toolkit

# Show services
docker compose ps

# Follow Tomcat logs
docker compose logs -f web

# Stop and restart without deleting data
docker compose stop
docker compose start

# Remove containers but keep named volumes
docker compose down

# Rebuild the pinned source revision
mvn -Pdocker clean install -DskipTests -B
docker compose up -d --build

# DESTRUCTIVE RESET: removes databases, users, and progress
docker compose down -v
docker compose up -d --build

OWASP Security Shepherd Troubleshooting

docker compose is not recognized

Install the Docker Compose plugin or use the legacy docker-compose command documented by the project. Do not mix two different Docker installations in the same environment.

Maven reports an unsupported Java release

Run java -version and mvn -version. Both should point to OpenJDK 17 for the documented build. On systems with multiple JDKs, correct JAVA_HOME and the active alternatives.

Port 80 or 443 is already in use

Find the existing listener before changing anything. Stop the conflicting local service or change the host-side port values in the project’s .env and Compose configuration. Keep the binding on 127.0.0.1.

# Linux or WSL
sudo ss -ltnp | grep -E ':(80|443)\b'

# Windows PowerShell
Get-NetTCPConnection -State Listen | Where-Object LocalPort -in 80,443

The setup wizard cannot connect to the database

Use secshep_mariadb and secshep_mongo, not localhost. Confirm the database containers are running, inspect their logs, and verify the password in the checked-out .env file.

MariaDB exits with a stored-procedure syntax error

The repository contributor notes identify a stale image cache as one possible cause. Rebuild the database image without cache after rerunning the Maven Docker profile:

mvn -Pdocker clean install -DskipTests -B
docker compose build --no-cache db
docker compose up -d db

If your Compose revision uses a different service name, obtain it from docker compose config --services before running the command.

The browser opens before Tomcat is ready

Wait for the web container to finish startup and follow its logs. A container marked “running” does not necessarily mean that the application has completed initialization.

I need a completely clean instance

Use docker compose down -v only after confirming that you no longer need users, scores, configuration, or lab progress. Then rebuild and repeat the first-run wizard.

What to Carry from the Lab into Real Applications

Security Shepherd is a training platform, not a model for production deployment. The durable value comes from translating each exercise into engineering and operational controls:

Related guides: OWASP Top 10 vulnerabilities with examples, API security testing versus runtime monitoring, and API security incident response playbook.

Security Shepherd Setup Checklist

Conclusion

The best 2026 Security Shepherd setup is a deliberately isolated, reproducible lab: use the official source, record the commit, build with Maven and OpenJDK 17, keep Docker’s web ports on loopback, complete first-time database initialization when required, change the documented default administrator password, and destroy the environment when training ends. This approach preserves the project’s learning value without turning an intentionally vulnerable application into an unmanaged network risk.

OWASP Security Shepherd FAQ