Custom Snippet Overview

A Custom Snippet is a visual rendering of the parameters and values needed to configure a policy condition. Custom Snippets provide a user-friendly visual representation of the requirements of conditions to understand the policy conditions' intent quickly.

Custom Snippets are supported for the following Styra Systems:

• Custom
• Entitlements
• Kubernetes
• Terraform

Custom Snippets are defined through Rego code and metadata.

Policy as code is written in Rego. Typically users familiar with Rego will define the Rego code and create Custom Snippets. The Custom Snippets are then used to establish and monitor Policies.

The Styra DAS UI uses Custom Snippet metadata to construct a visual representation of Rego code dynamically. The visual representation helps users who are not familiar with Rego code to understand the intent of the Rego policy. You control certain aspects of this dynamically constructed visual representation with your Custom Snippet’s associated metadata.

When the user instantiates snippet in the Styra DAS UI, whether it is a Custom Snippet or a Styra-provided snippet, a small shim of Rego code is dynamically generated. This shim includes the parameters entered by the user on the Custom Snippet’s card in the Styra DAS UI (if any), as well as an invocation of the requested Custom Snippet. The only difference between Custom Snippets and Styra-provided snippets is the library path with which the generated shim invokes the snippet.

Custom Snippet Metadata

Metadata is used by the Styra DAS UI to dynamically construct a visual representation of Rego code so developers unfamiliar with Rego can understand the intent of the Rego policy. You control certain aspects of the dynamically constructed visual representation with the snippets associated metadata.

The following table defines the fields associated with Custom Snippet metadata.

Field Name	Description	Required	Type
METADATA	Must be “library-snippet/{{system-type-name}}”. This signifies that the metadata describes a Custom Snippet.Everything organizations need to externalize authorization and use OPA at scale.	Yes	string
version	This is the version of the Custom Snippet	No	string
title	The title of the Custom Snippet. Displayed on the card and in the add rule menu.	Yes	string
description	The description of the Custom Snippet. This is displayed on the card and in the add rule menu.	Yes	string
filePath	Matches the value against the policy path to determine if the policy should have the option of adding the Custom Snippet. If the value within Rego files in Styra DAS does not match at least one regex in this field, the Custom Snippet will not appear in the “add rule” menu. If this field is empty, the Custom Snippet will appear in the “add rule” menu for all Rego files associated with a System of the Custom Snippet’s configured type. Example policy path: systems/{{systemId}}/{{filePath}}”	No	Array of strings

Example:

# METADATA: library-snippet/entitlements
# version: v1
# title: "Title for the custom snippet"
# description: >-
#   description for the custom snippet
# filePath: 
#   - systems/.*/policy/.*

Set of Strings

The following table defines Set of Strings metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	array of strings
label	Adds a label to the parameter on the card.	No	string
name	Must not match any other parameters name and controls the name of the key in the parameters object. The value must be unique across all parameters.	Yes	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label.	No	string
type	Must be a “set_of_strings”. Identifies the type of card that should be rendered.	Yes	string

Example:

#   - name: "param1"
#     label: label
#     type: set_of_strings
#     placeholder: placeholder
#     defaultValue: ["a", "b", "c"]

Object with Values as Set of Strings

The following table defines Object with Values as Set of Strings metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	object with values as array of strings
description	Adds a description next to each key-value pair on the card.	No	string
key	Metadata describing the key input field.	No	object
key.placeholder	Text that appears in the input field when empty.	No	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label.	No	boolean
type	Must be an “object”.	Yes	string
value	Metadata describing the value input field.	Yes	object
value.type	Must be “set_of_strings”.	Yes	string
value.placeholder	Text that appears in the input field when empty.	No	string

Example:

#   - name: "param2"
#     label: label
#     type: object
#     description: description
#     key:
#       placeholder: "key placeholder"
#     value:
#       type: set_of_strings
#       placeholder: "value placeholder"
#     defaultValue:
#       a: ["a", "b"]
#       b: ["c", "d"]

String

The following table defines the String metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label.	No	boolean
type	Must be an “string”.	Yes	string

Example:

#   - name: "param3"
#     label: label
#     type: string
#     placeholder: placeholder
#     default: 'aaaaaaaa'

String Select

The following table defines String Select metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	string
items	Determines the items that should be shown in the drop-down.	Yes	array of strings or object
items.datasource	Only applicable if the item is an object. Path to a policy from data, for example, dataset. Mutually exclusive with library and package.	No	string
items.library	This is only applicable if the item is an object. Path to a policy from data, for example global/{{library-name}}/{{policy-name}}. Mutually exclusive with Data Source and Package.	no	string
items.package	This is only applicable if an item is an Object. Path to a policy from the System level, for example, Rules. Mutually exclusive with Data Source and Library.	No	string
items.query	This is only applicable if an item is an object. Determines the variable to access in the policy.	Yes	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
name	Must not match any other parameters name and controls the name of the key in the parameters object. The value must be unique across all parameters.	Yes	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label. Defaults to true.	No	boolean
type	Must be a “string”.	Yes	string

Example:

#   - name: "param4"
#     label: label
#     type: string
#     items: ["a", "b", "c"]
#     defaultValue: 'bbbbbb'

Set of Strings with Suggestions

