How-to guide

Operations and troubleshooting

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.

Update the GitHub source pin

Choose a full commit SHA from the AIWAF repository and review its SDK changes.
Change the x-aiwaf-source Git URL fragment in docker-compose.yml, and the matching io.github.aiwaf.source label in all fifteen runtime Dockerfiles. The assessment proxy shares Express's Dockerfile.
If SDK versions changed, update aiwaf.version in the Java/Spring example POMs, source-runner version assertions, and affected JS lockfile metadata or Python dependency locks.
Rebuild and recreate the selected services, then run run-source-packages.py --verify-only.
Run fresh validation and image scans. Keep older reports identified by source, image and time.

A branch name may move; the current full SHA makes source selection reproducible. Source labels are build declarations checked against Compose, not cryptographically signed provenance. run-published-packages.py expects registry versions and is not the source-build runner.

Refresh dependencies deliberately

python examples/sandbox/lock-python-dependencies.py
python examples/sandbox/lock-python-dependencies.py --refresh-build-tools

The first command refreshes resolved wheel pins/hashes; the second changes only setuptools/wheel while preserving other pins. Review lock diffs, platform requirements and advisories before rebuilding. Node builds use npm ci; changing manifests requires matching lockfiles. Base digests and Java/Spring security overrides need explicit updates. A pinned source does not prove all package/image inputs produce bit-for-bit identical outputs.

Optional profiles

Profile	Services	Purpose
assessment	security-fixture, aiwaf-assessment	Direct/protected outcome checks on loopback 8090/3020.
assessment-tls	assessment-tls; use with assessment	Caddy direct/protected TLS on loopback 8443/8444.
trainer	aiwaf-trainer	Shared access-log training example; independent of the fifteen-runtime validation.
tests	aiwaf-tests	Optional existing test image; not a replacement for source runner/SDK suites.

docker compose --profile assessment stop aiwaf-assessment security-fixture
docker compose --profile assessment --profile assessment-tls stop assessment-tls

The TLS root/private CA material stays in assessment_tls_data. Export only the public root as described in TLS validation. After a large host clock jump, restart Caddy so it can renew its short-lived leaf certificates.

Preserve and inspect state

docker compose ps
docker compose logs --tail 100 aiwaf-django
docker compose exec redis redis-cli INFO keyspace
docker compose restart aiwaf-django

Normal restarts and docker compose down preserve named volumes. down -v deletes stored state and assessment CA data. Do not use it as a routine remedy for false positives. Global Redis flushing destroys other runtimes' evidence; use fresh synthetic clients and inspect service namespaces first. The isolated outage runner is preferable to stopping shared Redis during a test run.

Diagnose a failed check

Symptom	Check
Source/version assertion fails	Compare resolved Compose source with image labels. Rebuild and recreate; restarting a container does not install a new image.
GitHub fetch or registry install fails	Check Docker network/proxy access, repository visibility and the full SHA. Do not silently substitute a sibling checkout.
Django or burst requests time out	Finish scans/builds, verify application/upstream health, and rerun the affected target alone. Record any timeout change; the matrix default is five seconds.
Normal requests are blocked after attacks	Inspect persistent reputation and actual forwarded client IPs. Verify namespaces and headers; avoid erasing state to hide false positives.
TLS verification fails	Use localhost, the exported CA and both assessment profiles; inspect certificate time validity and Caddy logs. Keep certificate verification enabled.
Grype is slow on Windows	Use Docker's Linux engine and the dedicated database volume, not Windows bind-mounted SQLite storage. Inspect scanner errors; scan failure is not a clean result.
PHP blocks ordinary routes	Use its separate Composer package and autoloader. Sandbox UUID-only path rules are disabled for Juice Shop. PHP remains outside the current validated source scope.

Generated files and cleanup

Keep source, Dockerfiles, committed locks, fixtures, tests and the latest evidence. Generated reports, bytecode, dependency directories, tool caches and exported TLS certificates are ignored and excluded from images. Delete only exact obsolete paths after confirming they belong to the sandbox; do not remove package manifests, lockfiles or every JSON file.

The stack contains a deliberately vulnerable application and synthetic forwarded-IP controls. Use an isolated evaluation environment. The fixture endpoints bind to loopback; normal proxy ports follow Compose bindings. Production network and trust policies need their own review.