Skip to main content

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 quickly understand the policy conditions' intent.

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 dynamically construct a visual representation of Rego code. 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 NameDescriptionRequiredType
METADATAMust 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.Yesstring
versionThis is the version of the Custom SnippetNostring
titleThe title of the Custom Snippet. Displayed on the card and in the add rule menu.Yesstring
descriptionThe description of the Custom Snippet. This is displayed on the card and in the add rule menu.Yesstring
filePathMatches the value against the policy path to determine if the policy should have the option of adding the Custom Snippet. Example policy path: systems/{{systemId}}/{{filePath}}”NoRegex or string
parametersDescribes the parameter object of the Custom Snippet.NoArray of objects

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Noarray of strings
labelAdds a label to the parameter on the card.Nostring
nameMust 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.Yesstring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label.Nostring
typeMust be a “set_of_strings”. Identifies the type of card that should be rendered.Yesstring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Noobject with values as array of strings
descriptionAdds a description next to each key-value pair on the card.Nostring
keyMetadata describing the key input field.Noobject
key.placeholderText that appears in the input field when empty.Nostring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label.Noboolean
typeMust be an “object”.Yesstring
valueMetadata describing the value input field.Yesobject
value.typeMust be “set_of_strings”.Yesstring
value.placeholderText that appears in the input field when empty.Nostring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Nostring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label.Noboolean
typeMust be an “string”.Yesstring

Example:

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

String Select

The following table defines String Select metadata keys.

Field NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Nostring
itemsDetermines the items that should be shown in the drop-down.Yesarray of strings or object
items.datasourceOnly applicable if the item is an object. Path to a policy from data, for example, dataset. Mutually exclusive with library and package.Nostring
items.libraryThis 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.nostring
items.packageThis 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.Nostring
items.queryThis is only applicable if an item is an object. Determines the variable to access in the policy.Yesstring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
nameMust 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.Yesstring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label. Defaults to true.Noboolean
typeMust be a “string”.Yesstring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Noarray of strings
itemsDetermines the items that should be shown in the drop-down.yesarray of strings or object
items.datasourceOnly applicable if the item is an object. Path to a policy from data, for example, dataset. Mutually exclusive with library and package.Nostring
items.libraryThis 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.Nostring
items.packageThis 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.Nostring
items.queryThis is only applicable if an item is an Object. Determines the variable to access in the policy.Yesstring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
nameMust 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.Yesstring
placeholderText that appears in the input field when empty.Nostring
typeMust be a “string”.Yesstring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Nonumber
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
nameMust 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.Yesstring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label. Defaults to true if undefined.Noboolean
typeMust be an “number”.Yesstring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Noobject with values as arrays of strings
descriptionAdds a description next to each key-value pair on the card.NoString
keyMetadata describing the key input field.Noobject
key.placeholderText that appears in the input field when empty.Nostring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label. Defaults to true if undefined.Noboolean
typeMust be an “object”.Yesstring
valueMetadata describing the value input field.Yesobject
value.typeMust be “string”.Yesstring
value.placeholderText that appears in the input field when empty.Nostring

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 NameDescriptionRequiredType
defaultInitializes the parameter with the default value.Noobject with values as arrays of strings
descriptionAdds a description next to each key-value pair on the card.NoString
keyMetadata describing the key input field.Noobject
key.placeholderText that appears in the input field when empty.Nostring
labelAdds a label to the parameter on the card. Defaults to the value of the name field if omitted.Nostring
placeholderText that appears in the input field when empty.Nostring
requiredIf marked as false, adds (optional) next to the label. Defaults to true if undefined.Noboolean
typeMust be an “object”.Yesstring
valueMetadata describing the value input field.Yesobject
value.typeMust be “set_of_numbers”.Yesstring
value.placeholderText that appears in the input field when empty.Nostring

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 NameDescriptionRequiredType
policyDescribes the policy of the Custom Snippet.Yesobject
policy.ruleDescribes the rule of the Custom Snippet.Yesobject
policy.rule.typeOnly “rego” is supported.Yesstring
policy.rule.value“{{this}}” is the path that references the rule the metadata is attached to.Yesstring

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 NameDescriptionRequiredType
schemaDescribes the schema of the Custom Snippet.Yesobject
schema.decisionDescribes the schema of the decision object.Yesarray of objects

Example:

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

Decision Types Toggle

The following table defines Decision Types Toggle metadata keys.

Field NameDescriptionRequiredType
typeMust be “toggle”.Yesstring
labelAdds a label for the toggle buttons. Defaults to “Permission”.Nostring
togglesThis describes the toggle buttons on the card.YesArray of objects
toggles: [toggle.key]Decision object’s key when the toggle is selected.YesString
toggles: [toggle.value]Decision object’s value when the toggle is selected.Yesboolean
toggles: [toggle.label]Text of the toggle button. Defaults to the key value.Nostring

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 NameDescriptionRequiredType
typeMust be “rego”.Yesstring
keyDecision object’s key.Yesstring
valueDecision object’s value. Generated without quotes. If you want a string value, switch to type “string”.Yesstring

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.