Custom Enrichments

Enrich events with your own stored data

Overview

Custom enrichments (also referred to as "Lookup Tables") allow you to store and reference custom enrichment data in Panther. This means you can reference this added context in detections and pass it into alerts. It may be particularly useful to create custom enrichments containing identity/asset information, vulnerability context, or network maps.

There are three import method options: a static file, S3 bucket, or Google Cloud Storage (GCS) bucket.

You can associate one or more log types with your custom enrichment—then all incoming logs of those types (that match a enrichment table value) will contain enrichment data. Learn more about the enrichment process in How incoming logs are enriched. It's also possible to dynamically reference enrichment data in Python detections. Learn how to view stored enrichment data here, and how to view log events with enrichment data here.

If your data is only needed for a few specific detections and will not be frequently updated, consider using Global helpers instead of an enrichment. Also note that you can use Panther-managed enrichments like like IPinfo and Tor Exit Nodes.

To increase the limit on the number of custom enrichments and/or size of your enrichment tables, please contact your Panther support team.

How incoming logs are enriched

Enrichments in Panther traditionally define both of the following:

• A primary key: A field in the enrichment table data.

  • If the enrichment is defined in the CLI workflow, this is designated by the PrimaryKey field in the YAML configuration file.

• One or more associated log types, each with one or more Selectors: A Selector is an event field whose values are compared to the enrichment table's primary key values to find a match.

  • There are two ways to set log types/Selectors for an enrichment. See How log types and Selectors are set for an enrichment, below.

When a log is ingested into Panther, if its log type is one that is associated to an enrichment, the values of all of its Selector fields are compared against the enrichment's primary key values. When a match is found between a value in a Selector field and a primary key value, the log is enriched with the matching primary key's associated enrichment data in a p_enrichment field. Learn more about p_enrichment below, in p_enrichment structure.

In the example in the image below, the Selector field (in the events in Incoming Logs) is ip_address. The primary key of the enrichment LUT1 is bad_actor_ip. In the right-hand Alert Event, the log is enriched with the enrichment data (including bad_actor_name) because there was a match between the Selector value (1.1.1.1) and a primary key value (1.1.1.1).

How log types and Selectors are set for an enrichment

You can manually set associated log types and Selectors when creating an enrichment (Option 1), and/or let them be automatically mapped (Option 2).

Option 1: Manually choose log types and Selectors

When creating an enrichment, you can choose one or more log types the enrichment should be associated to—and for each log type, one or more Selector fields.

Note that even if you manually choose log types and Selectors in this way, the automatic mappings described in Option 2 will still be applied.

Panther Console

• When creating an enrichment in the Panther Console, you can set associated log types and Selectors. Learn more in How to configure a custom enrichment, below.

CLI workflow

Option 2: Let log types and selectors be automatically mapped by indicator fields

The schema for your enrichment data can mark fields as indicators—for example:

    - name: attack_ids
      description: Attack field
      type: array
      element:
        type: string
        indicators:
            - mitre_attack_technique

Then, for each indicator value, Panther automatically:

1. Finds all Active log schemas (or log types) that designate any event field as that same indicator.

2. Associates those log types to the enrichment.

3. For each log type, sets the p_any field associated to the indicator as a Selector.

For example, if your enrichment data's schema designates an attack_ids field as a mitre_attack_technique indicator as is shown above, all log types in your Panther instance that also set a mitre_attack_technique indicator will be associated to the enrichment, each with a p_any_mitre_attack_techniques Selector.

This mapping happens each time an enrichment's data is refreshed.

If the schema for your enrichment data is Panther-managed, the primary key's indicator field designations may not be visible (with an indicators sub-field). Its indicators may be defined in backend application code.

p_enrichment structure

If your log events are injected with enrichment data, a p_enrichment field is appended to the event and accessed within a detection using deep_get() or DeepKey. The p_enrichment field will contain:

• One or more enrichment name(s) that matched the incoming log event

• The name of the Selector from the incoming log that matched the enrichment

• The data from the enrichment that matched via the enrichment's primary key (including an injected p_match field containing the Selector value that matched)

This is the structure of p_enrichment fields:

'p_enrichment': {
    <name of enrichment1>: {
        <name of selector>: {
            'p_match': <value of Selector>,
	    <enrichment key>: <enrichment value>,
	    ...
	}
    }
}

Note that p_enrichment is not stored with the log event in the data lake. See Viewing log events with enrichment data for more information.

How to access enrichment data in detections

Option 1 (if log is enriched): Using deep_get()

If your log event was enriched on ingest (as described in How incoming logs are enriched), you can access the data within the p_enrichment field (whose structure is described above) using the deep_get() event object function. Learn more about deep_get() on Writing Python Detections.

See a full example of this method below, in Writing a detection using custom enrichment data.

