Business logic security methodology and benchmark.
Model the rules. Break the state. Prove the impact.
StateBreak is a testing method and controlled laboratory for business logic vulnerabilities. It covers invalid state transitions, limit bypasses, accounting failures, race conditions, replay, stale decisions, workflow abuse, and cross-system inconsistencies. It does not treat ordinary injection or configuration checks as business logic findings.
The repository has two independent parts:
methodology/— a research-backed testing method for source, runtime, or combined assessments.applications/— 16 isolated Docker applications with hidden evaluator cases and reproducible scoring.
- Docker Engine or Docker Desktop with Docker Compose v2
- Python 3.10 or later for the laboratory CLI
- At least 2 GB of free memory for one application pair
No Python packages are required to start an application. Docker builds the application dependencies inside the image.
cd applications
python tools/lab.py init
python tools/lab.py list
python tools/lab.py up bankOpen the URL printed by list. Read the generated passwords from applications/credentials.json.
The wrapper calls Docker Compose. The equivalent command for the bank target is:
docker compose --env-file .env -f compose.json up --build -d --wait --wait-timeout 90 bank bank-gatewaypython tools/lab.py down # stop the laboratory
python tools/lab.py reset bank # restore the bank fixtureEach application README contains its purpose, sector, URL, roles, operations, and exact Docker command.
Start at methodology/README.md. The method is sequential: profile the business, model its rules and state, select tests, execute bounded experiments, then reproduce and adjudicate each claim.
- Define the authorized hosts, accounts, actions, fixtures, and stopping conditions.
- Complete the business profile in
methodology/modules/01-profile.md. - Build the actor, asset, state-transition, and invariant model in
methodology/modules/02-model.md. - Select only tests supported by observed capabilities and applicable sector modules.
- Record executions with
methodology/templates/run-record.md. - Require independent reproduction and adversarial review before reporting a finding.
- Write confirmed findings with
methodology/templates/finding.md.
Give the agent the authorized target and the methodology/ directory, then use this instruction:
Read methodology/README.md and follow its linked modules in order. Profile the
target's business purpose, actors, assets, rules, state transitions, limits,
approvals, money flows, and trust boundaries before selecting tests. Test only
business logic failures within the stated scope. Record assumptions and primary
evidence. Treat acceptance, commitment, and finality as separate states. Use
separate agents for discovery, execution, independent reproduction, adversarial
review, and adjudication. Report only findings that identify a violated rule,
a reproducible sequence, the expected and observed outcomes, and demonstrated
business impact. Return no finding when the evidence does not meet that bar.
Detailed role prompts are in methodology/templates/agent-assignments.md. The catalogue uses stable BLV-<TYPE>-<DOMAIN>-<NNN> identifiers; agents should cite them in run records and findings.
Never give a participant the repository root. It contains the evaluator, repairs, case catalogue, and prior results.
Create a blind source target:
cd applications
python tools/lab.py export bank --destination ./exports/bank-seededGive the participant only:
- the exported application directory;
- the permitted runtime URL and credentials, if the track allows them;
applications/evaluator/blind-submission-schema.json;applications/prompts/common-discovery.txt;- a read-only copy of
methodology/for the harness arm.
For the baseline arm, provide an empty methodology directory. Keep the model, prompt, target state, credentials, tools, token budget, time limit, and action limit identical. Use fresh fixtures and a fresh context for every trial. The evaluator replays claims against seeded and repaired builds; independent adjudication still decides whether the claimed rule and impact are supported.
Read the evaluation protocol, model benchmark protocol, and scoring method before running comparisons.
| Domain | Application | Domain | Application |
|---|---|---|---|
| Banking | Alder Current | Brokerage | Northline Securities |
| Pensions | Meadow Retirement | Payments | Relay Acquiring |
| Insurance | Hearth Mutual | E-commerce | Alder Supply |
| Hotels | Cedar House | Travel | Meridian Travel |
| Ticketing | Parterre | Education | Westmere Learning |
| Healthcare | Cedar Care | Government | Borough Support |
| SaaS | Northstar Workspace | Logistics | Northline Freight |
| Utilities | Harbour Energy | Marketplace | Foundry Exchange |
The current suite contains 62 seeded cases, 88 controls, and 121 workflow actions. Application source does not label planted cases or import evaluator code.
methodology/
README.md method entry point
modules/ profile, model, patterns, agents, verification, math
sectors/ financial, commerce, bookings, public and other systems
research/ OWASP, papers, disclosed cases and harness research
templates/ assignments, run records and findings
applications/
apps/ independent participant applications
evaluator/ hidden cases, controls, repairs, replay and scoring
prompts/ fixed participant prompt
docs/ protocols, evidence and validation records
tools/lab.py Docker lifecycle and blind export CLI
The checked-in validation record reports 400/400 browser checks, 804/804 conventional-security checks, and 300 seeded/reference Docker episodes across 354 boundaries. These results establish the tested properties only. They do not prove the absence of every conventional vulnerability or measure model discovery rates.
Run the deterministic checks from applications/:
python evaluator/validate_catalog.py
python evaluator/verify.py
python evaluator/security_checks.py
python -m unittest discover -s evaluator -p 'test_*.py' -vThe full Docker and browser procedures are documented in applications/README.md.
Additions should define the business rule, reachable workflow, hidden invariant, negative controls, seeded behavior, repaired behavior, and deterministic evidence. New catalogue entries require a unique canonical identifier. Do not place answers, revealing comments, or evaluator imports in participant-visible source.
Run the structural validation and relevant Docker tests before submitting a change. Include the exact commands and results with the change.
Use StateBreak only against systems you own or are authorized to assess. The included applications are local benchmark targets. References to real services describe domain behavior and do not grant testing permission.
Licensed under the Apache License 2.0. You may use, modify and redistribute this work, including commercially, provided you retain the copyright notice, the NOTICE file, and a statement of any changes you made. If you report results from the benchmark or build on the methodology, cite the project using CITATION.cff.
I used Claude Code to develop the test applications and to conduct some of the tests.
Built to make business logic testing measurable.