Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 9 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <http://127.0.0.1:6080/vnc.html>, 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 <http://127.0.0.1:6080/vnc.html> (password `kalilab`). Each lab's README covers its usage.

## Security checks

Expand Down
44 changes: 44 additions & 0 deletions crapi/README.md
Original file line number Diff line number Diff line change
@@ -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 <http://127.0.0.1:6080/vnc.html>.
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.
159 changes: 159 additions & 0 deletions crapi/compose.yaml
Original file line number Diff line number Diff line change
@@ -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]
37 changes: 37 additions & 0 deletions dvwa/README.md
Original file line number Diff line number Diff line change
@@ -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 <http://127.0.0.1:6080/vnc.html>.
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.
8 changes: 8 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand All @@ -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
7 changes: 7 additions & 0 deletions kali/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
45 changes: 45 additions & 0 deletions kali/README.md
Original file line number Diff line number Diff line change
@@ -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 <lab>-up` command, then open <http://127.0.0.1:6080/vnc.html> 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 <lab>-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.
4 changes: 2 additions & 2 deletions kali/compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading
Loading