AIWAF sprint guide

Where to help

Set up

Fork and clone only the repository you're working on, and do this before the sprint if you can. The first Rust build and the sandbox's Docker images can take a while. You'll also need a GitHub account, and the GitHub CLI makes it easier to test a pull request locally.

aiwaf

You need Python 3.10 or newer, Rust, and a virtual environment. Add Node.js for JavaScript changes, or Java 17 and Maven for Java changes. Activate the environment after creating it.

git clone https://github.com/aiwaf-project/aiwaf.git
cd aiwaf
python -m venv .venv
python -m pip install maturin
python scripts/stage_rust_package_files.py
maturin develop --release --locked --manifest-path rust/Cargo.toml
python -m pip install -e ".[django,flask,fastapi]"
python -m pip install pytest pytest-cov coverage httpx redis djangorestframework python-multipart
python aiwaf_test.py --python-only

After this, python aiwaf_test.py rebuilds aiwaf-rust for you. For JavaScript, also run npm ci --prefix js. See Test changes to AIWAF itself if you hit a setup error.

aiwaf_website

You need Ruby 3.3 or newer, Bundler and Python, plus an aiwaf checkout in the same parent folder.

git clone https://github.com/aiwaf-project/aiwaf_website.git
cd aiwaf_website
bundle install
bundle exec jekyll serve

Open http://localhost:4000 to preview the site.

sandbox

You need Python and Node.js 22. Add Docker to run the protected services.

git clone https://github.com/aiwaf-project/sandbox.git
cd sandbox
python -m pip install requests
python -m unittest discover -s examples/sandbox -p 'test_*.py'

Choose your work

Pick one item, comment on it to claim it, and then start. That stops two people from doing the same work.

New to the project? Look for the good first issue label. If you submit a pull request, try to review someone else's as well.

Review a pull request in aiwaf

A good review answers one question: does this change fix the problem without breaking anything else? AIWAF is security software, so run the code rather than only reading the diff.

1. Comment on the pull request to say you're reviewing it.
2. Read the linked issue and what it says "done" means.
3. Check the pull request out locally.
4. Run the tests.
5. Reproduce the bug on main, and confirm it's gone on the branch.
6. Work through the checklist below.
7. Post your review, including what you tested.

gh pr checkout 123 --repo aiwaf-project/aiwaf
python aiwaf_test.py --python-only

What to check

• It fixes the issue: everything the issue asks for is done.
• It has a test: the new test fails on the old code and passes with the fix.
• It stays in scope: there are no unrelated changes, and removed code has a clear reason.
• It's safe: it can't let a blocked request through, trust a client-supplied value or hide an error.
• Languages agree: if Python and Rust share a behavior, both change together.
• Users are covered: CHANGELOG.md is updated for changes users can notice, and the description says whether a new aiwaf-rust or aiwaf-wasm release is needed.
• CI passes: if a check failed, find out whether this change caused it.

Rust changes also need to follow Proposing Rust changes.

Write useful comments

Be specific, say why something matters, and thank people for their work. Many contributors are new, and a kind, clear review is what brings them back.

Label small preferences with nit: so the author knows they don't block the change.

**Tested on:** OS, language version and commit
**Ran:** the test commands, and the result
**Reproduced the bug on main:** yes or no, and how
**Confirmed the fix on this branch:** yes or no, and how
**Not tested:** anything you skipped

**Result:** ready for a maintainer, or the changes needed

If you can't finish a review, post what you found anyway. A partial review with clear notes is still useful.

Submit a pull request to aiwaf_website or sandbox

Keep each pull request to one change, and run the checks before you open it. Small changes get reviewed sooner.

1. Comment on the issue to claim it. If there's no issue, open one first, unless it's a small fix.
2. Fork the repository and create a branch from main.
3. Make your change.
4. Run the checks for that repository.
5. Open the pull request, link the issue with Fixes #123, and fill in the template below.
6. Respond to review comments, and push fixes to the same branch.

Checks for aiwaf_website

Run these from the repository root, with an aiwaf checkout next to it:

python scripts/build_docs_search.py
bundle exec jekyll build
python scripts/check_site.py
python scripts/check_docs_accuracy.py --aiwaf ../aiwaf

