From 954d807108c86fb9197897784d78909e6a10952b Mon Sep 17 00:00:00 2001 From: Aaron <7063649+ahcodedev@users.noreply.github.com> Date: Tue, 10 Nov 2026 21:43:46 -0800 Subject: [PATCH] Add crAPI lab, per-lab READMEs and offline nuclei templates Add a crAPI lab adapted from the upstream compose file, without the chatbot. Move usage docs into a README per lab and for the Kali desktop, leaving the root README as an index. Make the shared kali-home volume external so Compose stops warning about project ownership, and bake nuclei templates into the Kali image since the lab has no internet. --- README.md | 27 +++---- crapi/README.md | 44 +++++++++++ crapi/compose.yaml | 159 ++++++++++++++++++++++++++++++++++++++ dvwa/README.md | 37 +++++++++ justfile | 8 ++ kali/Dockerfile | 7 ++ kali/README.md | 45 +++++++++++ kali/compose.yaml | 4 +- owasp_juiceshop/README.md | 35 +++++++++ 9 files changed, 346 insertions(+), 20 deletions(-) create mode 100644 crapi/README.md create mode 100644 crapi/compose.yaml create mode 100644 dvwa/README.md create mode 100644 kali/README.md create mode 100644 owasp_juiceshop/README.md diff --git a/README.md b/README.md index 9cbcbbb..71e1078 100644 --- a/README.md +++ b/README.md @@ -15,24 +15,15 @@ prek install ## Labs -Requires Docker. Each lab pairs a vulnerable target with the shared Kali desktop in `kali/` on an internal Docker network with no internet access. Only one lab runs at a time; starting one stops the other. - -| Command | Purpose | -| ----------------------- | ---------------------------------------------------------- | -| `just juice-shop-up` | Build and start the Juice Shop lab; auto-off after 2 hours | -| `just dvwa-up` | Build and start the DVWA lab; auto-off after 2 hours | -| `just juice-shop-up 30` | Either `up` command takes an auto-off time in minutes | -| `just juice-shop-down` | Stop the lab (`just dvwa-down` does the same) | - -| Lab | Directory | Target URL inside Kali | Notes | -| ---------- | ------------------ | ------------------------ | ------------------------------------------------------------------ | -| Juice Shop | `owasp_juiceshop/` | `http://juice-shop:3000` | | -| DVWA | `dvwa/` | `http://dvwa` | Log in as `admin` / `password`, then click Create / Reset Database | - -- Kali desktop: , password `kalilab` (override with `VNC_PASSWORD`, max 8 characters). -- Targets are reachable only from inside Kali. -- `/home/kali` persists in the `kali-home` volume, shared by both labs; everything else resets when a lab stops. -- To add or update tools, edit `kali/Dockerfile` and run `docker compose -f kali/compose.yaml build --pull --no-cache kali`. +Requires Docker. Each lab pairs a deliberately vulnerable target with a shared [Kali desktop](kali/README.md) on an isolated Docker network. One lab runs at a time, and each shuts itself down after 2 hours. + +| Lab | Target | Start | Stop | +| --------------------------------------- | ------------------------------------------ | -------------------- | ---------------------- | +| [Juice Shop](owasp_juiceshop/README.md) | Insecure online shop (web app) | `just juice-shop-up` | `just juice-shop-down` | +| [DVWA](dvwa/README.md) | One page per vulnerability class (PHP) | `just dvwa-up` | `just dvwa-down` | +| [crAPI](crapi/README.md) | Vulnerable API application (microservices) | `just crapi-up` | `just crapi-down` | + +After starting a lab, open the Kali desktop at (password `kalilab`). Each lab's README covers its usage. ## Security checks diff --git a/crapi/README.md b/crapi/README.md new file mode 100644 index 0000000..61a43af --- /dev/null +++ b/crapi/README.md @@ -0,0 +1,44 @@ +# crAPI lab + +[crAPI](https://owasp.org/www-project-crapi/) (Completely Ridiculous API) is OWASP's deliberately vulnerable API application. It models a car-owner portal with a shop, a mechanic workshop and a community forum, built from several services behind one web front end. It is aimed at API flaws such as the OWASP API Security Top 10, for example broken object-level authorization. + +## Usage + +```sh +just crapi-up # build and start +just crapi-down # stop +``` + +1. Run `just crapi-up`. The services start in order and wait for each other, so this takes a minute or two. +2. Open the [Kali desktop](../kali/README.md) at . +3. In the Kali browser, go to `http://crapi-web` and sign up for an account. +4. Open MailHog at `http://mailhog:8025` to read the emails crAPI sends you, such as the vehicle details needed to add your car. + +## Services + +| Service | Image | Purpose | +| ----------------------------- | ----------------------- | ---------------------------------------------- | +| `crapi-web` | `crapi/crapi-web` | Web front end and API entry point, on port 80 | +| `crapi-identity` | `crapi/crapi-identity` | Accounts, login and tokens | +| `crapi-community` | `crapi/crapi-community` | Forum posts and coupons | +| `crapi-workshop` | `crapi/crapi-workshop` | Shop and mechanic workshop | +| `mailhog` | `crapi/mailhog` | Catches outgoing email; web UI on port 8025 | +| `api.mypremiumdealership.com` | `crapi/gateway-service` | Simulated external partner API | +| `postgresdb` | `postgres:14` | Relational database | +| `mongodb` | `mongo:4.4` | Document database | +| `kali` | `lab-kali` | Attacker desktop | +| `gateway` | `alpine/socat` | Publishes the Kali desktop on `127.0.0.1:6080` | + +## How the lab behaves + +- **Isolated**: the target and Kali sit on an internal Docker network with no internet access. The target is not published to the host, so it is reachable only from inside Kali. +- **Auto-off**: the lab shuts itself down after 2 hours. Pass minutes to change it, for example `just crapi-up 30`. The timer only applies when the lab is started through `just`. +- **One lab at a time**: starting this lab stops any other lab that is running. +- **Resets on stop**: neither database is persisted, so accounts, vehicles and emails are lost when the lab stops. Files under `/home/kali` are kept; see the [Kali desktop](../kali/README.md). + +## Notes + +- `compose.yaml` is adapted from crAPI's upstream `deploy/docker/docker-compose.yml` and keeps its stock credentials. They are public defaults, which is acceptable only because the lab network is isolated. +- **No chatbot**: crAPI's chatbot needs an OpenAI API key and internet access, so it and its vector database are left out. The chatbot widget in the app returns an error. +- The `crapi-web` service carries the network alias `crapi-chatbot` because its nginx will not start unless that hostname resolves. +- Every service is reachable from Kali by its service name, not only the web front end. diff --git a/crapi/compose.yaml b/crapi/compose.yaml new file mode 100644 index 0000000..6125bb9 --- /dev/null +++ b/crapi/compose.yaml @@ -0,0 +1,159 @@ +name: crapi + +include: + - ../kali/compose.yaml + +# Adapted from crAPI's deploy/docker/docker-compose.yml, with its stock credentials. +# Nothing is published to the host, state is not persisted, and the chatbot is left +# out because it needs an OpenAI key and internet access. + +x-healthcheck: &healthcheck + interval: 15s + timeout: 15s + retries: 15 + +x-databases: &databases + DB_NAME: crapi + DB_USER: admin + DB_PASSWORD: crapisecretpassword + DB_HOST: postgresdb + DB_PORT: 5432 + MONGO_DB_HOST: mongodb + MONGO_DB_PORT: 27017 + MONGO_DB_USER: admin + MONGO_DB_PASSWORD: crapisecretpassword + MONGO_DB_NAME: crapi + +services: + crapi-web: + image: crapi/crapi-web:latest + environment: + COMMUNITY_SERVICE: crapi-community:8087 + IDENTITY_SERVICE: crapi-identity:8080 + WORKSHOP_SERVICE: crapi-workshop:8000 + CHATBOT_SERVICE: crapi-chatbot:5002 + MAILHOG_WEB_SERVICE: mailhog:8025 + TLS_ENABLED: "false" + depends_on: + crapi-community: { condition: service_healthy } + crapi-identity: { condition: service_healthy } + crapi-workshop: { condition: service_healthy } + healthcheck: + <<: *healthcheck + test: curl 0.0.0.0:80/health + networks: + lab: + # nginx will not start unless the chatbot hostname resolves. + aliases: [crapi-chatbot] + + crapi-identity: + image: crapi/crapi-identity:latest + environment: + <<: *databases + LOG_LEVEL: INFO + SERVER_PORT: 8080 + ENABLE_SHELL_INJECTION: "false" + ENABLE_LOG4J: "false" + JWT_SECRET: crapi + JWT_EXPIRATION: 604800000 + MAILHOG_HOST: mailhog + MAILHOG_PORT: 1025 + MAILHOG_DOMAIN: example.com + SMTP_HOST: smtp.example.com + SMTP_PORT: 587 + SMTP_EMAIL: user@example.com + SMTP_PASS: xxxxxxxxxxxxxx + SMTP_FROM: no-reply@example.com + SMTP_AUTH: "true" + SMTP_STARTTLS: "true" + API_GATEWAY_URL: https://api.mypremiumdealership.com + TLS_ENABLED: "false" + depends_on: + postgresdb: { condition: service_healthy } + mongodb: { condition: service_healthy } + mailhog: { condition: service_healthy } + healthcheck: + <<: *healthcheck + test: /app/health.sh + networks: [lab] + + crapi-community: + image: crapi/crapi-community:latest + environment: + <<: *databases + LOG_LEVEL: INFO + SERVER_PORT: 8087 + IDENTITY_SERVICE: crapi-identity:8080 + TLS_ENABLED: "false" + depends_on: + postgresdb: { condition: service_healthy } + mongodb: { condition: service_healthy } + crapi-identity: { condition: service_healthy } + healthcheck: + <<: *healthcheck + test: /app/health.sh + networks: [lab] + + crapi-workshop: + image: crapi/crapi-workshop:latest + environment: + <<: *databases + LOG_LEVEL: INFO + SERVER_PORT: 8000 + IDENTITY_SERVICE: crapi-identity:8080 + SECRET_KEY: crapi + API_GATEWAY_URL: https://api.mypremiumdealership.com + TLS_ENABLED: "false" + FILES_LIMIT: 1000 + depends_on: + postgresdb: { condition: service_healthy } + mongodb: { condition: service_healthy } + crapi-identity: { condition: service_healthy } + crapi-community: { condition: service_healthy } + healthcheck: + <<: *healthcheck + test: /app/health.sh + networks: [lab] + + postgresdb: + image: postgres:14 + command: ["postgres", "-c", "max_connections=500"] + environment: + POSTGRES_USER: admin + POSTGRES_PASSWORD: crapisecretpassword + POSTGRES_DB: crapi + healthcheck: + <<: *healthcheck + test: ["CMD-SHELL", "pg_isready"] + networks: [lab] + + mongodb: + image: mongo:4.4 + environment: + MONGO_INITDB_ROOT_USERNAME: admin + MONGO_INITDB_ROOT_PASSWORD: crapisecretpassword + healthcheck: + <<: *healthcheck + test: echo 'db.runCommand("ping").ok' | mongo mongodb:27017/test --quiet + start_period: 20s + networks: [lab] + + # Catches the emails crAPI sends (sign-up, OTP, vehicle details). + mailhog: + image: crapi/mailhog:latest + user: root + environment: + MH_MONGO_URI: admin:crapisecretpassword@mongodb:27017 + MH_STORAGE: mongodb + healthcheck: + <<: *healthcheck + test: ["CMD", "nc", "-z", "localhost", "8025"] + networks: [lab] + + api.mypremiumdealership.com: + image: crapi/gateway-service:latest + healthcheck: + <<: *healthcheck + test: bash -c 'echo -n "GET / HTTP/1.1\n\n" > /dev/tcp/127.0.0.1/443' + start_period: 15s + networks: [lab] diff --git a/dvwa/README.md b/dvwa/README.md new file mode 100644 index 0000000..4ab049c --- /dev/null +++ b/dvwa/README.md @@ -0,0 +1,37 @@ +# DVWA lab + +[Damn Vulnerable Web Application](https://github.com/digininja/DVWA) (DVWA) is a PHP and MariaDB application with one page per vulnerability class, such as SQL injection, command injection, file upload, CSRF and XSS. Each page can be set to a different difficulty, which makes it suited to practising one technique at a time. + +## Usage + +```sh +just dvwa-up # build and start +just dvwa-down # stop +``` + +1. Run `just dvwa-up`. +2. Open the [Kali desktop](../kali/README.md) at . +3. In the Kali browser, go to `http://dvwa/setup.php` and click **Create / Reset Database**. This is needed after every start. +4. Log in at `http://dvwa` as `admin` with the password `password`. +5. Choose a difficulty under **DVWA Security**. It starts on `impossible`, the hardened setting; pick `low` to begin. + +## Services + +| Service | Image | Purpose | +| --------- | ------------------------ | ---------------------------------------------- | +| `dvwa` | `ghcr.io/digininja/dvwa` | The target application, on port 80 | +| `db` | `mariadb:10` | DVWA's database | +| `kali` | `lab-kali` | Attacker desktop | +| `gateway` | `alpine/socat` | Publishes the Kali desktop on `127.0.0.1:6080` | + +## How the lab behaves + +- **Isolated**: the target and Kali sit on an internal Docker network with no internet access. The target is not published to the host, so it is reachable only from inside Kali. +- **Auto-off**: the lab shuts itself down after 2 hours. Pass minutes to change it, for example `just dvwa-up 30`. The timer only applies when the lab is started through `just`. +- **One lab at a time**: starting this lab stops any other lab that is running. +- **Resets on stop**: the database is not persisted, so it is empty on every start and must be created again in step 3. Files under `/home/kali` are kept; see the [Kali desktop](../kali/README.md). + +## Notes + +- The database uses DVWA's stock credentials, set in `compose.yaml`. They are public defaults, which is acceptable only because the lab network is isolated. +- The `db` service is also reachable from Kali on port 3306. diff --git a/justfile b/justfile index a12f25d..cc626e8 100644 --- a/justfile +++ b/justfile @@ -22,9 +22,16 @@ dvwa-up ttl="120": (lab-up "dvwa" ttl) # Stop the DVWA lab dvwa-down: lab-down +# Start the crAPI lab; it shuts itself down after `ttl` minutes +crapi-up ttl="120": (lab-up "crapi" ttl) + +# Stop the crAPI lab +crapi-down: lab-down + # Labs share the Kali desktop port, so only one runs at a time. [private] lab-up dir ttl: lab-down + @docker volume create kali-home >/dev/null docker compose -f {{ dir }}/compose.yaml up -d --build nohup sh -c 'sleep $(({{ ttl }} * 60)) && docker compose -f {{ dir }}/compose.yaml down' lab-auto-off >/dev/null 2>&1 & @echo "Kali desktop: http://127.0.0.1:6080/vnc.html (auto-off in {{ ttl }} min)" @@ -34,3 +41,4 @@ lab-down: -@pkill -f '[l]ab-auto-off' docker compose -f owasp_juiceshop/compose.yaml down docker compose -f dvwa/compose.yaml down + docker compose -f crapi/compose.yaml down diff --git a/kali/Dockerfile b/kali/Dockerfile index 1e938d8..82324df 100644 --- a/kali/Dockerfile +++ b/kali/Dockerfile @@ -21,6 +21,13 @@ RUN useradd --create-home --shell /bin/bash --groups sudo kali \ && mkdir -p /tmp/.X11-unix \ && chmod 1777 /tmp/.X11-unix +# nuclei fetches its templates at runtime, which the offline lab cannot do. +# Kept outside /home/kali, which is hidden by the shared volume. +RUN git clone --depth 1 https://github.com/projectdiscovery/nuclei-templates /opt/nuclei-templates \ + && rm -rf /opt/nuclei-templates/.git \ + && chown -R kali:kali /opt/nuclei-templates +ENV NUCLEI_TEMPLATES_DIR=/opt/nuclei-templates + COPY --chmod=755 entrypoint.sh /usr/local/bin/entrypoint.sh USER kali diff --git a/kali/README.md b/kali/README.md new file mode 100644 index 0000000..bd89b36 --- /dev/null +++ b/kali/README.md @@ -0,0 +1,45 @@ +# Kali desktop + +The attacker machine shared by every lab: a Kali Linux XFCE desktop that you use from your host browser. Each lab's `compose.yaml` includes `compose.yaml` from this directory, so all labs run the same image and share one home directory. + +## Usage + +Start any lab with its `just -up` command, then open and enter the password `kalilab`. + +- **Password**: set the `VNC_PASSWORD` environment variable before starting a lab to change it. VNC uses only the first 8 characters. +- **User**: you are logged in as `kali`, with passwordless `sudo`. +- **Targets**: reach a lab's services by name from the Kali browser or terminal, for example `http://juice-shop:3000`. + +## What is installed + +- `kali-linux-default`, Kali's standard toolset, including Metasploit, nmap, sqlmap, Wireshark and Firefox. +- Burp Suite and ZAP, added separately. +- nuclei, with its template library baked into the image at `/opt/nuclei-templates`. nuclei normally downloads templates at runtime, which the offline lab cannot do. They are as old as the last image build; rebuild to refresh them. Example: `nuclei -u http://dvwa/login.php -tags dvwa`. + +## Services + +| Service | Purpose | +| --------- | --------------------------------------------------------------------------------------------------------- | +| `kali` | The desktop: XFCE on a TigerVNC server, served to the browser by noVNC on port 6080 | +| `gateway` | A socat forwarder and the only container attached to both networks; it publishes port 6080 on `127.0.0.1` | + +| Network | Purpose | +| ------- | --------------------------------------------------------------------------------------- | +| `lab` | Internal network for Kali and the targets; no route to the host network or the internet | +| `edge` | Normal network used only by `gateway` to publish the desktop | + +## Persistence + +`/home/kali` is stored in the `kali-home` Docker volume, which every lab shares, so notes and Burp projects survive stops and lab switches. Everything outside the home directory resets when a lab stops. + +The volume is created by the `just -up` commands. Starting a lab with a bare `docker compose up` fails if the volume does not exist yet. + +## Adding or updating tools + +The container has no internet access, so `apt install` does not work at runtime. Edit `Dockerfile` and rebuild instead: + +```sh +docker compose -f kali/compose.yaml build --pull --no-cache kali +``` + +The image is about 18 GB and a full rebuild takes a long time. diff --git a/kali/compose.yaml b/kali/compose.yaml index a8829f8..f9ed4db 100644 --- a/kali/compose.yaml +++ b/kali/compose.yaml @@ -28,6 +28,6 @@ networks: edge: volumes: - # Fixed name so every lab shares the same home directory. + # Shared by every lab, so it is created outside Compose (see `lab-up` in the justfile). kali-home: - name: kali-home + external: true diff --git a/owasp_juiceshop/README.md b/owasp_juiceshop/README.md new file mode 100644 index 0000000..a64c20a --- /dev/null +++ b/owasp_juiceshop/README.md @@ -0,0 +1,35 @@ +# OWASP Juice Shop lab + +[OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) is a deliberately insecure online shop written in Node.js and Angular. It is a single web application with a large set of hacking challenges covering the OWASP Top 10 and more, tracked on a built-in score board. + +## Usage + +```sh +just juice-shop-up # build and start +just juice-shop-down # stop +``` + +1. Run `just juice-shop-up`. +2. Open the [Kali desktop](../kali/README.md) at . +3. In the Kali browser, go to `http://juice-shop:3000`. +4. Register your own shop account to begin. Finding the score board is the first challenge. + +## Services + +| Service | Image | Purpose | +| ------------ | ----------------------- | ---------------------------------------------- | +| `juice-shop` | `bkimminich/juice-shop` | The target shop, on port 3000 | +| `kali` | `lab-kali` | Attacker desktop | +| `gateway` | `alpine/socat` | Publishes the Kali desktop on `127.0.0.1:6080` | + +## How the lab behaves + +- **Isolated**: the target and Kali sit on an internal Docker network with no internet access. The target is not published to the host, so it is reachable only from inside Kali. +- **Auto-off**: the lab shuts itself down after 2 hours. Pass minutes to change it, for example `just juice-shop-up 30`. The timer only applies when the lab is started through `just`. +- **One lab at a time**: starting this lab stops any other lab that is running. +- **Resets on stop**: Juice Shop keeps no data between runs, so accounts, orders and solved challenges are lost when the lab stops. Files under `/home/kali` are kept; see the [Kali desktop](../kali/README.md). + +## Notes + +- Most challenges are solved with a browser and an intercepting proxy. Burp Suite and ZAP are installed in Kali. +- Challenges that depend on outside websites cannot be completed, because the lab has no internet access.