Jinja2 - References
On this page we will walk you through some of the references available within InsightCloudSec to use when configuring your Jinja2 templates.
The content on this page includes:
- Resource Attributes
- Resource Functions
- Using BotFactory Events with Jinja
- Example Jinja Templates
- Advanced templates for AWS bucket policies
For assistance with any of the examples or content on this page reach out to us through the Customer Support Portal.
Testing Jinja2 Code
You can test your Jinja code prior to running a Bot using the Preview message link located in the Actions section of the Bot Creation form.
Jinja2 Commands
Some Jinja2 commands may not work correctly until the Bot has deployed.
Resource Attributes
Available attributes vary based on the resource type (e.g. instances). A list of available attributes based on the resource type can be found through each category page, as follows:
- Compute Resources
- Storage Resources
- Network Resources
- Identity & Management Resources
- Container Resources
Finding a Specific Resource
We suggest navigating to the appropriate category page (e.g. Compute, Storage, etc.) and locating the individual resource. These are listed in the contents for each page on the right and can be accessed via that in-page Table of Contents, or by using a basic search on the page (e.g. CMD + F).
Using Resource Attributes
When using these actions, access resource properties by using the following syntax:
{{resource.<attribute>}}
Resource Common Data
For certain resources, the attribute details must be expressed in a slightly different format. Within InsightCloudSec there are a handful of resources that share what we refer to as common data and they are identified as such within our database.
To include these attributes you can access the properties of these specific resources with the following syntax:
{{resource.common.<attribute>}}
This syntax applies to ONLY the following:
text
Example of common Jinja2 command
jinja2
Resource External Data
Accessing external data also requires a different format, as it directly references the external data parameters harvested by InsightCloudSec.
To include these external data parameters for a given resource ID, use the following syntax:
jinja2
The <parameter> reference should be substituted with any of the named parameters found within a defined external data source. See Get Data Sources for more information.
**Example of external data Jinja2 command **
jinja2
Resource Functions
In addition to resource attributes InsightCloudSec includes support for some resource functions. Since our platform supports hundreds of resources if you are interested in a resource function or configuration that you do not see listed here reach out to our team through the Customer Support Portal.
When using these actions, you can access resource properties by using the following syntax:{{resource.<function>}}
Each of the resource functions below (listed alphabetically) provides a high-level explanation of the capability and the associated template element(s).
Create Network Flowlog
We have added Jinja2 field supports to the Bot action, Create Network Flow Log. This capability allows you to dynamically assign S3, S3 folder, and/or Cloudwatch Logs based upon related properties (e.g. a badge of the resource’s cloud, the region of the resource, and/or the name of the resource.)
For example, this Jinja2 will create a flow log targeted at a standard S3 bucket for flowlogs by account and region and use a different folder defined by network ID.
jinja2
Get Access Key Info
You can include this resource function in a Bot configuration for the Cloud User Resource Type. Doing so will retrieve information about the API access keys including the key ID, key status, create date, last used date, and age in days for any users included within the Bot scope.
{{resource.get_access_key_info()}}
For example:
jinja2
Get Age in Days
Allows you to retrieve information about the age of a resource in days and is applicable in any context where a date field is available. The create_date can be specified or will be assumed by default. Alternatively you can specify other dates fields, e.g. last_used_date, as a parameter.
Date fields are included in the attributes throughout our Resources documentation for each individual resource. For example, API Access Key details are here.
{{resource.get_age_in_days()}}
This template can also provide the number of days since a Cloud User's password has been used, as follows:
{{resource.get_age_in_days('password_last_used')}}
Get Attached Instance Name
The following {{resource.get_attached_instance_name()}} allows you to pull the name of the attached compute(EC2) instance/NAT gateway on Public IP resources.
Get Badge Value by Key for Parent Cloud
This new function is specific to our Microsoft Teams Integration and enables users to include dynamic details based on a particular badge key. By defining a Badge for Teams, users are able to identify multiple channels to target for messaging using a single Bot action.Previously users would be required to create a single Bot action for each Teams channel using an individual webhook).
{{resource.get_badge_value_by_key_for_parent_cloud()}}
For example, where ‘Teams’ is your badge key:
{{resource.get_badge_value_by_key_for_parent_cloud('Teams')}}
In addition users can choose to specify case sensitivity and to return a default value with the following:
- Specify case sensitivity
case_insensitive- Note that if not specified this value defaults to false
- Return a default value
default_return_str
For example, where case insensitivity is set to True and the default string is No Badge Found:{{resource.get_badge_value_by_key_for_parent_cloud('Teams', case_insensitive=True, default_return_str='No Badge Found')}} .
Get Cloud Organization Details
The following "getters" can be used in Bot notification to enrich notifications:
resource.get_cloud_organization_id()- Retrieves the cloud specific organization ID that's defined at the top level.resource.get_cloud_organization_nickname()- Retrieves the human readable nickname that's associated with the Organization within InsightCloudSec.
Get Cloud Type
To return the cloud type (AWS, Azure, GCP, etc.), use the function below:
{{resource.get_cloud_type().id}}
Get Daily Cost
Calculate the daily cost for the resource in question. If the resource does not support cost calculation then this function will return None.
{{resource.get_daily_cost()}}
In addition, use the function below to round up and limit cost value to 2 decimal places.
For example:
- Cost with limiting 2 decimals: $2.23
- Cost without limiting decimals: $2.2272
{{"{0:.2F}". format(resource.get_daily_cost())}}
Get Data Collection Value
This template retrieves the description for a specific data collection value.
{{resource.get_data_collection_value(collection_name='<data_collection_name>', key='<data_collection_value>')}}
For example, the following template would return the description for the value mv_1 inside the my_dc data collection: {{resource.get_data_collection_value('my_dc', key='mv_1')}}
Get Date, Timestamp, and Datetime
Calculate the date, timestamp, or datetime for a given event. These functions, in combination with a tagging strategy, can be used to provide context such as indicating when a resource was tagged with time-relevant keys, e.g. "Owner notified of impending delete", "30 day exemption granted", etc.
{{event.get_date()}}{{event.get_date().today()}}{{event.get_timestamp()}}{{event.get_timestamp().utcnow()}}{{event.get_unix_epoch_timestamp()}}{{event.get_date(days=30)}}{{event.get_timestamp(unit="minutes", value=60)}}{{event.get_timestamp(unit="hours", value=12)}}{{event.get_timestamp(unit="days", value=7)}}
In addition, the Filters Resource Tag Date Comparison and Resource Tag Date/Time Comparison, allow you to inspect those tags and make decisions based upon them, e.g. sending notifications, shutting down instances, deleting roles, etc.
Get Dependency IDs
Include the provider IDs of associated dependencies for a resource.
{{resource.get_dependency_ids()}}
Additionally, you can specify what type of resource as a dependency you want to list. For example, a bot scoped to Instances can have multiple dependencies (eg. Volumes, Networks, Subnets, etc). Use the syntax below to only list the Security Groups (or Access Lists).
{{resource.get_dependency_ids(resource_types=['resourceaccesslist'])}}
Get Impacted Resources
Include an optional tag key in the get_impacted_resources() to enrich the response with the value of the supplied tag. This enhancement applies to the following resource types:
- AWS Trusted Advisor
- AWS GuardDuty
These fields can be used when a Bot is linked to an Insight. For example, a Bot flagging a resource can share the {{event.bot_insight_name}} field to identify the specific Insight a resource is failing and to help the user more easily remedy the issue or add an exemption.
Get Last Event
This is a function that allows Bot authors to gain access to properties of the last eventof any type (from EDH) to further enrich Bot notification alerts. The syntax examples below allow you to obtain details from the last event object as follows:
- User -
{{resource.get_last_event().get('user')}} - User ARN -
{{resource.get_last_event().get('user_arn')}} - Action -
{{resource.get_last_event().get('action')}} - Timestamp -
{{resource.get_last_event().get('timestamp')}} - IP -
{{resource.get_last_event().get('ip')}} - Event ID -
{{resource.get_last_event().get('event_id')}} - Event Tags -
{{resource.get_last_event('tags')}} - Event Created -
{{resource.get_last_event('create')}} - Event Modify -
{{resource.get_last_event('modify')}}
To obtain the last suspicious event for a given resource, this function can be applied as follows: {{resource.get_last_event(None,True).get('user_arn')}}.
Get Linked Insight
This function allows Bot authors to gain access to the Insight linked to the Bot.
{{event.insight_link}}
Get Missing Permissions
Use this option as part of Bot automation to help identify and remediate cloud accounts with missing IAM permissions that impair InsightCloudSec visibility. This can be used alongside the Query Filter Cloud Account With Impaired Visibility.
{{resource.get_missing_permissions()}}
Get Monthly Cost
Calculate the monthly cost for the resource in question. If the resource does not support cost calculation then this function will return None.
{{resource.get_monthly_cost()}}
In addition, use the function below to round up and limit cost value to 2 decimal places.
For example:
- Cost with limiting 2 decimals: $2.23
- Cost without limiting decimals: $2.2272
{{"{0:.2F}". format(resource.get_monthly_cost())}}
Get Organization Service Name and Account ID
These walk the resource to the parent organization service (cloud account) to retrieve the name and account number assigned to the account (e.g. Acmecorp AWS Production and 123456789012).
{{resource.get_organization_service_name()}}
{{resource.get_organization_service().account_id}}
In addition, use the account_id attribute in conjunction with the "Enable Storage Container Logging" Bot Action to enable logging to buckets in each region and account (provided they follow a standard naming convention):
ics-target-bucket-{{resource.common.region_name}}-{{resource.get_organization_service().account_id}}
Get Owner Name
In InsightCloudSec you can assign ownership to resources. Doing this grants the owner full permission to that resource, and designates a point of contact (POC) for questions about the resource. This function will return the name of the POC if one is assigned, and None if one is not.
{{resource.get_owner_name()}}
Another Example Using get_owner_name
{{resource.get_owner_name()}}@rapid7.com;{{resource.common.resource_type}}@rapid7.com
In this example a customer may have an alias for all S3 buckets. The buckets can be set up with a tag owner_email, and a Bot can be set up with condition on that tag key being present, and use the delayed email action with Jinja recipient, set to: {{resource.get_tag_value('owner_email', True, '')}}
Get Provider Link
Capture the provider link to create a notification (for Slack or other services) and share a direct link for the applicable resource in the provider console. (Currently only available for specific resources, contact us via Getting Support with any questions.)
{{resource.get_provider_link()}}.
An example of this notification type is:
Get Resource Age
This field {{resource.get_age_in_days()}} allows you to retrieve the age of a resource. Including resource age information can provide meaningful context and allow users to generate notifications or take actions based upon a resource's age, e.g. rotating API keys once their age exceeds a user-defined threshold.
Get Resource CVEs
Provides a summary report of CVEs associated with the resource in question; currently valid for container images and container instances.
{{resource.get_resource_cves()}}
You can also limit CVEs to specific severities by including arguments:
{{resource.get_resource_cves(severities=['CRITICAL', 'HIGH'])}}
Get Resource Data
All
To return all the details about a resource, use the 'serialize' Jinja2 attribute shown below. Note that this can be used across all resource types, making it useful for bots that are scoped to more than one resource type.
{{resource.serialize(indent=2)}}
Example output:
jinja2
Partial - Using a JMESPath Query
InsightCloudSec has added support for a JMESPath query to resource.serialize, this allows you to:
- Access any field available on the serialized object
- Compose new JSON objects with the exact data and shape required
To use this feature you must pass a JMESPath expression as jmespath argument to resource.serialize.
Some examples using this capability are below:
Get All Resource Tags
text
Create a JSON Object with resource_id and tag values
text
Create a JSON Object with account_id, instance_id, and environments from tags
text
Get Resource Name
This walks the resource to the database object and returns the name. For resources which do not have a name, the primary key value is returned. With public IP addresses, for example, the resource’s IP address will be returned.
{{resource.get_resource_name()}}
This also works well with Bot actions that update S3 bucket policies, which require unique IDs, by using the bucket name, which is unique by definition. S3 bucket bot actions include object encryption and IP lockdown.
Get Tags from Cloud User via API Access Keys
You can include this resource function in a Bot configuration for the API Access Key Resource Type. Doing so will retrieve tag value(s) from the Cloud User using the API Access Key.
Input the tag key you're trying to retrieve the value for by replacing the key_here field, as shown in the example below:
{{resource.user.get_resource().get_tag_value(tag_key="key_here", case_insensitive=True)}}
Note
This function will only work with Users and is not applicable to any parent resource.
Get Tag Value
Get the value of a particular tag key. Only the tag key is required; however, you can optionally set the case_insensitive and default_return_str kwargs to force case sensitivity and/or return a specific value if the tag key does not exist.
{{resource.get_tag_value("tag_key", case_insensitive=True, default_return_str="None")}}
A tag key can be combined with the walk_parent_resource_group parameter to return any resources tagged with the provided key, and when those resources do not have the provided tag key, check to see if the resource's Resource Group does. If the Resource Group does, that tag value will be returned instead. For example, with a key of "Owner":
{{resource.get_tag_value(tag_key="Owner", walk_parent_resource_group=True)}}
Get Threat Finding Details
Returns a list of threat finding JSON blocks for AWS GuardDuty findings matching the following response syntax:
{{resource.get_threat_finding_details()}}
To pretty-print the JSON output:
{{resource.get_threat_finding_details(json_format=true)}}
Get Users
Currently only applicable to Secure File Transfer.
Provides information pertaining to users authorized to SSH into target server, to include user_name, public_keys, key_id, date_imported, and home_directory_type for each authorized user on the server.
{{resource.get_users()}}
Get Users Based on Credential Age
Identifies users whose server credentials are older than a given threshold, where n is the number of days.
{{resource.get_users_based_on_credential_age(threshold=n)}}
When used in conjunction with the Transfer Server User Credential Threshold Filter, you can identify any users with expired credentials who are also associated with a given server.
Get Vulnerabilities
Enables the return of vulnerability findings for more robust tickets, Slack messages, and alerts. Input the following syntax to return all vulnerability findings for a given resource:
{{resource.get_vulnerabilities()}}
The example below loops over all the vulnerabilities on a resource to export information about the vulnerabilities:
Using BotFactory Events with Jinja
To include Bot information on the Jinja output, use the following syntax:
text
Get Insight Information
Insight ID - {{event.bot_insight_id}}
Insight Name - {{event.bot_insight_name}}
Insight Severity - {{event.bot_insight_severity}}
These fields can be used when a Bot is linked to an Insight. For example, a Bot flagging a resource can share the {{event.bot_insight_name}} field to identify the specific Insight a resource is failing and to help the user more easily remedy the issue or add an exemption.
Get Bot Information
Bot Name - {{event.bot_name}}
Bot ID - {{event.bot_id}}
Bot Link - {{event.direct_link}}
Bot Severity - {{event.bot_severity}}
Bot Description - {{event.bot_description}}
Bot Timestamp - {{event.timestamp}}
Example output:
Example Jinja Templates
Included below are several examples of dynamic messages that can be used in emails, Slack, and other messaging tools.
The title provides an explanation of their use case and includes the appropriate resource attributes and formatting. They can be copied and applied to any Bot you'd like to create.
To copy the message simply hover over the text to trigger the copy function and apply the pre-constructed template to your Bot.
Resource Is Exposed To Public
jinja2
Instance in Unapproved Region
jinja2
Ensure Tag Strategy is Enforced
jinja2
Instance Has More Than 4 Cores
jinja2
A Resource You Own Was Removed
jinja2
Instance With Public IP Has SSH Open To The World
jinja2
Bad ACL
jinja2
Expensive Instance was created or discovered
jinja2
Database Open to the World
jinja2
Storage Container Public Access
jinja2
CloudWatch Alarm has triggered
jinja2
Database Instance has had Zero Connections in 14 days
jinja2
Instance Provisioned outside of AMI Whitelist
jinja2
User without MFA Enabled
jinja2
Advanced Jinja Templates (AWS)
In addition to templating for various notifications InsightCloudSec also supports the use of Jinja2 templating to add or update S3 bucket policies. These advanced capabilities are included here as examples/references of these capabilities. If you're interested in implementing Jinja2 in a more advanced way using custom policies we recommend connecting with our team through the Customer Support Portal.
In our two examples of updating bucket policy the first demonstrates the Jinja2 template required to enforce encryption, and the second is to restrict access.
Bucket Encryption Policy
If you would like to enforce encryption via bucket policy, you can create a bot that uses the Set Container Policy action and the following template to enforce encryption.
json
Bucket Lockdown Policy
If you would like to restrict bucket access to certain IP ranges or block specific IP ranges, you can use Set Container Policy and the following template to lock down the bucket to those IP ranges.
json