A self-hostable, open-source platform for learning Android application penetration testing through a guided, adaptive curriculum where every task is graded by a real Android emulator.
MASDojo turns the OWASP MASVS / MASTG body of knowledge into a hands-on dojo. Each task ships with a deliberately vulnerable target app, a clear objective, and an automated grader. When you think you've solved a task, MASDojo boots a real Android AVD, installs the target APK, applies your submission — a recovered secret, a Frida script, or a captured request — runs the grader, and returns a PASS or FAIL with concrete evidence of exactly which check passed or failed.
That live, evidence-backed grading loop is the heart of the platform.
- The emulator is the answer key. No self-reported "I think I got it." A task is complete only when a real device run verifies your solution.
- Watch it grade. A live flight-recorder console streams every step of the pipeline — AVD snapshot restore,
adb install, Frida injection, mitmproxy capture, each check — so PASS/FAIL is the climax of a visible pipeline, not a boolean from nowhere. - Proof-of-Pwn. Every PASS issues a signed, independently-verifiable certificate (public
/verify) binding the verdict to the task, the learner, and a digest of the evidence — so "how do I know that PASS isn't faked?" is answered on screen. - Adaptive pathway. Tasks form a prerequisite DAG across ten modules. A pathway engine recommends your next task based on mastery, hints used, and time-to-solve.
- AI mentor, bring-your-own-key. Plug in your own Anthropic or OpenAI API key to unlock Socratic tiered hints, "explain this smali/Frida error," and post-task remediation reviews. Keys are encrypted at rest, used server-side only, and the platform is fully functional without them — so it stays free to host.
- MASVS-aligned. Every task maps to a MASVS v2 control and references the relevant MASTG technique/test.
- Defensive education only. All target apps are intentionally-vulnerable training artifacts authored in this repo. No real malware, no third-party copyrighted apps.
Everything runs locally; live Frida/RASP grading uses your machine's own
Android emulator, so no KVM VM is needed. Full setup + troubleshooting:
docs/preflight.md and docs/local-mode.md.
git clone <your-fork-url> masdojo && cd masdojo
make doctor # check your machine has everything (tells you what's missing)
make solo # http://localhost:5173 — no login, straight into the curriculummake solo already gives you Lab 1 (RE/secrets) and Lab 3 (API abuse) —
neither needs an emulator. For Lab 2 (live Frida/RASP):
make avd-up # create a rooted local AVD + launch a matching frida-server
make avd-check # confirm it's ready
make runner-host # grade against your local AVD (attach mode)Heads-up: the grading runner boots an Android emulator and therefore needs a KVM-enabled host (nested virtualization). The database, Redis, backend, and frontend run anywhere Docker runs. See Runner & KVM.
git clone <your-fork-url> masdojo && cd masdojo
make env # writes .env with fresh JWT + master-key secrets
make apps # build the vulnerable target APKs (Docker, no host SDK)
make up # full stack: db, redis, backend, frontend, runnerThen open http://localhost:5173, register a local account, and start at Module 0 — Foundations.
No KVM host (e.g. on a Mac)? The emulator-backed runner needs /dev/kvm, but
everything else runs anywhere:
make up-core # db, redis, backend, frontend — skips the runnerYou can still browse the whole UI and use the AI mentor. To watch the grading
loop work without an emulator, run the runner in dry-run mode — it grades
flag and static_assert tasks (which compare against server-side expected
values). For the full emulator path on a real KVM box, see
docs/deploy-kvm.md.
To enable the AI mentor, go to Settings → AI Key, paste your Anthropic or OpenAI key, and click Test & Save.
┌────────────┐ ┌──────────────────────────────┐
│ frontend │ HTTP │ backend │
│ React + TS │◀──────▶│ FastAPI · auth · pathway │
└────────────┘ │ engine · mentor proxy │
└───────┬───────────────┬───────┘
│ │
┌───────▼──────┐ ┌──────▼──────┐
│ PostgreSQL │ │ Redis │
│ users/tasks/ │ │ grading │
│ submissions │ │ job queue │
└──────────────┘ └──────┬──────┘
│ consumes jobs
┌────────▼─────────┐
│ runner │ KVM host
│ AVD · adb · Frida│
│ mitmproxy· grader│
└──────────────────┘
| Component | Stack | Responsibility |
|---|---|---|
frontend/ |
React, TypeScript, Vite, Tailwind | Dark terminal-ops UI: dashboard skill map, task view, hint panel, live grading, BYOK settings |
backend/ |
FastAPI, SQLAlchemy, Pydantic, loguru | Auth (JWT), task API, pathway engine, AI mentor proxy, BYOK key management |
runner/ |
Python worker | Boots/snapshots AVD, installs APK, injects Frida, captures with mitmproxy, runs graders |
tasks/ |
YAML + Python graders | Self-contained curriculum task packages |
apps/ |
Kotlin | Source for the intentionally-vulnerable training apps |
infra/ |
Docker | Compose, Dockerfiles, AVD build, seed scripts |
docs/ |
Markdown | Architecture, authoring guide, MASVS coverage, demo assets |
Full design notes: docs/architecture.md.
Eleven modules, ordered so each builds the prerequisites for the next, covering all eight MASVS v2 categories. Full mapping in docs/masvs-coverage.md.
| Module | Domain | MASVS focus |
|---|---|---|
| 0 · Foundations & Tooling | foundations |
MASVS-CODE (awareness) |
| 1 · Static Analysis & RE | static-re |
MASVS-STORAGE-1, MASVS-CODE |
| 2 · Local Data Storage | storage |
MASVS-STORAGE-1/2 |
| 3 · Cryptography | crypto |
MASVS-CRYPTO-1/2 |
| 4 · Dynamic Instrumentation | rasp-bypass |
MASVS-RESILIENCE (intro) |
| 5 · Network & Interception | network |
MASVS-NETWORK-1/2 |
| 6 · SSL Pinning Bypass | rasp-bypass |
MASVS-NETWORK-2, MASVS-RESILIENCE |
| 7 · Auth & API Abuse | api-dynamic |
MASVS-AUTH-1/2 |
| 8 · Platform Interaction & IPC | platform |
MASVS-PLATFORM-1/2/3 |
| 9 · RASP & Anti-Tampering | rasp-bypass |
MASVS-RESILIENCE-1..4 |
| 10 · Privacy & Data Sharing | privacy |
MASVS-PRIVACY-1 |
| 11 · Capstone | capstone |
Cross-MASVS |
Every one of the 25 tasks has a real payload-detection grader — the system that verifies you genuinely applied the technique, not just that you guessed a flag. That's what sets MASDojo apart from a bag of vulnerable apps: an automated per-technique mastery check. Tasks are solvable and gradeable now, in dry-run, from committed artifacts (decoded resources, prefs/log/backup dumps, real encrypted blobs, captured traffic) — no emulator or APK build required. The three ⭐ reference tasks (001/005/009) additionally run on a live Android emulator. New comparison graders are a one-liner via runner/runner/graders.py; see tasks/_template/ and docs/authoring.md.
Each task declares a success_type. The runner produces a GradeResult(passed, evidence, checks, score):
success_type |
What the learner submits | What the grader asserts |
|---|---|---|
flag |
A string | Constant-time match against the expected flag |
static_assert |
An extracted value (secret/endpoint) | The value was genuinely present in the target |
frida_assert |
A Frida script | A hook fired / a guarded function's return was flipped |
network_assert |
A network interaction | A specific endpoint/param/auth-bypass was exercised (via mitmproxy) |
Every job is sandboxed, network-restricted, and hard-timeouted.
The emulator runner requires hardware-accelerated virtualization:
- Linux host with
/dev/kvmis the supported path. The runner container is launched with--device /dev/kvm. - If KVM is unavailable inside containers, run the runner on bare metal against the same Redis/Postgres — see
docs/architecture.md.
Drop a new directory under tasks/ following tasks/_template/. The full authoring workflow — task.yaml schema, grader contract, hint tiers, building the target app — is in docs/authoring.md.