Help centerLog inStart for free

Using Policies

Suggest Edits

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 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 [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