Using Policies to Send Alerts

Policies allow customers to create templates for their most common workflows such as sending alerts when detection rules are triggered.

These policies may be created manually through the dashboard or may be defined programmatically.

When defining an a Policy inline, in addition to specifying the Detection Rules (either by referencing the UUID of an existing Detection Rule or defining a Detection Rule and its Detectors inline), you must define an alertConfig which will determine where findings are sent.

The alertConfig can be either:

• an email address

• a Slack channel

• a webhook url

• a url to a SIEM host as well authentication and other headers

Below is a simple example of a payload with a policy that will send alerts to an email address that you would use with our endpoint for Scan Plain Text.

{     
  "policy": {
    "detectionRules": [
               {
                    "detectors": [
                        {
                            "detectorType": "NIGHTFALL_DETECTOR",
                            "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER",
                            "minNumFindings": 1,
                            "minConfidence": "LIKELY",
                            "displayName": "US Social Security Number"
                        }
                    ],
                    "name": "SSN Match Detection Rule",
                    "logicalOp": "ALL"
               }
          ],
    "contextBytes": 5,
    "alertConfig": {
      "email": {
        "address": "[e-mail]"
      }
    }
  },
  "payload": [
        "The customer's social security number is 555-55-5555",
        "No SSN in this string"
   ]
}

You will receive the following response:

{
    "findings": [
        [
            {
                "finding": "555-55-5555",
                "beforeContext": "r is ",
                "detector": {
                    "name": "US Social Security Number",
                    "uuid": "e30d9a87-f6c7-46b9-a8f4-16547901e069"
                },
                "confidence": "VERY_LIKELY",
                "location": {
                    "byteRange": {
                        "start": 41,
                        "end": 52
                    },
                    "codepointRange": {
                        "start": 41,
                        "end": 52
                    },
                    "rowRange": null,
                    "columnRange": null,
                    "commitHash": ""
                },
                "matchedDetectionRuleUUIDs": [],
                "matchedDetectionRules": [
                    "SSN Match Detection Rule"
                ]
            }
        ],
        []
    ],
    "redactedPayload": [
        "",
        ""
    ]
}

Note that you may also use a pre-defined policy defined under Developer Platform > Overview > Policies by copying the Policy UUID and sending a request as shown below.

curl --request POST \
     --url https://api.nightfall.ai/v3/scan \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <InsertYourApiKeyHere>' \
     --header 'content-type: application/json' \
     --data '
{
     "policyUUIDs": [
          "2b2ced32-80c3-4a89-8757-489743ec4640"
     ],
     "payload": [
          "My payload to scan"
     ]
}
'

policy vs. policyUUIDs vs. config

The policy object supersedes the config object. The use of config objects will still continue to be supported, but its use should be considered deprecated. If you specify policy object you cannot also specify a config object.

Also note that previous iterations of the API allowed for a simple list of policyUUIDs to be specified instead of of a policy object. This has been preserved for backwards compatibility, but it is recommended you use the policy object as it has a richer set of features. You may not use both a policyUUIDs list and a policy object.

The following payload will be sent to the given email address with the subject "🚨 Findings Detected by Nightfall! 🚨" as an attachment with the name nightfall-findings.json:

{
  "redactedPayload": [
    "", 
    ""
  ], 
  "findings": [
    [
      {
        "confidence": "LIKELY", 
        "matchedDetectionRules": [
          "SSN Match Detection Rule"
        ], 
        "matchedDetectionRuleUUIDs": [], 
        "location": {
          "codepointRange": {
            "start": 41, 
            "end": 52
          }, 
          "rowRange": null, 
          "byteRange": {
            "start": 41, 
            "end": 52
          }, 
          "columnRange": null, 
          "commitHash": ""
        }, 
        "finding": "555-55-5555", 
        "detector": {
          "name": "SSN Match Detector", 
          "uuid": "7270ccd5-07c5-44e5-b280-c768e0028963"
        }, 
        "beforeContext": "r is "
      }
    ], 
    []
  ]
}

This attachment has the same content as the response payload to the initial request.

Note that the sender address will be [e-mail]

This email address will not respond to messages sent to it.

Using Webhooks with Policies

Policies also allow you to send findings to a callback designated URL using the url property of the alertConfig object.

This mechanism allows you to programmatically consume findings and the data sent will contain sensitive information as well as additional metadata like the location of the findings in the payload. For this reason the URL must be an HTTPS URL and the service backing it be implemented to properly respond with your Webhook signing key and act as a Webhook Server.

Below is what Webhook URL should like in your policy's alertConfig in a payload sent to our endpoint used for scanning plain text.

{     
  "policy": {
    "detectionRuleUUIDs": [
      "c8d43147-0a63-4c01-8a57-83d8108422f5"
    ],
    "alertConfig": {
        "url": {
            "address": "https://mywebhookurl.com"
        }
    }
  },
  "payload": [
        "The customer's social security number is 555-55-5555"
   ]
}

Using Slack Channels With Policies

Another option supported by Policies is sending finding data to a designated Slack channel.

This feature requires that you have configured the Nightfall Slack integration.

