From 81c8a00ab0e0565b9b20ac51270ebffdfd399661 Mon Sep 17 00:00:00 2001 From: Deepak Gupta Date: Mon, 30 Dec 2024 15:14:10 -0500 Subject: [PATCH] add documentation for available wizards --- docs/guides/repo_level_policy.md | 4 +- docs/resources/policy_set.md | 121 ++++++++++++++++++ docs/resources/rego_policy_instance.md | 7 +- .../repo_level_policies/data_firewall.tf | 2 +- .../repo_level_policies/user_segmentation.tf | 2 +- templates/resources/policy_set.md.tmpl | 118 +++++++++++++++++ .../resources/rego_policy_instance.md.tmpl | 7 +- 7 files changed, 251 insertions(+), 10 deletions(-) diff --git a/docs/guides/repo_level_policy.md b/docs/guides/repo_level_policy.md index 47b5662c..472c559b 100644 --- a/docs/guides/repo_level_policy.md +++ b/docs/guides/repo_level_policy.md @@ -38,7 +38,7 @@ resource "cyral_policy_set" "data_firewall_policy" { wizard_id = "data-firewall" parameters = jsonencode( { - "dataSet" = "finance.cards" + "dataset" = "finance.cards" "dataFilter" = " finance.cards.country = 'US' " "labels" = ["CCN"] "excludedIdentities" = { "groups" = ["Admin"] } @@ -302,7 +302,7 @@ resource "cyral_policy_set" "user_segmentation_policy" { wizard_id = "user-segmentation" parameters = jsonencode( { - "dataSet" = "finance.cards" + "dataset" = "finance.cards" "dataFilter" = " finance.cards.country = 'US' " "labels" = ["CCN"] "includedIdentities" = { "groups" = ["Marketing"] } diff --git a/docs/resources/policy_set.md b/docs/resources/policy_set.md index 26c8e2e4..da6706d7 100644 --- a/docs/resources/policy_set.md +++ b/docs/resources/policy_set.md @@ -38,6 +38,127 @@ resource "cyral_policy_set" "repo_lockdown_example" { } ``` +## Available Policy Wizards + +The following policy wizards are available for creating policy sets. The wizard parameters, +specified as a JSON object, are described below for each wizard as well. + +-> You can also use the Cyral API `GET` `/v1/regopolicies/templates` to retrieve all existing templates and their corresponding parameters schema. + +### Data Firewall (data-firewall) - Ensure that sensitive data can only be read by specified individuals. + +- `dataset` (String) Data Set (table, collection, etc.) to which the policy applies. +- `dataFilter` (String) Data filter that will be applied when anyone tries to read the specified data labels from the data set. +- `substitutionQuery` (String) A query that will be used to replace all occurrences of the dataset in the original query. Only one of `dataFilter` and `substitutionQuery` can be specified. +- `excludedIdentities` (Object) Identities that will be excluded from this policy. See [identityList](#objects--identityList). + +### Data Masking (data-masking) - Mask fields for specific users and applications. + +- `maskType` (String) Mask Type (E.g.: `null`, `constant`, `format-preserving`). +- `maskArguments` (Array) Mask Argument associated to the given Mask Type (E.g.: Replacement Value). +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will apply to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will apply to any database account. See [dbAccounts](#objects--dbAccounts). + +### Data Protection (data-protection) - Guard against reads and writes of specified tables or fields. + +- `block` (Boolean) Policy action to block. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `read`, `update`, `delete`, and `insert`. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Object Protection (object-protection) - Guards against operations like create, drop, and alter for specified object types. + +- `objectType` (String) The type of object to monitor or protect. The only value currently supported is `role/user`. +- `block` (Boolean) Indicates whether unauthorized operations should be blocked. If true, operations violating the policy are prevented. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `create`, `drop`, and `alter`. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### Rate Limit (rate-limit) - Implement threshold on sensitive data reads over a period of time. + +- `rateLimit` (Integer) Maximum number of rows that can be returned per hour. Note: the value must be an integer greater than zero. +- `enforce` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Read Limit (read-limit) - Prevent certain data from being read beyond a specified limit. + +- `rowLimit` (Integer) Maximum number of rows that can be read per query. Note: the value must be an integer greater than zero. +- `enforce` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Repository Lockdown (repo-lockdown) - Deny all statements that are not allowed by some policy and/or not understood by Cyral. + +- `failClosed` (Boolean) Whether to fail closed, if true, all statements that are not understood by Cyral will be blocked. +- `denyByDefault` (Boolean) Whether to deny all statements by default, if true, all statements that are not explicitly allowed by some policy will be blocked. + +### Repository Protection (repository-protection) - Alert when more than a specified number of records are updated, deleted, or inserted in specified datasets. + +- `rowLimit` (Integer) Maximum number of rows that can be modified per query. Note: the value must be an integer greater than zero. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `update`, `delete` and `insert`. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Schema Protection (schema-protection) - Protect database schema against unauthorized creation, deletion, or modification of tables and views. + +- `block` (Boolean) Whether to block unauthorized schema changes. +- `schemas` (Array) Schemas to which the policy applies. +- `excludedIdentities` (Object) Identities that are exempt from the policy. See [identities](#objects--identityList). + +### Service Account Abuse (service-account-abuse) - Ensure service accounts can only be used by intended applications. + +- `block` (Boolean) Policy action to enforce. +- `serviceAccounts` (Array) Service accounts for which end user attribution is always required. +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### Stored Procedure Governance (stored-procedure-governance) - Restrict execution of stored procedures.. + +- `enforced` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `governedProcedures` (Array) Stored procedures to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### User Segmentation (user-segmentation) - Restrict specific users to a subset of data. + +- `dataset` (String) Data Set (table, collection, etc.) to which the policy applies. +- `dataFilter` (String) Data filter that will be applied when anyone tries to read the specified data labels from the data set. +- `substitutionQuery` (String) A query that will be used to replace all occurrences of the dataset in the original query. Only one of `dataFilter` and `substitutionQuery` can be specified. +- `includedIdentities` (Object) Identities that cannot see restricted records. See [identityList](#objects--identityList). +- `includedDbAccounts` (Array) Database accounts cannot see restricted records. + + + +### Objects + + + +- `identities` (Object) Identities. See properties below: + - `included` (Object) Included Identities. See [identityList](#objects--identityList). + - `excluded` (Object) Excluded Identities. See [identityList](#objects--identityList). + +- `dbAccounts` (Object) Database Accounts. See properties below: + - `included` (Array) Included Database Accounts. + - `excluded` (Array) Excluded Database Accounts. + +- `identityList` (Object) Identity List. See properties below: + - `userNames` (Array) Identity Emails. + - `emails` (Array) Identity Usernames. + - `groups` (Array) Identity Groups. + ## Schema diff --git a/docs/resources/rego_policy_instance.md b/docs/resources/rego_policy_instance.md index 1887bc77..b62367b7 100644 --- a/docs/resources/rego_policy_instance.md +++ b/docs/resources/rego_policy_instance.md @@ -113,9 +113,10 @@ All templates use parameters defined as JSON, below is a list of all the corresp ### Deprecated policy templates -The remaining list of policy templates are deprecated and can not be used for creating new policies. -Manage existing policy instances is still supported. -Please visit [`cyral_policy_set`](https://registry.terraform.io/providers/cyralinc/cyral/latest/docs/resources/policy_set) resource to find replacements for the deprecated policy templates. +The remaining list of policy templates have been deprecated in v4.18.X of the Cyral Control Plane +and can not be used for creating new policies. Managing existing policy instances is still supported. +Please visit [`cyral_policy_set`](https://registry.terraform.io/providers/cyralinc/cyral/latest/docs/resources/policy_set) +resource to find replacements for the deprecated policy templates. #### Data Firewall (data-firewall) diff --git a/examples/guides/repo_level_policies/data_firewall.tf b/examples/guides/repo_level_policies/data_firewall.tf index 1b94a2cf..73bcbf31 100644 --- a/examples/guides/repo_level_policies/data_firewall.tf +++ b/examples/guides/repo_level_policies/data_firewall.tf @@ -18,7 +18,7 @@ resource "cyral_policy_set" "data_firewall_policy" { wizard_id = "data-firewall" parameters = jsonencode( { - "dataSet" = "finance.cards" + "dataset" = "finance.cards" "dataFilter" = " finance.cards.country = 'US' " "labels" = ["CCN"] "excludedIdentities" = { "groups" = ["Admin"] } diff --git a/examples/guides/repo_level_policies/user_segmentation.tf b/examples/guides/repo_level_policies/user_segmentation.tf index f2708b5a..e3adb4b3 100644 --- a/examples/guides/repo_level_policies/user_segmentation.tf +++ b/examples/guides/repo_level_policies/user_segmentation.tf @@ -18,7 +18,7 @@ resource "cyral_policy_set" "user_segmentation_policy" { wizard_id = "user-segmentation" parameters = jsonencode( { - "dataSet" = "finance.cards" + "dataset" = "finance.cards" "dataFilter" = " finance.cards.country = 'US' " "labels" = ["CCN"] "includedIdentities" = { "groups" = ["Marketing"] } diff --git a/templates/resources/policy_set.md.tmpl b/templates/resources/policy_set.md.tmpl index f1fe8d09..2965ab72 100644 --- a/templates/resources/policy_set.md.tmpl +++ b/templates/resources/policy_set.md.tmpl @@ -8,4 +8,122 @@ {{ tffile "examples/resources/cyral_policy_set/resource.tf" }} +## Available Policy Wizards + +The following policy wizards are available for creating policy sets. The wizard parameters, +specified as a JSON object, are described below for each wizard as well. + +-> You can also use the Cyral API `GET` `/v1/regopolicies/templates` to retrieve all existing templates and their corresponding parameters schema. + +### Data Firewall (data-firewall) - Ensure that sensitive data can only be read by specified individuals. + +- `dataset` (String) Data Set (table, collection, etc.) to which the policy applies. +- `dataFilter` (String) Data filter that will be applied when anyone tries to read the specified data labels from the data set. +- `substitutionQuery` (String) A query that will be used to replace all occurrences of the dataset in the original query. Only one of `dataFilter` and `substitutionQuery` can be specified. +- `excludedIdentities` (Object) Identities that will be excluded from this policy. See [identityList](#objects--identityList). + +### Data Masking (data-masking) - Mask fields for specific users and applications. + +- `maskType` (String) Mask Type (E.g.: `null`, `constant`, `format-preserving`). +- `maskArguments` (Array) Mask Argument associated to the given Mask Type (E.g.: Replacement Value). +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will apply to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will apply to any database account. See [dbAccounts](#objects--dbAccounts). + +### Data Protection (data-protection) - Guard against reads and writes of specified tables or fields. + +- `block` (Boolean) Policy action to block. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `read`, `update`, `delete`, and `insert`. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Object Protection (object-protection) - Guards against operations like create, drop, and alter for specified object types. + +- `objectType` (String) The type of object to monitor or protect. The only value currently supported is `role/user`. +- `block` (Boolean) Indicates whether unauthorized operations should be blocked. If true, operations violating the policy are prevented. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `create`, `drop`, and `alter`. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### Rate Limit (rate-limit) - Implement threshold on sensitive data reads over a period of time. + +- `rateLimit` (Integer) Maximum number of rows that can be returned per hour. Note: the value must be an integer greater than zero. +- `enforce` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Read Limit (read-limit) - Prevent certain data from being read beyond a specified limit. + +- `rowLimit` (Integer) Maximum number of rows that can be read per query. Note: the value must be an integer greater than zero. +- `enforce` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `tags` (Array) Data Tags to which the policy applies. +- `labels` (Array) Data Labels to which the policy applies. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Repository Lockdown (repo-lockdown) - Deny all statements that are not allowed by some policy and/or not understood by Cyral. + +- `failClosed` (Boolean) Whether to fail closed, if true, all statements that are not understood by Cyral will be blocked. +- `denyByDefault` (Boolean) Whether to deny all statements by default, if true, all statements that are not explicitly allowed by some policy will be blocked. + +### Repository Protection (repository-protection) - Alert when more than a specified number of records are updated, deleted, or inserted in specified datasets. + +- `rowLimit` (Integer) Maximum number of rows that can be modified per query. Note: the value must be an integer greater than zero. +- `governedOperations` (Array) Operations governed by this policy, can be one or more of: `update`, `delete` and `insert`. +- `datasets` (Array) Data Sets (tables, collections, etc.) to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). + +### Schema Protection (schema-protection) - Protect database schema against unauthorized creation, deletion, or modification of tables and views. + +- `block` (Boolean) Whether to block unauthorized schema changes. +- `schemas` (Array) Schemas to which the policy applies. +- `excludedIdentities` (Object) Identities that are exempt from the policy. See [identities](#objects--identityList). + +### Service Account Abuse (service-account-abuse) - Ensure service accounts can only be used by intended applications. + +- `block` (Boolean) Policy action to enforce. +- `serviceAccounts` (Array) Service accounts for which end user attribution is always required. +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### Stored Procedure Governance (stored-procedure-governance) - Restrict execution of stored procedures.. + +- `enforced` (Boolean) Whether to enforce the policy, if false, only alerts will be raised on policy violations. +- `governedProcedures` (Array) Stored procedures to which the policy applies. +- `identities` (Object) Identities to which the policy applies. If empty, the policy will be applied to all identities. See [identities](#objects--identities). +- `dbAccounts` (Object) Database Accounts to which the policy applies. If empty, the policy will be applied to any database account. See [dbAccounts](#objects--dbAccounts). +- `alertSeverity` (String) Alert severity. Allowed values are: `low`, `medium`, `high`. + +### User Segmentation (user-segmentation) - Restrict specific users to a subset of data. + +- `dataset` (String) Data Set (table, collection, etc.) to which the policy applies. +- `dataFilter` (String) Data filter that will be applied when anyone tries to read the specified data labels from the data set. +- `substitutionQuery` (String) A query that will be used to replace all occurrences of the dataset in the original query. Only one of `dataFilter` and `substitutionQuery` can be specified. +- `includedIdentities` (Object) Identities that cannot see restricted records. See [identityList](#objects--identityList). +- `includedDbAccounts` (Array) Database accounts cannot see restricted records. + + +### Objects + +- `identities` (Object) Identities. See properties below: + - `included` (Object) Included Identities. See [identityList](#objects--identityList). + - `excluded` (Object) Excluded Identities. See [identityList](#objects--identityList). + +- `dbAccounts` (Object) Database Accounts. See properties below: + - `included` (Array) Included Database Accounts. + - `excluded` (Array) Excluded Database Accounts. + +- `identityList` (Object) Identity List. See properties below: + - `userNames` (Array) Identity Emails. + - `emails` (Array) Identity Usernames. + - `groups` (Array) Identity Groups. + {{ .SchemaMarkdown | trimspace }} diff --git a/templates/resources/rego_policy_instance.md.tmpl b/templates/resources/rego_policy_instance.md.tmpl index 49fedb2a..0edb23c7 100644 --- a/templates/resources/rego_policy_instance.md.tmpl +++ b/templates/resources/rego_policy_instance.md.tmpl @@ -53,9 +53,10 @@ All templates use parameters defined as JSON, below is a list of all the corresp - `alertSeverity` (String) Policy action to alert, using the respective severity. Allowed values are: `low`, `medium`, `high`. ### Deprecated policy templates -The remaining list of policy templates are deprecated and can not be used for creating new policies. -Manage existing policy instances is still supported. -Please visit [`cyral_policy_set`](https://registry.terraform.io/providers/cyralinc/cyral/latest/docs/resources/policy_set) resource to find replacements for the deprecated policy templates. +The remaining list of policy templates have been deprecated in v4.18.X of the Cyral Control Plane +and can not be used for creating new policies. Managing existing policy instances is still supported. +Please visit [`cyral_policy_set`](https://registry.terraform.io/providers/cyralinc/cyral/latest/docs/resources/policy_set) +resource to find replacements for the deprecated policy templates. #### Data Firewall (data-firewall)