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 at radar.nightfall.ai/login.


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.

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. If the repo has 1000 commits or fewer, the full commit history will be scanned. If this repo has more than 1000 commits, the files in the current working directory will be scanned. To scan the full commit history of larger repositories or to increase your scan limit, please contact us via email at support@nightfall.ai.

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).
  • is_large - Boolean, indicating size of the repo. If true, this means that the repository is over 1000 commits, so the files in the Current Working Directory (CWD) were scanned, instead of the full commit history. If false, this means the repo has 1000 or fewer commits, so the Full Commit History (FCH) was scanned.
  • 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.

GET /api/v1/scans/:scan_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


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.