Below is a sample payload for scanning plain text.

{     
     "policy": {
          "detectionRules": [
               {
                    "detectors": [
                        {
                            "detectorType": "NIGHTFALL_DETECTOR",
                            "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER",
                            "minNumFindings": 1,
                            "minConfidence": "LIKELY",
                            "displayName": "US Social Security Number"
                        }
                    ],
                    "name": "Simple SSN Match Detection Rule",
                    "logicalOp": "ALL"
               }
          ],
        "alertConfig": {
            "slack": {
                "target": "#securityalert"
            }
        }
    },
     "payload": [
          "The customer's social security number is 555-55-5555",
          "No SSN in this string"
     ]
}

Below is an example as to how the violation will appear in Slack.

See the section on Slack in the overview on Alerting for more details.

Sending Alerts to SIEMs and other HTTP Event Collectors

SIEM (pronounced “sim”) is a combination of security information management (SIM) and security event management systems. SIEM technology collects event log data for analysis in order to provide visibility into network activity.

It is possible to send findings from a policy to a SIEM service such as LogRhythm, SumoLogic, or Splunk using the siem alertConfig.

This configuration will require a URL to a collector that uses an HTTPS endpoint.

Note that the URL for the siem alertConfig must:

• use the HTTPS scheme

• be able to accept requests made with the POST verb

• respond with a 200 status code upon receipt of the event

See the documentation for your SIEM service for how to set up this URL.

• LogRhythm

• Sumo Logic

• Splunk

Unlike the url alertConfig option, the siem alertConfig does not require that the endpoint for the service implement a custom challenge response. Events sent to the siem alertConfig endpoint contain a subset of what is sent to the url alertConfig. Furthermore the findings are sent in a redacted form similar to Slack or email alerts.

In addition to the URL, you may provide headers such as those that are used for authorization.

The headers in the SIEM alertConfig are divided into sensitiveHeaders and plainTextHeaders header mappings.

The sensitiveHeaders field is specifically for header values like authentication. Nightfall ensures that these header values are always hidden in our service. They are never logged or saved in analytic events.

You can use plainTextHeaders for all other type of information you would like passed along with Nightfall alerts to you HTTP endpoint. Nightfall assumes that the values stored plainTextHeaders do not contain any sensitive information so we do not take any action to hide or protect these values.

Below is an example of a payload using a siem alertConfig.

{
     "policy": {
          "detectionRules": [
               {
                    "detectors": [
                         {
                              "nightfallDetector": "CREDIT_CARD_NUMBER",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "minConfidence": "POSSIBLE",
                              "minNumFindings": 1
                         }
                    ],
                    "logicalOp": "ALL"
               }
          ],
		"alertConfig": {
		   "email": {
			"address": "<your email>"
		   },
		   "siem": {
				"sensitiveHeaders": {
					 "Authorization": "Splunk <your token value>"
				},
				"address": "https://http-inputs-<yourhost>.splunkcloud.com:8088/services/collector/event"
		   }
		}
     },
     "payload": [
          "4916-6734-7572-5015 is my credit card number",
          "This string does not have any sensitive data",
          "my api key is yr+ZWwIZp6ifFgaHV8410b2BxbRt5QiAj1EZx1qj and my 💳 credit card number 💰 is 30204861594838"
     ]
}

Other Policy Features

Using Redaction Within a Policy

A policy may be configured with default redaction rules as a defaultRedactionConfig that will affect the content of the redactedPayload field of the content that is sent to the alert locations specified in the policy alertConfig. Note that this redaction does not affect the findings themselves.

These redaction rules will be applied to Detection Rules that do not have a specified redaction configuration.

The redactionConfig specified must be one and only one of the four available redaction types:

• maskConfig

• infoTypeSubstitutionConfig

• substitutionConfig

• cryptoConfig

For more information on Redactions see: Using Redaction

Below is a simple example of a payload for scanning plain text using a policy set up to use a defaultRedactionConfig

{
  "policy": {
    "detectionRules": [
      {
        "detectors": [
          {
            "detectorType": "NIGHTFALL_DETECTOR",
            "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER",
            "minNumFindings": 1,
            "minConfidence": "LIKELY",
            "displayName": "US Social Security Number"
          }
        ],
        "name": "Simple SSN Match Detection Rule",
        "logicalOp": "ALL"
      }
    ],
      "defaultRedactionConfig": {
        "maskConfig": {
          "charsToIgnore": [
            "-"
          ],   
            "maskingChar": "#",
              "numCharsToLeaveUnmasked": 4,
                "maskLeftToRight": true
        }
      },
        "contextBytes": 5,
          "alertConfig": {
            "email": {
              "address": "[e-mail]"
            }
          }
  },
    "payload": [
      "The customers social security number is 555-55-5555",
      "No SSN in this string"
    ]
}

Using Context Bytes Within a Policy

In additional to a defaultRedactionConfig it is possible to set the number of bytes to include as before and after a given finding as the contextBytes. This context can provide meaning to how the finding appears within the text to allow human readers to better understand the meaning of the finding. The maximum value for contextBytes is 40.