restler-fuzzing · git:20260728.1bce424 · 2026-07-28 · sha256 18eed9d72cf3d399
restler-fuzzing git:20260728.1bce424A
Immutable. This exact content never changes and is served at /api/v1/blob/18eed9d72cf3d399.
---
name: restler-fuzzing
description: "Runs stateful REST API fuzzing using Microsoft's RESTler - infers producer-consumer dependencies from an OpenAPI spec, drives sequences of requests (POST → GET → DELETE chains), and reports 5xx errors, resource leaks, and hierarchy violations. Wraps the canonical 4-stage workflow (compile → test → fuzz-lean → fuzz). Use when the API is stateful (resources are created, queried, modified, deleted) and Schemathesis's stateless fuzzing is missing the multi-step bugs."
---
# restler-fuzzing
## Overview
RESTler is a stateful REST API fuzzer that finds security and reliability bugs
([restler-readme][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.
[readme]: https://github.com/microsoft/restler-fuzzer
## 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][readme]: **Python 3.12.8** and
**.NET 8.0**.
### From source
```bash
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][readme].)
### Via Docker (preferred for CI)
```bash
docker build -t restler .
```
For one-off CI runs:
```bash
docker run --rm -v "$PWD/output:/output" restler ...
```
## The four-stage workflow
Per [restler-readme][readme]:
### Stage 1 - Compile
Generate a RESTler **grammar** from the OpenAPI spec. The grammar
captures the producer-consumer dependencies RESTler will exploit
during fuzzing.
```bash
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.
```bash
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.
```bash
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).
```bash
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][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:
1. Obtain the token with a short pre-script.
2. Pass it via the dictionary's `restler_custom_payload_header` for
the `Authorization` slot.
```bash
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][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](references/triage-and-ci.md).
Per-bug triage:
1. Read `bug_replay_log.txt` - the deterministic sequence.
2. Confirm the bug locally with `restler replay --replay_log <path>`.
3. 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](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][readme] - main repo: install, 4-stage workflow,
bug categories, authentication patterns.
- `schemathesis-fuzzing` -
stateless complement; lower setup cost; cover happy / boundary on
PRs.