diff --git a/docs/configuration-guides/endpoint-related-response.md b/docs/configuration-guides/endpoint-related-response.md new file mode 100644 index 00000000..7ea860e5 --- /dev/null +++ b/docs/configuration-guides/endpoint-related-response.md @@ -0,0 +1,33 @@ +# 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. + +!!! info "Example of `apifw.yaml`" + ```yaml + mode: "PROXY" + RequestValidation: "BLOCK" + ResponseValidation: "BLOCK" + ... + Endpoints: + - Path: "/test/endpoint1" + RequestValidation: "LOG_ONLY" + ResponseValidation: "LOG_ONLY" + - Path: "/test/endpoint1/{internal_id}" + Method: "get" + RequestValidation: "LOG_ONLY" + ResponseValidation: "DISABLE" + ``` + +The `Method` value is optional. If the `Method` is not set then the validation modes will be applied to all methods of the endpoint. + +Example of the same configuration via environment variables: + +``` +APIFW_ENDPOINTS=/test/endpoint1|LOG_ONLY|LOG_ONLY,GET:/test/endpoint1/{internal_id}|LOG_ONLY|DISABLE +``` + +The format of the `APIFW_ENDPOINTS` environment variable: + +``` +[METHOD:]PATH|REQUEST_VALIDATION|RESPONSE_VALIDATION +``` \ No newline at end of file diff --git a/docs/configuration-guides/system-settings.md b/docs/configuration-guides/system-settings.md index 10f4dcfa..3cf7c582 100644 --- a/docs/configuration-guides/system-settings.md +++ b/docs/configuration-guides/system-settings.md @@ -1,23 +1,27 @@ # System Settings -To fine-tune system API Firewall settings, use the following optional environment variables: +To fine-tune system API Firewall settings, use the following optional environment variables or YAML parameters: -| Environment variable | Description | -| -------------------- | ----------- | -| `APIFW_READ_TIMEOUT` | The timeout for API Firewall to read the full request (including the body) sent to the application URL. The default value is `5s`. | -| `APIFW_WRITE_TIMEOUT` | The timeout for API Firewall to return the response to the request sent to the application URL. The default value is `5s`. | -| `APIFW_SERVER_MAX_CONNS_PER_HOST`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The maximum number of connections that API Firewall can handle simultaneously. The default value is `512`. | -| `APIFW_SERVER_READ_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to read the full response (including the body) returned to the request by the application. The default value is `5s`. | -| `APIFW_SERVER_WRITE_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to write the full request (including the body) to the application. The default value is `5s`. | -| `APIFW_SERVER_DIAL_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to connect to the application. The default value is `200ms`. | -| `APIFW_SERVER_CLIENT_POOL_CAPACITY`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Maximum number of the fasthttp clients. The default value is `1000`. | -| `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`. | -| `APIFW_READ_BUFFER_SIZE`
(for APIFW server) | Per-connection buffer size for request reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies). The default value is `8192`. | -| `APIFW_WRITE_BUFFER_SIZE`
(for APIFW server) | Per-connection buffer size for response writing. The default value is `8192`. | -| `APIFW_MAX_REQUEST_BODY_SIZE`
(for APIFW server) | Maximum request body size. The server rejects requests with bodies exceeding this limit. The default value is `4194304`. | -| `APIFW_DISABLE_KEEPALIVE`
(for APIFW server) | Disables the keep-alive connections. The server will close all the incoming connections after sending the first response to the client if this option is set to `true`. The default value is `false`. | -| `APIFW_MAX_CONNS_PER_IP`
(for APIFW server) | Maximum number of concurrent client connections allowed per IP. The default value is `0` (means "unlimited"). | -| `APIFW_MAX_REQUESTS_PER_CONN`
(for APIFW server) | Maximum number of requests served per connection. The server closes the connection after the last request. The `Connection: close` header is added to the last response. The default value is `0` (means "unlimited"). | -| `APIFW_SERVER_READ_BUFFER_SIZE`
(for HTTP client sending requests) | Per-connection buffer size for request reading. This also limits the maximum header size. The default value is `8192`. | -| `APIFW_SERVER_WRITE_BUFFER_SIZE`
(for HTTP client sending requests) | Per-connection buffer size for response writing. The default value is `8192`. | -| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`
(for HTTP client sending requests) | Maximum response body size. The default value is `0` (means "unlimited"). | +| Environment variable | YAML parameter | Description | +| -------------------- | ----------- | ----------- | +| `APIFW_READ_TIMEOUT` | Server → `ReadTimeout` | The timeout for API Firewall to read the full request (including the body) sent to the application URL. The default value is `5s`. | +| `APIFW_WRITE_TIMEOUT` | Server → `WriteTimeout` | The timeout for API Firewall to return the response to the request sent to the application URL. The default value is `5s`. | +| `APIFW_SERVER_MAX_CONNS_PER_HOST`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `MaxConnsPerHost` | The maximum number of connections that API Firewall can handle simultaneously. The default value is `512`. | +| `APIFW_SERVER_READ_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Backend → ProtectedAPI → `ReadTimeout` | The timeout for API Firewall to read the full response (including the body) returned to the request by the application. The default value is `5s`. | +| `APIFW_SERVER_WRITE_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Backend → ProtectedAPI → `WriteTimeout` | The timeout for API Firewall to write the full request (including the body) to the application. The default value is `5s`. | +| `APIFW_SERVER_DIAL_TIMEOUT`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `DialTimeout` | The timeout for API Firewall to connect to the application. The default value is `200ms`. | +| `APIFW_SERVER_CLIENT_POOL_CAPACITY`
(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `ClientPoolCapacity` | Maximum number of the fasthttp clients. The default value is `1000`. | +| `APIFW_HEALTH_HOST` | HealthAPIHost | 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`. | +| `APIFW_READ_BUFFER_SIZE`
(for APIFW server) | `ReadBufferSize` | Per-connection buffer size for request reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies). The default value is `8192`. | +| `APIFW_WRITE_BUFFER_SIZE`
(for APIFW server) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. | +| `APIFW_MAX_REQUEST_BODY_SIZE`
(for APIFW server) | `MaxRequestBodySize` | Maximum request body size. The server rejects requests with bodies exceeding this limit. The default value is `4194304`. | +| `APIFW_DISABLE_KEEPALIVE`
(for APIFW server) | `DisableKeepalive` | Disables the keep-alive connections. The server will close all the incoming connections after sending the first response to the client if this option is set to `true`. The default value is `false`. | +| `APIFW_MAX_CONNS_PER_IP`
(for APIFW server) | `MaxConnsPerIP` | Maximum number of concurrent client connections allowed per IP. The default value is `0` (means "unlimited"). | +| `APIFW_MAX_REQUESTS_PER_CONN`
(for APIFW server) | `MaxRequestsPerConn` | Maximum number of requests served per connection. The server closes the connection after the last request. The `Connection: close` header is added to the last response. The default value is `0` (means "unlimited"). | +| `APIFW_SERVER_READ_BUFFER_SIZE`
(for HTTP client sending requests) | `ReadBufferSize` | Per-connection buffer size for request reading. This also limits the maximum header size. The default value is `8192`. | +| `APIFW_SERVER_WRITE_BUFFER_SIZE`
(for HTTP client sending requests) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. | +| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`
(for HTTP client sending requests) | `MaxResponseBodySize` | Maximum response body size. The default value is `0` (means "unlimited"). | + + +??? info "Example of `apifw.yaml`" + --8<-- "include/apifw-yaml-example.md" diff --git a/docs/include/apifw-yaml-example.md b/docs/include/apifw-yaml-example.md new file mode 100644 index 00000000..3f164565 --- /dev/null +++ b/docs/include/apifw-yaml-example.md @@ -0,0 +1,83 @@ +```yaml +mode: "PROXY" +RequestValidation: "BLOCK" +ResponseValidation: "BLOCK" +CustomBlockStatusCode: 403 +AddValidationStatusHeader: false +APISpecs: "openapi.yaml" +APISpecsCustomHeader: + Name: "" + Value: "" +PassOptionsRequests: true +SpecificationUpdatePeriod: "0" +Server: + APIHost: "http://0.0.0.0:8282" + HealthAPIHost: "0.0.0.0:9999" + ReadTimeout: "5s" + WriteTimeout: "5s" + ReadBufferSize: 8192 + WriteBufferSize: 8192 + MaxRequestBodySize: 4194304 + DisableKeepalive: false + MaxConnsPerIP: 0 + MaxRequestsPerConn: 0 +DNS: + Nameserver: + Host: "" + Port: "53" + Proto: "udp" + Cache: false + FetchTimeout: "1m" + LookupTimeout: "1s" +Denylist: + Tokens: + CookieName: "" + HeaderName: "" + TrimBearerPrefix: true + File: "" +AllowIP: + File: "" + HeaderName: "" +ShadowAPI: + ExcludeList: + - 404 + - 200 + UnknownParametersDetection: false +TLS: + CertsPath: "certs" + CertFile: "localhost.crt" + CertKey: "localhost.key" +ModSecurity: + ConfFiles: [] + RulesDir: "" +Endpoints: [] +Backend: + Oauth: + ValidationType: "JWT" + JWT: + SignatureAlgorithm: "RS256" + PubCertFile: "" + SecretKey: "" + Introspection: + ClientAuthBearerToken: "" + Endpoint: "" + EndpointParams: "" + TokenParamName: "" + ContentType: "" + EndpointMethod: "GET" + RefreshInterval: "10m" + ProtectedAPI: + URL: "http://localhost:3000/v1/" + RequestHostHeader: "" + ClientPoolCapacity: 1000 + InsecureConnection: false + RootCA: "" + MaxConnsPerHost: 512 + ReadTimeout: "5s" + WriteTimeout: "5s" + DialTimeout: "200ms" + ReadBufferSize: 8192 + WriteBufferSize: 8192 + MaxResponseBodySize: 0 + DeleteAcceptEncoding: false +``` \ No newline at end of file diff --git a/docs/installation-guides/docker-container.md b/docs/installation-guides/docker-container.md index 8d882d53..faf10650 100644 --- a/docs/installation-guides/docker-container.md +++ b/docs/installation-guides/docker-container.md @@ -71,37 +71,47 @@ If configuring your own application, define only settings required for the corre ## Step 4. Configure API Firewall -Pass API Firewall configuration in **docker-compose.yml** → `services.api-firewall` as follows: +Configure API Firewall as follows: -**With `services.api-firewall.volumes`**, please mount the [OpenAPI 3.0 specification](https://swagger.io/specification/) to the API Firewall container directory: +1. With `services.api-firewall.volumes`, mount the [OpenAPI 3.0 specification](https://swagger.io/specification/) to the API Firewall container directory: -* ``: the path to the OpenAPI 3.0 specification for your application REST API located on the host machine. The accepted file formats are YAML and JSON (`.yaml`, `.yml`, `.json` file extensions). For example: `/opt/my-api/openapi3/swagger.json`. -* ``: the path to the container directory to mount the OpenAPI 3.0 specification to. For example: `/api-firewall/resources/swagger.json`. - -**With `services.api-firewall.environment`**, please set the general API Firewall configuration through the following environment variables: - -| Environment variable | Description | Required? | -|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| -| `APIFW_API_SPECS` | Path to the OpenAPI 3.0 specification. There are the following ways to specify the path: | Yes | -| `APIFW_URL` | 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` | 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` | API Firewall mode when validating requests sent to the application URL: | Yes | -| `APIFW_RESPONSE_VALIDATION` | 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` | [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) | 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 -| `APIFW_SERVER_DELETE_ACCEPT_ENCODING` | If it is set to `true`, the `Accept-Encoding` header is deleted from proxied requests. The default value is `false`. | No | -| `APIFW_LOG_FORMAT` | The format of API Firewall logs. The value can be `TEXT` or `JSON`. The default value is `TEXT`. | No | -| `APIFW_SHADOW_API_EXCLUDE_LIST`
(only if API Firewall is operating in the `LOG_ONLY` mode for both the requests and responses) | [HTTP response status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) indicating that the requested API endpoint that is not included in the specification is NOT a shadow one. You can specify several status codes separated by a semicolon (e.g. `404;401`). The default value is `404`.

