Radar API Reference
Reference for the Nightfall Radar REST API to programmatically scan GitHub repos for sensitive data.

Introduction

With Nightfall'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 programmatically. 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

POST /api/v1/scans/new
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.
Sample Usage:
1
curl https://radar.nightfall.ai/api/v1/scans/new \
2
-u API_KEY: \
3
-d 'github_url=https://github.com/nightfalldlp/sample'
Copied!
Sample Response:
1
{
2
"status": "Running",
3
"message": "Scan is running. You will be notified via email ([email protected]) when scan is complete. You can view the scan results via the provided Scan ID when complete. You can also configure a Webhook endpoint to be programatically notified when the scan is complete. See API Docs: https://radar.nightfall.ai/docs#get-results",
4
"scan_id": "374b41aa-2567-4b58-828f-ea72684ca17c"
5
}
Copied!

Get List of Scans

GET /api/v1/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 Get Scan Results 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.
Sample Usage:
1
curl -X GET https://radar.nightfall.ai/api/v1/scans \
2
-u API_KEY:
Copied!
Sample Response:
1
{
2
"status": "Success",
3
"limit": 5,
4
"page": 1,
5
"scans": [
6
{
7
"id": "2ed12efe-1fbd-4d09-aad9-1e6867c1c80f",
8
"url": "https://github.com/nightfalldlp/sample",
9
"duration": "1.706554794",
10
"created_at": "2019-04-23T23:39:58.282Z"
11
},
12
{
13
"id": "f5edec8b-a215-4537-90db-8d02289e11e4",
14
"url": "https://github.com/nightfalldlp/sample",
15
"duration": "1.670032915",
16
"created_at": "2019-04-23T23:38:14.560Z"
17
}
18
]
19
}
Copied!

Get Scan Results

GET /api/v1/scans/:scan_id
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.
Sample Usage:
1
curl -X GET https://radar.nightfall.ai/api/v1/scans/SCAN_ID \
2
-u API_KEY:
Copied!
Sample Response:
1
{
2
"id": "0b6b08cf-f1ff-436b-a69f-7a1cb0d06e44",
3
"url": "https://github.com/nightfalldlp/sample",
4
"duration": "0.822404097",
5
"created_at": "2019-04-28 22:51:10 UTC",
6
"scanned_files": 24,
7
"status_code": 200,
8
"results_count": 1,
9
"results": [
10
{
11
"result_id": "db2d2f85-8c06-41ef-85bf-2ea2dc786ca3",
12
"repo_path": "sample",
13
"file_path": "sample.rb",
14
"branch": "origin/master",
15
"commit_hash": "3a07b08d2461b6906376081d1f13b303215bf55d",
16
"author_email": "[email protected]",
17
"context": "a4300836696c47b4f2d7c'\n+\n+auth_token = '",
18
"token": "db▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪",
19
"token_length": 32,
20
"permalink": "https://github.com/nightfalldlp/sample/blob/3a07b08d2461b6906376081d1f13b303215bf55d/sample.rb#L7",
21
"created_at": "2019-04-28 22:51:13 UTC",
22
"signature": "74285ef22c444da264ad891176d459ea16ae4d1g"
23
}
24
]
25
}
Copied!

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

GET /api/v1/allowlist
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.
Sample Usage:
1
curl -X GET https://radar.nightfall.ai/api/v1/allowlist \
2
-u API_KEY: \
3
-d 'key_type=api_key'
Copied!
Sample Response:
1
{
2
"status": "Success",
3
"allowlist": [
4
"testkey1",
5
"testkey2"
6
]
7
}
Copied!

Add to Allow List

POST /api/v1/allowlist
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.
Sample Usage:
1
curl -X POST https://radar.nightfall.ai/api/v1/allowlist \
2
-u API_KEY: \
3
--data-urlencode 'allowlist=["newtestkey"]' \
4
-d 'key_type=api_key'
Copied!
Sample Response:
1
{
2
"status": "Success",
3
"message": "Key(s) added successfully."
4
}
Copied!

Delete from Allow List

DELETE /api/v1/allowlist
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.
Sample Usage:
1
curl -X DELETE https://radar.nightfall.ai/api/v1/allowlist \
2
-u API_KEY: \
3
-d 'allowlist=["newtestkey"]' \
4
-d 'key_type=api_key'
Copied!
Sample Response:
1
{
2
"status": "Success",
3
"message": "Key(s) added successfully."
4
}
Copied!

Configuring a 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
1
{
2
"status": 200,
3
"scan_id": "2bf24516-337f-4dc2-83b2-4e9b101183cb",
4
"duration": "1.057264743",
5
"url": "https://github.com/nightfalldlp/sample"
6
}
Copied!

Running 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 do this via our Workflows feature. A Workflow is an on-demand or scheduled scan of all repos in a selected GitHub organization. A Workflow is composed of Runs. A Run corresponds to each time the Workflow is run, meaning every time you do a batch scan of your GitHub organization. For example, if you have a scheduled Workflow that scans your GitHub organization's repos every week, in 4 weeks you will have completed 4 Runs. Learn more about setting up Workflows here:
Last modified 3mo ago