Integrating with Your SIEM
Guide to integrate Nightfall with a SIEM or push violations downstream to any alert drain, SOAR tool, BI tool, and more.
To integrate with a SIEM or push Nightfall alerts downstream, specify a webhook URL in your Nightfall console.
First, configure an incoming webhook in the tool you'd like to send Nightfall alerts into. For example, this could be Splunk, Sumo Logic, LogRhythm, Slack, PagerDuty, etc.
LogRhythm
SumoLogic
Splunk
For LogRhythm integration, initialize the Webhook Beat by following these instructions.
This process will provide you with an HTTPS URL endpoint (as seen in step 4c). Copy this URL as you will use it to complete set up.
For Sumo Logic integration, configure an HTTP Logs and Metrics Source via the following instructions.
This process will provide you with a URL endpoint (as seen in step 10). Copy this URL as you will use it to complete set up.
For a Splunk integration, configure an HTTP Event Collector within Splunk via the following instructions.
This process will provide you with a URL endpoint (as seen in this step). Copy this URL as you will use it to complete set up. Regarding authentication to the HTTP Event Collector, you can add your HEC Token as part of the query string of the Collector URL. This can be done for both Splunk Cloud as well as Enterprise. If you are a Splunk Cloud customer, you will have to reach out to Splunk to enable the "allowQueryStringAuth" flag for your Splunk Cloud instance. This can be done by raising a Support Ticket with Splunk.
Note: If a Splunk Cloud customer, this field can only be updated if on a Paid account. For a free/trial account, it will be unavailable.
For Splunk Enterprise, you will have to enable query string authentication for your instance, by following these steps:
Go to $SPLUNK_HOME/etc/apps/splunk_httpinput/local/inputs.conf file. Your tokens will appear by name in this file, in the form of http://<token_name>.
Within the stanza for each token you want to enable query string authentication, add or change the following setting:
1
allowQueryStringAuth = true
Copied!
Once the flag is enabled, please use the following steps to query the HEC Token within the URL String. For more information on Query string authentication from Splunk, please reference the docs here.
You can specify the HEC token as a query string in the URL that you specify in your queries to HEC. This can be done with the format shown below:
1
?token=<hec_token>
Copied!
The following example shows a full Collector URL including a dummy HEC Token appended as a query string: (The example is for an Enterprise instance)
Note: We will be using the /services/collector/raw endpoint instead of the /services/collector/event endpoint. This is because of the JSON format that webhooks from Nightfall will carry, which will only be accepted with the raw version of the HTTP Event Collector endpoint.
1
https://mysplunkserver.example.com:8088/services/collector/raw?token=12345678-1234-1234-1234-1234567890AB
Copied!

For Splunk Cloud Customers:

For Splunk Cloud customers, the above example URL will look different including the public facing HEC URL. The endpoint (/services/collector/raw?token=12345678-1234-1234-1234-1234567890AB) should remain the same, however. Since you are on a Splunk Cloud instance, this URL should already be visible to the Nightfall console, and you would be able to start using this Webhook URL in the Nightfall console. Please continue with the steps after this section to complete webhook set up.

For Splunk Enterprise Customers:

