Contributing to Wallbreaker

Thanks for helping make LLM red-teaming better. By contributing you agree your work is licensed under the project’s AGPL-3.0-or-later  license, and that you’ll use the tool within the bounds described in the Security policy.

Dev Setup

Dashboard contributors should also install the frontend:

Architecture

House Rules

• No comments or emoji in code. Use short docstrings where they add real value.
• Presets are .format()-filled — keep literal {/} out of templates (use pipes or brackets for dividers); {request} must be the only brace token. A test enforces this.
• New tools register into a LOCAL ToolRegistry in their own test, not build_registry().
• Transforms: mark lossy ones lossy=True; lossless ones must round-trip exactly.
• Add a new tool by writing register(registry) and appending the module name to the tuple in tools/__init__.py (a serial collision hub — one edit at a time).
• Run pytest -q before opening a PR; the suite is the contract.

Adding a New Tool

1. Create wallbreaker/tools/my_tool.py
2. Define a register(registry) function that calls registry.register(Tool(...))
3. Add "my_tool" to the module tuple in tools/__init__.py
4. Write tests that register into a local ToolRegistry
5. Run pytest -q

# wallbreaker/tools/my_tool.py
from __future__ import annotations
 
 
def register(registry):
    registry.add(
        name="my_tool",
        description="What it does",
        parameters={
            "type": "object",
            "properties": {
                "target": {"type": "string", "description": "What to act on"},
            },
            "required": ["target"],
        },
        handler=_handler,
    )
 
 
async def _handler(ctx, target):
    ...

Adding a Transform

1. Create or extend a module in wallbreaker/transforms/
2. Add a _t("name", encode_fn, decode_fn, "description", lossy=False) entry to transforms/__init__.py
3. Lossless transforms must round-trip exactly (assert in tests)
4. Lossy transforms set lossy=True and test with normalized comparison

Adding a Jailbreak Technique

Most techniques land as one of:

Label generic academic techniques honestly (cite the paper) rather than overclaiming novelty.

Testing

pytest -q                      # full suite
pytest tests/test_my_tool.py   # single file

The full suite needs the project .venv (textual, fastapi, pillow, steg_core are installed there, not in system python).