Binwalk Enterprise API Documentation

Overview

Binwalk exposes its data via REST API so that users can interact with Binwalk in a programmatic way. An authenticated user can upload, analyze, and parse results all from a script or application.

Authentication

Most Binwalk API endpoints require an authentication token.

Each user has a unique token that is used to authenticate API queries so that only your applications access your data securely. You can retrieve your authtoken by logging into Binwalk and navigating to Account Settings in the User dropdown menu.

authtoken - The API key used to authenticate requests. Note: for API requests made in a web browser in an authenticated session, like the examples on this page, the authtoken is not required.
uploadFileId - This is how we refer to the files you upload for analysis, whether they are firmware images, tarballs, zip archives, or individual binaries. You will also see this referenced as ufid.

Pagination

Firmware images scanned by Binwalk can produce a lot of data. Most of the endpoints for fetching data employ the use of server-side pagination to keep responses snappy.

Since these parameters apply to many endpoints, we will define them once here and link to them from the endpoints that apply.

Query parameters used for controlling pagination

Parameter	Type	Description
limit	Number	Limit the number of results that are fetched per page for a query. Use with page parameter. Default value: 10
page	Number	Return a specific page of results for the query. Default value: 1
offset	Number	Some API endpoints use an offset rather than page number for more fine-grained pagination control. Default value: 1

Example Paginated Request

curl "https://centrifuge.refirmlabs.com/api/endpoint?limit=3&page=2"

Example Paginated Response

The paginated data will come back with a total count of results and an array containing the current page of results

{
  "count": 19,
  "results": [
    {
      "id": 4,
      "path": "/bin/busybox"
    },
    {
      "id": 5,
      "path": "/bin/ls"
    },
    {
      "id": 6,
      "path": "/sbin/ifconfig"
    }
  ]
}

Quick Start

Try it out! Here's a quick example that shows how to use the API to detect which firmware images(ufids) are finishing processing.

GET
/api/upload

Parameter

Field	Type	Description
authtoken	String	User authentication token

Send the Request

curl "https://centrifuge.refirmlabs.com/api/upload?authtoken=TOKEN"

Custom Pagination Values

curl "https://centrifuge.refirmlabs.com/api/upload?authtoken=TOKEN&limit=5&page=2"

Success 200

Field	Type	Description
finishedAt	String	Timestamp of completed report, or null if the firmware is still being analyzed

Example Response