Option 2: Dynamically using lookup()

It's also possible to dynamically access enrichment data from Python detections using the event.lookup() function. In this way, you can retrieve data from any enrichment, without it being injected into an incoming event as described in How incoming logs are enriched.

Prerequisites for configuring a custom enrichment

Before configuring an enrichment, be sure you have:

• Enrichment data in JSON or CSV format

  • JSON files can format events in various ways, including in lines, arrays, or objects.

• A schema specifically for your enrichment data

  • This describes the shape of your enrichment data.

• A primary key for your enrichment data

  • This primary key is one of the fields you defined in your enrichment's schema. The value of the primary key is what will be compared with the value of the selector(s) from your incoming logs.

  • See the below Primary key data types section to learn more about primary key requirements.

• (Optional) Selector(s) from your incoming logs

  • The values from these selectors will be used to search for matches in your enrichment data.

• (CLI workflow): An enrichment configuration file

  • See Custom Enrichment Specification Reference for a full list of fields.

  • We recommend you make a fork of the panther-analysis repository and install the Panther Analysis Tool (PAT).

Primary key data types

Your enrichment table's primary key column must be one of the following data types:

• String

• Number

• Array (of strings or numbers)

  • Using an array lets you associate one row in your enrichment table with multiple string or number primary key values. This prevents you from having to duplicate a certain row of data for multiple primary keys.

Example: string array vs. string primary key type

Perhaps you'd like to store user data in a custom enrichment table so that incoming log events associated with a certain user are enriched with additional personal information. You'd like to match on the user's email address, which means the email field will be the primary key in the enrichment table and the Selector in the log events.

You are deciding whether the primary key column in your enrichment table should be of type string or string array.

First, review the below two events you might expect to receive from your log source:

# Incoming log event one
{
    "actor_email": "[email protected]",
    "action": "LOGIN"
}

# Incoming log event two
{
    "actor_email": "[email protected]",
    "action": "EXPORT_FILE"
}

Note that the two email addresses ([email protected] and [email protected]) belong to the same user, Jane Doe.

When Panther receives these events, you would like to use an enrichment table to enrich each of them with Jane's full name and role. After enrichment, these events would look like the following:

# Log event one after enrichment
{
    "actor_email": "[email protected]",
    "action": "LOGIN",
    "p_enrichment": {
        "<lookup_table_name>": {
            "actor_email": {
                "full_name": "Jane Doe",
                "p_match":  "[email protected]",
                "role": "ADMIN"
            }
        }
    }
}

# Log event two after enrichment
{
    "actor_email": "[email protected]",
    "action": "EXPORT_FILE",
    "p_enrichment": {
        "<lookup_table_name>": {
            "actor_email": {
                "full_name": "Jane Doe",
                "p_match": "[email protected]",
                "role": "ADMIN"
            }
        }
    }
}

You can accomplish this enrichment by defining a custom enrichment with either:

• (Recommended) A primary key column that is of type array of strings

• A primary key column that is of type string

Using an enrichment table with a primary key column that is of type array of strings, you can include Jane's multiple email addresses in one primary key entry, associated to one row of data. This might look like the following:

Alternatively, you can define an enrichment table with a primary key column that is of type string. However, because the match between the event and enrichment table is made on the user's email address, and a user can have multiple email addresses (as is shown in Jane's case), you must duplicate the enrichment table row for each email. This would look like the following:

While both options yield the same result (i.e., log events are enriched in the same way), defining an enrichment with an array of strings primary key is recommended for its convenience and reduced proneness to maintenance error.

How to configure a custom enrichment

After fulfilling the prerequisites, custom enrichments can be created and configured using one of the following methods:

• Option 1: Import custom enrichment data via file upload

  • Best for data that is relatively static, such as information about AWS accounts or corporate subnets.

  • Example: adding metadata to distinguish developer and production accounts in your AWS CloudTrail logs.

• Option 2: Sync custom enrichment data from an S3 bucket or Option 3: Sync custom enrichment data from a Google Cloud Storage (GCS) bucket

  • Best when you have a large amount of data that updates relatively frequently. Any changes in the S3 or GCS bucket will sync to Panther.

  • Example: if you wanted to know which groups and permission levels are associated with employees at your company. In this scenario, your company might have an S3 bucket with an up-to-date copy of their Active Directory listing that includes groups and permissions information.

After choosing one of these methods, you can opt to work within the Panther Console or with PAT.

The maximum size for a row in a custom enrichment table is 65535 bytes.

Option 1: Import custom enrichment data via file upload

You can import data via file upload through the Panther Console or PAT:

Panther Console

Import custom enrichment data via file upload through the Panther Console

1. In the left-hand navigation bar in your Panther Console, click Configure > Enrichments.

