Attack scenariosAPI security
Requests that violate your API contract
An API endpoint expects an integer identifier and a typed JSON body. Mikiri API Firewall and Mikiri WAAP check the request against its OpenAPI operation before it reaches the application.
What this check protects
A loaded specification defines the accepted methods, parameters and bodies for known operations. Contract validation rejects requests that violate those rules. It does not decide who owns a record: a valid identifier belonging to another customer still needs an authorization check in the application. See object enumeration and the limits of perimeter protection.
What the API Firewall enforces
With a specification loaded for the host and enforcement enabled, the API Firewall checks the operation and its declared parameters and body. A schema violation or a method not declared for a known path produces blocking type 14. Detection mode records the violation without enforcing the block; an exclusion can skip the check.
Uploaded specifications are converted to OpenAPI 3.1 and checked before storage. The examples below describe Mikiri's validation behavior; numeric token checks are implementation rules, not a general definition of JSON Schema number types.
The test specification
This test specification declares an integer path identifier, an optional email in the query and a typed JSON body for updates. Load it for the test host before running the checks below.
OpenAPI test specification
openapi: 3.1.0
info:
title: Contract validation test
version: 1.0.0
servers:
- url: https://api.example.com
paths:
/api/v1/orders/{orderId}:
get:
parameters:
- name: orderId
in: path
required: true
schema:
type: integer
format: int64
- name: notify
in: query
schema:
type: string
format: email
responses:
"200":
description: Order
patch:
parameters:
- name: orderId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [email, shipBy, amount]
properties:
email:
type: string
format: email
shipBy:
type: string
format: date
amount:
type: number
format: double
reference:
type: string
format: uuid
responses:
"200":
description: Order updated
Path identifiers that are not integers
When orderId is integer / int64, only a whole number in the i64 range is accepted. The variants scanners try on the first pass are blocked before they reach the application.
Blocked path values
- Not an integer/api/v1/orders/10453;export
- Not an integer/api/v1/orders/all
- Not an integer/api/v1/orders/10453abc
- Rejected integer spelling/api/v1/orders/10453.0 — Mikiri checks the original numeric spelling
- Outside int64/api/v1/orders/99999223372036854775800
For Mikiri's number checks with format: float or format: double, a bare integer token such as 123 is rejected. float also allows at most eight significant decimal digits and must fit in f32. int32 rejects a value that only fits in int64. Verify these token and precision constraints against the values your API actually sends during evaluation.
Email, date, UUID and the other string formats
String format is checked on the path, the query, the headers, the cookies and the body. The API Firewall validates these formats itself:
String formats the API Firewall checks
- emailParsed as an address; the domain must be a hostname with a dot, or an IP in brackets
- date
YYYY-MM-DD - date-timeRFC 3339
- uuid36 characters, hex digits, dashes in the fixed positions
- ipv4, ipv6One address
- uri, uri-referenceNo whitespace or controls; a scheme, when present, must be well formed
- hostnameASCII hostname with label length limits
- byteStandard Base64; whitespace is rejected
password and binary are accepted as format names and are not rewritten. Formats such as duration and idn-email are checked through the fuller schema interpreter.
Against the test specification above, these values fail validation:
Blocked request values
GET /api/v1/orders/10453?notify=user_example.com
PATCH /api/v1/orders/10453
{"email":"user@example/com","shipBy":"2017-07-21","amount":12.5}
PATCH /api/v1/orders/10453
{"email":"user@example.com","shipBy":"2017-07-21","amount":12.5,
"reference":"not-a-uuid"}
PATCH /api/v1/orders/10453
{"email":"user@example.com","shipBy":"2017-07-21","amount":123}
The last body fails Mikiri's format: double check because amount is a bare integer token. A value such as 12.5 or 1.0000000000000002 passes that numeric check; a decimal token that does not survive the validator's f64 round-trip check does not.
If an operation declares a header with type: string and format: email, the same email checks apply to that header. The test specification above does not declare such a header, so it does not validate an X-Email value.
Wrong type in the body
The API Firewall checks the JSON types, not only the formats. A field declared as a string does not accept a number, and a required property cannot be omitted.
Blocked bodies
{"email":"user@example.com","shipBy":"2017-07-21","amount":"12.5"}
{"email":"user@example.com","shipBy":"2017-07-21"}
{"email":"user@example.com","shipBy":"2017-07-21","amount":12.5,
"extra":true}
The third example fails when the schema sets additionalProperties: false. For a body sent as application/json or a +json media type, duplicate object keys and invalid JSON are rejected even when the body is optional. A non-empty form posted to this JSON-only operation is rejected because its media type is not declared. An operation that declares multipart input can validate the parts as properties, including a declared format: uuid.
Wrong method
A path declared for GET and PATCH does not accept HEAD under this contract: Mikiri does not treat GET as an implicit HEAD operation. With enforcement enabled, Filter records this as an OpenAPI block with reason METHOD. Do not infer the client's HTTP status from the API Firewall's internal method-check response.
An unknown path passes the contract check by default. The host's Block paths not defined by this specification option (block_undefined_path, default false) can reject it with blocking type 14. Exclusions and API Firewall detection mode still affect enforcement.
Specification settings and unknown-path blocking · API Firewall detection mode
Reproduce the contract check
Use a test application behind an inline Filter running Mikiri API Firewall or Mikiri WAAP. Replace api.example.com in both the specification and commands with your test hostname; route it to Filter and use a valid TLS certificate. Upload the specification under that same hostname and wait for it to be applied. Specification upload fills the host's API URL list from its paths; verify that the test path remains covered if you have customized that list.
Enable enforcement for this test: the host must not be in general detection mode, and the test client and URL must not match API Firewall detection-mode or exclusion lists. Confirm that events reach WMC and that backend access logging is enabled. The requests below use only GET and HEAD; use a test endpoint with no side effects. The listed outcomes are expected checks to reproduce, not captured test results.
Run each check from an unblocked test client. An earlier rejected request can trigger an IP ban through the host's rate limit; let that test ban expire or clear it before the next check. If another control rejects the request first, inspect that event before attributing the result to API contract validation.
Control request: passes the contract check
curl -i https://api.example.com/api/v1/orders/10453
The control should reach the backend if no other protection rule blocks it. The application still decides whether to authenticate the client, authorize the order and return a record.
Wrong path type and undeclared method: blocked by the contract check
curl -i https://api.example.com/api/v1/orders/not-an-integer
curl --head https://api.example.com/api/v1/orders/10453
Both requests should be blocked before the backend. In WMC, check blocking type 14: the path-type check should name the failed parameter, and the undeclared method should show METHOD. Correlate the request times or identifiers with backend access logs. First confirm the control request appears in those logs, then check that the rejected requests do not; a client status code alone does not establish where a request was rejected.
Record the Mikiri package versions, the loaded specification, the host's mode, the exact requests, the WMC events and the matching backend log interval. On the isolated test host, repeat these read-only requests in API Firewall detection mode: they should be recorded and forwarded if no other control blocks them. Restore the intended mode after the check. Test an unknown path separately with block_undefined_path both off and on to verify that boundary.
Validate your own API contract
Request a free 14-day testing key for Mikiri API Firewall or Mikiri WAAP, load your specification and compare accepted and rejected requests in your environment.