For Splunk Enterprise customers, there are a few extra steps to have the Splunk Collector exposed to the Nightfall webhook console below.
The next step will be exposing the local host and port of the Splunk collector an HTTP Listening tool. This can be done by using an ngrok tunnel or nginx server, for example This is required so that the Enterprise Splunk instance is accessible to Nightfall's webhook from the console. Please make sure that port 8088 (this is the default port for receiving data for HEC) is accessible by navigating to "Global settings" in your Splunk Enterprise instance and enabling it.
Steps for setting up a ngrok tunnel can be found here. If using a ngrok tunnel, the following command would generate a ngrok tunnel listening to the correct port and protocol for the collector:
./ngrok http https://localhost:8088
Once complete, the ngrok tunnel should show you an HTTPS Forwarding address, that can be used as the ngrok host in the following step. (HTTPS is required by Nightfall's webhook URL validation)
Your ngrok tunnel URL with your HEC auth token should now look something like this:
This will be your Webhook URL that you can use in the Nightfall console. Now you are all set to integrate alerts from your Nightfall webhook to your ngrok tunnel.
Next, configure the outgoing webhook in Nightfall. This webhook will fire in real-time upon a new event (e.g. a new violation is created).
Navigate to the integration for which you would be interested in setting up a webhook for alerts: (Currently Webhooks are available for Slack, Google Drive, Jira, and Github)
Select the Settings tab on the top. (For the Github integrations, you will find the Alerting options on the bottom of the Policy page)
Select Change or Add next to the Webhook option.
Enter your webhook endpoint URL. Click Test to send a sample payload to the endpoint that you use to verify a successful connection.
Going forward, you will now see events sent directly from Nightfall into your SIEM or other solution of choice!
The following are examples of a sample payload for detection rules that were violated, that will be delivered to the webhook. These are examples from each integration, so the specific fields may vary based on the Nightfall product you are using (e.g. Slack, Github, Google Drive Jira, etc.).
Slack
Github
Google Drive
Jira
1
{
2
"detectionRulesLink": "https://app.nightfall.ai/detection-engine/detection-rules/",
3
"detectionRulesViolated": [
4
"test demo multi integration rule"
5
],
6
"eventType": "violation",
7
"message": "ID 18eb99 - Suspicious Policy violation detected.",
8
"policiesLink": "https://app.nightfall.ai/slack/policies",
9
"policiesViolated": [
10
"sample data testing"
11
],
12
"service": "slack",
13
"timestamp": "2022-01-26T22:59:17Z",
14
"violationId": "18eb99",
15
"violationMetadata": {
16
"channel": "general",
17
"contentType": "message",
18
"fileName": "",
19
"fileType": "",
20
"findings": {
21
"US social security number (SSN)": {
22
"Very_likely": 1
23
}
24
},
25
"permalink": "https://testworkspace-lkr9864.slack.com/archives/C025N9L0HU6/p1643237955018169",
26
"sender": "arslan_test",
27
"snippet": "Here is the customer ssn: 48*********",
28
"workspace": ""
29
},
30
"violationTime": "2022-01-26 22:59:15.018168832 +0000 UTC"
31
}
Copied!
1
{
2
"detectionRulesLink": "https://app.nightfall.ai/detection-engine/detection-rules",
3
"detectionRulesViolated": [
4
"dcc6dd2e-0177-4110-ab3d-0778cc1e76d2"
5
],
6
"eventType": "violation",
7
"message": "Policy Violation Detected",
8
"policiesLink": "https://app.nightfall.ai/github/policies",
9
"policiesViolated": [
10
"8478f262-e54d-423d-b63f-a3e322329eaf"
11
],
12
"service": "github",
13
"timestamp": "2022-01-26T23:05:35Z",
14
"violationId": "6d6639f0-6deb-4b81-ac89-59b4cf9448f4",
15
"violationMetadata": {
16
"authorEmail": "[email protected]",
17
"branchName": "main",
18
"commitRef": "11755af67b8ef514ce6f3ce13864cce69bbd2b24",
19
"confidence": "Very Likely",
20
"contentType": "commit",
21
"detector": "US social security number (SSN)",
22
"filePath": "traptext.txt",
23
"lineRangeEnd": 18,
24
"lineRangeStart": 18,
25
"organizationName": "test-org-aawan",
26
"repositoryName": "tst-secret-scan",
27
"violationLink": "https://app.nightfall.ai/github/violations/6d6639f0-6deb-4b81-ac89-59b4cf9448f4"
28
},
29
"violationTime": "2022-01-26T23:05:34Z"
30
}
Copied!
1
{
2
"detectionRulesLink": "https://app.nightfall.ai/?intendedRoute=detection-engine/detection-rules",
3
"detectionRulesViolated": "High Risk, Likely",
4
"eventType": "violation",
5
"message": "Policy violation detected in Google Drive",
6
"policiesLink": "https://app.nightfall.ai/?intendedRoute=google-drive-dlp/?policyUUID%5B%5D=d9c8cf04-b142-4bf6-b357-f4d1d3a3ea43",
7
"policiesViolated": "High Risk - Internally Shared",
8
"service": "GDrive",
9
"timestamp": "2022-01-26T23:13:05Z",
10
"violationID": "L5VJVL",
11
"violationMetadata": {
12
"actionLinks": "{\"acknowledge\":\"\",\"changeToDomain\":\"\",\"changeToRestricted\":\"https://app.nightfall.ai/?intendedRoute=google-drive-dlp/remediation/1dom27DWkoOBzTOmmGD7uc0jXQ0B7jJPyBsD_nQi3150/L5VJVL/restrict_file\",\"removeExternalUsers\":\"\",\"removeInternalUsers\":\"https://app.nightfall.ai/?intendedRoute=google-drive-dlp/remediation/1dom27DWkoOBzTOmmGD7uc0jXQ0B7jJPyBsD_nQi3150/L5VJVL/remove_internal_users\",\"notifyOwnerViaSlack\":\"https://app.nightfall.ai/?intendedRoute=google-drive-dlp/remediation/1dom27DWkoOBzTOmmGD7uc0jXQ0B7jJPyBsD_nQi3150/L5VJVL/notify_owner_slack\",\"notifyOwnerViaEmail\":\"https://app.nightfall.ai/?intendedRoute=google-drive-dlp/remediation/1dom27DWkoOBzTOmmGD7uc0jXQ0B7jJPyBsD_nQi3150/L5VJVL/notify_owner_email\"}",
13
"existingFindings": "{\"Credit card number\":{\"VERY_LIKELY\":1}}",
14
"fileName": "Test trap document",
15
"fileOwner": "",
16
"linkSettings": "Anyone in the organization with the link (viewer)",
17
"newFindings": "{\"US social security number (SSN)\":{\"VERY_LIKELY\":3}}",
18
"permalink": "https://docs.google.com/document/d/1dom27DWkoOBzTOmmGD7uc0jXQ0B7jJPyBsD_nQi3150/edit?usp=drivesdk",
19
"sharedDriveLink": "https://drive.google.com/drive/u/1/folders/0AC1lS8wgV2C-Uk9PVA",
20
"sharedDriveName": "Engineering",
21
"sharedWith": "1 internal users ([email protected])"
22
},
23
"violationTime": "26 Jan 2022 at 11:11PM UTC"
24
}
Copied!
1
{
2
"detectionRulesLink": "https://app.nightfall.ai/?intendedRoute=detection-engine/detection-rules",
3
"detectionRulesViolated": "High Risk, Likely",
4
"eventType": "violation",
5
"message": "Policy violation detected in Jira",
6
"policiesLink": "https://app.nightfall.ai/?intendedRoute=jira-dlp/?policyUUID%5B%5D=eee4b5e3-ebe6-4450-8878-593f3f486387",
7
"policiesViolated": "Customer Service",
8
"service": "Jira",
9
"timestamp": "2022-01-26T23:10:16Z",
10
"violationID": "MJNY6O",
11
"violationMetadata": {
12
"fields": "Description",
13
"findings": "{\"US social security number (SSN)\":{\"VERY_LIKELY\":1}}",
14
"issueKey": "CS-5",
15
"issueName": "test",
16
"jiraEventType": "Issue Updated",
17
"permalink": "https://nightfall-gtm.atlassian.net/browse/CS-5",
18
"project": "Customer Service (CS)",
19
"projectType": "Software project",
20
"who": "Arslan Awan"
21
},
22
"violationTime": "26 Jan 2022 at 11:10PM UTC"
23
}
Copied!
The following are examples of a sample payload for remediations/actions that were taken on the above mentioned violations, that will be delivered to the webhook. These are examples from each integration, so the specific fields may vary based on the Nightfall product you are using (e.g. Slack, Github, Google Drive Jira, etc.).
Slack
Google Drive
1
{
2
"eventType": "remediation",
3
"message": "Re: ID 2ec0a7 - Successfully quarantined suspicious message posted by Tehreem Tungekar (tehreem) in #project.",
4
"remediationMetadata": {
5
"actionType": "quarantine",
6
"actionUser": "tehreem",
7
"remediationType": "manual"
8
},
9
"remediationTime": "2022-02-01 18:21:24.173819136 +0000 UTC",
10
"service": "slack",
11
"timestamp": "2022-02-01T18:22:25Z",
12
"violationId": "2ec0a7"
13
}
Copied!
1
{
2
"eventType": "remediation",
3
"message": "Made file restricted",
4
"remediationMetadata": {
5
"actionType": "restrict_file",
6
"actionUser": "[email protected]",
7
"remediationType": "manual"
8
},
9
"remediationTime": "24 Jan 2022 at 11:54PM UTC",
10
"service": "GDrive",
11
"timestamp": "2022-01-24T23:54:11Z",
12
"violationID": "TGMGNQ"
13
}
Copied!
Copy link