2. In the upper-right corner, click Create New.

3. On the Basic Information page:

   • Enrichment Name: A descriptive name for your custom enrichment.

   • Enabled?: Ensure this toggle is set to YES. This is required to import your data later in this process.

   • Description - Optional: Additional context about the table.

   • Reference - Optional: Typically used for a hyperlink to an internal resource.

4. Click Continue.

5. On the Associated Log Types (Optional) page, optionally designate log types/Selectors:

   • Click Add Log Type.

   • Click the Log Type dropdown, then select a log type.

   • Choose one or more Selectors, the foreign key fields from the log type you want enriched with your custom enrichment.

     • You also can reference attributes in nested objects using JSON path syntax. For example, if you wanted to reference a field in a map, you could enter $.field.subfield.

   • Click Add Log Type to add another if needed. In the example screen shot above, we selected AWS.CloudTrail logs and typed in accountID and recipientAccountID to represent keys in the CloudTrail logs.

6. Click Continue.

7. On the Table Schema page, configure the Table Schema: Note: If you have not already created a new schema, please see our documentation on creating schemas. You can also use your custom enrichment data to infer a schema. Once you have created a schema, you will be able to choose it from the dropdown on the Table Schema page while configuring an Enrichment. Note: CSV schemas require column headers to work with custom enrichments.

   • Select a Schema Name from the dropdown.

   • Select a Primary Key Name from the dropdown. This should be a unique column on the table, such as accountID.

8. Click Continue.

9. On the Choose Import Method page, on the Import via File Upload tile, click Set Up.

10. On the Upload File page, drag and drop a file or click Select file to choose the file of your Enrichment data to import. The file must be in .csv or .json format.

11. Click Finish Setup. A source setup success page will populate.

12. Optionally, next to to Set an alarm in case this custom enrichment doesn't receive any data?, toggle the setting to YES to enable an alarm.

    • Fill in the Number and Period fields to indicate how often Panther should send you this notification.

    • The alert destinations for this alarm are displayed at the bottom of the page. To configure and customize where your notification is sent, see documentation on Panther Destinations.

    ​ ​

    Notifications generated for an custom enrichment upload failing are accessible in the System Errors tab within the Alerts & Errors page in the Panther Console.

PAT

Import custom enrichment data via file upload through PAT

If your data file is larger than 1MB, it's suggested to instead use the S3 sync upload method or GCS sync upload method.

File and folder setup

A custom enrichment requires the following files:

• A YAML configuration file for the enrichment table

  • This custom enrichment configuration file must be stored in a folder with a name containing lookup_tables. This could be a top-level lookup_tables directory, or sub-directories with names matching *lookup_tables*. You can use the panther-analysis repository as a reference.

• A YAML file defining the schema to use when loading data into the table

  • This data schema file must be stored in a directory outside the lookup_tables directory. You might choose to save it with your other custom log schemas, e.g., in a /schemas directory at the root of your panther-analysis repository.

• A JSON or CSV file containing data to load into the table (optional, read further).

Writing the schema and configuration files

It's usually prudent to begin writing the data schema first, because the table config will reference some of those values.

1. Create the YAML data schema file. This schema defines how to read the files you'll use to upload data to the table. If using a CSV file for data, then the schema should be able to parse CSV.

   • The table schema is formatted the same as a log schema. For more information on writing schemas, read our documentation around managing Log Schemas.

2. Create the YAML configuration file. See a full list of required and allowed values on Custom Enrichment Specification Reference.

   • For a custom enrichment with data stored in a local file, an example configuration would look like:

     AnalysisType: lookup_table
     LookupName: my_lookup_table # A unique display name
     Schema: Custom.MyTableSchema # The schema defined in the previous step
     Filename: ./my_lookup_table_data.csv # Relative path to data
     Description: >
       A handy description of what information this table contains.
       For example, this table might convert IP addresses to hostnames
     Reference: >
       A URL to some additional documentation around this table
     Enabled: true # Set to false to stop using the table
     LogTypeMap:
       PrimaryKey: ip                # The primary key of the table
       AssociatedLogTypes:           # A list of log types to match this table to
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # A field in CloudTrail logs
             - "p_any_ip_addresses"  # A panther-generated field works too
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # Paths to JSON values are allowed

3. From the root of the repository, upload the schema file by running panther_analysis_tool update-custom-schemas --path ./schemas.

4. From the root of the repository, upload the custom enrichment using panther_analysis_tool upload.

Update custom enrichments via Panther Analysis Tool:

1. Locate the YAML configuration file for the custom enrichment in question.

2. Open the file, and look for the field Filename. You should see a file path which leads to the data file.

3. Update or replace the file indicated in Filename. To see allowed values, see Custom Enrichment Specification Reference.

