From 2898253516a6035014fc8adfae15209e684f1600 Mon Sep 17 00:00:00 2001 From: Nikolay Tkachenko Date: Mon, 7 Feb 2022 13:21:51 +0700 Subject: [PATCH 1/5] Update conten.md and logo.svg files --- api-firewall/content.md | 134 ++++++++++++++++++++++------------------ api-firewall/logo.svg | 2 +- 2 files changed, 75 insertions(+), 61 deletions(-) diff --git a/api-firewall/content.md b/api-firewall/content.md index 5c031b5f0ae6..fdf1042691e1 100644 --- a/api-firewall/content.md +++ b/api-firewall/content.md @@ -2,81 +2,95 @@ # What is API Firewall? -Light-weighted Wallarm API Firewall protects your API endpoints in cloud-native environments with API schema validation. Wallarm API Firewall relies on a positive security model allowing calls that match a predefined API specification, while rejecting everything else. +Wallarm API Firewall is an open-source light-weighted proxy designed to protect REST API endpoints in cloud-native environments by hardening based on a strict OpenAPI/Swagger schema validation. Wallarm API Firewall relies on a positive security model allowing calls that match a predefined API specification for requests and responses, while rejecting everything else. -## API schema validation and positive security model +The **key features** of API Firewall are: -When starting API Firewall, you should provide the [OpenAPI 3.0 specification](https://swagger.io/specification/) of the application to be protected with API Firewall. The started API Firewall will operate as a reverse proxy and validate whether requests and responses match the schema defined in the specification. - -The traffic that does not match the schema will be logged using the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/) or blocked (depending on the configured API Firewall operation mode). If operating in the logging mode and detecting the traffic on endpoints that are not included in the specification, API Firewall also logs these endpoints as the shadow ones (except for endpoints returning the code `404`). - -Provided API schema should be described using the [OpenAPI 3.0 specification](https://swagger.io/specification/) in the YAML or JSON file (`.yaml`, `.yml`, `.json` file extensions). - -By allowing you to set the traffic requirements with the OpenAPI 3.0 specification, Wallarm API Firewall relies on a positive security model. - -## Technical characteristics - -API Firewall works as a reverse proxy with a built-in OpenAPI 3.0 request and response validator. The validator is written in Go and optimized for extreme performance and near-zero added latency. +* Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema +* Discover Shadow API endpoints +* If using OAuth 2.0 protocol-based authentication, validate access tokens +* Quick and easy deployment and configuration +* Customization of request and response processing modes, response codes and log format -# How to use this image +# Use cases -## Quick start with Docker +* Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode) +* Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode) +* Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode) -This quick start guide walks through downloading and starting Wallarm API Firewall with minimal configuration on Docker. +# API schema validation and positive security model -### Requirements - -- [Installed and configured Docker](https://docs.docker.com/get-docker/) -- [OpenAPI 3.0 specification](https://swagger.io/specification/) developed for the REST API of the application that should be protected with Wallarm API Firewall - -### Up and running - -To run Wallarm API Firewall with minimal configuration on Docker: - -1. Create the Docker network to connect your application and Wallarm API Firewall (e.g. `api-firewall-network`): - - ```bash - docker network create api-firewall-network - ``` +When starting API Firewall, you should provide the [OpenAPI 3.0 specification](https://swagger.io/specification/) of the application to be protected with API Firewall. The started API Firewall will operate as a reverse proxy and validate whether requests and responses match the schema defined in the specification. -2. Start the containerized application to be protected with API Firewall (e.g. [kennethreitz/httpbin](https://hub.docker.com/r/kennethreitz/httpbin/)): +The traffic that does not match the schema will be logged using the [`STDOUT` and `STDERR` Docker services](https://docs.docker.com/config/containers/logging/) or blocked (depending on the configured API Firewall operation mode). If operating in the logging mode and detecting the traffic on endpoints that are not included in the specification, API Firewall also logs these endpoints as the shadow ones (except for endpoints returning the code `404`). - ```bash - docker run --rm -it --network api-firewall-network \ - --network-alias backend -p 8090:8090 kennethreitz/httpbin - ``` +![API Firewall scheme](https://github.com/wallarm/api-firewall/blob/2ace2714ac5777694bde85c8cdbb1308e98a7fea/images/firewall-as-proxy.png?raw=true) -3. Start the API Firewall image: +Provided API schema should be described using the [OpenAPI 3.0 specification](https://swagger.io/specification/) in the YAML or JSON file (`.yaml`, `.yml`, `.json` file extensions). - ```bash - docker run --rm -it --network api-firewall-network --network-alias api-firewall \ - -v : -e APIFW_API_SPECS= \ - -e APIFW_URL= -e APIFW_SERVER_URL= \ - -e APIFW_REQUEST_VALIDATION= -e APIFW_RESPONSE_VALIDATION= \ - -p 8088:8088 %%IMAGE%%:v0.6.5 - ``` +By allowing you to set the traffic requirements with the OpenAPI 3.0 specification, Wallarm API Firewall relies on a positive security model. - | Variables | Description | - |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **For the `-v` option** | | - | `` | 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`. | - | **For the `-e` option** | | - | `APIFW_API_SPECS` | Path to the OpenAPI 3.0 specification mounted to the container. For example: `/api-firewall/resources/swagger.json`. | - | `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. | - | `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`. | - | `APIFW_REQUEST_VALIDATION` | 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.
| - | `APIFW_RESPONSE_VALIDATION` | 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.
| +# Technical characteristics -4. Test API Firewall operation by sending the request that does not match the mounted Open API 3.0 specification to the API Firewall Docker container address. For example, you can pass the string value in the parameter that requires the integer value. +API Firewall works as a reverse proxy with a built-in OpenAPI 3.0 request and response validator. The validator is written in Go and optimized for extreme performance and near-zero added latency. - If the request does not match the provided API schema, the appropriate ERROR message will be added to the API Firewall Docker container logs. +# Starting API Firewall -You have successfully started Wallarm API Firewall with minimal configuration. To learn advanced configuration options, please use the [separate instructions on running Wallarm API Firewall with Docker](https://docs.wallarm.com/api-firewall/installation-guides/docker-container/). +To download, install, and start Wallarm API Firewall on Docker, see the [instructions](https://docs.wallarm.com/api-firewall/installation-guides/docker-container/). -## Demos +# Demos You can try API Firewall by running the demo environment that deploys an example application protected with Wallarm API Firewall. There are two available demo environments: -- [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) -- [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) +* [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) +* [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) + +# Wallarm's blog articles related to API Firewall + +* [Discovering Shadow APIs with API Firewall](https://lab.wallarm.com/discovering-shadow-apis-with-a-api-firewall/) +* [Wallarm API Firewall outperforms NGINX in a production environment](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/) + +# Performance + +When creating API Firewall, we prioritized speed and efficiency to ensure that our customers would have the fastest APIs possible. Our latest tests demonstrate that the average time required for API Firewall to process one request is 1.339 ms: + +``` +$ ab -c 200 -n 10000 -p ./large.json -T application/json http://127.0.0.1:8282/test/signup + +Document Path: /test/signup +Document Length: 20 bytes + +Concurrency Level: 200 +Time taken for tests: 0.769 seconds +Complete requests: 10000 +Failed requests: 0 +Total transferred: 2150000 bytes +Total body sent: 283770000 +HTML transferred: 200000 bytes +Requests per second: 13005.81 [#/sec] (mean) +Time per request: 15.378 [ms] (mean) +Time per request: 0.077 [ms] (mean, across all concurrent requests) +Transfer rate: 2730.71 [Kbytes/sec] received + 360415.95 kb/s sent + 363146.67 kb/s total + +Connection Times (ms) + min mean[+/-sd] median max +Connect: 0 5 1.6 5 12 +Processing: 2 10 5.4 9 59 +Waiting: 2 8 5.2 7 56 +Total: 3 15 5.7 14 68 + +Percentage of the requests served within a certain time (ms) + 50% 14 + 66% 15 + 75% 16 + 80% 17 + 90% 18 + 95% 23 + 98% 36 + 99% 44 + 100% 68 (longest request) +``` + +These performance results are not the only ones we have got during API Firewall testing. Other results along with the methods used to improve API Firewall performance are described in this [Wallarm's blog article](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/). diff --git a/api-firewall/logo.svg b/api-firewall/logo.svg index cadeae5de7be..d0a2e7e1301c 100644 --- a/api-firewall/logo.svg +++ b/api-firewall/logo.svg @@ -1,7 +1,7 @@ + viewBox="0 0 652 652" style="enable-background:new 0 0 652 652;" xml:space="preserve" width="250" height="168"> From 7fded1ca6b90e512ce2a430cefdbab2c2672670b Mon Sep 17 00:00:00 2001 From: Nikolay Tkachenko Date: Mon, 7 Feb 2022 15:42:36 +0700 Subject: [PATCH 2/5] Update content.md --- api-firewall/content.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/api-firewall/content.md b/api-firewall/content.md index fdf1042691e1..495f8e6c287b 100644 --- a/api-firewall/content.md +++ b/api-firewall/content.md @@ -6,17 +6,17 @@ Wallarm API Firewall is an open-source light-weighted proxy designed to protect The **key features** of API Firewall are: -* Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema -* Discover Shadow API endpoints -* If using OAuth 2.0 protocol-based authentication, validate access tokens -* Quick and easy deployment and configuration -* Customization of request and response processing modes, response codes and log format +- Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema +- Discover Shadow API endpoints +- If using OAuth 2.0 protocol-based authentication, validate access tokens +- Quick and easy deployment and configuration +- Customization of request and response processing modes, response codes and log format # Use cases -* Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode) -* Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode) -* Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode) +- Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode) +- Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode) +- Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode) # API schema validation and positive security model @@ -42,13 +42,13 @@ To download, install, and start Wallarm API Firewall on Docker, see the [instruc You can try API Firewall by running the demo environment that deploys an example application protected with Wallarm API Firewall. There are two available demo environments: -* [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) -* [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) +- [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) +- [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) # Wallarm's blog articles related to API Firewall -* [Discovering Shadow APIs with API Firewall](https://lab.wallarm.com/discovering-shadow-apis-with-a-api-firewall/) -* [Wallarm API Firewall outperforms NGINX in a production environment](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/) +- [Discovering Shadow APIs with API Firewall](https://lab.wallarm.com/discovering-shadow-apis-with-a-api-firewall/) +- [Wallarm API Firewall outperforms NGINX in a production environment](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/) # Performance From 458635414bbc13ef4758aa31f7cdec8660baee0b Mon Sep 17 00:00:00 2001 From: Nikolay Tkachenko Date: Mon, 7 Feb 2022 15:50:59 +0700 Subject: [PATCH 3/5] Update content.md --- api-firewall/content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-firewall/content.md b/api-firewall/content.md index 495f8e6c287b..e52cb0ef1586 100644 --- a/api-firewall/content.md +++ b/api-firewall/content.md @@ -54,7 +54,7 @@ You can try API Firewall by running the demo environment that deploys an example When creating API Firewall, we prioritized speed and efficiency to ensure that our customers would have the fastest APIs possible. Our latest tests demonstrate that the average time required for API Firewall to process one request is 1.339 ms: -``` +```console $ ab -c 200 -n 10000 -p ./large.json -T application/json http://127.0.0.1:8282/test/signup Document Path: /test/signup From f5bccc62cee1f904ee8f31fac25483bf4f075d4c Mon Sep 17 00:00:00 2001 From: Nikolay Tkachenko Date: Mon, 7 Feb 2022 15:57:55 +0700 Subject: [PATCH 4/5] Update content.md --- api-firewall/content.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/api-firewall/content.md b/api-firewall/content.md index e52cb0ef1586..0091d4e1595e 100644 --- a/api-firewall/content.md +++ b/api-firewall/content.md @@ -6,17 +6,17 @@ Wallarm API Firewall is an open-source light-weighted proxy designed to protect The **key features** of API Firewall are: -- Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema -- Discover Shadow API endpoints -- If using OAuth 2.0 protocol-based authentication, validate access tokens -- Quick and easy deployment and configuration -- Customization of request and response processing modes, response codes and log format +- Protect REST API endpoints by blocking requests and responses that do not match the OAS/Swagger schema +- Discover Shadow API endpoints +- If using OAuth 2.0 protocol-based authentication, validate access tokens +- Quick and easy deployment and configuration +- Customization of request and response processing modes, response codes and log format # Use cases -- Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode) -- Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode) -- Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode) +- Block abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the blocking mode) +- Discover Shadow APIs and undocumented endpoints (if running API Firewall in the logging mode) +- Log abnormal requests and responses that do not match the OpenAPI 3.0 specification (if running API Firewall in the logging mode) # API schema validation and positive security model @@ -42,13 +42,13 @@ To download, install, and start Wallarm API Firewall on Docker, see the [instruc You can try API Firewall by running the demo environment that deploys an example application protected with Wallarm API Firewall. There are two available demo environments: -- [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) -- [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) +- [Wallarm API Firewall demo with Docker Compose](https://github.com/wallarm/api-firewall/tree/main/demo/docker-compose) +- [Wallarm API Firewall demo with Kubernetes](https://github.com/wallarm/api-firewall/tree/main/demo/kubernetes) # Wallarm's blog articles related to API Firewall -- [Discovering Shadow APIs with API Firewall](https://lab.wallarm.com/discovering-shadow-apis-with-a-api-firewall/) -- [Wallarm API Firewall outperforms NGINX in a production environment](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/) +- [Discovering Shadow APIs with API Firewall](https://lab.wallarm.com/discovering-shadow-apis-with-a-api-firewall/) +- [Wallarm API Firewall outperforms NGINX in a production environment](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/) # Performance @@ -94,3 +94,4 @@ Percentage of the requests served within a certain time (ms) ``` These performance results are not the only ones we have got during API Firewall testing. Other results along with the methods used to improve API Firewall performance are described in this [Wallarm's blog article](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/). + From b022aae54619d9cf6126c291d8b705931ab5f0f6 Mon Sep 17 00:00:00 2001 From: Nikolay Tkachenko Date: Mon, 7 Feb 2022 16:01:50 +0700 Subject: [PATCH 5/5] Update content.md --- api-firewall/content.md | 1 - 1 file changed, 1 deletion(-) diff --git a/api-firewall/content.md b/api-firewall/content.md index 0091d4e1595e..26515e7924f2 100644 --- a/api-firewall/content.md +++ b/api-firewall/content.md @@ -94,4 +94,3 @@ Percentage of the requests served within a certain time (ms) ``` These performance results are not the only ones we have got during API Firewall testing. Other results along with the methods used to improve API Firewall performance are described in this [Wallarm's blog article](https://lab.wallarm.com/wallarm-api-firewall-outperforms-nginx-in-a-production-environment/). -