From 5f2346a8a6af07c8eb3d651915d7ac6a051443f5 Mon Sep 17 00:00:00 2001 From: AnastasiaTWW <61460069+AnastasiaTWW@users.noreply.github.com> Date: Fri, 18 Jul 2025 20:10:29 +0400 Subject: [PATCH 1/2] update the docs on the 0.9.2 version --- .../endpoint-related-response.md | 5 ++- docs/installation-guides/api-mode.md | 35 +++++++++++++++++++ docs/installation-guides/docker-container.md | 6 ++-- docs/release-notes.md | 9 +++-- 4 files changed, 49 insertions(+), 6 deletions(-) diff --git a/docs/configuration-guides/endpoint-related-response.md b/docs/configuration-guides/endpoint-related-response.md index 7ea860e5..2d35e7f8 100644 --- a/docs/configuration-guides/endpoint-related-response.md +++ b/docs/configuration-guides/endpoint-related-response.md @@ -1,6 +1,6 @@ # Endpoint-Related Response Actions -You can configure [validation modes](../installation-guides/docker-container.md#apifw-req-val) (`RequestValidation`, `ResponseValidation`) for each endpoint separately. If not set for the endpoint specifically, global value is used. +You can configure [validation modes](../installation-guides/docker-container.md#apifw-req-val) (`RequestValidation`, `ResponseValidation`, ModSecurity → `RequestValidation`, ModSecurity → `ResponseValidation`) for each endpoint separately. If not set for the endpoint specifically, global value is used. !!! info "Example of `apifw.yaml`" ```yaml @@ -12,6 +12,9 @@ You can configure [validation modes](../installation-guides/docker-container.md# - Path: "/test/endpoint1" RequestValidation: "LOG_ONLY" ResponseValidation: "LOG_ONLY" + ModSecurity: + RequestValidation: "BLOCK" + ResponseValidation: "BLOCK" - Path: "/test/endpoint1/{internal_id}" Method: "get" RequestValidation: "LOG_ONLY" diff --git a/docs/installation-guides/api-mode.md b/docs/installation-guides/api-mode.md index 0e72c031..f0e83d92 100644 --- a/docs/installation-guides/api-mode.md +++ b/docs/installation-guides/api-mode.md @@ -56,6 +56,7 @@ You can pass to the container the following variables: | `APIFW_HEALTH_HOST` | The host of the health check service. The default value is `0.0.0.0:9667`. The liveness probe service path is `/v1/liveness` and the readiness service path is `/v1/readiness`. | No | | `APIFW_API_MODE_DB_VERSION` | Determines the SQLite database version that the API Firewall is configured to use. Available options are: | No | |`APIFW_API_MODE_MAX_ERRORS_IN_RESPONSE` | Limits the number of errors included in the API Firewall response for a single request validation.

The default value is `0`, which means no limit is applied.