By default, API Firewall operating in the `LOG_ONLY` mode for both the requests and responses marks all endpoints that are not included in the specification and are returning the code different from `404` as the shadow ones. | No -| `APIFW_MODE` | Sets the general API Firewall mode. Possible values are `PROXY` (default), [`graphql`](graphql/docker-container.md) and [`API`](api-mode.md). | No | -| `APIFW_PASS_OPTIONS` | When set to `true`, the API Firewall allows `OPTIONS` requests to endpoints in the specification, even if the `OPTIONS` method is not described. The default value is `false`. | No | -| `APIFW_SHADOW_API_UNKNOWN_PARAMETERS_DETECTION` | This specifies whether requests are identified as non-matching the specification if their parameters do not align with those defined in the OpenAPI specification. The default value is `true`.

If running API Firewall in the [`API` mode](api-mode.md), this variable takes on a different name `APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION`. | No | -| `APIFW_API_SPECS_CUSTOM_HEADER_NAME` | Specifies the custom header name to be added to requests for your OpenAPI specification URL (defined in `APIFW_API_SPECS`). For example, you can specify a header name for authentication data required to access the URL. | No | -| `APIFW_API_SPECS_CUSTOM_HEADER_VALUE` | Specifies the custom header value to be added to requests for your OpenAPI specification URL. For example, you can specify authentication data for the custom header defined in `APIFW_API_SPECS_CUSTOM_HEADER_NAME` to access the URL. | No | -| `APIFW_SPECIFICATION_UPDATE_PERIOD` | Specifies the interval for updating the OpenAPI specification from the hosted URL (defined in `APIFW_API_SPECS`). The default value is `0`, which disables updates and uses the initially downloaded specification. The value format is: `5s`, `1h`, etc. | No | -| `APIFW_MODSEC_CONF_FILES` | 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` | 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` | Sets a custom `Host` header for requests forwarded to your backend after API Firewall validation. | No | + * ``: the path to the OpenAPI 3.0 specification for your application REST API located on the host machine. The accepted file formats are YAML and JSON (`.yaml`, `.yml`, `.json` file extensions). For example: `/opt/my-api/openapi3/swagger.json`. + * ``: the path to the container directory to mount the OpenAPI 3.0 specification to. For example: `/api-firewall/resources/swagger.json`. + +1. Set the general API Firewall configuration using one of the approaches: + + * With `services.api-firewall.environment`, pass environment variables to **docker-compose.yml** → `services.api-firewall`. + * With `services.api-firewall.volumes`, mount the [`apifw.yaml`](#apifw-yaml-example) configuation file to the API Firewall container directory. + + !!! info "Priority" + If both specified, values in `apifw.yaml` have priority over environment variables. + +| Environment variable | YAML parameter | Description | Required? | +|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------| +| `APIFW_API_SPECS` | `APISpecs` | Path to the OpenAPI 3.0 specification. There are the following ways to specify the path:
  • 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 :` option.
  • URL address of the specification file, for example: `https://example.com/swagger.json`. When running the container, omit the `-v :` option.
| 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:
  • `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/).
  • `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/).
  • `DISABLE` to disable request validation.

    **Note** that you can [set validation mode for specific enponts](../configuration-guides/endpoint-related-response.md).
