Contributing

Contributing

New seed payloads and scenarios are the easiest and most valuable contributions. Full guide: CONTRIBUTING.md in the repo.

Setup

• Python 3.11+, uv. The package lives in engine/.
• Engine tests (offline): cd engine && uv run pytest -m "not live"
• Fixture tests (sandbox-inert + end-to-end seed run): uv run --with-editable ./engine --with flask --with "mcp>=2" --with pytest python -m pytest fixture/tests

Add a seed payload

Edit engine/src/aphasia/data/payloads.yaml under the matching scenario id (order matters for multi-phase scenarios). See Seed Payload Library. Only redistributable (Apache-2.0) payloads. Verify with aphasia run --mode seed against the fixture.

Add a scenario

1. Add an entry to engine/src/aphasia/data/scenarios.yaml (id, category, channel, goal, success_condition, atlas, owasp).
2. Give the The Fixture a deliberately-vulnerable, sandbox-inert surface in fixture/agent/app.py (string/dict ops only) and a test in fixture/tests/test_agent_sandbox.py.
3. Add seed payloads in payloads.yaml.
4. If it maps to a MITRE ATLAS technique, add the id + display name in engine/src/aphasia/report/render.py.

Rules

• Every change ships with a test. Keep PRs small and focused.
• Never weaken a safety invariant — see Security and Safety.
• By contributing you agree your work is licensed under Apache-2.0.