# 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](https://help.nightfall.ai/developer-api/key-concepts/setup/policies) 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](https://help.nightfall.ai/developer-api/key-concepts/scanning_features/inline_detection_rules)), 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 [Broken link](https://help.nightfall.ai/developer-api/key-concepts/scanning_features/broken-reference "mention"). ```json { "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": "youremail@nightfall.ai" } } }, "payload": [ "The customer's social security number is 555-55-5555", "No SSN in this string" ] } ``` You will receive the following response: ```json { "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. ```sh curl --request POST \ --url https://api.nightfall.ai/v3/scan \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "policyUUIDs": [ "2b2ced32-80c3-4a89-8757-489743ec4640" ], "payload": [ "My payload to scan" ] } ' ``` {% hint style="info" %} ### 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. {% endhint %} 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`: ```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 `no-reply@nightfall.ai` 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](https://docs.nightfall.ai/docs/webhook-signing-key)[ ](https://help.nightfall.ai/developer-api/key-concepts/file_scan/webhooks_async_notifications/webhook_signing_key)and act as a [Webhook Server](https://docs.nightfall.ai/docs/creating-a-webhook-server)[.](https://help.nightfall.ai/developer-api/key-concepts/file_scan/webhooks_async_notifications/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. ```json { "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](https://help.nightfall.ai/nightfall-for-slack/installation-instructions-nightfall-for-slack). Below is a sample payload for scanning plain text. ```json { "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](https://help.nightfall.ai/developer-api/alerting#slack) 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](https://docs.logrhythm.com/docs/OCbeats/webhook-beat/initialize-the-webhook-beat) * [Sumo Logic](https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source) * [Splunk](https://docs.splunk.com/Documentation/Splunk/8.2.2/Data/UsetheHTTPEventCollector) 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. ```json { "policy": { "detectionRules": [ { "detectors": [ { "nightfallDetector": "CREDIT_CARD_NUMBER", "detectorType": "NIGHTFALL_DETECTOR", "minConfidence": "POSSIBLE", "minNumFindings": 1 } ], "logicalOp": "ALL" } ], "alertConfig": { "email": { "address": "" }, "siem": { "sensitiveHeaders": { "Authorization": "Splunk " }, "address": "https://http-inputs-.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](https://help.nightfall.ai/developer-api/key-concepts/scanning_features/redaction) Below is a simple example of a payload for [scanning plain text](https://help.nightfall.ai/nightfall-firewall-for-ai/key-concepts/scanning-text) using a policy set up to use a `defaultRedactionConfig` ```json { "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": "eric@nightfall.ai" } } }, "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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.nightfall.ai/developer-api/key-concepts/scanning_features/send_alerts_using_policies.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.