Querying and Writing Detections for Panther Audit Logs

Monitor your Panther audit logs

Overview

You can enable Panther audit log ingestion into Panther, meaning you can then interact with Panther audit logs in detections, data lake queries, and more.

Querying the Data Lake for Panther audit logs

Audit logs can be found in the data lake under panther_logs.panther_audit. The following query, executed in Search or Data Explorer, shows all audit events within the last day:

SELECT * FROM panther_logs.panther_audit WHERE p_occurs_since('1 day');

The result of this query would include several audit logs, an example of which can be seen below:

{
	"XForwardedFor": [
		"72.72.72.72",
		"130.172.130.172"
	],
	"actionDescription": "Lists the details of all available data lake databases",
	"actionName": "LIST_DATA_LAKE_DATABASES",
	"actionParams": {},
	"actionResult": "SUCCEEDED",
	"actor": {
		"attributes": {
			"email": "[email protected]",
			"emailVerified": false,
			"roleId": ""
		},
		"id": "[email protected]",
		"name": "[email protected]",
		"type": "USER"
	},
	"errors": null,
	"p_any_ip_addresses": [
		"72.72.72.72",
		"130.172.130.172"
	],
	"p_any_trace_ids": [
		"[email protected]"
	],
	"p_any_usernames": [
		"[email protected]"
	],
	"p_event_time": "2022-04-22 15:39:55.358",
	"p_log_type": "Panther.Audit",
	"p_parse_time": "2022-04-22 15:41:36.276",
	"p_row_id": "asdfdjklasdfjklasdfjlk",
	"p_source_id": "abc12345-ab12-cd12-ef12-abc1234567890",
	"p_source_label": "panther-audit-logs-us-east-1",
	"pantherVersion": "1.34.0",
	"sourceIP": "72.72.72.72",
	"timestamp": "2022-04-22 15:39:55.358",
	"userAgent": ""
}

Writing a detection for Panther audit logs

Audit logs can be leveraged to write powerful detections for generating alerts when an unusual or important action has been taken within Panther.

Let's write a detection that alerts when a detection has been deleted.

Step 1: Begin creating the detection

1. In the left-hand navigation bar of your Panther Console, click Detections.

2. On the Detections page, click Create New.\

3. In the Select Detection Type modal, click Rule.

4. Enter a descriptive Name for your rule, e.g., Panther detection deleted.

5. Under For the Following Source, in the Log Types dropdown, select Panther.Audit.

6. In the Detect tile, click Python Editor.

7. In the code editor, enter the following Python code, which will generate an alert when a detection is deleted:

   def rule(event):    
       return event.get('actionName') == 'DELETE_DETECTION'
   def title(event):
       return 'Detection deleted!'

   • This code defines a simple title using the title() function. Learn how to create a more descriptive title below, in Creating a descriptive alert title.

8. In the Create Alert tile, under Required Fields, select a Severity.

9. Scroll down to the Test tile, and click Add New.

   • Continue in Step 2: Create a test for the detection.

Step 2: Create a test for the detection

In Step 1, you defined your detection and clicked Add New under Test to begin the process of testing.

Below, you will generate test data for the action you wrote a detection for. In the example, we defined a detection to check for the action of deleting a detection in the Panther Console.

1. In a separate browser tab, open your Panther Console. Perform the action you wrote a detection for to generate a test audit log.

   • In the example above, we defined a detection to check for the action of deleting a detection in the Panther Console. For this example, you would follow these steps:

     1. Navigate to Build > Detections.

     2. Create a test detection.

     3. After successfully creating the detection, delete it.

2. In the left sidebar, click Investigate > Data Explorer.

3. Execute a query to find the audit log for the action you are testing against.

   • Based on our example, we will use the following query to check for the recently deleted detection:

     SELECT * FROM panther_logs.panther_audit WHERE actionName = 'DELETE_DETECTION'
     ORDER BY timestamp DESC
     LIMIT 1;

   • If no results are returned, wait a few minutes and retry.

4. Copy the JSON object in the Data Explorer results representing this log. Navigate back to the detection you defined, then paste the JSON object into the Test text editor.

5. Leave the The detection should trigger based on the example event toggle set to YES.

6. Click Run Test.

   • Verify that the detection runs as expected and the alert title appears as expected.

7. In the upper-right corner of the page, click Deploy.

Creating a descriptive alert title

In the example above, we used a simple alert title:

def title(event):
    return 'Detection deleted!'

You can construct a more descriptive alert title using the values found in the actionParams field within the audit log:

def title(event):
    deleted_detection_id = event.get('actionParams').get('input').get('detections')[0].get('id')
    actor_type = event.get('actor').get('type').lower()
    actor_readable_id = event.get('actor').get('name') if event.get('actor').get('name') else event.get('actor').get('id')
    return f"Detection '{deleted_detection_id}' deleted by {actor_type} {actor_readable_id}!"

See the log schema for more information on the audit log fields.

The actionParams field is different for each audited action. To understand what information is present in this field for a given action, query the data lake for audit logs for the given action and use the results to inform how you write detections for that action.