The following table defines Set of Strings with Suggestions metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	array of strings
items	Determines the items that should be shown in the drop-down.	yes	array of strings or object
items.datasource	Only applicable if the item is an object. Path to a policy from data, for example, dataset. Mutually exclusive with library and package.	No	string
items.library	This is only applicable if the item is an object. Path to a policy from data, for example global/{{library-name}}/{{policy-name}}. Mutually exclusive with Data Source and Package.	No	string
items.package	This is only applicable if an item is an Object. Path to a policy from the System level, for example, Rules. Mutually exclusive with Data Source and Library.	No	string
items.query	This is only applicable if an item is an Object. Determines the variable to access in the policy.	Yes	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
name	Must not match any other parameters name and controls the name of the key in the parameters object. The value must be unique across all parameters.	Yes	string
placeholder	Text that appears in the input field when empty.	No	string
type	Must be a “string”.	Yes	string

Example:

#   - name: "param5"
#     label: label
#     type: set_of_strings
#     placeholder: placeholder
#     items: ["a", "b"]
#     defaultValue: ["c", "d"]

Number

The following table defines Number metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	number
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
name	Must not match any other parameters name and controls the name of the key in the parameters object. The value must be unique across all parameters.	Yes	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label. Defaults to true if undefined.	No	boolean
type	Must be an “number”.	Yes	string

Example:

#   - name: "param6"
#     label: label
#     type: number
#     placeholder: "placeholder"
#     defaultValue: 888888

Object with Values as Strings

The following table defines Object with Values as Strings metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	object with values as strings
description	Adds a description next to each key-value pair on the card.	No	String
key	Metadata describing the key input field.	No	object
key.placeholder	Text that appears in the input field when empty.	No	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label. Defaults to true if undefined.	No	boolean
type	Must be an “object”.	Yes	string
value	Metadata describing the value input field.	Yes	object
value.type	Must be “string”.	Yes	string
value.placeholder	Text that appears in the input field when empty.	No	string

Example:

#   - name: "param7"
#     label: label
#     type: object
#     description: description
#     key:
#       placeholder: "key placeholder"
#     value:
#       type: string
#       placeholder: "value placeholder"
#     defaultValue:
#       a: "aaa"
#       b: "bbb"

Object with Values as Numbers

The following table defines Object with Values as Numbers metadata keys.

Field Name	Description	Required	Type
default	Initializes the parameter with the default value.	No	object with values as arrays of strings
description	Adds a description next to each key-value pair on the card.	No	String
key	Metadata describing the key input field.	No	object
key.placeholder	Text that appears in the input field when empty.	No	string
label	Adds a label to the parameter on the card. Defaults to the value of the name field if omitted.	No	string
placeholder	Text that appears in the input field when empty.	No	string
required	If marked as false, adds (optional) next to the label. Defaults to true if undefined.	No	boolean
type	Must be an “object”.	Yes	string
value	Metadata describing the value input field.	Yes	object
value.type	Must be “set_of_numbers”.	Yes	string
value.placeholder	Text that appears in the input field when empty.	No	string

Example:

#   - name: "param8"
#     label: label
#     type: object
#     description: description
#     key:
#       placeholder: "key placeholder"
#     value:
#       type: set_of_numbers
#       placeholder: "value placeholder"
#     defaultValue:
#       a: [1, 2, 3]
#       b: [4, 5, 6]

Custom Snippet Policy Metadata

The following table defines Custom Snippet Policy metadata keys.

Field Name	Description	Required	Type
policy	Describes the policy of the Custom Snippet.	Yes	object
policy.rule	Describes the rule of the Custom Snippet.	Yes	object
policy.rule.type	Only “rego” is supported.	Yes	string
policy.rule.value	“{{this}}” is the path that references the rule the metadata is attached to.	Yes	string

Example:

# policy:
#   rule:
#     type: rego
#     value: "{{this}}[obj]"

Custom Snippet Decision Metadata

The following table defines how the decision object in the rule should be defined.

Field Name	Description	Required	Type
schema	Describes the schema of the Custom Snippet.	Yes	object
schema.decision	Describes the schema of the decision object.	Yes	array of objects

Example:

# schema:
#   decision:
#   - type: rego
#     key: entz
#     value: "set()"

Decision Types Toggle

The following table defines Decision Types Toggle metadata keys.

Field Name	Description	Required	Type
type	Must be “toggle”.	Yes	string
label	Adds a label for the toggle buttons. Defaults to “Permission”.	No	string
toggles	This describes the toggle buttons on the card.	Yes	Array of objects
toggles: [toggle.key]	Decision object’s key when the toggle is selected.	Yes	String
toggles: [toggle.value]	Decision object’s value when the toggle is selected.	Yes	boolean
toggles: [toggle.label]	Text of the toggle button. Defaults to the key value.	No	string

Example:

#   - type: toggle
#     label: Permission
#     toggles:
#     - key: allowed
#       value: true
#       label: Allow
#     - key: denied
#       value: true
#       label: Deny

Rego

The following table defines Rego metadata keys.

Field Name	Description	Required	Type
type	Must be “rego”.	Yes	string
key	Decision object’s key.	Yes	string
value	Decision object’s value. Generated without quotes. If you want a string value, switch to type “string”.	Yes	string

Example:

#   - type: rego
#     key: entz
#     value: "set()"

Custom Snippet Examples

Examples of Custom Snippets are located in Styra DAS Custom Snippet Samples.

Custom Snippet Metadata Validator

The Custom Snippet Metadata Validator validates if the Custom Snippets metadata is properly structured in a development environment before committing changes to your production environment.

See Styra DAS Custom Snippet Metadata Validator for additional information.