Alerting

Nightfall has the ability to send alerts when a policy violation is detected.

Policies for alerting may be configured through the Nightfall app user interface or they may be set up programmatically. Policies that are configured under Developer Platform > Overview > Policies may be used in the API by referencing their Policy UUID.

The way that an alert notification presents itself depends on the platform in question.

For example, notifications sent to Slack will appear as formatted messages sent by the Nightfall Alerts Bot. Other destinations such as email, SIEM url, and webhooks, will present the information as JSON objects.

In the case of webhooks, detailed information about the finding will be sent. For other destinations, sensitive information is redacted.

Supported Alert Platforms

Slack

In order to use asynchronous notifications with Slack, you must install the Nightfall Alerts plugin from the Slack Marketplace.

See our end user documentation on installing Nightfall for Slack for more details.

Once you have authenticated Nightfall to your Slack workspace, you can provide any public channel name (e.g. #general) as part of a request to the Nightfall API.

To send notifications to a private channel, a member of the channel should invite the Nightfall bot to the specific private channel and allow channel access to the bot.

Follow the steps below to invite Nightfall Alerts bot to a private channel:

1. Go to the Slack channel in question

2. Type /invite @Nightfall Alerts as a message

3. Press 'Enter' (you should see a message that Nightfall Alerts has now joined the channel)

If any findings are detected as part of that request, then the Nightfall Alerts bot will send a message to the channel you configured. Conversely, if there are no findings in the request payload, then Nightfall will not send an alert message.

Teams

Documentation TBD

Email

Email is unauthenticated, so you can get started using Nightfall to send email alerts without any initial setup work.

Nightfall will send an email to the provided address only if findings were detected as part of the request. The findings themselves will be attached in a JSON file.

SIEM

You may send your alerts to a designated url, such as an endpoint hosted by SIEM software for log collection.

In addition to the url, you may provide headers, either for security or logging purposes.

See integrating with SIEM in our end user guide or our API documentation on using policies for more details.

Webhook

You may use a webhook server to programmatically handle a finding, allowing you to create your own custom workflows with your own or 3rd party systems.

Nightfall will always send an alert to the client's webhook server if it is provided as part of an API request, even if the scan request yielded no findings.

See Creating a Webhook Server for more details.

Alert Schemas

The request body sent by Nightfall is JSON, and uses the schemas in the section documented below.

File Scans

Since file scans can produce a large number of results, findings are not transmitted directly in the notification that Nightfall sends. The notification object looks like the following:

{
  "errors": [],
  "findingsPresent": true,
  "findingsURL": "https://files.nightfall.ai/877442c5-1573-4637-a223-595bf620e3e5.json?Expires=1645722381&Signature=C-kQbtonFAPXfooGcm0dYgbsn9jfGu~vGSv5yK5j1z2f7aAhk0WuaL4bISUwx5MZkQmPVFgeyMwemvEoI8aI11lPA-ORsX5LtRdGJBOma4sPVl~9f9qBPKE2VSrdGDmT4EpBLc8ewUtKrLm2xE-0BzW~5PdLSvZ~NQxtB7OMBaYm7h~y2NSUZfpqzdzENyKhyHx5QxH2PJvxeN5IvMXqNUrKyZsxviSYY6kDNAiGExS-u6PmKKS1GhXOaFLdJSRjgtFhUxDLyWl~xTYR-lJol5UTgtcuYU8AaJ3xVTF1-1JYRlioRlaf9shAvme4djFyg8k~zOB8bYgzBeaRqSjeWA__&Key-Pair-Id=K3RYMP51FKX5HX",
  "requestMetadata": "some data",
  "uploadID": "877442c5-1573-4637-a223-595bf620e3e5",
  "validUntil": "2022-02-24T17:06:21.412377682Z"
}

The requestMetadata field contains arbitrary contents provided by the client at request time, and can be used by the client to correlate this response to the original request.

The value of the findingsURL field is a pre-signed URL, which means anyone with the link can download the file. Therefore, this URL itself should be treated as sensitive and must not be leaked. The object stored at this URL is a JSON file containing a single key findings containing a list of all data detected from the request. The schema for the finding object inside the list is shared between the text-based and file-based API endpoints.

{
  "findings": [
    {
      "detector": {
        "id": "74d1315e-c0c3-4ef5-8b1e-6cf98664a854"
      },
      "finding": "4242-4242-4242-4242",
      "confidence": "VERY_LIKELY",
      "location": {
        "byteRange": {
          "start": 146,
          "end": 165
        },
        "codepointRange": {
          "start": 146,
          "end": 165
        },
        "lineRange": {
          "start": 3,
          "end": 3
        },
        "rowRange": null,
        "columnRange": null,
        "commitHash": ""
      },
      "beforeContext": "nd HIPAA Defined PII\nHIPAA HIPAA hooray\n",
      "afterContext": " is my credit card number\n\n",
      "matchedDetectionRuleUUIDs": ["7bd6166a-b9af-4069-847d-487a88788122"],
      "matchedDetectionRules": []
    } 
  ]    
}

Text Scans

The payload that is forwarded on behalf of text scanning requests is identical to the response body that is synchronously returned to the client. Refer to the API docs for more details on this payload.

{
  "findings": [
    [
      {
        "finding": "4242-4242-4242-4242",
        "beforeContext": "hello world cc ",
        "detector": {
          "name": "Credit card number",
          "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 15,
            "end": 34
          },
          "codepointRange": {
            "start": 15,
            "end": 34
          },
          "rowRange": null,
          "columnRange": null,
          "commitHash": ""
        },
        "matchedDetectionRuleUUIDs": [
          "42efe36c-6479-412a-9049-fd8cdf895ced"
        ],
        "matchedDetectionRules": []
      }
    ]
  ],
  "redactedPayload": [""]
}