Tutorial

Your first sandbox run

Source and package versions

One AIWAF repository. Python: py/aiwaf/ · Node.js: js/ · Rust/WASM: rust/ · Java: java/. Source and canonical README. Versions shown describe the source checkout; package releases are independent. Current Python/Node source targets are aiwaf 1.1.8 (Python) and aiwaf 1.1.5 (npm), with Rust/Python 0.2.7 and WASM 0.2.5 and Java 1.3.5. Sandbox guides retain their separately pinned builds.

You will start Juice Shop, Redis, and fifteen non-PHP proxies, then verify their source versions and test one endpoint. Run every command from the sandbox repository root.

1. Check requirements

  • Docker Desktop using Linux containers, or Docker Engine with BuildKit and Compose additional-context support.
  • Git, Python 3.10+, and network access to GitHub and package registries.
  • Host Node.js only for JavaScript unit tests outside Docker.
  • Time and disk space for Node, Python, Java, and R image builds.
docker version
docker compose version
git --version
python --version

2. Clone the sandbox

git clone https://github.com/aayushgauba/sandbox.git
cd sandbox
python -m pip install requests

Use a sandbox revision containing run-source-packages.py and the GitHub source contexts. x-aiwaf-source in Compose pins AIWAF commit 843a35f4fd48b4ef565e3c1ec8a42db9b1c41946. BuildKit clones it automatically. A host SDK installation or adjacent checkout does not select the SDK inside the image.

3. Build the validated integrations

docker compose up -d --build aiwaf aiwaf_fastify aiwaf_hapi aiwaf_koa aiwaf_nest aiwaf_next aiwaf_adonis aiwaf_sails aiwaf-django aiwaf-flask aiwaf-fastapi aiwaf-java aiwaf-spring aiwaf-java-r aiwaf-spring-r
docker compose ps

Compose starts Redis and Juice Shop dependencies. Without a service selection, docker compose up -d --build also starts the default PHP integrations. PHP is outside this validation scope.

Checkpoint: Redis and Juice Shop should be healthy and all selected proxies running. The baseline is http://localhost:3001; Express protection uses http://localhost:3000.

4. Verify the installed source

python examples/sandbox/run-source-packages.py --verify-only

The verifier compares each running proxy's io.github.aiwaf.source label with the resolved Compose context, checks Python/JavaScript 1.1.1 and Java 1.3.2, checks installation paths, and verifies the Java SQL-inspection class. Stale containers fail with a rebuild-required assertion.

results_local_versions.json records the installed SDKs under examples/sandbox/. The filename denotes local Docker execution; github_source identifies remote source and commit.

5. Test a protected endpoint

python examples/sandbox/smoke-test.py --target node=http://127.0.0.1:3000 --burst-workers 16 --output examples/sandbox/results_first_smoke.json
python examples/sandbox/validate-login-bypass.py --target node=http://127.0.0.1:3000 --output examples/sandbox/results_first_login.json

The smoke check requires normal requests to succeed, automation and excess traffic to be denied, and benign invalid credentials to reach Juice Shop as a 401. The SQL check requires two payloads to fail to obtain an authentication token; token values are omitted from reports.

Continue with full validation. If a check fails, inspect docker compose logs --tail 100 aiwaf and troubleshooting.