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 defined through Rego code and metadata. Users familiar with Rego can define Rego policy code in Custom Snippets. The Custom Snippets can then be used by others to build 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 include library-snippet/{{system-type-name}}. This signifies that the metadata describes a Custom Snippet for a system type.	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/.*
#   - stacks/.*/policy/.*

Custom Snippet Schema Metadata

The schema metadata is used to define the parameters and the decision object of a Custom Snippet.

Custom Snippet Parameters Metadata

Parameters provide inputs to configure the conditions for a Custom Snippet.

# schema:
#   parameters:

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
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 string.	Yes	string

Example:

# schema:
#   parameters:
#     - name: "param1"
#       label: label
#       type: string
#       placeholder: placeholder
#       default: 'aaaaaaaa'

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 number.	Yes	string

Example:

# schema:
#   parameters:
#     - name: "param2"
#       label: label
#       type: number
#       placeholder: "placeholder"
#       default: 888888

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. Defaults to true if undefined.	No	string
type	Must be set_of_strings. Identifies the type of card that should be rendered.	Yes	string

Example:

# schema:
#   parameters:
#     - name: "param3"
#       label: label
#       type: set_of_strings
#       placeholder: placeholder
#       default: ["a", "b", "c"]

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	Path to a data source from data, for example, dataset. This is only applicable if the item is an object. Mutually exclusive with library and package.	No	string
items.library	Path to a policy from data, for example libraries/{{library-name}}/{{policy-name}}. This is only applicable if the item is an object. Mutually exclusive with Data Source and Package.	no	string
items.package	Path to a policy from the System level, for example, rules. This is only applicable if the item is an object. Mutually exclusive with Data Source and Library.	No	string
items.query	Determines the variable to access in the policy. This is only applicable if the item is an object.	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 if undefined.	No	boolean
type	Must be string.	Yes	string

Examples:

# schema:
#   parameters:
#     - name: "param4"
#       label: label
#       type: string
#       items: ["a", "b", "c"]
#       default: "b"

# schema:
#   parameters:
#     - name: month
#       label: Month
#       type: string
#       items:
#         library: libraries/demo/snippets
#         query: months_of_year
#       defaultValue: "Jan"

Set of Strings with Multi-Select

The following table defines Set of Strings with Multi-Select 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	Path to a data source from data, for example, dataset. This is only applicable if the item is an object. Mutually exclusive with library and package.	No	string
items.library	Path to a policy from data, for example libraries/{{library-name}}/{{policy-name}}. This is only applicable if the item is an object. Mutually exclusive with Data Source and Package.	No	string
items.package	Path to a policy from the System level, for example, Rules. This is only applicable if the item is an object. Mutually exclusive with Data Source and Library.	No	string
items.query	Determines the variable to access in the policy. This is only applicable if the item is an object.	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 if undefined.	No	boolean
type	Must be string.	Yes	string

Examples:

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

# schema:
#   parameters:
#     - name: subjects
#       type: set_of_strings
#       placeholder: "Match subjects"
#       required: false
#       items:
#         package: completions
#         query: subjects

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
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 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:

# schema:
#   parameters:
#     - name: "param6"
#       label: label
#       type: object
#       description: description
#       key:
#         placeholder: "key placeholder"
#       value:
#         type: string
#         placeholder: "value placeholder"
#       default:
#         a: "aaa"
#         b: "bbb"

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
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 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:

# schema:
#   parameters:
#     - name: "param7"
#       label: label
#       type: object
#       description: description
#       key:
#         placeholder: "key placeholder"
#       value:
#         type: set_of_strings
#         placeholder: "value placeholder"
#       default:
#         a: ["a", "b"]
#         b: ["c", "d"]

Object with Values as Set of 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
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 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:

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

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:

Decision Type Toggle

The following table defines Decision Type 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:

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

Decision 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:

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

Custom Snippet Policy Metadata

The optional policy metadata object controls how the Custom Snippet is referenced in the generated rule Rego code when added to a policy. The policy metadata object is required if the Custom Snippet's decision metadata object includes a rego type value which references the return value from the Custom Snippet.

The following table defines Custom Snippet Policy metadata keys.

Field Name	Description	Required	Type
policy	Describes the policy of the Custom Snippet.	No	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 1:

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

For a Custom Snippet user_has_attributes defined in a Library example, this will render the Custom Snippet in the generated rego code as:

data.libraries.example.user_has_attributes[violation]

Example 2:

# policy:
#   rule:
#     type: rego
#     value: "entz := {{this}}"

For the same user_has_attributes Custom Snippet, this will render as:

entz := data.libraries.example.user_has_attributes

note

If the policy metadata object is not defined, this is treated the same as:

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

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.