Skip to content

feat(mobile): add unified Security Shepherd Android app - #894

Closed
SeanDuggan wants to merge 28 commits into
OWASP:devfrom
SeanDuggan:dev#829-app
Closed

SeanDuggan wants to merge 28 commits into
OWASP:devfrom
SeanDuggan:dev#829-app

Conversation

@SeanDuggan

@SeanDuggan SeanDuggan commented Jun 12, 2026 •

Copy link
Copy Markdown
Member

Replaces the collection of per-challenge standalone APKs with a single unified app (org.owasp.mobileshepherd) covering all 19 mobile modules: lessons and challenges for Client-Side Injection, Insecure Data Storage, Insecure Communication, Insufficient Cryptography, Reverse Engineering, Poor Authentication, Security Misconfiguration, Privacy Controls, Input Validation, Insecure Authorization, and Supply Chain.

Android app changes:

  • New unified app with Navigation Component and ViewBinding
  • Material Design 3 with dark mode support
  • Full login/registration flow connected to the web platform
  • Progress tracking and scoreboard integration
  • Cheatsheets for all 19 modules
  • CI workflow for Android lint and build

Server-side changes:

  • Add MobileFlagGet, MobileFlagSubmit, MobileInsecureApi, MobileModuleFlags, MobileModuleProgress, MobileModuleStart, MobileRegister servlets
  • Update MobileLogin servlet
  • Update coreSchema.sql with mobile module tables and procedures
  • Add i18n properties for mobile challenge/lesson strings
  • Add Android lint and build GitHub Actions workflows

Closes #829
Closes #752
Closes #458
Closes #459
Closes #473

@SeanDuggan

Copy link
Copy Markdown
Member Author

@ismisepaul Standalone APK has been improved and new levels added. I've been testing but will perform more testing before release to ensure everything works as intended.

Let me know if changes are needed.

DuggSe01 and others added 22 commits October 20, 2026 00:25
Replaces the collection of per-challenge standalone APKs with a single
unified app (org.owasp.mobileshepherd) covering all 19 mobile modules:
lessons and challenges for Client-Side Injection, Insecure Data Storage,
Insecure Communication, Insufficient Cryptography, Reverse Engineering,
Poor Authentication, Security Misconfiguration, Privacy Controls,
Input Validation, Insecure Authorization, and Supply Chain.

Android app changes:
- New unified app with Navigation Component and ViewBinding
- Material Design 3 with dark mode support
- Full login/registration flow connected to the web platform
- Progress tracking and scoreboard integration
- Cheatsheets for all 19 modules
- CI workflow for Android lint and build

Server-side changes:
- Add MobileFlagGet, MobileFlagSubmit, MobileInsecureApi, MobileModuleFlags,
  MobileModuleProgress, MobileModuleStart, MobileRegister servlets
- Update MobileLogin servlet
- Update coreSchema.sql with mobile module tables and procedures
- Add i18n properties for mobile challenge/lesson strings
- Add Android lint and build GitHub Actions workflows
MobileFlagGet was calling Getter.hasPlayerStarted() as a DB fallback
for the in-memory module-start cache, but this method does not exist
in upstream's Getter class. Remove the fallback; the in-memory check
in MobileModuleProgress.hasStarted() is sufficient.
…ster

Fix Spotless violations:
- MobileLogin.java: convert CRLF to LF line endings
- MobileRegister.java: reflow Javadoc and method call line breaks
The previous version re-inserted 68 modules that already exist in the
upstream schema, causing PRIMARY KEY violations during integration test
DB setup and failing all IT tests.

Replace with upstream coreSchema.sql and append only the 9 genuinely
new mobile modules:
- Mobile Insecure Authorization (lesson)
- Mobile Insecure Communication (lesson + challenge)
- Mobile Security Misconfiguration (lesson + challenge)
- Mobile Input Validation (lesson)
- Mobile Privacy Controls (lesson)
- Mobile Supply Chain (lesson)
- Mobile Insufficient Cryptography (lesson)

