Custom Enrichment Examples

The following are examples of using custom enrichments for detections.

Example for translating 1Password UUIDs into human readable names

Please see our guide about using custom enrichments to translate 1Password's Universally Unique Identifier (UUID) values into human readable names: Using Custom Enrichments: 1Password UUIDs.

Example using CIDR matching through Panther Console

Example scenario: Let's say you want to write detections that consider the traffic logs from company IP space (e.g. VPNs and hosted systems) differently from others logs originating from public IP space.

You have a list of your company's allowed CIDR blocks listed in a .csv file (e.g. 4.5.0.0/16):

cidr	description
10.2.3.0/24	San Francisco Office
20.3.4.0/24	DC Office
30.4.5.0/24	Boston Office

Set up a custom enrichment with the CIDR list

1. Follow the instructions to set up a custom enrichment via file upload and configure its basic information.

   • The name of the Enrichment in this example is Company CIDR Blocks.

2. On the Associated Log Types page, choose the Log Type and Selectors.

   • For this example, we used AWS.VPCFlow logs and associated the source IP (srcAddr) and destination (dstAddr) keys.

3. Associate a schema for your Enrichment: Select an existing one from your list or create a new schema.

   • Note: The primary key column which will hold the CIDR blocks needs to have a CIDR validation applied in the schema to indicate that this enrichment will do CIDR block matching on IP addresses. See our log schema reference.

     # Will allow valid ip6 CIDR ranges
     # e.g. 2001:0db8:85a3:0000:0000:0000:0000:0000/64
     - name: address
       type: string
       validate:
         cidr: "ipv6" 
         
     # Will allow valid ipv4 IP addresses e.g. 100.100.100.100/00
     - name: address
       type: string
       validate:
         cidr: "ipv4"  

4. Drag & drop a file or click Select File to choose the file of your CIDR block list to import. The file must be in .csv or .json format. The maximum file size supported is 5MB.

5. After you successfully import a file, click View in Data Explorer to query that table data or click Finish Setup to go back to a list of your custom Enrichments.

Write a detection

You might like to receive an alert if any VPC traffic comes from a source IP address that is not part of your company's allowed CIDR blocks. Here is an example of a rule that will send an alert in this case:

Python

def rule(event):
  if event.get('flowDirection') == 'egress': # we care about inbound
        return False
  if event.get('action') == 'REJECT': # we don't care about these either
        return False
  if deep_get(event, 'p_enrichment','Company CIDR Blocks','srcAddr'): # these are ok
        return False 
  return True # alert if NOT from an approved network range

Simple Detection

Note: The CIDR validation applied in the Enrichment schema in this example will enable the system to match IP addresses in VPC flow log to CIDR blocks in the lookup.

Example using IP for Geolocation with Panther Analysis Tool

Let's say you want to know which geographical location your employees are connecting from (e.g., using info like geonames.org). In this scenario, your company has a static file that maps CIDRs to a GeoId, like the one we have in this example_cidr_lookup_content.csv.

> curl https://raw.githubusercontent.com/panther-labs/panther-analysis/master/templates/example_cidr_lookup_content.csv

network,geoname_id
1.0.0.0/24,2077422
1.0.1.0/24,1814991
1.0.2.0/23,1814991
1.0.4.0/22,2077456
1.0.8.0/21,1814991
1.0.16.0/20,1814991

You could use a YAML schema similar to the following:

AnalysisType: lookup_table # always lookup_table
LookupName: simple_cidr_lookup # str
Enabled: true # bool
Description: Enrichment description # str (Optional)
FileName: ./relative/path/to/content.csv # str (Optional)
Reference: An optional reference link # str (Optional)
Schema: Custom.Simple.Cidr # str (should already exist)
LogTypeMap:
  PrimaryKey: network # str
  AssociatedLogTypes: # [...]
    - LogType: Aws.CloudTrail # str
      Selectors: # [str]
        - 'p_any_ip_addresses'
    - LogType: Aws.VPCFlow
      Selectors:
        - 'p_any_ip_addresses'