| Yes | +| `APIFW_RESPONSE_VALIDATION` | `ResponseValidation` | API Firewall mode when validating application responses to incoming requests:
  • `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/).
  • `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/).
  • `DISABLE` to disable request validation.

    **Note** that you can [set validation mode for specific enponts](../configuration-guides/endpoint-related-response.md).
| Yes | +| `APIFW_LOG_LEVEL` | - | API Firewall logging level. Possible values:
  • `DEBUG` to log events of any type (INFO, ERROR, WARNING, and DEBUG).
  • `INFO` to log events of the INFO, WARNING, and ERROR types.
  • `WARNING` to log events of the WARNING and ERROR types.
  • `ERROR` to log events of only the ERROR type.
  • `TRACE` to log incoming requests and API Firewall responses, including their content.
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 +| `APIFW_SERVER_DELETE_ACCEPT_ENCODING` | `DeleteAcceptEncoding` | If it is set to `true`, the `Accept-Encoding` header is deleted from proxied requests. The default value is `false`. | No | +| `APIFW_LOG_FORMAT` | - | The format of API Firewall logs. The value can be `TEXT` or `JSON`. The default value is `TEXT`. | No | +| `APIFW_SHADOW_API_EXCLUDE_LIST`
(only if API Firewall is operating in the `LOG_ONLY` mode for both the requests and responses) | ShadowAPI → `ExcludeList` | [HTTP response status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) indicating that the requested API endpoint that is not included in the specification is NOT a shadow one. You can specify several status codes separated by a semicolon (e.g. `404;401`). The default value is `404`.

