diff --git a/docs/configuration-guides/endpoint-related-response.md b/docs/configuration-guides/endpoint-related-response.md index 7ea860e5..7a98de38 100644 --- 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 index 0e72c031..12da72ef 100644 --- 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: | 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 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://: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://: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 index 70ae5a0a..aab35c37 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)