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

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

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.

Request an evaluation