Basic Usage (Ruby)

This guide describes how to use Nightfall with the Ruby programming language.

The example below will demonstrate how to use Nightfall’s text scanning functionality to verify whether a string contains sensitive PII using the Nightfall Python SDK.

Prerequisites

To follow along, you will need:

A Nightfall API Key
An existing Detection Rule
Data to scan. Note that the API interprets data as plaintext, so you may pass it in any structured or unstructured format.
A local Ruby 2.6 or greater environment.

Code Walkthrough

Start by creating a new file called nightfall_demo.rb

Now we will walk through the code step by step. If you'd like to skip ahead you can see the complete code sample at the bottom of this page.

We will be using a few built-in Ruby libraries to run this sample API script.

# Load dependencies
require 'open-uri'
require 'net/http'
require 'json'

First, we will load some environment variables that will be used to interact with the Nightfall API. NIGHTFALL_API_KEY should be your Nightfall API Key, and NIGHTFALL_DETECTION_RULE_UUID should be the UUID for your existing Nightfall condition set.

# Load environment variables for Nightfall API
nightfall_api_key = ENV['NIGHTFALL_API_KEY']
detection_rule_uuid = ENV['NIGHTFALL_DETECTION_RULE_UUID']

Next, we will construct our payload to scan as an array. You can replace this with any data you'd like, or read plaintext from a file.

# Text data to scan
payload = [
    "The customer social security number is 458-02-6124",
    "No PII in this string",
    "My credit card number is 4916-6734-7572-5015"
]

Next, we build the HTTP request headers and body using the environment variables that we previously defined.

# Configure detection settings
config = { 
	"config": {
		"detectionRuleUUIDs": [detection_rule_uuid]
	},
	"payload": payload
}

Next, we build the HTTP object and make a request to the Nightfall API.

# Build API request
url = URI("https://api.nightfall.ai/v3/scan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Authorization"] = "Bearer #{nightfall_api_key}"
request.body = config.to_json

Lastly, we make the API request and process the response from Nightfall. If there are sensitive findings in the response we pretty-print them to the console. If there are no findings, we print a message to the console. Otherwise, if there is a problem with the HTTP request we print the status code and message to the console.

# Make API request
response = http.request(request)

# Parse response
if response.code.to_i == 200 and response.body['findings']
    puts "This text contains sensitive data.\n\n"
    puts JSON.pretty_generate(JSON.parse(response.body))
elsif response.code.to_i == 200
    puts "No sensitive data found. Hooray!"
else
    puts "Something went wrong -- Response #{response.code}."
end

Usage

Now we can run our script:

ruby nightfall_demo.rb

If there are sensitive findings based on your Nightfall detection rule, you should see output similar to this in your console, corresponding to each of the 3 items inputted to scan in the payload.

This text contains sensitive data.

{
  "findings": [
    [
      {
        "finding": "458-02-6124",
        "detector": {
          "name": "US social security number (SSN)",
          "uuid": "e30d9a87-f6c7-46b9-a8f4-16547901e069"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 39,
            "end": 50
          },
          "codepointRange": {
            "start": 39,
            "end": 50
          }
        },
        "matchedDetectionRuleUUIDs": [
          "996a3c12-35d1-48cb-b858-5ee0841c652d"
        ],
        "matchedDetectionRules": [

        ]
      }
    ],
    [

    ],
    [
      {
        "finding": "4916-6734-7572-5015",
        "detector": {
          "name": "Credit card number",
          "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 25,
            "end": 44
          },
          "codepointRange": {
            "start": 25,
            "end": 44
          }
        },
        "matchedDetectionRuleUUIDs": [
          "996a3c12-35d1-48cb-b858-5ee0841c652d"
        ],
        "matchedDetectionRules": [

        ]
      }
    ]
  ],
  "redactedPayload": [
    "",
    "",
    ""
  ]
}

Congrats! You've successfully scanned text for sensitive data with Ruby using the Nightfall API.

Complete Code Sample

For your convenience, the complete Ruby code sample is shown below.

# Load dependencies
require 'open-uri'
require 'net/http'
require 'json'

# Load environment variables for Nightfall API
nightfall_api_key = ENV['NIGHTFALL_API_KEY']
detection_rule_uuid = ENV['NIGHTFALL_DETECTION_RULE_UUID']

# Text data to scan
payload = [
    "The customer social security number is 458-02-6124",
    "No PII in this string",
    "My credit card number is 4916-6734-7572-5015"
]

# Configure detection settings
config = { 
	"config": {
		"detectionRuleUUIDs": [detection_rule_uuid]
	},
	"payload": payload
}

# Build API request
url = URI("https://api.nightfall.ai/v3/scan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Authorization"] = "Bearer #{nightfall_api_key}"
request.body = config.to_json

# Make API request
response = http.request(request)

# Parse response
if response.code.to_i == 200 and response.body['findings']
    puts "This text contains sensitive data.\n\n"
    puts JSON.pretty_generate(JSON.parse(response.body))
elsif response.code.to_i == 200
    puts "No sensitive data found. Hooray!"
else
    puts "Something went wrong -- Response #{response.code}."
end