Skip to main content

Create an Alert Profile

This topic describes how to create a custom alert profile that extends a predefined alert profile.

For example, you would use a custom alert profile when you want to customize the event's text on the Events page under the timeline, in the event summary, or the event's individual dossier.

All Lacework endpoints require an API access (bearer) token to be specified when you invoke the endpoint. If you already have a secret key, you can use the POST /api/v2/access/tokens endpoint to generate an access token. For details, see API Access Keys and Tokens.

Identify the Alert Profile to Extend​

Because an alert profile helps to map what data is available for the alert message, each alert profile corresponds to a datasource. For example, if your query uses the LW_CFG_AWS_EC2_SECURITY_GROUPS datasource, extend the LW_CFG_AWS_DEFAULT_PROFILE alert profile. See Identifying Which Alert Profile to Use for more information.

This example shows the predefined LW_CFG_AWS_DEFAULT_PROFILE alert profile. This is the alert profile you will extend.

GET https://AccountName.lacework.net/api/v2/AlertProfiles/LW_CFG_AWS_DEFAULT_PROFILE
LW_CFG_AWS_DEFAULT_PROFILE details (truncated)
{
    "data": {
        "alertProfileId": "LW_CFG_AWS_DEFAULT_PROFILE",
        "extends": "LW_LPP_BaseProfile",
        "fields": [
            {
                "name": "_PRIMARY_TAG"
            },
            {
                "name": "RESOURCE_ID"
            }, ...
        ],
        "descriptionKeys": [
            {
                "name": "_OCCURRENCE",
                "spec": "{{_OCCURRENCE}}"
            },            
            {
                "name": "RESOURCE_ID",
                "spec": "{{RESOURCE_ID}}"
            }, ...
        ],
        "alerts": [
            {
                "name": "CFG_AWS_NewViolation",
                "eventName": "LW Configuration AWS Violation Alert",
                "description": "{{_OCCURRENCE}} Violation for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}",
                "subject": "{{_OCCURRENCE}} violation detected for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}"
            },
            {
                "name": "CFG_AWS_PolicyChanged",
                "eventName": "LW Configuration AWS Violation Alert",
                "description": "{{_OCCURRENCE}} Violation for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}",
                "subject": "{{_OCCURRENCE}} violation detected for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}"
            },
            {
                "name": "CFG_AWS_Violation",
                "eventName": "LW Configuration AWS Violation Alert",
                "description": "{{_OCCURRENCE}} Violation for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}",
                "subject": "{{_OCCURRENCE}} violation detected for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}"
            }
        ]
    }
}

Customize the Alert Profile​

From the alert profile that you want to extend, you only need its alert profile ID. Your custom alert profile inherits all of its other data.

Configure the custom alert profile using the following guidelines:

  • alertProfileId: Specify a unique identification for the alert profile.
  • extends: Specify the alert profile ID of the alert profile you want to extend. Don't extend LW_LPP_BaseProfile because it doesn't have alerts.

Under the alerts field:

  • name: Specify a unique name for the alert template. If you specify an existing name, it overrides the existing alert template.
  • eventName: Specify a meaningful name for the event. The eventName displays in the event summary and the event's individual dossier.
  • description: Specify a description. You can use regular text and the available descriptionKeys. The description displays in the event summary and the event's individual dossier.
  • subject: Specify a subject line. You can use regular text and the available descriptionKeys. The subject displays on the Events page under the timeline.

To see which description keys you can use in the description and subject, review the alert profile's data in the GET /api/v2/AlertProfiles/{alertProfileId} response.

Create the Alert Profile​

To create the custom alert profile in your Lacework instance, call the POST /api/v2/AlertProfiles endpoint with the alert profile in the body, for example:

Example custom alert profile
{
    "alertProfileId": "Custom_CFG_AWS_Profile",
    "extends": "LW_CFG_AWS_DEFAULT_PROFILE",
    "alerts": [
        {
            "name": "Custom_Violation",
            "eventName": "Custom Violation Alert",
            "description": "Violation for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}",
            "subject": "Violation detected for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}"
        }
    ]
}

If successful, it returns a response:

{
    "alertProfileId": "Custom_CFG_AWS_Profile",
    "extends": "LW_CFG_AWS_DEFAULT_PROFILE",
    ...
}

The returned response includes the data from your custom alert profile and all data inherited from its parent alert profile.

Modify an Alert Template within an Alert Profile​

You can modify a specified alert template within an alert profile. Use the endpoints described in the following sections.

Create an Alert Template​

Use the POST /api/v2/AlertProfiles/{alertProfileId}/AlertTemplates endpoint to create an alert within an existing custom alert profile.

For example, to create another alert template in the example profile from Create the Alert Profile, call this endpoint: 

POST https://AccountName.lacework.net/api/v2/AlertProfiles/Custom_CFG_AWS_Profile/AlertTemplates

Provide the alert template fields in the request body:

{
    "name": "Another_Custom_Violation",
    "eventName": "Another Custom Violation Alert",
    "description": "Violation for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}",
     "subject": "Violation detected for AWS Resource {{RESOURCE_TYPE}}:{{RESOURCE_ID}} in account {{ACCOUNT_ID}} region {{RESOURCE_REGION}}"
}

Update an Alert Template​

Use the PATCH /api/v2/AlertProfiles/{alertProfileId}/AlertTemplates/{alertTemplateName} endpoint to update an alert template within a custom alert profile.

For example, to update the example alert template from Create the Alert Profile, call this endpoint: 

PATCH https://AccountName.lacework.net/api/v2/AlertProfiles/Custom_CFG_AWS_Profile/AlertTemplates/Custom_Violation

Provide the updated alert template fields in the request body (all fields are optional):

{
    "eventName": "Revised Event Name for the Alert",
    "description": "Revised description",
    "subject": "Revised subject for violation detected"
}

Delete an Alert Template​

Use the DELETE /api/v2/AlertProfiles/{alertProfileId}/AlertTemplates/{alertTemplateName} endpoint to delete an alert template from a custom alert profile.

For example, to delete the example alert template from Create the Alert Profile, call this endpoint: 

DELETE https://AccountName.lacework.net/api/v2/AlertProfiles/Custom_CFG_AWS_Profile/AlertTemplates/Custom_Violation

Next Steps​

Create a new policy or update an existing policy to use the alert profile. In the policy's alertProfile field, specify the alert profile ID and the alert template name in this format: alertProfileId.alertTemplateName.

To use the example Custom_CFG_AWS_Profile alert profile and alert template above, you would specify the following in the alertProfile field: Custom_CFG_AWS_Profile.Custom_Violation.