From 91ae6a1b746151a37ad48d76176f5c255d24dcb5 Mon Sep 17 00:00:00 2001 From: Igor Date: Wed, 21 Aug 2024 11:59:08 +0400 Subject: [PATCH] Doc for API Spec --- CHANGELOG.md | 11 ++ docs/resources/api_spec.md | 42 ++++++ docs/resources/integration_data_dog.md | 108 +++++++++++++++ docs/resources/integration_ms_teams.md | 112 ++++++++++++++++ docs/resources/rule_rate_limit.md | 177 +++++++++++++++++++++++++ docs/resources/trigger.md | 15 +++ examples/wallarm_rule_rate_limit.tf | 28 ++++ go.mod | 2 +- go.sum | 4 +- 9 files changed, 496 insertions(+), 3 deletions(-) create mode 100644 docs/resources/api_spec.md create mode 100644 docs/resources/integration_data_dog.md create mode 100644 docs/resources/integration_ms_teams.md create mode 100644 docs/resources/rule_rate_limit.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d05aad..64915a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +# v1.5.0 (September 1, 2024) + +## NOTES: + +* Added integration with DataDog +* Added integration with Telegram +* Added integration with MS Teams +* Added API Spec resource for managing API specifications +* Added Rate Limit rule +* Added support for all triggers that we have in the UI + # v1.1.0 (May 24, 2023) ## BUG FIXES: diff --git a/docs/resources/api_spec.md b/docs/resources/api_spec.md new file mode 100644 index 0000000..22c730b --- /dev/null +++ b/docs/resources/api_spec.md @@ -0,0 +1,42 @@ +--- +layout: "wallarm" +page_title: "Wallarm: wallarm_api_spec" +subcategory: "API Specification" +description: |- + Provides the resource to manage API Specs[1] in Wallarm. +--- + +# wallarm_api_spec + +Provides the resource to manage API Spec in Wallarm. + +## Example Usage + +```hcl +# Creates an API specification for Wallarm +resource "wallarm_api_spec" "api_spec" { + client_id = 1 + title = "Example API Spec" + description = "This is an example API specification created by Terraform." + file_remote_url = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/api-with-examples.yaml" + regular_file_update = true + api_detection = true + domains = ["ex.com"] + instances = [1] +} +``` + +## Argument Reference + +* `client_id` - (required) ID of the client to apply the API specification to. +* `title` - (required) The title of the API specification. +* `description` - (optional) A description of the API specification. +* `file_remote_url` - (required) The remote URL to the API specification file. This is useful for pulling specifications from external sources. +* `regular_file_update` - (optional) Indicator of whether the API specification file should be regularly updated from the file_remote_url. Can be true or false. Default: false. +* `api_detection` - (optional) Indicator of whether Wallarm should automatically detect APIs based on this specification. +* `domains` - (required) List of domains associated with the API. +* `instances` - (required) List of Wallarm node instances where the API specification should be applied. + +## Attributes Reference +* `api_spec_id` - Integer ID of the created API specification. +[1]: https://docs.wallarm.com/api-specification-enforcement/overview/ diff --git a/docs/resources/integration_data_dog.md b/docs/resources/integration_data_dog.md new file mode 100644 index 0000000..b6e9020 --- /dev/null +++ b/docs/resources/integration_data_dog.md @@ -0,0 +1,108 @@ +--- +layout: "wallarm" +page_title: "Wallarm: wallarm_integration_data_dog" +subcategory: "Integration" +description: |- + Provides the resource to manage DataDog integrations. +--- + +# wallarm_integration_data_dog + +Provides the resource to manage integrations to send [notifications to DataDog][1]. + +The types of events available to be sent to DataDog: +- Detected hits +- System related: newly added users, deleted or disabled integration +- Detected vulnerabilities +- Changes in exposed assets: updates in hosts, services, and domains + +## Example Usage + +```hcl +# Creates an integration to send notifications to DataDog Logic + +resource "wallarm_integration_data_dog" "data_dog_integration" { + name = "New Terraform DataDog Integration" + region = "US1" + token = "eb7ddfc33acaaacaacaca55a398" + + event { + event_type = "hit" + active = true + } + + event { + event_type = "scope" + active = true + } + + event { + event_type = "system" + active = false + } +} + +``` + + +## Argument Reference + +* `client_id` - (optional) ID of the client to apply the integration to. The value is required for [multi-tenant scenarios][2]. +* `active` - (optional) indicator of the integration status. Can be: `true` for active integration and `false` for disabled integration (notifications are not sent). + + Default: `false` +* `name` - (optional) integration name. +* `token` - (required) DataDog token. +* `region` - (required) DataDog region. + +## Event + +`event` are events for integration to monitor. Can be: + +* `event_type` - (optional) event type. Can be: + - `hit` - detected hits + - `vuln_low` - detected vulnerabilities + - `system` - system related + - `scope` - scope changes + + Default: `vuln_low` +* `active` - (optional) indicator of the event type status. Can be: `true` for active events and `false` for disabled events (notifications are not sent). +Default: `true` + + +Example: + +```hcl + # ... omitted + + event { + event_type = "hit" + active = true + } + + event { + event_type = "scope" + active = false + } + + event { + event_type = "system" + active = true + } + + event { + event_type = "vuln" + active = false + } + + # ... omitted +``` + +## Attributes Reference + +* `integration_id` - integer ID of the created integration. +* `created_by` - email of the user who created the integration. +* `is_active` - indicator of the integration status. Can be: `true` and `false`. + +[1]: https://docs.wallarm.com/user-guides/settings/integrations/datadog/ +[2]: https://docs.wallarm.com/installation/multi-tenant/overview/ diff --git a/docs/resources/integration_ms_teams.md b/docs/resources/integration_ms_teams.md new file mode 100644 index 0000000..0aafdb0 --- /dev/null +++ b/docs/resources/integration_ms_teams.md @@ -0,0 +1,112 @@ +--- +layout: "wallarm" +page_title: "Wallarm: wallarm_integration_ms_teams" +subcategory: "Integration" +description: |- + Provides the resource to manage MS Teams integrations. +--- + +# wallarm_integration_ms_teams + +Provides the resource to manage [integrations via MS Teams][1]. + +The types of events available to be sent via MS Teams: +- Detected hits +- System related: newly added users, deleted or disabled integration +- Detected vulnerabilities +- Changes in exposed assets: updates in hosts, services, and domains + +## Example Usage + +```hcl +# Creates an integration to send notifications via +# MS Teams to the provided URL and corresponding HTTP method + +resource "wallarm_integration_ms_teams" "teams_integration" { + name = "New Terraform MS Teams Integration" + webhook_url = "https://gar8347sk.webhook.office.com/webhookb2/a92734837" + active = true + + event { + event_type = "hit" + active = true + } + + event { + event_type = "scope" + active = true + } + + event { + event_type = "system" + active = true + } + + event { + event_type = "vuln" + active = true + } +} +``` + + +## Argument Reference + +* `client_id` - (optional) ID of the client to apply the integration to. The value is required for [multi-tenant scenarios][2]. +* `active` - (optional) indicator of the integration status. Can be: `true` for active integration and `false` for disabled integration (notifications are not sent). + + Default: `false` +* `name` - (optional) integration name. +Default: `POST` +* `webhook_url` - (required) MS Teams URL with the schema (https://). +## Event + +`event` are events for integration to monitor. Can be: + +* `event_type` - (optional) event type. Can be: + - `hit` - detected hits + - `vuln` - detected vulnerabilities + - `system` - system related + - `scope` - scope changes + + Default: `vuln` +* `active` - (optional) indicator of the event type status. Can be: `true` for active events and `false` for disabled events (notifications are not sent). +Default: `true` + + +Example: + +```hcl + # ... omitted + + event { + event_type = "hit" + active = true + } + + event { + event_type = "scope" + active = false + } + + event { + event_type = "system" + active = true + } + + event { + event_type = "vuln" + active = false + } + + # ... omitted +``` + +## Attributes Reference + +* `integration_id` - integer ID of the created integration. +* `created_by` - email of the user who created the integration. +* `is_active` - indicator of the integration status. Can be: `true` and `false`. + +[1]: https://docs.wallarm.com/user-guides/settings/integrations/microsoft-teams/ +[2]: https://docs.wallarm.com/installation/multi-tenant/overview/ diff --git a/docs/resources/rule_rate_limit.md b/docs/resources/rule_rate_limit.md new file mode 100644 index 0000000..5fc06a5 --- /dev/null +++ b/docs/resources/rule_rate_limit.md @@ -0,0 +1,177 @@ +--- +layout: "wallarm" +page_title: "Wallarm: wallarm_rate_limit" +subcategory: "Rule" +description: |- + Provides the "Rate Limit" rule resource. +--- + +# wallarm_rate_limit + +Wallarm provides the Set rate limit rule to help prevent excessive traffic to your API. This rule enables you to specify the maximum number of connections that can be made to a particular scope, while also ensuring that incoming requests are evenly distributed. If a request exceeds the defined limit, Wallarm rejects it and returns the code you selected in the rule. + +**Important:** Rules made with Terraform can't be altered by other rules that usually change how rules work (middleware, variative_values, variative_by_regex). This is because Terraform is designed to keep its configurations stable and not meant to be modified from outside its environment. + +## Example Usage + +```hcl +resource "wallarm_rate_limit" "example" { + comment = "Example rate limit rule" + + action = { + type = "equal" + value = "example_value" + point = { + header = ["X-Example-Header"] + method = "GET" + path = 10 + action_name = "example_action" + action_ext = "example_extension" + query = "example_query" + proto = "HTTP/1.1" + scheme = "https" + uri = "/example_uri" + instance = 1 + } + } + + point = ["example_point_1", "example_point_2"] + + delay = 100 + burst = 200 + rate = 300 + rsp_status = 404 + time_unit = "rps" +} +``` + +## Argument Reference + +* `client_id` - (optional) ID of the client to apply the rules to. The value is required for [multi-tenant scenarios][1]. +* `delay` - (required) Specifies the delay. +* `burst` - (required) Specifies the burst size. +* `rate` - (required) Specifies the rate limit. +* `rsp_status` - (optional) Specifies the response status code when the rate limit is exceeded. +* `time_unit` - (required) Specifies the time unit for rate limiting. Can be rps (requests per second) or rpm (requests per minute). +* `action` - (optional) rule conditions. Possible attributes are described below. + +**action** + +`action` argument shares the available conditions which can be applied. The conditions are: + +* `type` - (optional) condition type. Can be: `equal`, `iequal`, `regex`, `absent`. Must be omitted for the `instance` parameter in `point`. + For more details, see the official [Wallarm documentation](https://docs.wallarm.com/user-guides/rules/add-rule/#condition-types) + Example: + `type = "absent"` +* `value` - (optional) value of the parameter to match with. Must be omitted for the `instance` parameter in `point` or if `type` is `absent`. + Example: + `value = "example.com"` +* `point` - (optional) request parameters that trigger the rule. Possible values are described below. For more details, see the official [Wallarm documentatioon](https://docs.wallarm.com/user-guides/rules/request-processing/#identifying-and-parsing-the-request-parts). + +### Nested Objects + +**point** + + * `header` - (optional) arbitrary HEADER parameter name. + Example: + `header = "HOST"` + * `method` - (optional) request method. Can be: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`. + Example: + `method = "POST"` + * `path` - (optional) array with URL parts separated by the `/` symbol (the last URL part is not included in the array). If there is only one part in the URL, the array will be empty. + Example: + `path = 0` + * `action_name` - (optional) the last part of the URL after the `/` symbol and before the first period (`.`). This part of the URL is always present in the request even if its value is an empty string. + Example: + `action_name = "login"` + * `action_ext` - (optional) the part of the URL after the last period (`.`). It may be missing in the request. + Example: + `action_ext = "php"` + * `query` - (optional) the query parameter name. + Example: + `query = "user"` + * `proto` - (optional) version of the HTTP Protocol. + Example: + `proto = "1.1"` + * `scheme` - (optional) `http`/`https`. + Example: + `scheme = "https"` + * `uri` - (optional) part of the request URL without domain. + Example: + `uri = "/api/login"` + * `instance` - (optional) ID of the application. + Example: + `instance = 42` + +Example: + + ```hcl + # ... omitted + + action { + type = "equal" + point = { + scheme = "https" + } + } + + action { + point = { + instance = 9 + } + } + + action { + type = "absent" + point = { + path = 0 + } + } + + action { + type = "regex" + point = { + action_name = "masking" + } + } + + action { + type = "absent" + point = { + action_ext = "" + } + } + + action { + type = "iequal" + value = "example.com" + point = { + header = "HOST" + } + } + + action { + type = "equal" + value = "admin" + point = { + query = "user" + } + } + + # ... omitted + ``` + +> **_NOTE:_** +See below what limitations apply + +When `type` is `absent`, `point` must contain key with the default value. For `action_name`, `action_ext`, `method`, `proto`, `scheme`, `uri` default value is `""` (empty string). + +## Attributes Reference + +* `rule_id` - ID of the created rule. +* `counter` - Name of the counter. Randomly generated, but always starts with `d:`. +* `action_id` - the action ID (The conditions to apply on request). +* `rule_type` - type of the created rule. For example, `rule_type = "dirbust_counter"`. + + +[1]: https://docs.wallarm.com/installation/multi-tenant/overview/ diff --git a/docs/resources/trigger.md b/docs/resources/trigger.md index 749db83..8937643 100644 --- a/docs/resources/trigger.md +++ b/docs/resources/trigger.md @@ -119,6 +119,12 @@ resource "wallarm_trigger" "attack_trigger" { - `incidents_exceeded` for detected incidents number exceeded the specified value - `vector_attack` for detected malicious payloads number exceeded the specified value - `bruteforce_started` for detected attack to be identified as brute-force + - `bola_search_started` for detected attack identified as BOLA + - `blacklist_ip_added` for IP list added to denylist + - `api_structure_changed` for detected new, changed or unused endpoints + - `attack_ip_grouping` for threshold to group hits from the same IP into one address + - `compromised_logins` for attempts to use compromised user credentials + - `rogue_api_detected` for Shadow, Orphan or Zombie API detected * `enabled` - (optional) indicator of the trigger status. Can be: `true` for enabled trigger and `false` for disabled trigger (notifications are not sent). * `name` - (optional) Trigger name. * `comment` - (optional) Trigger description. @@ -141,6 +147,15 @@ resource "wallarm_trigger" "attack_trigger" { * `Database` * `response_status` - Integer response code returned to the request. * `hint_tag` - Arbitrary tag of any request tuned in by a rule. +* `pii` - Array of fields that are considered sensitive (PII). +* `change_type` - Array of change types for API structure changed trigger. Can be: + * `added` + * `changed` + * `excluded` +* `deviation_type` - Array of Rogue API types for Rogue api detected trigger. Values in the array can be: + * `shadow` + * `orphan` + * `zombie` * `operator` - (optional) Operator to compare the specified filter value and a real value. Can be: * `eq` - Equal * `ne` - Not equal diff --git a/examples/wallarm_rule_rate_limit.tf b/examples/wallarm_rule_rate_limit.tf index e69de29..1514023 100644 --- a/examples/wallarm_rule_rate_limit.tf +++ b/examples/wallarm_rule_rate_limit.tf @@ -0,0 +1,28 @@ +resource "wallarm_rate_limit" "example" { + comment = "Example rate limit rule" + + action = { + type = "equal" + value = "example_value" + point = { + header = ["X-Example-Header"] + method = "GET" + path = 10 + action_name = "example_action" + action_ext = "example_extension" + query = "example_query" + proto = "HTTP/1.1" + scheme = "https" + uri = "/example_uri" + instance = 1 + } + } + + point = ["example_point_1", "example_point_2"] + + delay = 100 + burst = 200 + rate = 300 + rsp_status = 404 + time_unit = "rps" +} \ No newline at end of file diff --git a/go.mod b/go.mod index 2a0ddf7..0d36e9f 100644 --- a/go.mod +++ b/go.mod @@ -7,7 +7,7 @@ require ( github.com/hashicorp/go-cleanhttp v0.5.1 github.com/hashicorp/terraform-plugin-sdk v1.16.0 github.com/pkg/errors v0.9.1 - github.com/wallarm/wallarm-go v0.5.1 + github.com/wallarm/wallarm-go v0.5.2 golang.org/x/net v0.0.0-20210726213435-c6fcb2dbf985 // indirect golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c // indirect golang.org/x/tools v0.1.5 // indirect diff --git a/go.sum b/go.sum index 91cbeea..f9ee644 100644 --- a/go.sum +++ b/go.sum @@ -292,8 +292,8 @@ github.com/ulikunitz/xz v0.5.7/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oW github.com/vmihailenco/msgpack v3.3.3+incompatible/go.mod h1:fy3FlTQTDXWkZ7Bh6AcGMlsjHatGryHQYUTf1ShIgkk= github.com/vmihailenco/msgpack v4.0.1+incompatible h1:RMF1enSPeKTlXrXdOcqjFUElywVZjjC6pqse21bKbEU= github.com/vmihailenco/msgpack v4.0.1+incompatible/go.mod h1:fy3FlTQTDXWkZ7Bh6AcGMlsjHatGryHQYUTf1ShIgkk= -github.com/wallarm/wallarm-go v0.5.1 h1:EGdk7mejmlcEAXd+N7761zpKX6ShYZ98kHRsJufRf1E= -github.com/wallarm/wallarm-go v0.5.1/go.mod h1:KQxO+EBaGpIgOqBoByKW4KNMEJFgkxR64FSiA4U/52I= +github.com/wallarm/wallarm-go v0.5.2 h1:f//OxeLo5kyTRjo+z4C6Zuib8EATwIA7t3eLYk2a5S0= +github.com/wallarm/wallarm-go v0.5.2/go.mod h1:KQxO+EBaGpIgOqBoByKW4KNMEJFgkxR64FSiA4U/52I= github.com/xanzy/ssh-agent v0.2.1 h1:TCbipTQL2JiiCprBWx9frJ2eJlCYT00NmctrHxVAr70= github.com/xanzy/ssh-agent v0.2.1/go.mod h1:mLlQY/MoOhWBj+gOGMQkOeiEvkx+8pJSI+0Bx9h2kr4= github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=