incrementalRank values set to 105-113 (after upstream's highest rank of ~100)
to avoid conflicts.
…edWhereClause

testGetModuleStatusMenuWhenMobileOnlyOpen validates that every module
in the DB belongs to either the web or mobile hardcoded category list.
Our 7 new mobile categories were missing from the list, causing the test
to fail with a count mismatch after openOnlyMobileCategories() was called.
getModulesJson() calls ResourceBundle.getString() for each module's
moduleNameLangPointer and 'category.' + moduleCategoryLangPointer.
Without these keys, a MissingResourceException is thrown mid-iteration,
causing getModulesJson() to return an incomplete JSON array (missing the
modules wrapper element), which breaks LevelsIT and GetterIT tests.

Adds 9 module name keys and 7 category keys for the new modules added
in coreSchema.sql.
Delete 16 DB modules, their JSP pages, cheatsheet entries, locale
keys and solutions that have no corresponding fragment in the Android
app.  These modules (Mobile Broken Crypto x4, Content Provider x2,
Data Leakage x3, RE lesson+RE2+RE3, Untrusted Input, Poor Auth 2,
IDS2+IDS3) were causing IT test failures in
testGetModuleStatusMenuWhenMobileOnlyOpen because the DB module count
diverged from what the Setter where-clause matched.

Also add a dedicated DB module and cheatsheet entry for
InsufficientCryptoChallengeFragment (previously mapped to the deleted
Broken Crypto 1 row) and update MODULE_DB_IDS accordingly.

Removes four empty categories from
mobileModuleCategoryHardcodedWhereClause (Mobile Broken Crypto,
Mobile Content Provider, Mobile Data Leakage, Mobile Security
Decisions via Untrusted Input).
The RE lesson (LessonFragment / nav_lesson) exists on the Android app
and maps to FlagValidator.Module.RE_LESSON in MainActivity.  It was
incorrectly removed in the previous commit.

Restore:
- coreSchema.sql INSERT for module 2ab09c0c (Reverse Engineering lesson)
  and its cheatSheetCreate call
- reverse.engineering locale key in moduleNames.properties
- solutions.properties entry for 2ab09c0c
- The lesson JSP file 19753b94...
- MODULE_DB_IDS entry for re_lesson in MobileModuleFlags
The Content Provider Leakage module (5b461ebe...) was removed from
coreSchema.sql when old mobile modules without app implementations
were deleted. Replace it with the Client Side Injection lesson
(335440fe...) which exists in the current schema and serves the
same purpose in testCheckPlayerResultWhenModuleNotComplete.
Re-add 11 mobile challenge modules that were removed in ab0c50e but
are still needed by the IT test threshold (testGetChallenges requires
> 58 challenges, and the removals brought the count to 55).

Changes:
- coreSchema.sql: restore 11 challenge module INSERTs and 8
  cheatSheetCreate calls for modules with solutions
- Setter.java: add Mobile Broken Crypto, Mobile Content Provider,
  and Mobile Data Leakage to mobileModuleCategoryHardcodedWhereClause
- moduleNames.properties: add 11 module name keys, 3 category keys
- solutions.properties: restore 8 solution texts for modules with
  cheatsheet entries
Restore challenge web pages for mobile modules that were deleted in
ab0c50e. Two modules (Poor Authentication 2 and Content Provider
Leakage 1) are mobile-app-only and never had JSP files in the repo.
The new unified Android app replaces the old standalone MobileShepherd
APKs. 11 legacy mobile challenge modules (Broken Crypto 1/2/3,
Reverse Engineering 2/3, etc.) are not implemented in the new app and
have been removed from the platform DB.

Current DB has 55 challenges, so lower totalNumberOfModulesInShepherd
from 58 to 54 so testGetChallenges (requires > threshold) still passes.
…udit updates

- Add SQLCipher encryption to client-side injection lesson and challenges
  - DB key is the server-issued per-user HMAC flag (not hardcoded)
  - DatabaseHelper, Challenge1DatabaseHelper, Challenge2DatabaseHelper updated
- Add 7 new mobile lesson fragments: RE, IDS, Poor Auth, CSI, Insecure Comm,
  Privacy Controls, and more
- Add new JSP pages for new mobile lesson and challenge modules
- Update all mobile i18n properties to match content audit (flag -> key throughout)
- Remove challenge spoiler hints and hints toast from all challenge fragments
- Add docs/mobile-jsp-content-audit.md content audit document
…r resource

- Strip UTF-8 BOM from 8 Java files introduced by editor encoding
- Remove orphaned FlagValidator class code appended to 5 fragment files
- Add missing import for LessonModel in ReverseEngineeringLessonFragment
- Add error_red color alias to colors.xml
- Update mobile navigation graph and several challenge/lesson fragments
- Add Chinese translations for mobile lesson i18n content
- Add reverse engineering challenge i18n content
- Fix mobile insecure comm and security misconfig challenge JSPs to match app implementation
- Correct insecure data and insufficient crypto challenge descriptions
- Wire up MobileRegister, MobileModuleStart, MobileFlagGet, MobileFlagSubmit servlet mappings
- Commit gradle-wrapper.jar so ./gradlew runs standalone
The Chinese (_zh) translations for the 7 newly added mobile module
lessons (input validation, insecure authorization, insecure
communication, insufficient cryptography, privacy controls, security
misconfiguration, supply chain) were machine-translated and are being
removed pending proper human translation.
@ismisepaul ismisepaul mentioned this pull request Oct 24, 2026
15 of 44 tasks
@ismisepaul ismisepaul moved this from Backlog to Next Release Backlog in Security Shepherd Oct 24, 2026
@ismisepaul ismisepaul added this to the 4.0.0 milestone Oct 24, 2026
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 25, 2026
… Setup

Resource lookups used URL.getFile() directly, which keeps percent-encoding
(for example %20 for spaces), so Setup and Database could not open their
schema and properties files when the install path contained spaces or other
encoded characters. Decode the path before building the File, and load the
configured JDBC driver class before testing the connection.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 25, 2026
Adds the challenge screens (reverse engineering, insecure data storage, poor
authentication, insecure communication, insufficient cryptography, security
misconfiguration, client-side injection 1 and 2), their layouts and unit
tests.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 25, 2026
…ule set

Updates coreSchema.sql, the lesson and challenge JSPs, i18n strings,
cheat-sheet solutions, uri.properties and the mobile category filter in
Setter to match the new unified Android app: removes the old per-challenge
mobile modules and adds the new lessons and challenges. GetterIT is updated
for the new module count and no longer uses the removed Content Provider
Leakage module.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 25, 2026
Moved out of the mobile app PRs so they can be reviewed (or dropped)
separately. android-lint.yml still points at the old src/MobileShepherd path
and build-and-publish-dev.yml is a manually-triggered GCP deploy.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 25, 2026
Adds the server API used by the Security Shepherd Android app: registration,
module start/progress/flags, per-player flag retrieval and submission with
server-side scoring, a scoreboard feed, and an intentionally insecure API for
the insecure-communication module. Servlet mappings are added to web.xml.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 26, 2026
Adds the server API used by the Security Shepherd Android app: registration,
module start/progress/flags, per-player flag retrieval and submission with
server-side scoring, and a scoreboard feed. Servlet mappings are added to
web.xml.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 26, 2026
Adds the lesson screens (reverse engineering, insecure data storage, poor
authentication, insecure authorization, supply chain, insecure communication,
insufficient cryptography, security misconfiguration, input validation,
privacy controls, client-side injection), their layouts and unit tests, and
registers the two lesson-only activities in the manifest.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 26, 2026
Adds the challenge screens (reverse engineering, insecure data storage, poor
authentication, insecure communication, insufficient cryptography, security
misconfiguration, client-side injection 1 and 2), their layouts and unit
tests.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 26, 2026
Adds the server API used by the Security Shepherd Android app: registration,
module start/progress/flags, per-player flag retrieval and submission with
server-side scoring, and a scoreboard feed. Servlet mappings are added to
web.xml.

Part of the split of OWASP#894 (mobile app).
SeanDuggan added a commit to SeanDuggan/SecurityShepherd that referenced this pull request Oct 26, 2026
Adds the Gradle project, manifest, resources, launch/login/main activities,
navigation, preferences, authentication, key validation and progress
tracking utilities, and the home, progress, scoreboard and ADB reference
screens. Lesson and challenge screens referenced by the navigation graph are
added in the following PRs, so those destinations are not usable until then.

Part of the split of OWASP#894 (mobile app).
@SeanDuggan

Copy link
Copy Markdown
Member Author

Thanks Paul, all ten points are addressed. #894 is now split into smaller PRs, so each fix is in the PR that owns the code.

  1. App flags rejected by web /solutionSubmit: fixed. The old rows used a static hardcodedKey=1. Client-Side Injection (feat(mobile): add Client-Side Injection lesson and challenges to the Android app #1069), Insecure Data Storage (feat(mobile): add Insecure Data Storage lesson and challenges to the Android app #1104) and Poor Authentication (feat(mobile): add Poor Authentication lesson and challenges to the Android app- #1069 #1105) now use hardcodedKey=0 with moduleResult set to the MobileModuleFlags.BASE_FLAGS value. I checked this locally end to end (app login, start, get flag, then /solutionSubmit). It was rejected before and accepted after. I kept MobileModuleFlags and aligned the rows to it, and I'm happy to switch to Getter.getModuleResult if you prefer.
  2. Reverse Engineering: fixed in feat(mobile): add Reverse Engineering lesson and challenges to the Android app #1106. These modules are offline-only, so they keep hardcodedKey=1 with the static keys the app validates against.
  3. Module gating: fixed in feat(mobile): add Mobile* servlets for the unified Android app #1062. MobileModuleGate (via Getter.isModuleOpen) is checked by start, get-flag, submit and status. A closed module returns 403 and nothing is scored.
  4. 4–7: these files and lines no longer exist on the split branches, so there is nothing left to change.
  5. Servlet tests: added in feat(mobile): add Mobile* servlets for the unified Android app #1062 (MobileFlagSubmitTest, 13 tests passing). They cover unauthenticated, missing params, unknown module, closed module, correct, already completed, score not recorded, too soon (429) and no recorded start. A flag submitted before start is still scored, which is deliberate. /mobileFlagGet already refuses to issue a flag until the module is started, and the flag is a per-user HMAC that can't be forged.
  6. Existing installs: fixed in feat(mobile): add upgrade SQL for existing installs (#894 review) #1119, an idempotent updatev4_mobile_modules.sql plus a docs/upgrading.md step. It aligns the 9 rows and adds the two Insecure Communication modules.
  7. AGENTS.md path: fixed in feat(mobile): android app shell #1068.

Merge order: #1062 first, then #1065 and #1068, then the module PRs. #1119 can go in any time after #1062. I'll rebase after each merge and close #894 once everything has landed.

@SeanDuggan

Copy link
Copy Markdown
Member Author

Closing this in favour of the split PRs, which cover everything in this PR except the items listed under "Not carried over".

Merge order: #1062 first, then #1065 and #1068, then the module PRs. #1119 can go in any time after #1062.

Area PR
Mobile servlets, module gating, flag-submit tests #1062
Module ids, renames, cheatsheets, legacy-module removal, upgrade path #1065
App shell, theming, AGENTS.md, SDK 35, SQLCipher 4.17.0 #1068
Client-Side Injection #1069
Insecure Data Storage #1104
Poor Authentication #1105
Reverse Engineering #1106
Insufficient Crypto #1107
Lesson-only modules #1109
Security Misconfiguration #1118
Existing-install upgrade SQL and docs #1119

Not carried over:

  • Insecure Communication: deferred to 4.0.1 so it can be redesigned.
  • android-lint.yml and build-and-publish-dev.yml: dropped.
  • MobileInsecureApi.java: dropped, as it was unmapped.
  • Top 10 URLs in uri.properties: dropped. The app now names the risk instead of linking to it.
  • Database.java change: dropped, because it is a platform change.
  • Reverse Engineering variant (f04a272a… JSP and reverseEngineeringStrings.properties): replaced by the implementation in feat(mobile): add Reverse Engineering lesson and challenges to the Android app #1106.

Closes #829, #752, #458, #459 and #473 once the PRs above land.

@SeanDuggan SeanDuggan closed this Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Next Release Backlog

2 participants