An oracle specification is a YAML file that defines how to probe a target. It consists of a request template and a set of match rules.
Request Template
The request section defines the HTTP method, URL, headers, and body. It supports placeholders that are substituted per subject:
{{email}}: The full subject value.{{username}}: The subject value.{{localpart}}: The part before the @ (e.g., alice from alice@demo.local).{{domain}}: The part after the @ (e.g., demo.local).
Note: Placeholders are escaped according to body_encoding (json, form, or raw). URL placeholders are automatically URL-escaped.
Match Rules and Verdicts
Rules are evaluated in order; the first matching rule determines the verdict. Conditions within a when block are AND-ed together.
Available when conditions:
status: Matches if the response status equals the integer or is in a provided list.body_contains: Matches if the response body contains the specified substring.body_regex: Matches if the response body matches the provided RE2 regex.json_field: Matches if a dot-path value equals or is in a set.header: Matches if a response header is present or equals a value.
Verdicts:
exists: The subject is valid.absent: The subject does not exist.error: The response was ambiguous or no rules matched (use the default key to specify this behavior).
version: "1"
oracle:
name: demo-forgot-password
request:
method: POST
url: "http://localhost:8080/api/forgot-password"
headers:
Content-Type: application/json
body: '{"email":"{{email}}"}'
body_encoding: json
match:
rules:
- when:
status: 200
body_contains: "reset link sent"
verdict: exists
confidence: high
- when:
status: 404
body_contains: "No account found"
verdict: absent
confidence: high
default: error
