Validating Individual Requests Without Proxying¶

If you need to validate individual API requests based on a given OpenAPI specification without further proxying, you can utilize Wallarm API Firewall in a non-proxy mode. In this case, the solution does not validate responses.

Requirements¶

• Installed and configured Docker

• SQLite database with the table containing one or more OpenAPI 3.0 specifications. The database can be of one of the following formats:

  SQLite database V1SQLite database V2

  • Table name is openapi_schemas.
  • schema_id, integer (auto-increment) - ID of the specification.
  • schema_version, string - Specification version. You can assign any preferred version. When this field changes, API Firewall assumes the specification itself has changed and updates it accordingly.
  • schema_format, string - The specification format, can be json or yaml.
  • schema_content, string - The specification content.

  Use this format if you need to control whether a specification from the database has been handled by the API Firewall or not.

  • Table name is openapi_schemas.
  • schema_id, integer (auto-increment) - ID of the specification.
  • schema_version, string - Specification version. You can assign any preferred version. When this field changes, API Firewall assumes the specification itself has changed and updates it accordingly.
  • schema_format, string - The specification format, can be json or yaml.
  • schema_content, string - The specification content.

  • status, string - Specifies whether a specification is new (not yet processed) or applied (already processed). It is expected to be set to new by default.

    At startup, the API Firewall automatically updates processed specification status from new to applied.

    During the APIFW_SPECIFICATION_UPDATE_PERIOD, only specifications marked as new receive updates.

Running the API Firewall container¶

To use the API Firewall for request validation without further proxying, you need to mount the SQLite database containing OpenAPI 3.0 specifications to /var/lib/wallarm-api/1/wallarm_api.db inside the API Firewall Docker container. The path can be changed using the APIFW_API_MODE_DEBUG_PATH_DB variable.

Use the following command to run the API Firewall container:

docker run --rm -it -v <PATH_TO_SQLITE_DATABASE>:/var/lib/wallarm-api/1/wallarm_api.db \
    -e APIFW_MODE=API -p 8282:8282 wallarm/api-firewall:v0.8.0

You can pass to the container the following variables:

Evaluating requests against the specification¶

When evaluating requests against the mounted specification, include the header X-Wallarm-Schema-ID: <schema_id> to indicate to API Firewall which specification should be used for validation:

curl http://0.0.0.0:8282/path -H "X-Wallarm-Schema-ID: <SCHEMA_ID>"

curl http://0.0.0.0:8282/path -H "X-Wallarm-Schema-ID: 1, 2"

Understanding API Firewall responses¶

API Firewall responds with the 200 HTTP code and JSON with details on request validation:

{
    "summary": [
        {
            "schema_id": 1,
            "status_code": 200
        }
    ]
}

{
    "summary": [
        {
            "schema_id":1,
            "status_code":403
        }
    ],
    "errors": [
        {
            "message":"method and path are not found",
            "code":"method_and_path_not_found",
            "schema_id":1
        }
    ]
}

{
    "summary": [
        {
            "schema_id": 0,
            "status_code": 500
        }
    ]
}

Database issues¶

Handling invalidity in an already mounted SQLite database¶

The API Firewall automatically retrieves specification updates from the mounted database at intervals defined by the APIFW_SPECIFICATION_UPDATE_PERIOD variable. If the database structure or specifications become invalid, or if the database file disappears post-update, the Firewall maintains the last valid specification file and pauses further updates. This method guarantees continuous operation with the most recent valid specifications until a correct database file is reestablished in the API Firewall.

In cases where the database file is valid but contains an invalid specification, the API Firewall will disregard the faulty specification and proceed to load all valid specifications.

Example

Suppose the API Firewall has loaded two specifications, labeled 1 and 2. If specification 1 is modified and becomes invalid (due to syntax errors or parsing issues), the API Firewall will then only load and use specification 2. It will log an error message indicating the issue and will operate with only specification 2.

Mounting empty SQLite database¶

If the API Firewall is initiated with an empty, invalid, or non-existent database file, it will start and log errors if updates fail. In this state, the API Firewall will not have any specification, thus unable to validate requests, and will respond with a 500 status code. Note that the readiness probe will fail until a valid database is loaded.