HTTP/1.1 200 OK
{
  "count": 22,
  "results": [
    {
      "id":21,
      ...
      "finishedAT": "2018-09-04T19:55:59.000Z"
    },
    {
      "id": 22,
      ...
      "finishedAt": null
    }
}

# See below for the types of error responses you might see from the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken.
FileNotFoundError	The requested file could not be found.
UserPermissionDeniedError	You do not have permission to access/alter this resource.
UploadFileNotFoundError	The requested upload file could not be found.
InvalidUploadFileError	The ufid parameter must be a number.

Invalid user

HTTP/1.1 400 Bad Request
  {
     "error":"User not Specified"
  }

File Not Found

HTTP/1.1 404 File Not Found
  {
     "error":"File not Found"
  }

Permission Denied

HTTP/1.1 403 Forbidden
  {
     "error":"Permission denied"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
     "error":"Upload File not Found"
  }

Invalid Upload File ID

HTTP/1.1 400 Bad Request
  {
     "error":"ufid parameter must be a number"
  }

Uploads

Add firmware for analysis

PostUpload

Upload a firmware image to be analyzed.

POST
/api/upload
``

**Example Usage**
```python
curl -X POST \
 -F "file=@path/to/firmware.img" \
 -F "vendor=Linksys" \
 -F "device=WRT54G" \
 -F "version=6.0" \
 -F "description=Custom build 123" \
 "https://centrifuge.refirmlabs.com/api/upload?authtoken=TOKEN"

Upload via url

curl -X POST \
 -F "url=https://publicly/accessible/firmware.bin" \
 -F "vendor=Linksys" \
 -F "device=WRT54G" \
 -F "version=6.0" \
 -F "description=Custom build 123" \
 "https://centrifuge.refirmlabs.com/"

Parameter

Field	Type	Description
file	file	Firmware image file being uploaded
url (optional)	String	A link to the firmware image you want to upload. May be used instead of file
vendor	String	Vendor/Manufacturer name
device	String	Device/Model name
Version	String	Firmware version string
description (optional)	String	Optional user-defined description for the uploaded firmware image

Success 200

Field	Type	Description
ufid	Number	The upload file ID (ufid) assigned to the firmware image

Success-Response

HTTP/1.1 200 OK
  {
    "ufid": 398
  }

Add large firmware for analysis

PostUploadChunky

Upload a large firmware image to be analyzed. The file should be spit into "chunks" and each chunk should be sent by a separate call to this endpoint. Additional metadata is required in order for the server to reassemble the file after all the chunks have been uploaded. For example, a 5MB firmware image will require 3 separate calls to this endpoint using chunk size of 2MB.

POST
/api/upload/chunky

Example usage

# sending the 2nd chunk out of 3
 -F "file=@path/to/firmware.img.chunk.2" \
 -F "vendor=Linksys" \
 -F "device=WRT54G" \
 -F "version=6.0" \
 -F "description=Custom build 123" \
 -F "dzuuid=29eb1e9d-fcb2-40b3-88e8-340c39f0f8b7" \
 -F "dzchunkindex=1" \
 -F "dztotalfilesize=4829328" \
 -F "dzchunksize=2000000" \
 -F "dztotalchunkcount=3" \
 -F "dzchunkbyteoffset=2000000" \
 "https://centrifuge.refirmlabs.com/api/upload?authtoken=TOKEN"

Download extracted file

GetAPIUploadFileUfidExidPath

Download a file extracted from the firmware image.

GET
/api/upload/file/:ufid/:path

Parameter

Field	Type	Description
ufid	Number	Upload file ID
exid	Number	Extraction ID
path	string	Path to the desired file within the extraction directory for this ufid. This value may contain / but but it may be helpful to URI encode this value, especially for filenames with unicode characters

Success-Response

HTTP/1.1 200 OK
<binary file content>

Download firmware image

GetUploadFileByID

Download an uploaded firmware image from Binwalk.

GET
/api/upload/:ufid

Example Usage

curl "https://centrifuge.refirmlabs.com/api/upload/1234?authtoken=TOKEN" > newfile.img
 or
curl -O -J "https://centrifuge.refirmlabs.com/api/upload/1234?authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success-Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream
    <binary file contents>

Get details by ID

GetUploadDetailsByID

Request details for an uploaded firmware image including user-supplied metadata, file size and finished time.

GET
/api/upload/details/:ufid

Example Usage

curl "https://centrifuge/refirmlabs.com/api/upload/details/1234?authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success 200

Field	Type	Description
id	Number	Upload file ID(or ufid)
originalFilename	String	The filename of the uploaded file
vendor	String	User-Provided Vendor name
device	String	User-Provided device name
version	String	User-provided version string
description	String	User-provided description
createdAt	String	The time the firmware image was uploaded
updatedAt	String	The last time the file status was updated
finishedAt	String	The time the firmware scan was completed, or null if the scan is still in progress
extractedSize	Number	The total size on disk of all the extracted files from the firmware image, or null if the firmware is still extracting
fileCount	Number	The number of files extracted from the firmware image
regularFileCount	Number	The number of regular files extracted from the firmware image (not symbolic links, directories, device files, etc)
executableFileCount	Number	The number of ELF executables extracted from the firmware image
fileSize	Number	Size(in bytes) of the uploaded firmware image
md5sum	String	The MD5 hash of the uploaded firmware image
analysisTimeInMilliseconds	Number	Number of milliseconds it took to scan the firmware image
analysisTimeInSeconds	Number	Number of seconds it took to scan the firmware image
User	Object	Metadata about the user that uploaded the firmware image
id	Number	The user ID
username	String	The Binwalk login name of the user

Success-Response

HTTP/1.1 200 OK
  {
    "id": 49,
    "userId": 42,
    "originalFilename": "firmware.img",
    "createdAt": "2018-12-07T08:09:32.000Z",
    "updatedAt": "2018-12-07T08:10:01.000Z",
    "finishedAt": "2018-12-07T08:10:01.000Z",
    "vendor": "Linksys",
    "device": "WRT54G",
    "version": "6.0",
    "description": "Custom build 123",
    "extractedSize": 2414241,
    "fileCount": 17,
    "regularFileCount": 12,
    "executableFileCount": 2,
    "fileSize": 49772,
    "md5sum": "12345678901234567890123456789012",
    "analysisTimeInMilliseconds": 290000,
    "analysisTimeInSeconds": 290,
    "User": {
        "id": 42,
        "username": "[email protected]",
    }
  }, {
    ...
  }

Get extractions by ID

GetUploadExtractionsByID

Request the list of extractions IDs(exids) for an uploaded firmware. For every container-type file(zip, tar, bin, img, etc) from which Binwalk was able to upack other files, it assigns an ID number to track and organize the resulting extracted files.

GET
/api/upload/extractions/:ufid

Parameter

Field	Type	Descirption
ufid	Number	Upload file ID

Success 200

Field	Type	Description
exid	Number	The extraction ID
md5sum	String	The md5 hash of the file that was extracted
path	String	The path within Binwalk storage for the file that was extracted

Success-Response

  HTTP/1.1 200 OK
[
  {
    "exid": 0,
    "md5sum": "431db022e249585eff4546d53f07c6af",
    "path": "firmware.bin"
  },
  {
    "exid": 1,
    "md5sum": "0aa752041893792a136d3b969d10b903",
    "path": "/0/original"
  },
  {
    "exid": 2,
    "md5sum": "3098134feb119a08c92746591bbea925",
    "path": "/1/img-0_vol-rootfs_ubifs.ubifs"
  },
]

Get kernels found by ID

GetUploadUfidKernels

Request the list of kernel version strings found, along with the files in which they were discovered.

GET
/api/upload/:ufid/kernals

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success 200

Field	Type	Description
path	String	The path to the extracted file in which the kernel version string was found.
kernelVersionString	String	The kernel version string

Success-Response

   HTTP/1.1 200 OK
[
  {
    "path": "/1/70",
    "kernelVersionString": "Linux kernel version 2.6.33"
  }
]

Get root file system directories found for ID

GetUploadUfidRootfsDirectories

Request the list of kernel version strings found, along with the files in which they were discovered.

GET
/api/upload/:ufid/rootfsDirectories

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success 200

Field	Type	Description
rootfsDirectoryPath	String	An extracted path identified as a root file system directory

Success-Response

   HTTP/1.1 200 OK
[
  "/2/squashfs-root"
]

Get status for all firmware

Getuploads

Request a list of all your uploaded firmware images.

GET
/api/upload

Example Usage

curl "https://centrifuge.refirmlabs.com/api/upload?authtoken=TOKEN"

Fetch 10 at a time

curl "https://centrifuge.refirmlabs.com/api/upload?limit=10&offset=10&authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object	List of status for all uploaded files

Success-Response

HTTP/1.1 200 OK
{
  "count": 49,
  "results":
  [{
    "id": 1,
    ...
    }
  }, {
    "id": 2,
     ...
  }]
}

Mark scan as finished

MarkUploadFinished

Sometimes, especially for very large uploads, a firmware scan can fail to change to complete status. In some cases this can happen even if it successfully performed all analysis. This endpoint allows the user to force the specified scan to be marked as finished so it moves out of the "In progress" list of reports. Note this does not affect extraction or analysis, so even if a report is marked as finished prematurely it won't prevent the remainder of analysis for that report.

POST
/api/upload/finished

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Parameter

Field	Type	Description
ufid	Number	The report ID to be marked as finished
timestamp (Optional)	String	Optional timestamp to set as the finish date of the scan. Formatted like "169-12-31 23:59:59". Defaults to current time.

Example Usage

curl -X POST -H "Content-Type: application/json" -d '{"ufid": 1234}' "https://centrifuge.refirmlabs.com/api/upload/finished?authtoken=TOKEN"

Example usage with timestamp

curl -X POST -H "Content-Type: application/json" -d '{"ufid": 1234, "timestamp": "1969-12-31 23:59:59"}' "https://centrifuge.refirmlabs.com/api/upload/finished?authtoken=TOKEN"

Success-Response

HTTP/1.1 204 OK

Possible Error Responses for the API

|Name|Description|
|-|-|
|InvalidUserError|The requested user could not be found. Usually means invalid authtoken|
|UploadFileNotFoundError|The requested upload file could not be found|

**Invalid User**
```python
HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Modify firmware details

PutUploadDetailsByID

Change properties of an existing upload file.

PUT
/api/upload/details/:ufid

Example Usage

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"version": "6.0-b"}' \
  "https://centrifuge.refirmlabs.com/api/upload/details/1234?authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload file ID
userID (optional)	Number	New user ID
vendor (optional)	String	New vendor name
device (optional)	String	New device model name
version (optional)	String	New firmware version
description (optional)	String	New description

Success-Response

HTTP/1.1 204 No Content

Re-analyze

PutUploadByID

PUT
/api/upload/:ufid

Example Usage

curl -X PUT \
  "https://centrifuge.refirmlabs.com/api/upload/1234?authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success-Response

HTTP/1.1 204 OK

Remove firmware

DeleteUploadByID

Deletes an uploaded firmware image from Binwalk along with all of its analysis data.

Delete
/api/upload

Example Usage

curl -X DELETE \
  "https://centrifuge.refirmlabs.com/api/upload?ufid=1234&authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload file ID

Success-Response

HTTP/1.1 204 No Content

Guardian

Get analyzer by ID

GetAnalyzerById

Request Guardian analyzer details for a specific analyzer ID

GET
/api/analyzers/:id

Parameter