Supported starting from version 0.9.1. | No | +|`APIFW_METRICS_ENABLED` | Enables the [built-in Prometheus metrics endpoint](#prometheus-metrics), which is exposed at port `9010` on the `/metrics` path. The default value is `false`. | No | ## Evaluating requests against the specification @@ -134,6 +135,40 @@ API Firewall responds with the `200` HTTP code and JSON with details on request | `errors.related_fields_details.current_value` | Parameter value passed in a request. | | `errors.related_fields_details.pattern` | Parameter value pattern specified in the specification. | +## Prometheus metrics + +To enable Prometheus-compatible metrics: + +1. Set the `APIFW_METRICS_ENABLED` environment variable to `true`. +1. Expose port `9010` in your container or deployment configuration (`-p 9010:9010`). + +Once enabled, metrics are available at `http://:9010/metrics`. + +The following Prometheus metrics are exposed: + +``` +# HELP wallarm_apifw_http_request_duration_seconds HTTP request duration in seconds +# TYPE wallarm_apifw_http_request_duration_seconds histogram +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.001"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.005"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.025"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.05"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.25"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="0.5"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="1"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="2.5"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="5"} 2 +wallarm_apifw_http_request_duration_seconds_bucket{schema_id="1",le="+Inf"} 2 +wallarm_apifw_http_request_duration_seconds_sum{schema_id="1"} 0.00028954100000000004 +wallarm_apifw_http_request_duration_seconds_count{schema_id="1"} 2 +# HELP wallarm_apifw_http_requests_total Total number of HTTP requests +# TYPE wallarm_apifw_http_requests_total counter +wallarm_apifw_http_requests_total{schema_id="1",status_code="200"} 2 +# HELP wallarm_apifw_service_errors_total Total number of errors occurred in the APIFW service. +# TYPE wallarm_apifw_service_errors_total counter +wallarm_apifw_service_errors_total 0 +``` + ## Database issues ### Handling invalidity in an already mounted SQLite database diff --git a/docs/installation-guides/docker-container.md b/docs/installation-guides/docker-container.md index 70ae5a0a..b1bb71ac 100644 --- a/docs/installation-guides/docker-container.md +++ b/docs/installation-guides/docker-container.md @@ -91,8 +91,8 @@ Configure API Firewall as follows: | `APIFW_API_SPECS` | `APISpecs` | Path to the OpenAPI 3.0 specification. There are the following ways to specify the path: | Yes | | `APIFW_URL` | Server → `APIHost` | URL for API Firewall. For example: `http://0.0.0.0:8088/`. The port value should correspond to the container port published to the host.

If API Firewall listens to the HTTPS protocol, please mount the generated SSL/TLS certificate and private key to the container, and pass to the container the [API Firewall SSL/TLS settings](../configuration-guides/ssl-tls.md).

The default value is `http://0.0.0.0:8282/`. | Yes | | `APIFW_SERVER_URL` | Backend → ProtectedAPI → URL | URL of the application described in the mounted OpenAPI specification that should be protected with API Firewall. For example: `http://backend:80`. | Yes | -| `APIFW_REQUEST_VALIDATION` | `RequestValidation` | API Firewall mode when validating requests sent to the application URL: | Yes | -| `APIFW_RESPONSE_VALIDATION` | `ResponseValidation` | API Firewall mode when validating application responses to incoming requests: | Yes | +| `APIFW_REQUEST_VALIDATION` | `RequestValidation` | API Firewall mode when validating requests sent to the application URL: | Yes | +| `APIFW_RESPONSE_VALIDATION` | `ResponseValidation` | API Firewall mode when validating application responses to incoming requests: | Yes | | `APIFW_LOG_LEVEL` | - | API Firewall logging level. Possible values: The default value is `DEBUG`. Logs on requests and responses that do not match the provided schema have the ERROR type. | No | | `APIFW_CUSTOM_BLOCK_STATUS_CODE` | `CustomBlockStatusCode` | [HTTP response status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) returned by API Firewall operating in the `BLOCK` mode if the request or response does not match the schema provided in the mounted OpenAPI 3.0 specification. The default value is `403`. | No | `APIFW_ADD_VALIDATION_STATUS_HEADER`
(EXPERIMENTAL) | `AddValidationStatusHeader` | Whether to return the header `Apifw-Validation-Status` containing the reason for the request blocking in the response to this request. The value can be `true` or `false`. The default value is `false`.| No @@ -108,6 +108,8 @@ Configure API Firewall as follows: | `APIFW_MODSEC_CONF_FILES` | ModSecurity → `ConfFiles` | Allows to set the list of [ModSecurity](../migrating/modseс-to-apif.md) configuration files. The delimiter is ;. The default value is [] (empty). Example: `APIFW_MODSEC_CONF_FILES=modsec.conf;crs-setup.conf.example`. | No | | `APIFW_MODSEC_RULES_DIR` | ModSecurity → `RulesDir` | Allows to set the [ModSecurity](../migrating/modseс-to-apif.md) directory with the rules that should be loaded. The files with the `*.conf` wildcard will be loaded from the directory. The default value is `""`. | No | | `APIFW_SERVER_REQUEST_HOST_HEADER` | `RequestHostHeader` | Sets a custom `Host` header for requests forwarded to your backend after API Firewall validation. | No | +| `APIFW_MODSEC_REQUEST_VALIDATION` | ModSecurity → `RequestValidation` | Defines how requests to the application URL are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set. This setting takes priority if used together with `APIFW_REQUEST_VALIDATION`. | No | +| `APIFW_MODSEC_RESPONSE_VALIDATION` | ModSecurity → `ResponseValidation` | Defines how application responses are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set. This setting takes priority if used together with `APIFW_RESPONSE_VALIDATION`. | No | ??? info "Example of `apifw.yaml`" diff --git a/docs/release-notes.md b/docs/release-notes.md index b57bf0bf..f762e116 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -4,9 +4,12 @@ This page describes new releases of Wallarm API Firewall. ## v0.9.2 (2025-06-09) -* Added Prometheus metrics support in the `API` mode -* Added support of the env vars in the API-Firewall pkg -* Add ModSecurity-specific validation configuration options (#127) +* Added support for [Prometheus metrics in `API` mode](installation-guides/api-mode.md#prometheus-metrics) +* Added parameters to configure request and response validation in line with ModSecurity rules ([#127 PR](https://github.com/wallarm/api-firewall/pull/127)): + + * The `APIFW_MODSEC_REQUEST_VALIDATION` environment variable with the corresponding `ModSecurity.RequestValidation` YAML configuration parameter + * The `APIFW_MODSEC_RESPONSE_VALIDATION` environment variable with the corresponding `ModSecurity.ResponseValidation` YAML configuration parameter +* Added support for the environment variables in the API Firewall package * Dependency upgrade ## v0.9.1 (2025-04-23) From d1537faa22288fac0dff8b35b8feaa9d63bf56fd Mon Sep 17 00:00:00 2001 From: AnastasiaTWW <61460069+AnastasiaTWW@users.noreply.github.com> Date: Fri, 25 Jul 2025 22:25:15 +0400 Subject: [PATCH 2/2] fixes --- .../endpoint-related-response.md | 8 ++++---- docs/installation-guides/api-mode.md | 12 +++++++++--- docs/installation-guides/docker-container.md | 4 ++-- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/configuration-guides/endpoint-related-response.md b/docs/configuration-guides/endpoint-related-response.md index 2d35e7f8..7a98de38 100644 --- a/docs/configuration-guides/endpoint-related-response.md +++ b/docs/configuration-guides/endpoint-related-response.md @@ -1,20 +1,20 @@ # Endpoint-Related Response Actions -You can configure [validation modes](../installation-guides/docker-container.md#apifw-req-val) (`RequestValidation`, `ResponseValidation`, ModSecurity → `RequestValidation`, ModSecurity → `ResponseValidation`) for each endpoint separately. If not set for the endpoint specifically, global value is used. +You can configure [validation modes](../installation-guides/docker-container.md#apifw-req-val) (`RequestValidation`, `ResponseValidation`) for each endpoint separately. If not set for the endpoint specifically, global value is used. !!! info "Example of `apifw.yaml`" ```yaml mode: "PROXY" RequestValidation: "BLOCK" ResponseValidation: "BLOCK" + ModSecurity: + RequestValidation: "LOG_ONLY" + ResponseValidation: "LOG_ONLY" ... Endpoints: - Path: "/test/endpoint1" RequestValidation: "LOG_ONLY" ResponseValidation: "LOG_ONLY" - ModSecurity: - RequestValidation: "BLOCK" - ResponseValidation: "BLOCK" - Path: "/test/endpoint1/{internal_id}" Method: "get" RequestValidation: "LOG_ONLY" diff --git a/docs/installation-guides/api-mode.md b/docs/installation-guides/api-mode.md index f0e83d92..12da72ef 100644 --- a/docs/installation-guides/api-mode.md +++ b/docs/installation-guides/api-mode.md @@ -56,7 +56,9 @@ You can pass to the container the following variables: | `APIFW_HEALTH_HOST` | The host of the health check service. The default value is `0.0.0.0:9667`. The liveness probe service path is `/v1/liveness` and the readiness service path is `/v1/readiness`. | No | | `APIFW_API_MODE_DB_VERSION` | Determines the SQLite database version that the API Firewall is configured to use. Available options are: | No | |`APIFW_API_MODE_MAX_ERRORS_IN_RESPONSE` | Limits the number of errors included in the API Firewall response for a single request validation.

The default value is `0`, which means no limit is applied.

Supported starting from version 0.9.1. | No | -|`APIFW_METRICS_ENABLED` | Enables the [built-in Prometheus metrics endpoint](#prometheus-metrics), which is exposed at port `9010` on the `/metrics` path. The default value is `false`. | No | +|`APIFW_METRICS_ENABLED` | Enables the [built-in Prometheus metrics endpoint](#prometheus-metrics), which is exposed at port `9010` on the `/metrics` path by default. The default value is `false`. | No | +|`APIFW_METRICS_ENDPOINT_NAME` | Defines the path at which the [built-in Prometheus metrics endpoint](#prometheus-metrics) is exposed. The default value is `metrics`. | No | +|`APIFW_METRICS_HOST` | Defines the IP address and/or port for the [built-in Prometheus metrics endpoint](#prometheus-metrics). When specifying a port, prefix it with a colon (`:`). The default value is `:9010`. | No | ## Evaluating requests against the specification @@ -140,9 +142,13 @@ API Firewall responds with the `200` HTTP code and JSON with details on request To enable Prometheus-compatible metrics: 1. Set the `APIFW_METRICS_ENABLED` environment variable to `true`. -1. Expose port `9010` in your container or deployment configuration (`-p 9010:9010`). +1. If needed, customize the default Prometheus endpoint `http://:9010/metrics` using the following environment variables: -Once enabled, metrics are available at `http://:9010/metrics`. + * `APIFW_METRICS_ENDPOINT_NAME`: the path at which the metrics endpoint is exposed. + * `APIFW_METRICS_HOST`: the IP address and/or port for the metrics endpoint. When specifying a port, prefix it with a colon (`:`). +1. Expose the metrics port in your container or deployment configuration (e.g., for the default state, use `-p 9010:9010`). + +Once enabled, metrics are available at `http://:9010/metrics` unless custom host or path are used. The following Prometheus metrics are exposed: diff --git a/docs/installation-guides/docker-container.md b/docs/installation-guides/docker-container.md index b1bb71ac..aab35c37 100644 --- a/docs/installation-guides/docker-container.md +++ b/docs/installation-guides/docker-container.md @@ -108,8 +108,8 @@ Configure API Firewall as follows: | `APIFW_MODSEC_CONF_FILES` | ModSecurity → `ConfFiles` | Allows to set the list of [ModSecurity](../migrating/modseс-to-apif.md) configuration files. The delimiter is ;. The default value is [] (empty). Example: `APIFW_MODSEC_CONF_FILES=modsec.conf;crs-setup.conf.example`. | No | | `APIFW_MODSEC_RULES_DIR` | ModSecurity → `RulesDir` | Allows to set the [ModSecurity](../migrating/modseс-to-apif.md) directory with the rules that should be loaded. The files with the `*.conf` wildcard will be loaded from the directory. The default value is `""`. | No | | `APIFW_SERVER_REQUEST_HOST_HEADER` | `RequestHostHeader` | Sets a custom `Host` header for requests forwarded to your backend after API Firewall validation. | No | -| `APIFW_MODSEC_REQUEST_VALIDATION` | ModSecurity → `RequestValidation` | Defines how requests to the application URL are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set.
  • `BLOCK` to block and log the requests that violate the ModSecurity Rule Set (the `403 Forbidden` response will be returned to the blocked requests). Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `LOG_ONLY` to log but not block the requests that violate the rule set. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `DISABLE` (default) to disable request validation against the ModSecurity Rule Set.

    **Note** that you can [set validation mode for specific endpoints](../configuration-guides/endpoint-related-response.md).
This setting takes priority if used together with `APIFW_REQUEST_VALIDATION`. | No | -| `APIFW_MODSEC_RESPONSE_VALIDATION` | ModSecurity → `ResponseValidation` | Defines how application responses are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set.
  • `BLOCK` to block and log the corresponding requests (the `403 Forbidden` response will be returned to the blocked requests). Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `LOG_ONLY` to log but not block the corresponding requests. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `DISABLE` (default) to disable response validation against the ModSecurity Rule Set.

    **Note** that you can [set validation mode for specific endpoints](../configuration-guides/endpoint-related-response.md).
This setting takes priority if used together with `APIFW_RESPONSE_VALIDATION`. | No | +| `APIFW_MODSEC_REQUEST_VALIDATION` | ModSecurity → `RequestValidation` | Defines how requests to the application URL are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set.
  • `BLOCK` to block and log the requests that violate the ModSecurity Rule Set (the `403 Forbidden` response will be returned to the blocked requests). Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `LOG_ONLY` to log but not block the requests that violate the rule set. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `DISABLE` (default) to disable request validation against the ModSecurity Rule Set.
This setting takes priority if used together with `APIFW_REQUEST_VALIDATION`. | No | +| `APIFW_MODSEC_RESPONSE_VALIDATION` | ModSecurity → `ResponseValidation` | Defines how application responses are validated against the [ModSecurity](../migrating/modseс-to-apif.md) Rule Set.
  • `BLOCK` to block and log the corresponding requests (the `403 Forbidden` response will be returned to the blocked requests). Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `LOG_ONLY` to log but not block the corresponding requests. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).
  • `DISABLE` (default) to disable response validation against the ModSecurity Rule Set.
This setting takes priority if used together with `APIFW_RESPONSE_VALIDATION`. | No | ??? info "Example of `apifw.yaml`"