restler-fuzzing
Overview
RESTler is a stateful REST API fuzzer that finds security and reliability bugs
(restler-readme). Its differentiator vs. stateless fuzzers like
schemathesis-fuzzing is that it infers producer-consumer dependencies from
the OpenAPI spec - if POST /resources returns an id and GET /resources/{id}
accepts that id, RESTler sequences them in that order to reach deeper state.
When to use
- The API is stateful: resources are created, queried, modified,
deleted, and bugs lurk in the dependency chains.
- A team is on Schemathesis already but suspects multi-step bugs
aren't being reached. RESTler is the next layer down.
- A new service is launching and the team wants the broadest
possible auto-coverage before releasing - particularly for cloud
services.
- The API exposes a complete OpenAPI 2.0 / 3.x specification (RESTler
consumes JSON or YAML).
If the API is stateless (search endpoints, calculator endpoints,
report-generation endpoints), Schemathesis is sufficient and lighter
to operate. RESTler shines on resource lifecycle APIs.
Install
Prerequisites per restler-readme: Python 3.12.8 and
.NET 8.0.
From source
git clone https://github.com/microsoft/restler-fuzzer.git
cd restler-fuzzer
mkdir restler_bin
python ./build-restler.py --dest_dir "$(pwd)/restler_bin"
(Per restler-readme.)
Via Docker (preferred for CI)
docker build -t restler .
For one-off CI runs:
docker run --rm -v "$PWD/output:/output" restler ...
The four-stage workflow
Per restler-readme:
Stage 1 - Compile
Generate a RESTler grammar from the OpenAPI spec. The grammar
captures the producer-consumer dependencies RESTler will exploit
during fuzzing.
restler compile --api_spec openapi.json
Output: Compile/grammar.py plus Compile/dict.json (a starter
dictionary RESTler uses to seed parameter values).
Stage 2 - Test (smoke)
Run a single end-to-end pass to verify the spec, auth, and target
URL are wired correctly. Measures endpoint coverage - what
fraction of the API RESTler can reach with the current grammar /
dictionary.
restler test --grammar_file Compile/grammar.py \
--dictionary_file Compile/dict.json \
--target_ip <api-host> \
--target_port 443 \
--use_ssl
If endpoint coverage is below the team's threshold (often 80%+),
stop and amend the dictionary or grammar before continuing.
Stage 3 - Fuzz-lean
One pass through every endpoint with default checkers active -
fast bug discovery focused on the obvious failure modes.
restler fuzz-lean --grammar_file Compile/grammar.py \
--dictionary_file Compile/dict.json \
--target_ip <api-host> \
--target_port 443 \
--use_ssl
Stage 4 - Fuzz (deep)
Aggressive breadth-first exploration. Run for a fixed time budget
(hours to days for a comprehensive run).
restler fuzz --grammar_file Compile/grammar.py \
--dictionary_file Compile/dict.json \
--target_ip <api-host> \
--target_port 443 \
--use_ssl \
--time_budget 8.0 # hours
Bug detection
Per restler-readme, RESTler reports two bug categories:
| Category | Trigger |
|---|
| 5xx errors | Any 5xx response is a bug; RESTler triages by URL pattern. |
| Checker violations | Targeted sequences look for resource leaks, hierarchy violations (e.g. accessing a resource after deletion), and use-after-free patterns. |
Each bug appears in RestlerResults/.../bug_buckets/ with a replay
log - the exact sequence of requests that triggered it. Replay
logs are deterministic - the bug reproduces on demand.
Authentication
RESTler doesn't bake in an auth strategy; for tokens, the canonical
pattern is:
- Obtain the token with a short pre-script.
- Pass it via the dictionary's
restler_custom_payload_header for
the Authorization slot.
TOKEN=$(curl -s ... | jq -r .access_token)
echo "{\"restler_custom_payload_header\": {\"Authorization\": [\"Bearer $TOKEN\"]}}" > auth-dict.json
restler fuzz-lean ... --dictionary_file auth-dict.json
For OAuth flows that rotate tokens during a long fuzz run, supply a
refresh script RESTler invokes periodically. See restler-readme
for the --token_refresh_command flag and cadence settings.
Output and triage
Results land under RestlerResults/ with Compile/, Test/, FuzzLean/, and
Fuzz/ subtrees; each unique bug gets a bug_buckets/Bug_N/ folder holding a
bug_replay_log.txt and bug_request.txt. The full directory layout is in
references/triage-and-ci.md.
Per-bug triage:
- Read
bug_replay_log.txt - the deterministic sequence.
- Confirm the bug locally with
restler replay --replay_log <path>.
- File a ticket with the replay log attached; the replay log can be
converted into a project-specific failing regression test.
CI integration
RESTler is not a per-PR tool by default - fuzz-lean takes 5-30
minutes typically; deep fuzz is hours. The canonical cadence:
| Cadence | Stage | Time budget | Trigger |
|---|
| Per-PR | Test only | <1 minute | Schema-validation smoke; fail fast. |
| Nightly | Fuzz-lean | 30-60 minutes | New endpoint regression scan. |
| Weekly | Fuzz | 4-12 hours | Deep state-machine exploration. |
| Pre-release | Fuzz | 24-72 hours | Final security / reliability gate. |
The nightly cadence runs on a schedule: cron trigger: build the RESTler
Docker image, compile the grammar from openapi.json, run fuzz-lean against
staging, upload RestlerResults/ as an artifact (if: always()), then fail the
job when any bug_replay_log.txt exists (find ... | wc -l). The complete
GitHub Actions workflow is in
references/triage-and-ci.md.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
| Running RESTler on production | Generated requests mutate live data; 5xx alerts spam oncall. | Always target staging; production is for runtime monitoring, not fuzz traffic. |
| Skipping Stage 2 (Test) | Spec-vs-impl drift is invisible until Stage 4 wastes hours. | Always run Test first; check coverage before fuzz-lean. |
| Stage 4 (Fuzz) on every PR | Hours-long PR CI; no team accepts that. | Fuzz is nightly / weekly only. |
| Triaging bugs without replay-log confirmation | Some bugs are environmental (test DB state); confirm reproducibility. | Always run restler replay on each bug before opening a ticket. |
| Letting bug counts grow unbounded | Backlog of unfixed bugs becomes noise; team learns to ignore RESTler reports. | Treat each bug as a P1 / P2 ticket; fix or document waiver per the team's escape-defect policy. |
Limitations
- OpenAPI-driven only. No GraphQL support; for GraphQL fuzzing,
use
schemathesis-fuzzing.
- Heavy infra. Python 3.12 + .NET 8 prereqs are non-trivial;
Docker is the practical install path.
- Run-time cost. Deep fuzz is hours-to-days; budget accordingly.
Fuzz-lean is the cost-effective sweet spot for nightly runs.
- No native parallelism. RESTler runs single-threaded; for
parallelism, shard at the endpoint level via multiple invocations
with different grammar subsets.
- State across runs. Each fuzz run is independent - there's no
built-in mechanism to remember "we've explored these states
already." Use the
progress/ directory for manual checkpointing.
References
- restler-readme - main repo: install, 4-stage workflow,
bug categories, authentication patterns.
schemathesis-fuzzing -
stateless complement; lower setup cost; cover happy / boundary on
PRs.