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 scanning plain text.
You will receive the following response:
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.
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
:
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 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.
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.
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.
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.
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
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.
Last updated