4. Save the configuration file, then upload your changes with:

   panther_analysis_tool upload

   Optionally, you can specify only to upload the custom enrichment:

   panther_analysis_tool upload --filter AnalysisType=lookup_table

Option 2: Sync custom enrichment data from an S3 bucket

You can set up data sync from an S3 bucket through the Panther Console or PAT:

Panther Console

Sync custom enrichment data from an S3 bucket through the Panther Console

1. In the left-hand navigation bar in your Panther Console, click Configure > Enrichments.

2. In the upper-right corner, click Create New.

3. Click Add Custom Enrichment card.

4. On the Basic Information page, fill in the fields:

   • Enrichment Name: A descriptive name for your custom enrichment.

   • Enabled?: Ensure this toggle is set to YES. This is required to import your data later in this process.

   • Description - Optional: Additional context about the table.

   • Reference - Optional: Typically used for a hyperlink to an internal resource.

   • 

1. On the Associated Log Types page, optionally designate log types/Selectors:

   • Click Add Log Type.

   • Click the Log Type dropdown, then select a log type.

   • Choose one or more Selectors, the foreign key fields form the log type you want enriched with your custom enrichment data.

     • You also can reference attributes in nested objects using JSON path syntax. For example, if you wanted to reference a field in a map, you could enter $.field.subfield.

• Click Add Log Type to add another if needed. In the example screen shot above, we selected AWS.VPCFlow logs and typed in account to represent keys in the VPC Flow logs.

1. Click Continue.

1. On the Table Schema page, configure the Table Schema. Note: If you have not already created a new schema, please see our documentation on creating schemas. Once you have created a schema, you will be able to select it from the dropdown on the Table Schema page while configuring a custom enrichment.

   1. Select a Schema Name from the dropdown.

   2. Select a Primary Key Name from the dropdown. This should be a unique column on the table, such as accountID.

1. Click Continue.

1. On the Choose Import Method page, on the Sync Data from an S3 Bucket tile, click Set Up.

1. Set up your S3 source. Note that your data must be in .csv or .json format.

   • Enter the Account ID, the 12-digit AWS Account ID where the S3 bucket is located.

   • Enter the S3 URI, the unique path that identifies the specific S3 bucket.

   • Optionally, enter the KMS Key if your data is encrypted using KMS-SSE.

   • Enter the Update Period, the cadence your S3 source gets updated (defaulted to 1 hour).

1. Click Continue.

1. Set up an IAM role.

   • Please see the next section, Creating an IAM role, for instructions on the three options available to do this.

1. Click Finish Setup. A source setup success page will populate.

1. Optionally, next to to Set an alarm in case this custom enrichment doesn't receive any data?, toggle the setting to YES to enable an alarm.

   • Fill in the Number and Period fields to indicate how often Panther should send you this notification.

   • The alert destinations for this alarm are displayed at the bottom of the page. To configure and customize where your notification is sent, see documentation on Panther Destinations.

​​

Notifications generated for a custom enrichment upload failing are accessible in the System Errors tab within the Alerts & Errors page in the Panther Console.

Creating an IAM role

There are three options for creating an IAM Role to use with your Panther custom enrichment using an S3 source:

• Create an IAM role using AWS Console UI.

• Create an IAM role using CloudFormation Template File.

• Create an IAM role manually.

Create an IAM role using AWS Console UI

1. On the "Set Up an IAM role" page, during the process of creating a custom enrichment with an S3 source, locate the tile labeled "Using the AWS Console UI". On the right side of the tile, click Select.

2. Click Launch Console UI.

   • You will be redirected to the AWS console in a new browser tab, with the template URL pre-filled.

   • The CloudFormation stack will create an AWS IAM role with the minimum required permissions to read objects from your S3 bucket.

   • Click the "Outputs" tab of the CloudFormation stack in AWS, and note the Role ARN.

3. Navigate back to your Panther account.

4. On the "Use AWS UI to set up your role" page, enter the Role ARN.

5. Click Finish Setup.

Create an IAM role using CloudFormation Template File

1. On the "Set Up an IAM role" page, during the process of creating a custom enrichment with an S3 source, locate the tile labeled "CloudFormation Template File". On the right side of the tile, click Select.

2. Click CloudFormation template, which downloads the template to apply it through your own pipeline.

3. Upload the template file in AWS:

   1. Open your AWS console and navigate to the CloudFormation product.

   2. Click Create stack.

   3. Click Upload a template file and select the CloudFormation template you downloaded.

4. On the "CloudFormation Template" page in Panther, enter the Role ARN.

5. Click Finish Setup.

Create an IAM role manually

1. On the "Set Up an IAM role" page, during the process of creating a custom enrichment with an S3 source, click the link that says I want to set everything up on my own.