By default, API Firewall operating in the `LOG_ONLY` mode for both the requests and responses marks all endpoints that are not included in the specification and are returning the code different from `404` as the shadow ones. | No +| `APIFW_MODE` | `mode` | Sets the general API Firewall mode. Possible values are `PROXY` (default), [`graphql`](graphql/docker-container.md) and [`API`](api-mode.md). | No | +| `APIFW_PASS_OPTIONS` | `PassOptionsRequests` | When set to `true`, the API Firewall allows `OPTIONS` requests to endpoints in the specification, even if the `OPTIONS` method is not described. The default value is `false`. | No | +| `APIFW_SHADOW_API_UNKNOWN_PARAMETERS_DETECTION` | ShadowAPI → `UnknownParametersDetection` | This specifies whether requests are identified as non-matching the specification if their parameters do not align with those defined in the OpenAPI specification. The default value is `true`.

If running API Firewall in the [`API` mode](api-mode.md), this variable takes on a different name `APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION`. | No | +| `APIFW_API_SPECS_CUSTOM_HEADER_NAME` | APISpecsCustomHeader → `Name` | Specifies the custom header name to be added to requests for your OpenAPI specification URL (defined in `APIFW_API_SPECS`). For example, you can specify a header name for authentication data required to access the URL. | No | +| `APIFW_API_SPECS_CUSTOM_HEADER_VALUE` | APISpecsCustomHeader → `Value` | Specifies the custom header value to be added to requests for your OpenAPI specification URL. For example, you can specify authentication data for the custom header defined in `APIFW_API_SPECS_CUSTOM_HEADER_NAME` to access the URL. | No | +| `APIFW_SPECIFICATION_UPDATE_PERIOD` | `SpecificationUpdatePeriod` | Specifies the interval for updating the OpenAPI specification from the hosted URL (defined in `APIFW_API_SPECS`). The default value is `0`, which disables updates and uses the initially downloaded specification. The value format is: `5s`, `1h`, etc. | No | +| `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 | + + +??? info "Example of `apifw.yaml`" + --8<-- "include/apifw-yaml-example.md" **With `services.api-firewall.ports` and `services.api-firewall.networks`**, set the API Firewall container port and connect the container to the created network. The provided **docker-compose.yml** instructs Docker to start API Firewall connected to the `api-firewall-network` [network](https://docs.docker.com/network/) on the port 8088. diff --git a/docs/release-notes.md b/docs/release-notes.md index 4f7059c1..f374f33d 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -2,6 +2,12 @@ This page describes new releases of Wallarm API Firewall. +## v0.9.0 (2025-04-01) + +* Added support of the [YAML configuration file](installation-guides/docker-container.md#step-4-configure-api-firewall) +* Added support of the [endpoint-related response actions](configuration-guides/endpoint-related-response.md) +* Replaced the Logrus logging library with ZeroLog + ## v0.8.9 (2025-03-28) * Dependency upgrade diff --git a/mkdocs.yml b/mkdocs.yml index 08241524..0948d83e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,6 +95,7 @@ nav: - Allowlisting IPs: configuration-guides/allowlist.md - SSL/TLS Configuration: configuration-guides/ssl-tls.md - DNS Cache Update: configuration-guides/dns-cache-update.md + - Endpoint-Related Response Actions: configuration-guides/endpoint-related-response.md - System Settings: configuration-guides/system-settings.md - Demos: - Docker Compose: demos/docker-compose.md