Field	Type	Description
id	Number	The Guardian analyzer ID to query

Example Request

curl "https://centrifuge.refirmlabs.com/api/analyzers/123?authtoken=TOKEN"

Success 200

Field	Type	Description
id	Number	The ID of the Guardian analyzer
latest	Boolean	Flag indicating that this analyzer version is the latest for this vulnerability
name	String	Name of the vulnerability
type	String	The type of analyzer. Allowed values:CVE
queue	String	The internal analyzer group name
version	String	The version of the Guardian analyzer
ctx	Object	Additional data specific to this analyzer
affects	String	The software component affected by the vulnerability
cwe_description	String	Short description of the vulnerability category
cwe_id	Number	The CWE ID of the vulnerability
cvss_v2_severity	Number	The CVSS v2 severity of the vulnerability
cvss_v3_severity	Number	The CVSS v3 severity of the vulnerability. The version reported in Binwalk is the greater of either the v2 or v3 severity scores
description	String	Detailed description of the vulnerability
references	Object	A list of URLs related to the vulnverability
remediation	String	Remdiation steps for eliminating the vulnerability
schema_version	String	The version of the ctx schema used to describe this analyzer

Example Response

HTTP/1.1 200 OK
{
  "id": 1,
  "latest": false,
  "name": "CVE-2011-3601",
  "type": "cve",
  "queue": "radvd",
  "version": "1.0.0",
  "ctx": {
    "remediation": "Upgrade dnsmasq to 1.82 or later.",
    "cwe_id": 119,
    "schema_version": "1.0.0",
    "cvss_v2_severity": 7.5,
    "description": "Buffer overflow in the process_ra function in the router advertisement daemon (radvd) before 1.8.2 allows remote attackers to execute arbitrary code or cause a denial of service (crash) via a negative value in a label_len value.",
    "cvss_v3_severity": null,
    "references": [
      "http://www.litech.org/radvd/CHANGES",
      "http://www.openwall.com/lists/oss-security/2011/10/06/3",
      "http://www.ubuntu.com/usn/USN-1257-1"
    ],
    "affects": "radvd",
    "cwe_description": "Denial of Service Execute Code Overflow"
  }
  }, {
     ...
  }]
}

Get analyzers

GetAnalyzers

Request a list of Guardian analyzer details containing related CVE information.

GET
/api/analyzers

Parameter

Field	Type	Description
limit (optional)	Number	Return this many items per query. Use with 'offset' parameter. Default value:All
offset (optional)	Number	Return 'limit' results starting at this offset. Default value:1.

Example Request

curl "https://centrifuge.refirmlabs.com/api/analyzers?authtoken=TOKEN"

Fetch 10 at a time

curl "https://centrifuge.refirmlabs.com/api/analyzers?limit=10&offset=10&authtoken=TOKEN

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object	List of Guardian analyzer details.

Example Response

HTTP/1.1 200 OK
{
  "count": 423,
  "results":
  [{
    "id": 11,
    ...
    }
  }, {
     ...
  }]
}

Get vulnerabilities

GetAnalyzerResults

Request a list of Guardian vulnerabilities for the given ufid.

GET
/api/report/:ufid/analyzer-results

Parameter

Field	Type	Description
ufid	Number	Upload file ID
affected (optional)	Boolean	Return only vulnerable results

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/12/analyzer-results?authtoken=TOKEN"

Fetch 10 at a time

curl "https://centrifuge.refirmlabs.com/api/report/12/analyzer-results?limit=10&offset=10&authtoken=TOKEN

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object	List of vulnerabilities found by Guardian

Example Response

HTTP/1.1 200 OK
{
  "count": 423,
  "results":
  [{
    "id": 1,
    ...
    }
  }, {
    ...
  }]
}

Get vulnerability by ID

GetAnalyzerResultById

GET
/api/report/:ufid/analyzer-results/:id
``

**Example Usage**
```python
# fetch Guardian vulnerability id 790 for ufid 12
curl "https://centrifuge.refirmlabs.com/api/12/analyzer-results/790?authtoken={AUTHTOKEN}"

Parameter

Field	Type	Description
ufid	Number	Upload file ID
id	Number	Guardian vulnerability result ID number

Success 200

Field	Type	Description
id	Number	Analyzer Result id
ufid	Number	Upload file id of the analyzed file
exid	Number	Extraction id of the analyzed file
filepath	String	Path to analyzed file
startTime	String	Time that analyzer began processing(UTC)
updatedTime	String	Time that analyzer was last updated(UTC)
finishedTime	String	Time that analyzer completed processing(UTC)
affected	Boolean	Indicates if analyzer found a matching vulnerability
analyzer	Object	Details about the Guardian vulnerability found
analyzer_id	Number	Id of the analyzer that produced the result
analyzerVersion	String	Internal version of the analyzer that produced the result

Success-Response

HTTP/1.1 200 OK
  {
   "id":790,
   "ufid":1234,
   "exid":2,
   "filePath":"/usr/sbin/speciald",
   "startTime":"2018-01-01T01:05:01.001Z",
   "updatedTime":"2018-01-01T01:07:07.007Z",
   "finishedTime":"2018-01-01T01:07:07:007Z",
   "affected":true,
   "analyzer_id":401,
   "analyzerVersion":"1.0.0"
  }

Get vulnerability summary

GetAnalyzerResultSummary

Request a summary of Guardian vulnerabilities for the given ufid.

GET
/api/report/:ufid/analyzer-results/summaries

**Parameter**
|Field|Type|Description|
|-|-|-|
|ufid|Number|Upload file ID|

**Example Request**
```python
curl "https://centrifuge.refirmlabs.com/api/report/analyzer-results/summaries?authtoken=TOKEN"

Success 200

Field	Type	Description
results	Object	An object containing the tally of vulnerabilities by CVSS severity score for this ufid
files_scanned	Number	The number of files scanned by Guardian for this ufid
files_vulnerable	Number	The number of files flagged by Guardian as vulnerable for this ufid
analyzers_run	Number	The number of Guardian analyzers run for this ufid
analyzers_vulnerable	Number	The number of Guardian analyzers that found at least one vulnerability for this ufid
Last_scanned	Number	The timestamp for the most recent Guardian scan activity for this ufid

Example Response

HTTP/1.1 200 OK
{
  "results": {
    "none": 0,
    "low": 0,
    "medium": 0,
    "high": 0,
    "critical": 0
  },
  "files_scanned": 0,
  "files_vulnerable": 0,
  "analyzers_run": 0,
  "analyzers_vulnerable": 0,
  "last_scanned": null
}

Code Analysis

Get all flawed files

GetReportVulnerableFiles

Get a list of all the executable files found to have patterns of insecure code. The flaws detected in these binaries could lead to errors, crashes, or even exploitation of the device.

GET
/api/report/:ufid/vulnerable-files

Parameter