2. Create the required IAM role. You may create the required IAM role manually or through your own automation. The role must be named using the format PantherLUTsRole-${Suffix}(e.g., PantherLUTsRole-MyLookupTable).

   • The IAM role policy must include the statements defined below:

         "Version": "2012-10-17",
         "Statement": [
             {
                 "Action": "s3:GetBucketLocation",
                 "Resource": "arn:aws:s3:::<bucket-name>",
                 "Effect": "Allow"
             },
             {
                 "Action": "s3:GetObject",
                 "Resource": "arn:aws:s3:::<bucket-name>/<input-file-path>",
                 "Effect": "Allow"
             }
         ]
     }

   • If your S3 bucket is configured with server-side encryption using AWS KMS, you must include an additional statement granting the Panther API access to the corresponding KMS key. In this case, the policy will look something like this:

         "Version": "2012-10-17",
         "Statement": [
             {
                 "Action": "s3:GetBucketLocation",
                 "Resource": "arn:aws:s3:::<bucket-name>",
                 "Effect": "Allow"
             },
             {
                 "Action": "s3:GetObject",
                 "Resource": "arn:aws:s3:::<bucket-name>/<input-file-path>",
                 "Effect": "Allow"
             },
             {
                 "Action": ["kms:Decrypt", "kms:DescribeKey"],
                 "Resource": "arn:aws:kms:<region>:<your-accound-id>:key/<kms-key-id>",
                 "Effect": "Allow"
             }
         ]
     }

3. On the "Setting up role manually" page in Panther, enter the Role ARN.

   • This can be found in the "Outputs" tab of the CloudFormation stack in your AWS account.

4. Click Finish Setup, and you will be redirected to the Enrichments list page with your new Employee Directory table listed.

PAT

Sync custom enrichment data from an S3 bucket through PAT

File and folder setup

A custom enrichment requires the following files:

• A YAML configuration file for the enrichment table

  • This custom enrichment configuration file must be stored in a folder with a name containing lookup_tables. This could be a top-level lookup_tables directory, or sub-directories with names matching *lookup_tables*. You can use the panther-analysis repository as a reference.

• A YAML file defining the schema to use when loading data into the table

  • This data schema file must be stored in a directory outside the lookup_tables directory (for example, /schemas in the root of your panther analysis repo). You might choose to save it with the rest of your custom log schemas.

• A JSON or CSV file containing data to load into the table (optional, read further).

Writing the schema and configuration files

It's usually prudent to begin writing the data schema first, because the table configuration will reference some of those values.

1. Create the YAML data schema file. This schema defines how to read the files you'll use to upload data to the table. If using a CSV file for data, then the schema should be able to parse CSV.

   • The table schema is formatted the same as a log schema. For more information on writing schemas, read our documentation around managing Log Schemas.

2. Create a YAML file for the table configuration. For a custom enrichment with data stored in a file in S3, an example configuration would look like this:

   • Note that the Refresh field contains RoleARN, ObjectPath, and PeriodMinutes fields.

   • See a full list of required and allowed values on Custom Enrichment Specification Reference.

     AnalysisType: lookup_table
     LookupName: my_lookup_table # A unique display name
     Schema: Custom.MyTableSchema # The schema defined in the previous step
     Refresh:
       RoleArn: arn:aws:iam::123456789012:role/PantherLUTsRole-my_lookup_table # A role in your organization's AWS account
       ObjectPath: s3://path/to/my_lookup_table_data.csv
       PeriodMinutes: 120 # Sync from S3 every 2 hours
     Description: >
       A handy description of what information this table contains.
       For example, this table might convert IP addresses to hostnames
     Reference: >
       A URL to some additional documentation around this table
     Enabled: true # Set to false to stop using the table
     LogTypeMap:
       PrimaryKey: ip                # The primary key of the table
       AssociatedLogTypes:           # A list of log types to match this table to
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # A field in CloudTrail logs
             - "p_any_ip_addresses"  # A panther-generated field works too
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # Paths to JSON values are allowed

1. From the root of the repository, upload the schema file by running panther_analysis_tool update-custom-schemas --path ./schemas.

2. From the root of the repository, upload the custom enrichment using panther_analysis_tool upload.

Prerequisites

Before you can configure your custom enrichment to sync with S3, you'll need to have the following ready:

1. The ARN of an IAM role in AWS, which Panther can use to access the S3 bucket. For more information on setting up an IAM role for Panther, see the section on Creating an IAM Role.

2. The path to the file you intend to store data in. The path should be of the following format: s3://bucket-name/path_to_file/file.csv

Option 3: Sync custom enrichment data from a Google Cloud Storage (GCS) bucket

Syncing enrichment data from a GCS bucket is in open beta starting with Panther version 1.114, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

You can set up data sync from a GCS bucket through the Panther Console or PAT:

