You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* describe the new graphql params
* describe the changed api mode behavior
* fixes to the main guide
* add the changelog on the apif 0.6.14
* update the tags to 0.6.14
* add the command for mkdocs serve to the dockerfile to quickly copy it
* fixes after review
* actualize the list of system varuable for the api mode
* fix the description of db update process
Copy file name to clipboardexpand all lines: docs/configuration-guides/system-settings.md
+5-5
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,10 @@ To fine-tune system API Firewall settings, use the following optional environmen
6
6
| -------------------- | ----------- |
7
7
|`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`. |
8
8
|`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`. |
9
-
|`APIFW_SERVER_MAX_CONNS_PER_HOST`| The maximum number of connections that API Firewall can handle simultaneously. The default value is `512`. |
10
-
|`APIFW_SERVER_READ_TIMEOUT`| 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`. |
11
-
|`APIFW_SERVER_WRITE_TIMEOUT`| The timeout for API Firewall to write the full request (including the body) to the application. The default value is `5s`. |
12
-
|`APIFW_SERVER_DIAL_TIMEOUT`| The timeout for API Firewall to connect to the application. The default value is `200ms`. |
13
-
|`APIFW_SERVER_CLIENT_POOL_CAPACITY`| Maximum number of the fasthttp clients. The default value is `1000`. |
9
+
|`APIFW_SERVER_MAX_CONNS_PER_HOST`<br>(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`. |
10
+
|`APIFW_SERVER_READ_TIMEOUT`<br>(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`. |
11
+
|`APIFW_SERVER_WRITE_TIMEOUT`<br>(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`. |
12
+
|`APIFW_SERVER_DIAL_TIMEOUT`<br>(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`. |
13
+
|`APIFW_SERVER_CLIENT_POOL_CAPACITY`<br>(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`. |
14
14
|`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`. |
Copy file name to clipboardexpand all lines: docs/installation-guides/api-mode.md
+117-14
Original file line number
Diff line number
Diff line change
@@ -5,27 +5,130 @@ If you need to validate individual API requests based on a given OpenAPI specifi
5
5
!!! info "Feature availability"
6
6
This feature is available for the API Firewall versions 0.6.12 and later, and it is tailored for REST API.
7
7
8
-
To do so:
8
+
## Requirements
9
9
10
-
1. Instead of [mounting the OpenAPI specification](../installation-guides/docker-container.md) file to the container, mount the [SQLite database](https://www.sqlite.org/index.html) containing one or more OpenAPI 3.0 specifications to `/var/lib/wallarm-api/1/wallarm_api.db`. The database should adhere to the following schema:
10
+
*[Installed and configured Docker](https://docs.docker.com/get-docker/)
11
+
*[SQLite database](https://www.sqlite.org/index.html) with the `openapi_schemas` table containing one or more [OpenAPI 3.0 specifications](https://swagger.io/specification/). The table should adhere to the following schema:
11
12
12
13
*`schema_id`, integer (auto-increment) - ID of the specification.
13
14
*`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.
14
15
*`schema_format`, string - The specification format, can be `json` or `yaml`.
15
16
*`schema_content`, string - The specification content.
16
-
1. Run the container with the environment variable `APIFW_MODE=API` and if needed, with other variables that specifically designed for this mode:
17
17
18
-
| Environment variable | Description |
19
-
| -------------------- | ----------- |
20
-
|`APIFW_MODE`| Sets the general API Firewall mode. Possible values are [`PROXY`](docker-container.md) (default), [`graphql`](graphql/docker-container.md), and `API`. |
21
-
|`APIFW_SPECIFICATION_UPDATE_PERIOD`| Determines the frequency of specification updates. If set to `0`, the specification update is disabled. The default value is `1m` (1 minute). |
22
-
|`APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION`| Specifies whether to return an error code if the request parameters do not match those defined in the the specification. The default value is `true`. |
23
-
|`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`. |
18
+
## Running the API Firewall container
24
19
25
-
1. When evaluating whether requests align with the mounted specifications, include the header `X-Wallarm-Schema-ID: <schema_id>` to indicate to API Firewall which specification should be used for validation.
20
+
To use the API Firewall for request validation without further proxying, you need to mount the [SQLite database containing OpenAPI 3.0 specifications](#requirements)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.
26
21
27
-
API Firewall validates requests as follows:
22
+
Use the following command to run the API Firewall container:
28
23
29
-
* If a request matches the specification, an empty response with a 200 status code is returned.
30
-
* If a request does not match the specification, the response will provide a 403 status code and a JSON document explaining the reasons for the mismatch.
31
-
* If it is unable to handle or validate a request, an empty response with a 500 status code is returned.
24
+
```
25
+
docker run --rm -it -v <PATH_TO_SQLITE_DATABASE>:/var/lib/wallarm-api/1/wallarm_api.db \
|`APIFW_MODE`| Sets the general API Firewall mode. Possible values are [`PROXY`](docker-container.md) (default), [`graphql`](graphql/docker-container.md), and `API`.<br><br>The appropriate value for this case is `API`. | Yes |
34
+
|`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.<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/`. | No |
35
+
|`APIFW_API_MODE_DEBUG_PATH_DB`| Sets a path to a specification database inside the Docker container.<br><br>The default value is `/var/lib/wallarm-api/1/wallarm_api.db`. | No |
36
+
|`APIFW_SPECIFICATION_UPDATE_PERIOD`| Determines the frequency of fetching updates from the mounted database. If set to `0`, the update is disabled. The default value is `1m` (1 minute). | No |
37
+
|`APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION`| Determines if requests with undefined parameters, as per the specification, are blocked.<br><br>When set to `true`, requests with any non-required, undefined parameters are rejected (e.g., `GET test?a=123&b=123` is blocked if `b` is undefined in the `/test` endpoint specification). If set to `false`, such requests are allowed, provided they contain all required parameters.<br><br>The default vaue is `true`. | No |
38
+
|`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 |
39
+
|`APIFW_READ_TIMEOUT`| The timeout for API Firewall to read the full request (including the body). The default value is `5s`. | No |
40
+
|`APIFW_WRITE_TIMEOUT`| The timeout for API Firewall to return the response to the request. The default value is `5s`. | No |
41
+
|`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 |
42
+
43
+
## Evaluating requests against the specification
44
+
45
+
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:
You can evaluate requests against multiple specifications simultaneously. To do this, include the relevant list of specification IDs in the `X-Wallarm-Schema-ID` header, separated by commas. For instance, to assess a request against specifications with IDs 1 and 2, use the following format:
API Firewall responds with the `200` HTTP code and JSON with details on request validation:
62
+
63
+
=== "Request matches the specification"
64
+
```json
65
+
{
66
+
"summary": [
67
+
{
68
+
"schema_id": 1,
69
+
"status_code": 200
70
+
}
71
+
]
72
+
}
73
+
```
74
+
=== "Request does not match the specification"
75
+
```json
76
+
{
77
+
"summary": [
78
+
{
79
+
"schema_id":1,
80
+
"status_code":403
81
+
}
82
+
],
83
+
"errors": [
84
+
{
85
+
"message":"method and path are not found",
86
+
"code":"method_and_path_not_found",
87
+
"schema_id":1
88
+
}
89
+
]
90
+
}
91
+
```
92
+
=== "Unable to validate a request"
93
+
```json
94
+
{
95
+
"summary": [
96
+
{
97
+
"schema_id": 0,
98
+
"status_code": 500
99
+
}
100
+
]
101
+
}
102
+
```
103
+
104
+
| JSON key | Description |
105
+
| -------- | ----------- |
106
+
|`summary`| Array with a request validation summary. |
107
+
|`summary.schema_id`| The ID of the specification against which the API Firewall performed the request validation. |
108
+
|`summary.status_code`| Request validation status code. Possible values:<ul><li>`200` if a request matches the specification.</li><li>`403` if a request does not match the specification.</li><li>`500` if it is unable to handle or validate a request.</li></ul> |
109
+
|`errors`| Array containing details about the reasons why a request does not match the specification. |
110
+
|`errors.message`| Explanation for the request's dismatch with the specification. |
111
+
|`errors.code`| Code indicating the reason for a request's mismatch with the specification. [Possible values](https://github.com/wallarm/api-firewall/blob/50451e6ae99daf958fa75e592d724c8416a098dd/cmd/api-firewall/internal/handlers/api/errors.go#L14). |
112
+
|`errors.schema_version`| The version of the specification against which the API Firewall performed the request validation. |
113
+
|`errors.related_fields`| An array of parameters that violated the specification. |
114
+
|`errors.related_fields_details`| Details on parameters that violated the specification. |
|`errors.related_fields_details.expected_type`| Expected parameter type (if the type is wrong). |
117
+
|`errors.related_fields_details.current_value`| Parameter value passed in a request. |
118
+
|`errors.related_fields_details.pattern`| Parameter value pattern specified in the specification. |
119
+
120
+
## Database issues
121
+
122
+
### Handling invalidity in an already mounted SQLite database
123
+
124
+
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.
125
+
126
+
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.
127
+
128
+
**Example**
129
+
130
+
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.
131
+
132
+
### Mounting empty SQLite database
133
+
134
+
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.
| <a name="apifw-api-specs"></a>`APIFW_API_SPECS` | 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 |
86
-
| `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.<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** described below. | Yes |
86
+
| `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.<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 |
87
87
| `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 |
88
88
| `APIFW_REQUEST_VALIDATION` | 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.</li></ul> | Yes |
89
89
| `APIFW_RESPONSE_VALIDATION` | 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.</li></ul> | Yes |
@@ -153,6 +153,6 @@ To start API Firewall on Docker, you can also use regular Docker commands as in
Copy file name to clipboardexpand all lines: docs/installation-guides/graphql/docker-container.md
+4-2
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ networks:
29
29
services:
30
30
api-firewall:
31
31
container_name: api-firewall
32
-
image: wallarm/api-firewall:v0.6.13
32
+
image: wallarm/api-firewall:v0.6.14
33
33
restart: on-failure
34
34
volumes:
35
35
- <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>
@@ -96,7 +96,9 @@ Pass API Firewall configuration in **docker-compose.yml** → `services.api-fire
96
96
| `APIFW_GRAPHQL_MAX_QUERY_COMPLEXITY` | [Defines](limit-compliance.md) the maximum number of Node requests that might be needed to execute the query. Setting it to `0` disables the complexity check. The default value is `0`. | Yes |
97
97
| `APIFW_GRAPHQL_MAX_QUERY_DEPTH` | [Specifies](limit-compliance.md) the maximum permitted depth of a GraphQL query. A value of `0` means the query depth check is skipped. | Yes |
98
98
| `APIFW_GRAPHQL_NODE_COUNT_LIMIT` | [Sets](limit-compliance.md) the upper limit for the node count in a query. When set to `0`, the node count limit check is skipped. | Yes |
99
+
| `APIFW_GRAPHQL_MAX_ALIASES_NUM` | Sets a limit on the number of aliases that can be used in a GraphQL document. If this variable is set to `0`, it implies that there is no limit on the number of aliases that can be used. | Yes |
99
100
| <a name="apifw-graphql-introspection"></a>`APIFW_GRAPHQL_INTROSPECTION` | Allows introspection queries, which disclose the layout of your GraphQL schema. When set to `true`, these queries are permitted. | Yes |
101
+
| `APIFW_GRAPHQL_FIELD_DUPLICATION` | Defines whether to allow or prevent the duplication of fields in a GraphQL document. The default value is `false` (prevent). | No |
100
102
| `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 |
101
103
| `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 |
102
104
| `APIFW_LOG_FORMAT` | The format of API Firewall logs. The value can be `TEXT` or `JSON`. The default value is `TEXT`. | No |
@@ -182,6 +184,6 @@ To start API Firewall on Docker, you can also use regular Docker commands as in
Copy file name to clipboardexpand all lines: docs/installation-guides/graphql/limit-compliance.md
+3-1
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,9 @@ When [running](docker-container.md) the API Firewall Docker container for a Grap
8
8
| -------------------- | ----------- |
9
9
|`APIFW_GRAPHQL_MAX_QUERY_COMPLEXITY`| Defines the maximum number of Node requests that might be needed to execute the query. Setting it to `0` disables the complexity check. |
10
10
|`APIFW_GRAPHQL_MAX_QUERY_DEPTH`| Specifies the maximum permitted depth of a GraphQL query. A value of `0` means the query depth check is skipped. |
11
-
|`APIFW_GRAPHQL_NODE_COUNT_LIMIT`| Sets the upper limit for the node count in a query. When set to `0`, the node count limit check is skipped. |
11
+
|`APIFW_GRAPHQL_NODE_COUNT_LIMIT`| Sets the upper limit for the node count in a query. When set to `0`, the node count limit check is skipped. |
12
+
|`APIFW_GRAPHQL_MAX_ALIASES_NUM`| Sets a limit on the number of aliases that can be used in a GraphQL document. If this variable is set to `0`, it implies that there is no limit on the number of aliases that can be used. | Yes |
13
+
|`APIFW_GRAPHQL_FIELD_DUPLICATION`| Defines whether to allow or prevent the duplication of fields in a GraphQL document. The default value is `false` (prevent). |
Copy file name to clipboardexpand all lines: docs/release-notes.md
+5
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,11 @@
2
2
3
3
This page describes new releases of Wallarm API Firewall.
4
4
5
+
## v0.6.14 (2023-11-23)
6
+
7
+
* Introduced new environment variables to limit GraphQL queries: `APIFW_GRAPHQL_MAX_ALIASES_NUM` and `APIFW_GRAPHQL_FIELD_DUPLICATION`.
8
+
* Implemented more [detailed responses](installation-guides/api-mode.md#understanding-api-firewall-responses) for requests that do not match mounted specifications in the **API non-proxy mode**.
9
+
5
10
## v0.6.13 (2023-09-08)
6
11
7
12
*[Support for GraphQL API requests validation](installation-guides/graphql/docker-container.md)
0 commit comments