Field	Type	Description
ufid	Number	Upload File ID

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1234/vulnerable-files?authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	Total number of (filtered) results for the query
results	Object[]	List of result objects
basename	Number	The base filename of the reported file
commandInjectionCount	Number	The number of flaws detected that could potentially lead to command injection detected
connectionCount	Number	The number of networking system calls detected in the file. This number is not counted towards the total number of flaws but is still interesting to report, especially if this executable file should not be doing anything on the network
createdAt	String	Creation timestamp of this analysis result
emulatedFunctionCount	Number	The number of critical flaws detected in the file via emulation. This number is not counted towards the total number of flaws because it is usually a subset of the command injection and buffer overflow flaws detected by static analysis
extractionId	Number	The exid for this result
fullpath	String	The path that can be used within the Binwalk API to reference this analyzed file
id	Number	The ID of this analysis result
overflowCount	Number	The number of flaws detected that could potentially lead to buffer overflow
path	String	The path of the analyzed file, relative to its extraction ID
tainted	Boolean	Indicator of vulnerable call arguments being influenced by the calling function
updatedAt	String	Result update timestamp
uploadFileId	Number	The ufid for this result

Example Result

HTTP/1.1 200 OK
{
  "count": 52,
  "results": [
  {
    "basename": "busybox",
    "commandInjectionCount": 2,
    "connectionCount": 13,
    "createdAt": "2018-08-27T19:32:15.000Z",
    "emulatedFunctionCount": 5,
    "extractionId": 3,
    "fullpath": "/3/squashfs-root/bin/busybox",
    "id": 724,
    "overflowCount": 20,
    "path": "/squashfs-root/bin/busybox",
    "totalFlaws": 22,
    "updatedAt": "2018-08-27T19:33:09.000Z",
    "uploadFileId": 1234
  }, {
    ...
  }]
}

Get critical flaws by path

GetReportEmulatedFileByPath

Request a list of coe flaws that were identified(via function-level emulation) as having a high probability of being vulnerable.

GET
/api/report/:ufid/emulated-files/:exid

Parameter

Field	Type	Description
ufid	Number	Upload File ID
exid	Number	Extraction ID of path
path	String	File path that was analyzed

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1234/emulated-files/1?authtoken=TOKEN&path=/bin/busybox"

Success 200

Field	Type	Description
count	Number	The total number of (filtered) results for the query
results	Object[]	List of result objects
byteOffset	Number	The offset of the emulated function
call	Boolean	The flawed function call that could be vulnerable to attack
createdAt	String	Result creation timestamp
extractionId	Number	The exid for this result
id	number	The ID of this result
path	String	The path of the analyzed file
tainted	Boolean	Indicator of vulnerable call arguments being influenced by the calling function
type	String	The type of vulnerability. Allowed Values: overflow, cmd_injection
updatedAt	String	Result update timestamp
uploadFileId	Number	The ufid for this result
caller	Object	The calling function that was emulated to identify the flawed call
createdAt	String	Result creation timestamp
functionName	String	The name of the calling function
id	Number	The id of the calling function
updatedAt	String	Result update timestamp
vulnerableEmulatedCallId	Number	The id of the critical flaw result

Example Response

 HTTP/1.1 200 OK
 {
   "count": 423,
   "results": [
   {
     "byteOffset": 4000000,
     "call": "strcpy(0x800200, 'AAAA')",
     "caller": {
         "createdAt": "2018-07-16T19:13:15.000Z",
         "functionName": "main",
         "id": 417,
         "updatedAt": "2018-07-16T19:13:15.000Z",
         "vulnerableEmulatedCallId":1
     }
     "createdAt": "2018-07-16T19:13:15.000Z",
     "extractionId": 1,
     "id": 1,
     "tainted": true,
     "type": "overflow",
     "path": "/bin/busybox",
     "updatedAt": "2018-07-16T19:13:15.000Z",
     "uploadFileId": 1234,
  }, {
    ...
  }]
}

Get flaws by path

GetReportVulnerableFileByPath

GET
/api/report/:ufid/vulnerable-files/:exid

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/1234/vulnerable-files/12?path=usr/sbin/httpd?authtoken={AUTHTOKEN}"

Parameter

Field	Type	Description
ufid	Number	Upload File ID
exid	Number	Extraction ID
Path	String	File Path

Success 200

Field	Type	Description
Count	number	The total number of (filtered) results for the query
results	Object[]	List of result objects
callType	String	The type of vulnerability this call has been identified under. Allowed values: "overflow", "cmd_injection", "connection". Oveflow: there is a potential that a stack-based buffer could be overflown. Command injection: there is a potential that a user may supply malicious shell commands that will be executed. Connection: this function call makes the process accessible via the network.
createdAt	String	Creation timestamp of this analysis result
extractionId	Number	The exid for this file
id	Number	The Id of this analysis result
offset	Number	the decimal offset of the flaw within the file
path	String	The path of the file relative to its extraction ID
symbolicOffset	String	The symbol name and offset where the flawed code was found
updatedAt	String	the last time this analysis result was updated
uploadFileId	Number	The ufid for this file
vulnerableCall	String	The function call being reported as flawed

Success-Response

HTTP/1.1 200 OK
{
  "count": 16,
   "results": [
   {
     "callType": "connection",
     "createdAt": "2018-12-07T12:09:59.000Z",
     "extractionId": 5,
     "id": 77134,
     "offset": 4222228,
     "path": "/ext-root/bin/dnsmasq",
     "symbolicOffset": "find_all_interfaces+54",
     "updatedAt": "2018-12-07T08:09:59.000Z",
     "uploadFileId": 449
     "vulnerableCall": "socket(2, 1, $zero);",
   },
   {
     ...
   }]
}

**

Report

Download analysis artifact

GetArtifactById

Request an analysis artifact for download based on id. An artifact is an object extracted or derived from a file in order to perform further analysis. Examples of artifacts are PKI certificates or private keys that may have been located in .pem files or embedded within other binaries.

GET
/api/report/{ufid}/artifacts/{artifactId}

Path Variable

Field	Type	Description
artifactId	Number	Artifact ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1/artifacts/1234?authtoken=TOKEN"

Success 200

Field	Type	Description
The	Data	artifact data

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

File statistics

GetReportStatisticsUfidExidFilepath

Request analysis statistics for the file identified by filePatId.

GET
/api/report/statistics/{ufid}/{filePath}

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/statistics/1234/12?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID
filePathId	Number	File Path ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Success 200

Field	Type	Description
ufid	Number	Upload File ID
filePathId	Number	File Path ID
risk	Number	CSP-determined risk value; larger value=higher risk
overflowCount	Number	Number of potential buffer overflows
commandInjectionCount	Number	Number of potential command line injections
maxEmulatedFunctionCount	Number	Maximum number of emulated functions called in a dynamic analysis session

Success-Response

   HTTP/1.1 200 OK
{
  "ufid" : "5",
  "exid" : "1",
  "filePathId" : "338",
  "risk" : 1,
  "overflowCount" : 1,
  "commandInjectionCount" : 0,
  "maxEmulatedFunctionCount" : 0
}

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Request Binary Hardening features