Panther Console

Sync custom enrichment data from a GCS bucket through the Panther Console

1. In the left-hand navigation bar in your Panther Console, click Configure > Enrichments.

2. In the upper-right corner, click Create New.

3. Click the Custom Enrichment card.

4. On the Basic Information page, fill in the fields:

   • Enrichment Name: A descriptive name for your custom enrichment.

   • Enabled?: Ensure this toggle is set to YES. This is required to import your data later in this process.

   • Description - Optional: Additional context about the table.

   • Reference - Optional: Typically used for a hyperlink to an internal resource.

   

5. Click Continue.

6. On the Associated Log Types (Optional) page, optionally designate log types/Selectors:

   • Click Add Log Type.

   • Click the Log Type dropdown, then select a log type.

   • Choose one or more Selectors, the foreign key fields form the log type you want enriched with your custom enrichment data.

     • You also can reference attributes in nested objects using JSON path syntax. For example, if you wanted to reference a field in a map, you could enter $.field.subfield.

   • Click Add Log Type to add another if needed. In the example screen shot above, we selected AWS.VPCFlow logs and typed in account to represent keys in the VPC Flow logs.

7. Click Continue.

8. On the Table Schema page, configure the Table Schema: Note: If you have not already created a new schema, please see our documentation on creating schemas. Once you have created a schema, you will be able to select it from the dropdown on the Table Schema page while configuring a custom enrichment.

   1. Select a Schema Name from the dropdown.

   2. Select a Primary Key Name from the dropdown. This should be a unique column on the table, such as accountID.

9. Click Continue.

10. On the Choose Import Method page, on the Sync Data from a Google Cloud Storage Bucket tile, click Set Up.

11. Set up your Google Cloud Storage source. Note that your data must be in .csv or .json format.

    • Enter the Google Cloud Storage URI, the unique path that identifies the specific object.

    • Enter the Update Period, the cadence your S3 source gets updated (defaulted to 1 hour).

12. Click Continue.

13. Set up an identity.

    • Please see the next section, Set up an identity, for instructions on how to do this.

14. Click Finish Setup. A source setup success page will populate.

15. Optionally, next to to Set an alarm in case this custom enrichment doesn't receive any data?, toggle the setting to YES to enable an alarm.

    • Fill in the Number and Period fields to indicate how often Panther should send you this notification.

    • The alert destinations for this alarm are displayed at the bottom of the page. To configure and customize where your notification is sent, see documentation on Panther Destinations.

    ​

Notifications generated for a custom enrichment upload failing are accessible in the System Errors tab within the Alerts & Errors page in the Panther Console.

Set up an identity

The identity method supported is Workload Identity Federation. There are three options for setting up Workflow Identity Federation to use with your Panther custom enrichment using a GCS source:

• Set up Workload Identity Federation using Terraform template file

• Set up Workload Identity Federation manually in GCP console

Set up Workload Identity Federation using Terraform template file

1. On the Setup an Identity page, during the process of creating a custom enrichment with a GCS source, locate the tile labeled "Terraform Template File". On the right side of the tile, click Select.

2. Click Terraform template, which downloads the template to apply it through your own pipeline.

3. Fill out the fields in the panther.tfvars file with your configuration.

   • Provide values for panther_workload_identity_pool_id, panther_workload_identity_pool_provider_id, and panther_aws_account_id.

   • Follow the instructions in the file regarding whether you want to create a bucket along with the rest of the resources or if you already have one.

4. Initialize a working directory containing Terraform configuration files and run terraform init.

5. Copy the corresponding Terraform Command provided and run it in your CLI.

6. Generate a credential configuration file for the pool by copying the gcloud Command provided, replacing the value for the project number, pool ID, and provider ID, and running it in your CLI.

   • You can find the project number, the pool ID and the provider ID in the output of the Terraform Command.

7. Under Provide JSON file, upload your credential configuration file.

8. Click Finish Setup

Set up Workload Identity Federation manually in GCP console

1. In your Google Cloud console, determine which bucket Panther will pull logs from.

   • If you have not created a bucket yet, please see Google's documentation on creating a bucket.

   Uniform bucket-level access must be enabled on the target bucket in order to grant Workload Identity Federation entities access to cloud storage resources.

2. Enable the IAM API.

3. Configure Workload Identity Federation with AWS by following the Configure Workload Identity Federation with AWS or Azure documentation.

   1. As you are defining an attribute mapping(s) and condition, take note of the following examples:

      • Example attribute mappings:

        Google	AWS
        google.subject	assertion.arn.extract('arn:aws:sts::{account_id}:')+":"+assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')
        attribute.account	assertion.account

        The value of the google.subject attribute cannot exceed 127 characters. You may use Common Expression Language (CEL) expressions to transform or combine attributes from the token issued by AWS. The expression suggested in the table above takes this limit into account, and is an attempt at transforming the ARN into a value that uniquely identifies Panther entities. For more information on the AWS attributes, see "Example 2 - Called by user created with AssumeRole" on this AWS documentation page.

      • Example attribute condition: attribute.account=="<PANTHER_AWS_ACCOUNT_ID>"

   2. When you are adding a provider to your identity pool, select AWS.

