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.

To get started, create a Nightfall account by logging in via GitHub here.

Authentication

  • The Nightfall API uses API keys to authenticate requests. You can view your API key on your Settings page.
  • 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.

Terminology

  • A Scan is a historical scan of a single GitHub repository. A Scan can be run on its own, or can belong to a Workflow Run, detailed below. A Scan has many Results.
  • A Result is a single violation or sensitive finding of sensitive data. A Result belongs to a Scan.
  • A Workflow represents an automatic bulk scan all repos in a GitHub organization, either on-demand or on a scheduled basis. Each time a Workflow is run, this generates a Workflow Run. Thus, a Workflow has many Workflow Runs.
  • A Run, or a Workflow Run, is an instance of a Workflow being run or performed. A Run performs a full historical scan of all repos in its corresponding Workflow's GitHub organization. Thus, a Run belongs to a Workflow, and a Run has many Scans, corresponding to all repos in the GitHub organization being scanned at the time of the Run.

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 100 completed scans per month. 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.

POST /api/v1/scans/new

Sample Usage — Login to auto-fill values below

Sample Response

Get List of Scans

Returns a list of most recent scans, ordered by creation date. The scan results are not included. To get scan results, refer to the /api/v1/scans/:scan_id endpoint below.

Arguments:

  • limit - Optional, default is 5. A limit on the number of objects to be returned, between 1 and 100. Max is 100.
  • page - Optional, default (index) is 1. Page of results to fetch. The number of results per page is defined by the limit parameter above.

Returns:

  • status - The status of the scan. One of Completed, Running, or Failed.
  • limit - The number of results to return. Default is 5. Max is 100.
  • page - The page number of the paginated results.
  • scans - An array of Scan objects. Each Scan object has the following attributes:
    • id - Identifier of the scan.
    • url - URL of the GitHub repo that was scanned.
    • duration - Duration of scan in seconds.
    • created_at - Date/time of when the scan was initiated.

GET /api/v1/scans

Sample Usage — Login to auto-fill values below

Sample Response

Get Scan Results

Returns the results for a specific scan.

Arguments:

  • 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.
    • created_at - Date/time of when the result was found.
    • signature - SHA1 hash of commit_hash, permalink, and context together.

GET /api/v1/scans/:scan_id

Sample Usage — Login to auto-fill values below

Sample Response

Get Runs

Returns all Runs for all Workflows in an organization, sorted newest to oldest.

Arguments:

  • None

Returns:

  • An array of Run objects. A Run is a singular run of a Workflow and corresponds to a full historical scan of a GitHub organization at a moment in time. This array is sorted by most recent Run (first array element is the most recent). Each Run object has the following attributes:
    • id - Identifier of the Run. Use this ID when calling Get Run Results below.
    • workflow_id - Identifier of the Workflow that the Run belongs to.
    • status - The status of the Run. If 1 this means the Run is finished running, else it is still running or in a pending state.
    • created_at - Date/time of when the Run was started.
    • updated_at - Date/time of when the Run was last updated.

GET /api/v2/runs

Sample Usage — Login to auto-fill values below

Sample Response

Get Run Results

Returns all results for all scans in a completed Workflow Run, as JSON or CSV.

Arguments:

  • run_id - Required. The identifier of the Run for which results are being retrieved.
  • export_format - Optional. Specify this argument with value csv as a query parameter for response to be in a CSV format (e.g. /api/v2/runs/:run_id?export_format=csv). If any other value, or if excluded, response will be standard JSON.

Returns:

  • run_id - Identifier of the Run whose results are being retrieved.
  • 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.
    • scan_id - Identifier of the corresponding scan that the result belongs to.
    • repo_path - Path of the repository in which the result was found.
    • author_email - Author of the commit.
    • commit_hash - Commit hash in GitHub repo.
    • file_path - Path of the file in which the result was found.
    • context - The preceding characters before the sensitive token.
    • token - Redacted sensitive token that was discovered.
    • permalink - A permalink to the exact line of the sensitive finding in GitHub.
    • created_at - Date/time of when the result was found.
    • signature - SHA1 hash of commit_hash, permalink, and context together.

GET /api/v2/runs/:run_id

Sample Usage — Login to auto-fill values below

Sample Response

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

Allowing Tokens via Allow List

The allow list enables you to "allow" tokens, files, or directories to pass through our filters undetected. In other words, items on the allow list 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 allow list. The allow list applies on a global, account level and will affect all subsequent scans for all repos.

Allow-listing 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 allow-listing, you could ignore the token “test_api_key” individually. As an example of subpath allow-listing, 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 Allow List

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

Arguments:

  • key_type - Required. The type of key to allow, 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.
  • allowlist - An array of items currently in the allow list, corresponding to the key type specified in the request.

GET /api/v1/allowlist

Sample Usage — Login to auto-fill values below

Sample Response

Add to Allow List

Add a list of keys to the allow list, so Radar doesn't flag them. For example, these could be example or test keys that have been verified as safe to expose.

Arguments:

  • key_type - Required. The type of key to allow, value is one of (a) api_key, corresponding to an individual token, or (b) subpath, corresponding to an entire file/directory.
  • allowlist - Required. An array of items to add to the allow list, corresponding to the key type specified above.

Returns:

  • status - The status of the request. One of Success or Error.
  • message - A verbose description of the status.

POST /api/v1/allowlist

Sample Usage — Login to auto-fill values below

Sample Response

Delete from Allow List

Remove a list of keys from the allow list.

Arguments:

  • key_type - Required. The type of key to allow, value is one of (a) api_key, corresponding to an individual token, or (b) subpath, corresponding to an entire file/directory.
  • allowlist - Required. An array of items to remove from the allow list, corresponding to the key type specified above.

Returns:

  • status - The status of the request. One of Success or Error.
  • message - A verbose description of the status.

DELETE /api/v1/allowlist

Sample Usage — Login to auto-fill values below

Sample Response

Bulk & Automated Scans

With Radar, you can scan all the GitHub repos in your account that you have access to, either manually or automatically on a fixed schedule.

You can accomplish this manually by writing a short script in a language of your choice. Follow our tutorial here to write a bash script to scan all your repos:
How to bulk scan your organization's GitHub repos

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 support widget in the bottom right.