GetBinaryHardening

Request binary hardening analysis results found in the firmware image identified by ufid.

GET
/api/report/{ufid}/binary-hardening

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken
format (optional)	String	Output format for the results. Default value:json Allowed Value: json, csv

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1234/binary-hardening?authtoken=TOKEN"

Fetch 50 at a time

curl "https://centrifuge.refirmlabs.com/api/report/1234/binary-hardening?limit=50&offset=0&authtoken=TOKEN"

Success 200

Field	Type	Description
Count	Number	The total number of binary hardening results
results	Object[]	List of binary hardening results(paginated)

Success Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserErrror	The requested user could not be found. Usually means invalid authtoken.
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Request PKI Certificates

GetCertificates

Request a list of PKI certificates discovered in the firmware.

GET
/api/report/crypto/{ufid}/certificates

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
isAuthorities (Optional)	Boolean	Include Certificate Authority Certs(default:true)
isIntermediate (Optional)	Boolean	Include Intermediate Autherity Certs(default:true)
isSelfSigned (optional)	Boolean	Include Self Signed Certs(default:true)

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/crypto/12/certificates?authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object[]	List of certificates discovered

Example Response

HTTP/1.1 200 OK
  {
      "rflid": "2eb9e0ec-a45c-492d-8cb3-a0a1880384b0",
      "subject": {
          "commonName": "Joe User",
          "organizationName": "XySSL",
          "organizationalUnitName": null,
          "emailAddress": null
      },
      "issuer": {
          "commonName": "XySSL Test CA",
          "organizationName": "XySSL",
          "organizationalUnitName": null,
          "emailAddress": null
      },
      "keySize": 2048,
      "keyAlgorithm": "rsaEncryption",
      "displayKeyAlgorithm": "RSA Encryption",
      "keyData": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArgyq69aVU5sGe2nsShO6JE2yW9TP4fZO/X2ImRrpTpqJqxAztGCJvJqsj2pDxij0Tv/eRT631ciXJG+DOfKGIQF6Sy56vPraipyYFEJkDq0ips7XjfkWhnqmJ8XrsCGCMUo3kfUub3yqOY9CnimpA0LaxNKmiuPkIkK8vZsINTx4hK8ZxalcqV5KTGze63IyIxTUqgFWHMYGd6CZn6l/hSE2jmNRCHkJzATUKJB10meICzeTtFRdGKFAPpVqI3QSbU/AgUNdv3MSQufXLSYucTL3HYI2zb8Y9948Lzsvk5LMUTuI4Nr9ore7OBi9321UZP0cz/xKBq8LSnjW6dIquQIDAQAB",
       "keyHash": "13f0d25eaffc4db91a4c9e66526742c49932ad0f5268802fd079b1caa3fad1ea",
       "validityStart": "1157638053000",
       "validityEnd": "1189174053000",
       "serialNumber": "15246786378589513302",
       "signatureAlgorithm": "sha1WithRSAEncryption",
       "displaySignatureAlgorithm": "SHA-1 with RSA Encryption",
       "fingerprint": "26:60:c4:9d:12:ff:ee:7e:63:ba:d8:7a:a6:4e:a8:dd:5a:04:68:c2:f0:7f:6c:96:81:a9:59:f9:6b:a6:85:02",
       "paths": [
           "/extractions/8/squashfs-root/usr/lib/libxyssl.so"
       ],
       "isAuthority": false,
       "isSelfSigned": false,
       "isIntermediate": false,
       "privateKey": {
         "rflid": "84a71481-0ef4-4aae-a5c6-39ae9c4bc547"
         "artifactStorageId": 5,
         "privateKeyHash": "aff99f4147a296705b9a20832de53977cb696d610e8ea55826cb9c5211cdd368",
         "publicKeyHash": "13f0d25eaffc4db91a4c9e66526742c49932ad0f5268802fd079b1caa3fad1ea",
         "keySize": 2048,
         "paths": [
           "/extractions/8/squashfs-root/usr/lib/libxyssl.so"
         ]
       },
       "createdAt": "1569583795000",
       "updatedAt": "1569583795000"
   }, {
    ...
  }]
}

Request PasswordHash comparison

GetReportPasswordhashUfidCompare

Request a comparison of password hashes between uploaded files.

GET
/api/report/passwordhash/{ufid}/compare

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/passwordhash/1234/compare?authtoken={AUTHTOKEN}&compareWith={COMPAREWITH}&offset={OFFSET}&limit={LIMIT}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken
compareWith	Number	Upload File ID to compare against {ufid}
offset	Number	Offset from which to begin returning results
limit	Number	Number of results to be returned

Success 200

Field	Type	Description
Count	Number	Number of total results available
passwordHashes	Object[]	An array of PasswordHashDifferences

PasswordHashDifference

Field	Type	Description
annotations	String	A string informing as to whether or not the PasswordHash was removed("removed"), added("added"), or remains unchanged("")
passwordHashes	Object[]	An array of PasswordHashDifference objects

PasswordHash

Field	Type	Description
context	String	Context in which the password hash was found
hash	String	The password hash
salt	String	The hash salt

Success-Response

   HTTP/1.1 200 OK
{
  "count": 2,
  "passwordHashes": [
    {
      "annotations": "removed",
      "passwordHash": {
        "context": "bf7de88b:5663d2a1:9c013c10279e5d4f94428c3a8fc69597",
        "hash": "9c013c10279e5d4f94428c3a8fc69597",
        "salt": "5663d2a1"
      }
    },
    {
      "annotations": "added",
      "passwordHash": {
        "context": "bc3bf86964:3391f771:4cf0ed8641cfcbbf46784e620a0316fb",
        "hash": "4cf0ed8641cfcbbf46784e620a0316fb",
        "salt": "3391f771"
      }
    }
  ]
}

Request Private Keys

GetPrivateKeys

Request a list of private keys discovered in the firmware.

GET
/api/report/crypto/{ufid}/privatekeys

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
type	String	Select the type of private key to search for. Allowed Values:ssh,cert.

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/crypto/12/privateKeys?authtoken=TOKEN"

Fetch only SSL Cert Private Keys

curl "https://centrifuge.refirmlabs.com/api/report/crypto/12/privateKeys?authtoken=TOKEN&type=cert"

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object[]	List of certificates discovered

Example Response

HTTP/1.1 200 OK
{
  "count": 5
  "results":
   [{
     "rflid": "25d9cee6-050e-4eca-9379-d81c8b600a9b",
     "artifactStorageId": 4,
     "privateKeyHash": "040b41d1eb8ed6c6a17b2ca3d200fa7190d6e1452feb9bc54df3d2cee97dd74b",
     "publicKeyHash": "01943cf22e54ef2b8caaa49b23e6a34462f20879f22c84565e20692917bbb043",
     "keySize": 2048,
     "pairedObject": {
       "subject": {
         "commonName": "localhost",
         "organizationName": "XySSL"
       },
       "rflid": "8a8d0d8a-bbe4-4cf9-8bac-93472d4823c7",
       "paths": [
         "/extractions/8/squashfs-root/usr/lib/libxyssl.so"
       ],
       "displayKeyAlgorithm": "RSA Encryption",
       "keySize": 2048
     },
     "createdAt": "1569583794000",
     "updatedAt": "1569583794000"
},{
    ...
  }]
}