4. Assign the required IAM roles to the account.

   • The following permissions are required for the project where the Pub/Sub subscription and topic lives:

     Permissions required	Role	Scope
     storage.objects.get storage.objects.list	roles/storage.objectViewer	bucket-name

     • Note: You can set conditions or IAM policies on permissions for specific resources. This can be done either in the IAM section in GCP (as seen in the example screenshot below) or in the specific resource's page.

     • Note: You can create the permissions using the gcloud CLI tool, where the $PRINCIPAL_ID may be something like: principalSet://iam.googleapis.com/projects/<THE_ACTUAL_GOOGLE_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<THE_ACTUAL_POOL_ID>/attribute.account/<THE_ACTUAL_PANTHER_AWS_ACCOUNT_ID>

       • gcloud projects add-iam-policy-binding $PROJECT_ID --member="$PRINCIPAL_ID" --role="roles/storage.objectViewer"

5. Download the credential configuration file, which will be used in Panther to authenticate to the GCP infrastructure.

   • To generate a credential configuration file using the gcloud CLI tool, use the following command format: gcloud iam workload-identity-pools create-cred-config projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID --aws --output-file=config.json

PAT

Sync custom enrichment data from a GCS bucket through PAT

File and folder setup

A custom enrichment requires the following files:

• A YAML configuration file for the enrichment table

  • This custom enrichment configuration file must be stored in a folder with a name containing lookup_tables. This could be a top-level lookup_tables directory, or sub-directories with names matching *lookup_tables*. You can use the panther-analysis repository as a reference.

• A YAML file defining the schema to use when loading data into the table

  • This data schema file must be stored in a directory outside the lookup_tables directory. You might choose to save it with your other custom log schemas, e.g., in a /schemas directory at the root of your panther-analysis repository.

• A JSON or CSV file containing data to load into the table (optional, read further).

Writing the schema and configuration files

It's usually prudent to begin writing the data schema first, because the table configuration will reference some of those values.

1. Create the YAML data schema file. This schema defines how to read the files you'll use to upload data to the table. If using a CSV file for data, then the schema should be able to parse CSV.

   • The table schema is formatted the same as a log schema. For more information on writing schemas, read our documentation around managing Log Schemas.

2. Create a YAML file for the table configuration. For a custom enrichment with data stored in a file in GCS, see the below example file.

   • Note that the Refresh field contains GCSCredentials, StorageProvider, ObjectPath, and PeriodMinutes fields.

   • See a full list of required and allowed values on Custom Enrichment Specification Reference.

     AnalysisType: lookup_table
     LookupName: my_lookup_table # A unique display name
     Schema: Custom.MyTableSchema # The schema defined in the previous step
     Refresh:
       ObjectPath: gs://path/to/my_lookup_table_data.csv
       GCSCredentials: '{"universe_domain":"googleapis.com","type":"external_account","audience":"//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/mypool/providers/myprovider","subject_token_type":"urn:ietf:params:aws:token-type:aws4_request","token_url":"https://sts.googleapis.com/v1/token","credential_source":{"environment_id":"aws1","region_url":"http://169.254.169.254/latest/meta-data/placement/availability-zone","url":"http://169.254.169.254/latest/meta-data/iam/security-credentials","regional_cred_verification_url":"https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"},"token_info_url":"https://sts.googleapis.com/v1/introspect"}'
       StorageProvider: GCS
       PeriodMinutes: 120 # Sync from GCS every 2 hours
     Description: >
       A handy description of what information this table contains.
       For example, this table might convert IP addresses to hostnames
     Reference: >
       A URL to some additional documentation around this table
     Enabled: true # Set to false to stop using the table
     LogTypeMap:
       PrimaryKey: ip                # The primary key of the table
       AssociatedLogTypes:           # A list of log types to match this table to
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # A field in CloudTrail logs
             - "p_any_ip_addresses"  # A panther-generated field works too
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # Paths to JSON values are allowed

1. From the root of the repository, upload the schema file by running panther_analysis_tool update-custom-schemas --path ./schemas.

2. From the root of the repository, upload the custom enrichment using panther_analysis_tool upload.

Prerequisites

Before you can configure your custom enrichment to sync with a GGS bucket, you'll need to have the following ready:

• The JSON credential configuration for a workload identity pool, which Panther can use to access the Google Cloud Storage object. For more information on setting up Workload Identity Federation for Panther, see the Set up an identity section in the Panther Console instructions above.

• The path to the file you intend to store data in. The path should be of the following format: gs://bucket-name/path_to_file/file.csv

Writing a detection using custom enrichment data

After you configure a custom enrichment, you can write detections based on the additional context.

For example, if you configured a custom enrichment to distinguish between developer and production accounts in AWS CloudTrail logs, you might want receive an alert only if the following circumstances are both true:

• A user logged in who did not have MFA enabled.

• The AWS account is a production (not a developer) account.

See how to create a detection using enrichment data below:

Python

Accessing enrichment data the event was automatically enriched with

In Python, you can use the deep_get() helper function to retrieve the looked up field from p_enrichment using the foreign key field in the log. The pattern looks like this:

deep_get(event, 'p_enrichment', <Enrichment name>, <foreign key in log>, <field in Enrichment>)

The custom enrichment name, foreign key and field name are all optional parameters. If not specified, deep_get() will return a hierarchical dictionary with all the enrichment data available. Specifying the parameters will ensure that only the data you care about is returned.

The rule would become:

from panther_base_helpers import deep_get
 def rule(event):
   is_production = deep_get(event, 'p_enrichment', 'account_metadata',
'recipientAccountId', 'isProduction') # If the field you're accessing is stored within a list, use deep_walk() instead
   return not event.get('mfaEnabled') and is_production

---

Dynamically accessing enrichment data

You can also use the event object's lookup() function to dynamically access enrichment data in your detection. This may be useful when your event doesn't contain an exact match to a value in the enrichment's primary key column.

Simple Detection

The Panther rules engine will take the looked up matches and append that data to the event using the key p_enrichment in the following JSON structure:

{ 
    "p_enrichment": {
        <name of enrichment table>: { 
            <key in log that matched>: <matching row looked up>,
            ...
	    <key in log that matched>: <matching row looked up>,
	}    
    }
} 

Example:

 {
  "p_enrichment": {
      "account_metadata": {
          "recipientAccountId": {
              "accountID": "90123456", 
              "isProduction": false, 
              "email": "[email protected]",
              "p_match": "90123456"
              }
          }
      }
}

If the value of the matching log key is an array (e.g., the value of p_any_aws_accout_ids), then the lookup data is an array containing the matching records.

{ 
    "p_enrichment": {
        <name of enrichment table>: { 
            <key in log that matched that is an array>: [
                <matching row looked up>,
                <matching row looked up>,
                <matching row looked up>
            ]
	}
     }
} 

Example:

 {
  "p_enrichment": {
      "account_metadata": {
          "p_any_aws_account_ids": [
             {
              "accountID": "90123456", 
              "isProduction": false, 
              "email": "[email protected]",
              "p_match": "90123456"
              },
              {
              "accountID": "12345678", 
              "isProduction": true, 
              "email": "[email protected]",
              "p_match": "12345678"
              }
          ]
      }
  }
}

Testing detections that use enrichment

For rules that use p_enrichment, click Enrich Test Data in the upper right side of the JSON code editor to populate it with your Enrichment data. This allows you to test a Python function with an event that contains p_enrichment.

In order for your unit test to enrich properly, your event must specify the following two fields:

• p_log_type: This determines which Enrichments to use

• The selector field: This provides a value to match against

Enrichment (Lookup Table) History Tables

Enrichments will generate a number of tables in the Data Explorer. There are two main types of tables generated:

1. The current custom enrichment version: example

   • Contains the most up-to-date custom enrichment data

   • Should be targeted in any Saved Searches, or anywhere you expect to see the most current data

   • This table name will never change

   • In the example above, the table is named example

2. The current History Table version: example_history

   • Contains a version history of all data uploaded to the current custom enrichment

   • The table schema is identical to the current custom enrichment (here named example) except for two additional fields:

     • p_valid_start

     • p_valid_end

   • These fields can be used to view the state of the custom enrichment at any previous point in time

When a new schema is assigned to the custom enrichment, the past versions of the custom enrichment and the History Table are both preserved as well.

These past versions are preserved by the addition of a numeric suffix, _### and will be present for both the custom enrichment and the History Table. This number will increment by one each time the schema associated with the custom enrichment is replaced, or each time the primary key of the custom enrichment is changed.

The current custom enrichment and History Table are views that point at the highest numeric suffix table. This means when a new custom enrichment (called example below) is created, you will see 4 tables:

• example

• example_history

• example_001

• example_history_001

The current-version tables shown here (example and example_history) are views that are pointing at the respective underlying tables (suffixed with _001).

If a new schema is created, then _002 suffixed tables will be created, and the current-version tables will now point at those. The _001 tables will be no longer updated.