Escalations
Escalation definitions describe a sequence of action items to be taken when a policy fails to validate. Action items are run in order and the escalation will run until all actions are complete or until an error is encountered running one of the action items. Escalation Action Items are describe below. Action items may appear any number of times in any order, except when noted. Escalation Example are also included in this section.
Syntax:
escalation <name> do
automatic <term>
label <string literal>
description <string literal>
parameter <parameter definition 1>
parameter <parameter definition 2>
parameter ...
<action item 1>
<action item 2>
<action item 3>
<action item ...>
end
Where:
| • | name is the name of the escalation. It may be referenced in validate and validate_each blocks by escalate $<name>. |
| • | label gives a human readable label for the escalation. |
| • | description is optional and should give a description of what will happen when the action is run. |
| • | automatic controls whether the escalation is automatically run when an incident is generated, or is manually run. Automatic can be true or false, or a function that evaluates to true or false. If unspecified, it defaults to true for backwards compatibility. Functions used can operate on Parameters to the applied policy in order to make whether actions are automatically run configurable. |
| • | parameter can appear any number of times. parameters are optional parameters to inject into the request approval. They can be referenced by subsequent actions such as Cloud Workflows or emails within the same escalation. See the Parameters section for more information about defining parameters. |
The following links describe the possible action items.
| • |
| • | Request Approval |
| • | Cloud Workflow |
email causes an email to be sent to the given address or addresses.
email <addresses> do
subject_template <subject template>
body_template <body template>
end
Where:
| • | addresses can be a string, an array of strings corresponding to email addresses. It can also be Parameters, datasource (data), or a jq (function), which evaluates to a string or array of strings. For the definition of data, see Reserved Word Reference. |
| • | subject template must be a go template (see Incident Message and Email Templates) that is evaluated to be the email subject line. If no subject template is provided, the incident summary is used. |
| • | body template must be a go template (see Incident Message and Email Templates) that is evaluated to be the email body. If no body template is provided, the incident detail is used. |
The following is an example of using datasource in sending escalation emails:
# Datasource is a string or an array of strings.
# For example, "example1@mail.com" or ["example1@mail.com", "example2@mail.com"]
escalation "email" do
email data
end
The following are examples of using jq function in sending escalation emails:
# Datasource is an array of objects.
# For example, [ { "email": "example1@mail.com", "email": "example2@mail.com" } ]
escalation "email" do
email jq(data, ".[].email", "array")
end
# Datasource is an object.
# For example, { "emails": ["example1@mail.com", "email": "example2@mail.com"] }
escalation "email" do
email jq(data, ".emails")
end
Potential Risks of Using Dynamically Generated Email Lists
The dynamically generated email lists offer flexibility and allow routing of notifications to the relevant recipients. However, it is important to be aware of the following potential risks:
| • | Data accuracy—Errors in dynamically generated email lists, stemming from outdated or incorrect contact information, may result in emails failing to reach their intended recipients. |
| • | Data security—Sensitive information can be inadvertently sent to unintended recipients, compromising data security. |
| • | Spam and compliance issues—Adding unauthorized or inaccurate email address to the list could lead to spam complaints and compliance violations. |
| • | Email overload—Poorly built dynamic email lists may lead to excessive email notifications. |
Best Practices of Using Dynamically Generated Email Lists
The following are the best practices to mitigate the risks associated with dynamically generated email lists:
| • | Use validated data sources—Utilize only thoroughly vetted and validated sources of email contacts when generating dynamic email lists. |
| • | Thorough testing—Prior to enabling notifications, rigorously test email list building code to identify and address any potential issues and inaccuracies. |
| • | Prioritize restriction—Prioritize more restrictive email lists over expansive ones to ensure that only the intended recipients receive notifications, minimizing the risk of sending sensitive information to unintended parties. |
| • | Maintain data integrity—Ensure that the source of contact information is properly maintained, and that those responsible for its upkeep are aware of the implications of any changes made. |
request_approval creates an approval request, causing the escalation to pause and wait for manual input. The manual input can either be an approval or denial. If its an approval, actions after the request approval will be taken. If its a denial, no further actions will be taken. When applying a policy, policy managers can choose to skip all approvals in the policy using the Skip Approvals option.
request_approval do
label <string literal>
description <string literal>
parameter <parameter definition 1>
parameter <parameter definition 2>
parameter ...
end
Where:
| • | label gives a human readable label for the request approval. |
| • | description is optional and should give a description of what will happen when the action is approved. |
| • | parameters are optional parameters to inject into the request approval. They can be referenced by subsequent cloud workflows or emails within the same escalation. See the Parameters section for more information. |
run launches a Cloud Workflow using the given Cloud Workflow Language definition. This definition may be given parameters specified in a comma separated list. Parameters may be references or any of the applicable functions.
run <rcl definition name>[, <parameter>]*
parameter can be any term. It may be a reference to a datasource, a parameter, a literal value of any type, a function, or a reserved keyword such as data.
Cloud Workflow Variables
Besides parameters passed explicitly in the define declaration, a handful of variables are available automatically:
|
Variable |
Type |
Value |
|
@@account |
Integer |
The Flexera project you're currently running in, example: 60073 |
|
$$cred_* |
Credentials reference |
Any credentials or auth declaration is exported based upon name. For example if you have a declaration credentials "cred_azure" do... it will be available for signing http_* requests as $$cred_azure. Note this differs slightly from the reference name in datasource declarations where the reference name would be $cred_azure. |
Here is an example employing all previously described actions. It does not run automatically. It first optionally sends an email to a third party asking them to look at the approval request that will be created. If the approval request is approved, a Cloud Workflow is run in order to delete the volumes.
# RCL used to delete volumes using Cloud Management.
define run_delete_volumes($data) do
# loop through each data item
foreach $volume in $data do
# get the volume resource
@volume = rs_cm.get(href: $volume['href'])
#delete the volume
@volume.delete
end
end
escalation "delete_volumes_with_approval" do
automatic false
label "Deleted Volumes"
description "Delete the selected volumes"
parameter "param_email" do
type "string"
label "Person to notify of action"
description "If this is not-empty, a notification email will be sent to the following address."
end
email $param_email do
subject_template "Approval request: delete unencrypted volumes found in project {{ rs_project_name }}"
body_template <<-EOS
Unencrypted Volumes
The following volumes are tagged with one of the tags shown below and are unencrypted:
{{ range $index, $tag := parameters.enforced_tags }}{{ if $index }}, {{ end }}{{ $tag }}{{ end }}
{{ range data }}
| Region | Volume ID | Volume Tags |
| ------------ | --------- | ----------- |
| {{.region }} | {{.id}} | {{.tag_set} |
{{ end }}
We would like your approval to delete the following volumes, please approve or deny this request.
[JIRA Ticket]({{ parameters.jira_url }}/{{ data.jira_ticket_id }})
EOS
request_approval do
label "Delete volumes"
description "Approving this will delete the listed volumes."
end
run "run_delete_volumes", data, $param_top_level, rs_project_id
end