Request Public Keys

GetPublicKeys

Request a list of Public Keys discovered in the firmware.

GET
/api/report/crypto/{ufid}/publicKeys

Path Variable

Field	Type	Description
ufid	Type	Description

Query Parameter

Field	Type	Description
Type	String	Select the type of public key to search for. Allowed values:ssh,pem

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/crypto/12/publicKeys?authtoken=TOKEN"

Request only SSH public keys

curl "https://centrifuge.refirmlabs.com/api/report/crypto/12/publicKeys?authtoken=TOKEN&type=ssh"

Success 200

Field	Type	Description
count	Number	The total number of results for the query
results	Object[]	List of certificates discovered

Example Response

HTTP/1.1 200 OK
{
  "count": 5
  "results":
  [{
    "rflid": "569d8675-c3ce-4ba6-abc3-d958fc3e6b9d",
    "userName": null,
    "keySize": 1024,
    "displayKeyAlgorithm": "RSA",
    "type": "SSH",
    "modulus": "9a:56:1e:b7:45:0b:86:33:59:d1:05:99:4e:b6:d0:34:95:56:b6:4b:2f:e0:db:1d:84:28:f7:36:59:94:24:1b:7c:75:05:17:a3:70:ca:52:87:65:84:88:0d:4e:4a:ab:7c:41:24:c8:7b:00:ca:a0:88:09:e8:9f:4b:61:fe:9b:04:97:9f:5a:f3:a4:b4:a8:59:8b:0c:34:e9:6d:5d:ad:90:26:79:33:7b:b9:96:db:29:c0:a3:4e:8e:ff:fd:d4:55:5d:6b:c4:92:6b:3f:3c:4a:92:75:93:b4:58:80:31:85:7c:9c:9a:98:7a:34:3d:9a:ca:94:9c:86:da:67:bd",
    "privateKey": {
      "rflid": "8bf6d774-c29d-469d-992d-5722641dd8f3",
      "artifactStorageId": 1,
      "privateKeyHash": "1522dd56a696a8444ccc98e04ace914855d94a1f6c0f06dc428ba707dac86d06",
      "keyAlgorithm": "rsaEncryption",
      "displayKeyAlgorithm": "RSA",
      "keySize": 1024,
      "paths": [
        "/extractions/9/jffs2-root/home/user/.ssh/id_rsa",
      ]
    },
    "paths": [
      "/extractions/9/jffs2-root/home/user/.ssh/id_rsa.pub"
    ]
  }, {
    ...
  }]
}

Request crypto keys

GetReportCryptoUfid

Request crypto keys found in the firmware image identified by ufid.

GET
/api/report/crypto/{ufid}

Example usage

 curl "https://centrifuge.refirmlabs.com/api/report/crypto/1234?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Success 200

Field	Type	Description
hashes	Object	An array of hashes
passwords	Object	An array of passwords
keys	Object	An array of certificates

Key Certificate

Field	Type	Description
private	Boolean	True if this is the private key for an asymmetric keypair; false if it is public
keyText	String	Decoded certificate data
selfSigned	Boolean	True if this is a self-signed certificate; false otherwise
filePath	String	The location of this key in the extracted file system
keyData	String	the raw data of this key file

Success-Response

  HTTP/1.1 200 OK
{
   "hashes" : [],
   "passwords" : [],
   "keys" : [
      {
         "private" : false,
         "keyText" : "Certificate:\n    Data:\n        Version: 3 (0x2)...",
         "selfSigned" : true,
         "filePath" : "/etc/certs/server.pem",
         "keyData" : "-----BEGIN CERTIFICATE-----\nMIIDXDCCA..."
      }
   ]
}

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Request file details

GetReportFilesystemUfidExidFiledetails

Request extended details for an extracted file.

 GET
/api/report/filesystem/:ufid/filedetails

Example Usage:

curl "https://centrifuge.refirmlabs.com/api/report/filesystem/1234/1/filedetails?&filepath=/usr/lib/libcurl-1.so.0.0&authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload File ID
exid	Number	Extraction ID
authtoken	String	Authentication Token
filepath	String	The file path for which to retrieve extended details(url encoded)

Success 200

Field	Type	Description
file	Object	An object containing extended details of the requested file

Success-Response

HTTP/1.1 200 OK
{
    "id": 1234567,
    "ufid": 1234,
    "userId": 42,
    "groupId": 42,
    "basename": "libcurl-1.so.0.0",
    "path": "/extractions/1/usr/lib/libcurl-1.so.0.0",
    "size": "4321",
    "sha256sum": "a8b2194df67d3d170dab5f561a4c1d9cb95eaf605194132d5c7144c3ffe5ba8d",
    "mode": null,
    "MimeType": {
        "type": "application/x-sharedlib",
        "encoding": "charset=binary"
    },
    "createdAt": "1578998290000",
    "updatedAt": "1578998290000"
}

Request file listing

GetReportFilesystemUfidExid

Request a listing of files for the specified extraction id and directory path.

GET
/api/report/filesystem/{ufid}/{exid}

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/filesystem/1234/1?dirpath=%2Fusr%2Flocal&authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID
exid	Number	Extraction ID

Query Parameter

Field	Type	Description
dirpatch (Optional)	String	The directory to retrieve within this extracted file(url encoded). Default value:%2F

Success 200

Field	Type	Description
files	Object	An array of file descriptors in the requested dirpath for ufid+exid

File Descriptor

Field	Type	Description
id	String	A unique identifier for the file
text	String	The basename for the file
children	Boolean	true if this file is a directory; false otherwise
type	String	Allowed values:"directory", "file", "symlink", "archive"
exid	Integer	The extraction id to which this file belongs
path	String	The path to this file relative to the extraction directory

Success-Response

   HTTP/1.1 200 OK
[
  {
    "id" : "12B0,
    "type" : "directory",
    "text" : "squashfs-root",
    "children" : true,
    "exid" : 2,
    "path" : "/2/squashfs-root"
  }, {
    ...
  }
]

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

Invalid User
Upload File Not Found
HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Request found password hashes

GetReportPasswordhashUfid

Request password hashes identified throughout the extracted file system.

GET
/api/report/passwordhash/{ufid}

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/passwordhash/1234?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Success 200

Field	Type	Description
ufid	Number	Upload File ID
filepathID	Number	File Path ID
file	String	Path to file represented by filePathID
algorithmID	String	The algorithm identifier string 'man 3 crypt'
algorithmName	String	The human-readable algorithm name(if known)
context	String	The original, full line of text, wherein this password hash was found
hash	String	The isolated password hash
salt	String	The isolated hashing salt

Success-Response

   HTTP/1.1 200 OK