• Test what you write: run every command and code sample before adding it.
• Document what's released: only describe behavior in a published version. Merge code in aiwaf before docs that depend on it.
• New pages: give each one a unique title and a description, and link it from site/pages/contents.html.
• Don't edit generated files by hand: that includes the configuration defaults tables. See the website README.
• Fixing a known problem: remove its entry from scripts/docs_accuracy_baseline.txt, or the check will fail.

Checks for sandbox

python -m unittest discover -s examples/sandbox -p 'test_*.py'
python examples/sandbox/check-package-pins.py
node --test examples/sandbox/common/redis-cache.test.js
docker compose config -q

If you changed a proxy, rebuild that service and run the smoke and login checks from Your first sandbox run.

• Dependencies: update lockfiles with the project's tools, such as npm install or lock-python-dependencies.py, rather than by hand.
• Versions: keep every manifest and lockfile in step with package-versions.json.
• Don't commit node_modules, result files, certificates or credentials.
• Stay local: only test against the sandbox's own services, and keep them bound to loopback. Never run its attack tools against a system you don't own.

Pull request template

Fixes #123

**What changed:**
A short description.

**How I tested it:**
The commands you ran, and what you checked by hand.

**Not tested:**
Anything you couldn't run.

**AI tools:**
None, or which tool you used and what for.

Using AI tools

AI tools are fine, but you're responsible for what you submit. Understand every line, run it yourself, and say in the pull request that you used one. Changes that show no sign of being tested may be closed without review. Reviews should come from people too, so don't paste an AI's output as your review.

Review a pull request in aiwaf_website or sandbox

Use the same steps and summary as an aiwaf review, with these checklists instead. You don't need to be an expert: following the instructions as a new user is a real test.

aiwaf_website

Check the pull request out, then preview it with bundle exec jekyll serve.

• Follow it yourself: run every command and sample as written, in a clean environment.
• Check facts against the code: setting names, defaults, flags and behavior should match aiwaf and the published version.
• Look for features that don't exist: a passing check only proves a name exists, not that the description is right.
• Look at the page: check it on desktop and on a phone.
• Read it as a new user: a reader should know what to do next. Look for unexplained terms and missing steps.
• Check the links: the checks only cover links within the site, so click external links yourself.
• Check the scope: the page should only claim what was tested, and security advice should be safe if followed exactly.

sandbox

Check the pull request out, then run the checks above. Docker is needed for anything that changes a service.

• Follow it yourself: build and start the changed service.
• Run the smoke and login checks: do this against that service, and compare the results with main.
• Check dependencies: lockfiles should only change what the description says, and package-versions.json should still match. Look up any new package.
• Keep it isolated: ports stay on loopback, containers keep their restrictions, and no real credentials are added.
• Read reports carefully: a passing test proves only that scenario, and a 403 might not come from AIWAF.
• Check other runtimes: a change to shared code can affect all of them, so ask a maintainer to run the all-runtimes job.
• Update the docs: if commands or services changed, the README and the sandbox pages on this site may need a matching pull request.

How review works

Anyone can review a pull request, and only maintainers merge. Your review helps a maintainer decide faster, so it counts even if you aren't a maintainer.

Automatic checks

A first-time contributor's checks wait until a maintainer approves them, so "waiting for approval" doesn't mean something is wrong. An older pull request may also need main merged in to pick up the current checks.

Review outcomes

Etiquette

• Before you start: read existing comments, and don't repeat them.
• Authors: reply to every comment, and mark a conversation resolved once it's handled. It's fine to disagree, as long as you explain why.
• Stuck work: if a claimed issue or pull request goes quiet, ask on it before taking it over. If you can't finish something, say so, so someone else can pick it up.
• Competing pull requests: compare the work, not the people. Credit good ideas from the one that doesn't get merged.
• Security problems: if a change could help someone bypass AIWAF, tell a maintainer privately rather than explaining it in a public comment.

Getting help

If you've been stuck for 15 minutes, ask. You won't be the only one, and setup problems are often quick to fix.

• About a task: comment on its issue or pull request, or use the sprint's chat channel.
• Setup errors: see Common setup errors.
• Behavior: everyone taking part follows the Code of Conduct. Report problems to the maintainers.