Architecture¶
This page is for contributors. It describes how Security Shepherd is put together: the parts of the web application, how a player's request reaches a level, and how a completed level is scored. Database layer goes further into the databases, and Creating a level uses this page to add one.
The parts¶
Security Shepherd is a Java web application, a WAR, that runs on Tomcat 11 with Jakarta EE 11 and Java 17. It keeps its data in MariaDB, plus MongoDB for one level. The mobile levels are separate Android apps in mobile/MobileShepherd/, and aren't covered here.
flowchart TB
browser["Player's browser, with a proxy"]
subgraph tomcat["Tomcat 11"]
jsp["JSPs<br/>pages and level views"]
platform["Platform servlets<br/>login, admin, getModule, …"]
levels["Level servlets<br/>lessons and challenges"]
db["dbProcs<br/>Getter, Setter, Database"]
end
core[("core<br/>with the core account")]
schemas[("A schema per SQL level<br/>with the level's account")]
mongo[("MongoDB<br/>NoSQL level only")]
browser --> jsp & platform & levels
platform --> db
levels --> db
db --> core
db --> schemas
levels --> mongo
| Part | Where | What it does |
|---|---|---|
| Platform servlets | src/main/java/servlets/, servlets/admin/, servlets/module/ |
Login and registration, setup, the scoreboard, the Admin menu, and the module framework that opens levels and checks result keys |
| Level servlets | servlets/module/lesson/, servlets/module/challenge/ |
The lessons and challenges. Deliberately vulnerable: don't fix them. |
| JSPs | src/main/webapp/ |
The platform's pages, the Admin pages in admin/, and each level's page in lessons/ or challenges/, named after the level's hash |
| Utilities | src/main/java/utils/ |
Session and input validation, result key hashing, the cached settings (ScoreboardStatus, ModulePlan, CountdownHandler, …), logging, and single sign-on (SamlSso) |
| Database layer | src/main/java/dbProcs/ |
Connection pools, and the queries on core, mostly through stored procedures. See Database layer. |
| Text | src/main/resources/i18n/ |
Every string shown to players, in properties files, with a copy per language. See Translating Security Shepherd. |
| Schemas | src/main/resources/database/ |
coreSchema.sql (the platform's tables, stored procedures, levels and settings) and moduleSchemas.sql (the levels' schemas and accounts) |
Two classes run around every request. SetupFilter sends every request to the setup page until the database is configured. listeners.DatabaseLifecycleListener opens the connection pools when the application starts, and closes them when it stops.
How a player completes a level¶
The start page, index.jsp, is a single page. Its menu asks the platform servlets for levels, and shows each level's page in a frame.
sequenceDiagram
actor Player
participant Platform as Platform servlets
participant Level
participant Core as core database
Player->>Platform: Open a level (getModule)
Platform->>Core: Record the start time
Platform-->>Player: The level's page
Player->>Level: Attack it, through a proxy
Level-->>Player: Result key
Player->>Platform: Submit the key (solutionSubmit)
Platform->>Core: Check the level is open and the key is right
opt Feedback is on
Platform-->>Player: Feedback form
Player->>Platform: Answers (feedbackSubmit)
end
Platform->>Core: Add points, bonus and medal
Platform-->>Player: Level completed
- Opening a level.
getModulechecks the level is open and returns the address of its page. ThemoduleGetHashstored procedure records when the player started it, which View Feedback uses to show how long each player took. - Result keys. A level either has one fixed key for everyone, or a key of its own for each player. Per-player keys are made by
Hash.generateUserSolutionfrom the level's base key and the player's username.solutionSubmitmakes the same key again to check a submission, so a key copied from another player fails.hardcodedKeyin the level's database entry says which kind a level uses. - Scoring. The
userUpdateResultstored procedure adds the level's points, the bonus for the first five players in the class, and a medal for the first three. Wrong keys are counted byuserBadSubmission. Players lose 10% of their score for each wrong key after the 40th. - Event times. While the event is locked, completions are recorded with no points, and before the start or after the end, levels can't be opened or submitted. See Event times.
Settings and state¶
The Admin menu's settings are stored in the settings table of core, and each is cached in a class in utils/ the first time it's read: ScoreboardStatus, ModulePlan (the layout), OpenRegistration, CheatSheetStatus, FeedbackStatus and CountdownHandler. The Admin pages update both the table and the cache, so a change made directly in the database needs a Tomcat restart.
The module block is the exception: ModuleBlock keeps it in memory only, so restarting Tomcat removes it. Configuration lists the settings.
Sessions are Tomcat's own HTTP sessions. Every form and request that changes something carries a CSRF token, which the platform servlets check with Validate.validateTokens.
Building and running¶
| Command | What it makes |
|---|---|
mvn clean package -DskipTests |
target/owaspSecurityShepherd.war, for your own Tomcat. See Manual setup. |
mvn -Pdocker clean package -DskipTests |
The WAR, plus the SQL and MongoDB scripts the Docker images need |
docker compose up -d --build |
The three containers described in Getting started |
Development workflow and Running tests cover the rest of the development cycle.