[
    {
        "algorithmId": "algoIdString",
        "algorithmName": "Algorithm Name",
        "context": "Full line of text where $algoIdString$salt$hash was found",
        "file": "path/to/file",
        "filePathId": 0,
        "hash": "hash",
        "salt": "salt",
        "ufid": 0
    }
]

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
FileNotFoundError	The requested file cannot be found
UserPermissionDeniedError	You do not have permission to access/alter this resource

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Invalid Upload File ID

HTTP/1.1 404 File Not Found
  {
    "error":"File not found"
  }

Permission Denied

HTTP/1.1 403 Forbidden
  {
    "error":"Permission denied"
  }

Request top level file listing

GetReportFileSystemUfid

Request the top level listing of extracted files for the specified upload file id.

GET
/api/report/filesystem/{ufid}

Example Usage

curl "https://centrifuge.refirmlabs.com/api/report/filesystem/1234?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Success 200

Field	Type	Description
files	Object	An array of file descriptors in the requested dirpath for ufid

File Descriptor

Field	Type	Description
id	String	A unique identifier for the file
text	String	The basename for the file
children	Boolean	true if this file is a directory; false otherwise
type	String	Allowed values:"directory", "file", "symlink", "archive"
exid	Integer	The extraction id to which this file belongs
path	String	The path to this file relative to the extraction directory

Success-Response

   HTTP/1.1 200 OK
[
  {
    "id" : "1A82,
    "type" : "directory",
    "text" : "originalUploadFile.bin",
    "children" : true,
    "exid" : 1,
    "path" : "/1"
  }
]

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Retrieve Security Checklist results

GetSecurityChecklist

retrieve security checklist from a report.

GET
/api/report/SecurityChecklist/{ufid}

Path Variable

Field	Type	Description
ufid	Number	Upload File ID of the report

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/SecurityChecklist/1234?authtoken=TOKEN"

Success 200

Field	Type	Description
AnalyzerResults	Object[]	When Populated, points to the vulnerable file(s) detected when a test did not pass
key	String	A simple descriptor for the failed test results
value	String	The value presented as the test failure(for example, a vulnerable file path)
Analyzer	Object	Metadata about the test
name	String	A unique identifier for the checklist test. Combined with the version, this presents a unique identifier
version	Number	The version of this analyzer. Versions are simple incrementing integers per test analyzer
references	String[]	A list of urls to give supporting detail about the test
remediation	String	Curated advice on what steps, if any, should be taken to mitigate the vulnerability
type	String	The category of the test performed(eg. "exploit" or "backdoor")

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Retrieve a list of all the components detected by Binwalk

GetComponents

Request a list of all the components that Binwalk has detectors for.

GET
/api/report/components

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/components?authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of results
results	Object[]	List of all components

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Retrieve the Software Bill of Materials
GetSbom

Request Software Bill of Materials(SBOM) information for the firmware image, including the names and versions of each detected component.

GET
/api/report/{ufid}/sbom

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken
format (Otpional)	String	Output format for the results

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1234/sbom?authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of SBOM results
results	Object[]	List of SBOM components

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Search file tree for matching names

GetReportFilesystemSearchUfid

Handle ajax search requests and return a list of parent nodes.

GET
/api/report/filesystem/search/{ufid}

Example usage

curl "https://centrifuge.refirmlabs.com/api/report/filesystem/search/1234?str=httpd&authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
str (optional)	String	The case-insensitive, partial pattern to find in file/dir names. Default value: pattern

Success 200

Field	Type	Description
files	Object	An array of path node ids, including all parent paths leading up to the matched results

Success-Response

   HTTP/1.1 200 OK
["/etc/init.d", "/etc", "/", "/sbin"]]

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken.
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Show overall pass/fail tally for Security Checklist

GetSecurityChecklistSummary

Retrieve a quick high level summary of the Security Checklist tests performed for a firmware image.

GET
/api/report/SecurityChecklist/{ufid}/threatCount

Path Variable

Field	Type	Description
ufid	Number	Upload File ID of the report

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/SecurityChecklist/1234/threatCount?authtoken=TOKEN"

Success 200

Field	Type	Description
threatcount	Number	The number of tests that failed
issuesFound	Boolean	A boolean flag indicating if any tests failed
status	String	The processing status for the Security Checklist in this report. Allowed values: ready, queued, dequeued, finished

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Comparison

Compare Security Checklist results between two reports

CompareSecurityChecklist

Compare the security checklist results from the report {ufid} against the results from another report provided as a query parameter.

GET
/api/report/SecurityChecklist/{ufid}/compare

Path Variable

Field	Type	Description
ufid	Number	Upload File ID of the "current" report. All results will be in the reference to this

Query Parameter

Field	Type	Description
compareWith	Number	Upload file ID of the older report to compare against
authtoken	String	User authentoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/SecurityChecklist/1234/compare?compareWith=1229&authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of tests that were run for the Security Checklist
items	Object[]	List of Security Checklist results with embedded metadata indicating whether the test was added, removed, or modified from the {compareWith} report to the current {ufid} report
summary	Object	High level statistics of the binary hardening differences between the two reports

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFound	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Request Binary Hardening comparison to another report

CompareBinaryHardening

Compare the binary hardening analysis results from the report {ufid} against the results from anothe report provided as a query parameter.

GET
/api/report/{ufid}/binary-harening/compare

Path Variable

Field	Type	Description
ufid	Number	Upload File ID of the "current" report. All results will be in reference to this

Query Parameter

Field	Type	Description
compareWith	Number	Upload File ID of the "compared" report
authtoken	String	User authtoken

Example Reqiest

curl "https://centrifuge.refirmlabs.com/api/report/1234/binary-hardening/compare?compareWith=1229&authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of binary hardening results
items	Object[]	List of binary hardening results with embedded metadata indicating whether the file was added, removed, or modified between the {compareWith} report and the current {ufid} report
summary	Object	High level statistics of the binary hardening differences between the two reports

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
InvalidUserError	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Request SBOM comparison to another report

CompareSBOM

Compare the Software Bill of Materials analysis results from the report {ufid} against the results from another report(usually a previous version of the firmware) provided as a query parameter.

GET
/api/report/{ufid}/sbom/compare

Path Variable

Field	Type	Description
ufid	Number	Upload File ID of the "Current" report. All results will be in reference to this

Query Parameter

Field	Type	Description
compareWith	Number	Upload File ID of the "compared" report
authtoken	String	User authtoken

Example Request

curl "https://centrifuge.refirmlabs.com/api/report/1234/sbom/compare?compareWith=1229&authtoken=TOKEN"

Success 200

Field	Type	Description
count	Number	The total number of SBOM results
items	Object[]	List of SBOM results with embedded metadata indicating whether the component was added, removed, or modified between the {compareWith} report and the current {ufid} report
summary	Object	High level statistics of the SBOM differences between the two reports

Success-Response

HTTP/1.1 200 OK

Possible Error Responses for the API

