Radar API Documentation

With Nightfall (fka Watchtower)'s Radar API, you can scan GitHub repositories for sensitive credentials & secrets, like API keys for services like AWS, Twilio, and Stripe. Nightfall's detectors are built via machine learning, so you'll receive more accurate, less noisy results than traditional approaches like regular expressions or high-entropy string detection. There's also no need to specify what exact types of keys or credentials you're looking for - Nightfall will discover a very broad set of secrets. All scan results are also accessible in our dashboard UI, in case you'd prefer to access results visually rather than programatically. Nightfall does not store or track sensitive findings.

Authentication

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Start a New Scan

Scan a GitHub repository for sensitive credentials or secrets. The repo can be public or private. If this repo is private, you must have access to it via the GitHub account that you've logged in to Nightfall with. By default, users are limited to 5 completed scans. You can check your current scan usage on your Settings page. The full commit history of the repository will be scanned, irrespective of its size.

Note that scans are run asynchronously. This means that this endpoint will respond immediately upon starting the scan with a Scan ID. You can use this Scan ID to retrieve the results when ready via the API call below, Get Scan Results. You will be notified via email, and optionally at your Webhook endpoint explained below, when the scan is complete and results are ready for your retrieval.

Arguments:

github_url - Required. URL to a GitHub repository to scan with 1000 or fewer commits, for example: https://github.com/nightfalldlp/sample

Returns:

status - The status of the scan. One of Running, Error, Scan Limit Exceeded, or Usage Error.

message - Message regarding status of the scan.

scan_id - Identifier for the scan. You can use this identifier to get scan results, see Get Scan Results below.

Get Scan Results

scan_id - Required. The identifier of the scan for which results are being retrieved.

Returns:

scan_id - Identifier of the scan.

url - URL of GitHub that was scanned.

duration - Duration of scan in seconds.

created_at - Date/time of when scan was initiated.

scanned_files - Number of files scanned in repo.

status_code - Status of the scan. Conventional HTTP response code. Codes in the 2xx indicate success. Codes in the 4xx range indicate a failure given the information provided. Codes in the 5xx range indicate an error with Nightfall's servers (these are rare).

results_count - Number of scan results.

results - An array of Result objects. There is one Result object for each sensitive token string (API key, credential, etc.) that is found. Each Result object has the following attributes:

result_id - Identifier of the result.

repo_path - Path of the repository in which the result was found.

file_path - Path of the file in which the result was found.

branch - Branch name in which the result was found.

commit_hash - Commit hash in GitHub repo.

author_email - Author of the commit.

context - The preceding characters before the sensitive token.

token - Redacted sensitive token that was discovered.

token_length - Length, in number of characters, of the sensitive token found.

permalink - A permalink to the exact line of the sensitive finding in GitHub.

Webhook Endpoint

You can register a webhook URL for Nightfall to notify you when a scan is completed and results are ready for you to retrieve. When a scan is completed, Nightfall creates an Event object.

This Event object contains relevant information about the Scan. Nightfall then sends the Event object, via an HTTP POST request, to the webhook URL that you have defined on your Settings page.

To set up an endpoint, you need to define a route on your server for receiving events and configure your Webhook URL on your Settings page so Nightfall knows where to POST events.

Event Object

Attributes:

status - Conventional HTTP response code indicating the status of the scan. If the code is 2xx it indicates success, and you can use the scan_id to get the scan's results via the Get Scan Results endpoint, described above.

scan_id - Identifier of the scan.

duration - Duration of the scan in seconds.

url - URL of the GitHub repo that was scanned.

Sample Event

Ignoring Tokens via Blacklist

Blacklisting is the concept of curating a list of objects to either avoid or ignore. In the context of Radar, items on the blacklist will be ignored when displaying scan results for a repository. For example, let’s say there is a test API key in your repository that you do not want to get flagged by Radar - you can add it to the blacklist. The blacklist applies on a global, account level and will affect all subsequent scans for all repos.

Blacklisting can be performed on two Key Types (specified by the key_type parameter below): individual tokens (where the Key Type is api_key) or on an entire file/directory level (where the Key Type is subpath). As an example of api_key blacklisting, you could ignore the token “test_api_key” individually. As an example of subpath blacklisting, you could specify that the file “test_keys.py” is ignored completely. The inputs for a subpath start at the root of the repo and can be a specific file, blob, or directory.

File path: /path/to/file/to/ignore.py

Directory path: /path/to/some/test/directory/*

Get Blacklist

Returns an array of items to be blacklisted. This array will be filtered based on the type of key you are adding to the blacklist (key_type), as described above.

Arguments:

key_type - Required. The type of key to blacklist, value is one of (a) api_key, corresponding to an individual token, or (b) subpath, corresponding to an entire file/directory.

Returns:

status - The status of the request. One of Success or Error.

blacklist - An array of items currently in the blacklist, corresponding to the key type specified in the request.

If you would like to automatically scan all of your organization's repos on a fixed schedule (e.g. weekly or monthly), this is a feature we can enable for you. Once enabled, scans will trigger on your set cadence, and results will automatically populate in your dashboard upon completion (similar to a manual scan). By default, scans will include all organization repos that you have access to.

If you would like to have Radar automatically scan the repos your account has access to, please email support@nightfall.ai to enable this.

Using the Dashboard

All scan results are also accessible in our dashboard UI, in case you'd prefer to access results visually rather than programatically.

See a full list of scans:

For each scan, see the results:

Questions?

For help, please email us at support@nightfall.ai or via the Intercom chat widget in the bottom right.