update the docs on the 0.9.2 version (#133)

AnastasiaTWW · web-flow · commit bc13db716274 · 2025-07-25T21:30:35.000+03:00
* update the docs on the 0.9.2 version
diff --git a/docs/configuration-guides/endpoint-related-response.md b/docs/configuration-guides/endpoint-related-response.md
@@ -7,6 +7,9 @@ You can configure [validation modes](../installation-guides/docker-container.md#
     mode: "PROXY"
     RequestValidation: "BLOCK"
     ResponseValidation: "BLOCK"
+    ModSecurity:
+      RequestValidation: "LOG_ONLY"
+      ResponseValidation: "LOG_ONLY"
     ...
     Endpoints:
     - Path: "/test/endpoint1"
diff --git a/docs/installation-guides/api-mode.md b/docs/installation-guides/api-mode.md
@@ -56,6 +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:<ul><li>`0` (default) - tries to load V2 (with the `status` field) first; if unsuccessful, attempts V1. On both failures, the firewall fails to start.</li><li>`1` - recognize and process the database as V1 only.</li><li>`2` - recognize and process the database as V2 only.</li></ul> | No |
 |`APIFW_API_MODE_MAX_ERRORS_IN_RESPONSE` | Limits the number of errors included in the API Firewall response for a single request validation.<br><br>The default value is `0`, which means no limit is applied.<br><br>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 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
 
@@ -134,6 +137,44 @@ 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. If needed, customize the default Prometheus endpoint `http://<host>:9010/metrics` using the following environment variables:
+
+    * `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://<host>:9010/metrics` unless custom host or path are used.
+
+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
@@ -91,8 +91,8 @@ Configure API Firewall as follows:
 | <a name="apifw-api-specs"></a>`APIFW_API_SPECS`                 | `APISpecs` | Path to the OpenAPI 3.0 specification. There are the following ways to specify the path:<ul><li>Path to the specification file mounted to the container, for example: `/api-firewall/resources/swagger.json`. When running the container, mount this file with the `-v <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>` option.</li><li>URL address of the specification file, for example: `https://example.com/swagger.json`. When running the container, omit the `-v <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>` option.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | 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.<br><br>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).<br><br>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       |
-| <a name="apifw-req-val"></a>`APIFW_REQUEST_VALIDATION`        | `RequestValidation` | API Firewall mode when validating requests sent to the application URL:<ul><li>`BLOCK` to block and log the requests that do not match the schema provided in the mounted OpenAPI 3.0 specification (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/).</li><li>`LOG_ONLY` to log but not block the requests that do not match the schema provided in the mounted OpenAPI 3.0 specification. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`DISABLE` to disable request validation.<br><br>**Note** that you can [set validation mode for specific enponts](../configuration-guides/endpoint-related-response.md).</li></ul>                                                                                                                           | Yes       |
-| `APIFW_RESPONSE_VALIDATION`       | `ResponseValidation` | API Firewall mode when validating application responses to incoming requests:<ul><li>`BLOCK` to block and log the request if the application response to this request does not match the schema provided in the mounted OpenAPI 3.0 specification. This request will be proxied to the application URL but the client will receive the `403 Forbidden` response. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`LOG_ONLY` to log but not block the request if the application response to this request does not match the schema provided in the mounted OpenAPI 3.0 specification. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`DISABLE` to disable request validation.<br><br>**Note** that you can [set validation mode for specific enponts](../configuration-guides/endpoint-related-response.md).</li></ul> | Yes       |
+| <a name="apifw-req-val"></a>`APIFW_REQUEST_VALIDATION`        | `RequestValidation` | API Firewall mode when validating requests sent to the application URL:<ul><li>`BLOCK` to block and log the requests that do not match the schema provided in the mounted OpenAPI 3.0 specification (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/).</li><li>`LOG_ONLY` to log but not block the requests that do not match the schema provided in the mounted OpenAPI 3.0 specification. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`DISABLE` to disable request validation.<br><br>**Note** that you can [set validation mode for specific endpoints](../configuration-guides/endpoint-related-response.md).</li></ul>                                                                                                                           | Yes       |
+| `APIFW_RESPONSE_VALIDATION`       | `ResponseValidation` | API Firewall mode when validating application responses to incoming requests:<ul><li>`BLOCK` to block and log the request if the application response to this request does not match the schema provided in the mounted OpenAPI 3.0 specification. This request will be proxied to the application URL but the client will receive the `403 Forbidden` response. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`LOG_ONLY` to log but not block the request if the application response to this request does not match the schema provided in the mounted OpenAPI 3.0 specification. Logs are sent to the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/).</li><li>`DISABLE` to disable request validation.<br><br>**Note** that you can [set validation mode for specific endpoints](../configuration-guides/endpoint-related-response.md).</li></ul> | Yes       |
 | `APIFW_LOG_LEVEL`                 | - | API Firewall logging level. Possible values:<ul><li>`DEBUG` to log events of any type (INFO, ERROR, WARNING, and DEBUG).</li><li>`INFO` to log events of the INFO, WARNING, and ERROR types.</li><li>`WARNING` to log events of the WARNING and ERROR types.</li><li>`ERROR` to log events of only the ERROR type.</li><li>`TRACE` to log incoming requests and API Firewall responses, including their content.</li></ul> The default value is `DEBUG`. Logs on requests and responses that do not match the provided schema have the ERROR type.                                                                                                                                                                                                                                       | No        |
 | <a name="apifw-custom-block-status-code"></a>`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`<br>(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.<ul><li>`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/).</li><li>`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/).</li><li>`DISABLE` (default) to disable request validation against the ModSecurity Rule Set.</li></ul>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.<ul><li>`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/).</li><li>`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/).</li><li>`DISABLE` (default) to disable response validation against the ModSecurity Rule Set.</li></ul>This setting takes priority if used together with `APIFW_RESPONSE_VALIDATION`. | No |
 
 <a name="apifw-yaml-example"></a>
 ??? info "Example of `apifw.yaml`"
diff --git 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)
