Using Policies
Policies allow customers to create templates for their most common workflows 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 scanning 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": "[email protected]"
}
}
},
"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": [
"",
""
]
}
policy vs. policyUUIDs vs. config
The
policy
object supersedes theconfig
object. The use ofconfig
objects will still continue to be supported, but its use should be considered deprecated. If you specifypolicy
object you cannot also specify aconfig
object.Also note that previous iterations of the API allowed for a simple list of
policyUUIDs
to be specified instead of of apolicy
object. This has been preserved for backwards compatibility, but it is recommended you use thepolicy
object as it has a richer set of features. You may not use both apolicyUUIDs
list and apolicy
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 [email protected]
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 URL must be an HTTPS URL configured 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 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.
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": "[email protected]"
}
}
},
"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.
Updated 8 days ago