Name	Description
Invalid User	The requested user could not be found. Usually means invalid authtoken
UploadFileNotFoundError	The requested upload file could not be found

Invalid User

HTTP/1.1 400 Bad Request
  {
    "error":"User not specified"
  }

Upload File Not Found

HTTP/1.1 404 Not Found
  {
    "error":"Upload file not found"
  }

Export

Get Executive Summary PDF

GetSummaryPDF

Export an executive summary of a Binwalk report as a PDF file.

GET
/api/summary/:ufid/pdf

Example Request

curl "https://centrifuge.refirmlabs.com/api/summary/12/pdf?authtoken=TOKEN" > binwalk-report.pdf
 or
curl -O -J "https://centrifuge.refirmlabs.com/api/summary/12/pdf?authtoken=TOKEN"

Parameter

Field	Type	Description
ufid	Number	Upload File ID

Success-Response

HTTP/1.1 200 OK
Content-Type: application/pdf
    <PDF file content>

SharedReports

Create shared report link

PostSharedUfid

Create a shareable report link for the specified Upload File ID.

POST
/api/shared/{ufid}

Example Usage

curl -X POST "https://centrifuge.refirmlabs.com/api/shared/1234?authtoken={AUTHTOKEN}"

Expiration Date

curl -H 'Content-Type: application/json' -d '{"expirationDate": "2020-12-31 23:59:59"}' "https://centrifuge.refirmlabs.com/api/shared/1234?authtoken={AUTHTOKEN}"

Password

curl -H 'Content-Type: application/json' -d '{"password": "Passw0rd4Sh@redL!nk"}' "https://centrifuge.refirmlabs.com/api/shared/1234?authtoken={AUTHTOKEN}"

Notes

curl -H 'Content-Type: application/json' -d '{"notes": "Shared to vendor for triage"}' "https://centrifuge.refirmlabs.com/api/shared/1234?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
ufid	Number	Upload File ID

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Body Data

Field	Type	Description
expiration (optional)	String	A timestamp after which the shared link stops working. Prefer dates like YYY-MM-DD
password (optional)	String	An optional password to protect the shared link
notes (optional)	String	Optional remarks to help you remember the reason for sharing. Only visible to you

Success 200

Field	Type	Description
sharedURL	String	A shareable URL for the given report containing the unique shared report link identifier hash

Success-Response

  HTTP/1.1 200 OK
{
   "sharedUrl": "https://centrifuge.refirmlabs.com/shared/a1b2c3d4e5f6"
}

Get shared report links

GetShared

Retrieve all shared report links generated by the requesting user.

GET
/api/shared

Example usage

curl "https://centrifuge.refirmlabs.com/api/shared?authtoken={AUTHTOKEN}"

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Success 200

Field	Type	Description
sharedLinks	Object[]	An array of shared link objects
createdAt	String	The date and time this shared link was created
expirationDate	String	The date and time upon which this shared link expires
expired	Boolean	Set to true if expirateDate is set and is in the past
notes (optional)	String	Optional private remarks to help the user organize their shared links
id	Number	The shared link id number; use this for the DELETE API endpoint
passwordProtected	String	Set to true if the shared link has a password set
sharedUri	String	The unique identifier for this shared link
ufid	Number	The Upload File ID to which this shared link grants access

Success-Response

  HTTP/1.1 200 OK
[
    {
        "createdAt": "2020-09-01T08:00:00Z",
        "expirationDate": "2017-08-19T20:59:32.000Z",
        "expired": true,
        "id": 22,
        "passwordProtected": true,
        "sharedUri": "a1b2c3d4e5f6",
        "ufid": 209
    }
]

Revoke a shared report link

DeleteSharedHash

Delete a shareable report link. The report itself is unaffected but users will not be able to view the report using that shared link any more.

DELETE
/api/shared/hash

Example usage

curl -X DELETE "https://centrifuge.refirmlabs.com/api/shared/a1b2c3e4e5f6?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
hash	String	Unique identifier for this shared report link

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Success-Response

HTTP/1.1 204 OK

Revoke all shared report links

DeleteShared

Delete all shared report links. Users will no longer be able to use those links to access the linked reports.

DELETE
/api/shared

Example Usage

curl -X DELETE "https://centrifuge.refirmlabs.com/api/shared?authtoken={AUTHTOKEN}"

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Update shared report link options

PatchSharedHash

Update the options for the specified a shareable report link.

PATCH
/api/shared/{hash}

Update Expiration Date

curl -X PATCH -H 'Content-Type: application/json' -d '{"expirationDate": "2021-01-15 13:00:00"}' "https://centrifuge.refirmlabs.com/api/shared/a1b2c3d4e5f6?authtoken={AUTHTOKEN}"

Remove Password

curl -X PATCH -H 'Content-Type: application/json' -d '{"password": ""}' "https://centrifuge.refirmlabs.com/api/shared/a1b2c3d4e5f6?authtoken={AUTHTOKEN}"

Update Notes

curl -X PATCH -H 'Content-Type: application/json' -d '{"notes": "The week is long"}' "https://centrifuge.refirmlabs.com/api/shared/a1b2c3d4e5f6?authtoken={AUTHTOKEN}"

Path Variable

Field	Type	Description
hash	String	Unique identifier of the shared report link

Query Parameter

Field	Type	Description
authtoken	String	User authtoken

Body Data

Field	Type	Description
expirationDate (optional)	String	A timestamp after which the shared link stops working. Prefer dates like YYY-MM-DD. Set to null to remove expiration
password (optional)	String	An optional password to protect the shared link. Set to empty string to remove the password
notes (optional)	String	Optional remarks to help you remember the reason for sharing. Only visible to you. Set to empty string to remove notes

Success 200

Field	Description
200	Ok

Binwalk Enterprise API Documentation

Binwalk Enterprise API Documentation

Authentication

Pagination

Example Paginated Request

Example Paginated Response

Add firmware for analysis

Add large firmware for analysis

Download extracted file

Download firmware image

Get details by ID

Get extractions by ID

Get kernels found by ID

Get root file system directories found for ID

Get status for all firmware

Mark scan as finished

Modify firmware details

Re-analyze

Remove firmware

Get analyzer by ID

Get analyzers

Get vulnerabilities

Get vulnerability by ID

Get vulnerability summary

Get all flawed files

Get critical flaws by path

Get flaws by path

Download analysis artifact

File statistics

Request Binary Hardening features

Request PKI Certificates

Request PasswordHash comparison

Request Private Keys

Request Public Keys

Request crypto keys

Request file details

Request file listing

Request found password hashes

Request top level file listing

Retrieve Security Checklist results

Retrieve a list of all the components detected by Binwalk

Search file tree for matching names

Show overall pass/fail tally for Security Checklist

Compare Security Checklist results between two reports

Request Binary Hardening comparison to another report

Request SBOM comparison to another report

Get Executive Summary PDF

Create shared report link

Get shared report links

Revoke a shared report link

Revoke all shared report links

Update shared report link options

Clone this wiki locally