REST API Reference

Introduction

The Collective Defense Cloud has provided a RESTful API to query the status and the results of binaries submitted for CB Inspection.

Example client scripts are included for reference purposes and are implemented in Python.

The Collective Defense Cloud REST API uses a set of HTTP header fields for authentication of all requests. Please refer to the REST API authentication reference for more details on these authentication parameters and how to get access to the API.

CB Inspection API, version 1.0.0

Base URL: https://threatintel.bit9.com/api/v1/inspection

Endpoints
- GET /status/{hash}
- GET /report/{hash}
Definitions
- Yara
- SubFile
- Detonation
- StringsAnalysis
- ScoreFactors
- Status
- Report
- Error
- NotFound

Endpoints

GET /status/{hash}

The status endpoint returns data about the status of the inspection.

Parameters

in	name	type	required	description
path	hash	string	true	Hex string of either MD5 or SHA256 checksum of submitted binary

Response: 200

A status object

Schema

Status

Response: 404

Inspection submission not found

Schema

NotFound

Response: default

Unexpected error

Schema

Error

Example

Request

import requests
auth_headers = {
    "X-Tic-User-Key": "eeacdcc1b-e5e5-f6f6abab-0101010101aad",
    "X-Tic-User-Secret": "Kp7B9fkZxm5TloYuXUGb566OC00YWQ5LTkwZjc3NTU2M2Ex"
}
url = "https://threatintel.bit9.com/api/v1/inspection/status/a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0"
response = requests.get(url, headers=auth_headers)
if response.status_code == 200:
    print (response.json())

Response

{
  "analysis_complete": false,
  "completed": "2016-10-11T14:49:30",
  "eta_to_complete": 3600,
  "md5": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
  "requested": "2016-10-11T14:49:17",
  "results": null,
  "sha1": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
  "sha256": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
  "status": "submitted"
}

GET /report/{hash}

The report endpoint returns both detailed telemetry data and status info of the inspection.

Parameters

in	name	type	required	description
path	hash	string	true	Hex string of either MD5 or SHA256 checksum of submitted binary

Response: 200

A report object

Schema

Report

Response: 404

Inspection submission not found

Schema

NotFound

Response: default

Unexpected error

Schema

Error

Example

Request

import requests
auth_headers = {
    "X-Tic-User-Key": "eeacdcc1b-e5e5-f6f6abab-0101010101aad",
    "X-Tic-User-Secret": "Kp7B9fkZxm5TloYuXUGb566OC00YWQ5LTkwZjc3NTU2M2Ex"
}
url = "https://threatintel.bit9.com/api/v1/inspection/status/a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0"
response = requests.get(url, headers=auth_headers)
if response.status_code == 200:
    print (response.json())

Response

{
  "metadata": {
    "magic": "PE32 executable for MS Windows (native) Intel 80386 32-bit",
    "md5": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
    "mime": "application/octet-stream",
    "name": "2c018e375986cb29a76910850eb83bb0c14ed22c2d00194692e27955f3707f67.exe",
    "sha1": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
    "sha256": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
    "size": "4134122"
  },
  "report_url": "https://analysis.carbonblack.com/report/g",
  "results": {
    "analysis_summary": "bad",
    "detonation": {
      "data": [
        {
          "te": {
            "CPULevelDetection": "false",
            "SuspiciousActivities": {
              "SuspiciousEvent": {
                "SuspiciousActivity": [
                  {
                    "Path": "[low confidence] Behaves like a known malware ( Generic.MALWARE.x )"
                  }
                ],
                "Type": "SuspiciousActivityEvent"
              }
            },
            "System": {
              "OsInfo": "Microsoft Windows 7 32 bit, Office 2003, Office 2007, Adobe Acrobat Reader 9.0, Adobe Flash Player 10, Java SE 1.6.0",
              "OsRev": "53",
              "OsUID": "7e6fe36e-889e-4c25-8704-56378f0830df",
              "Osname": "Windows 7"
            },
            "reportDate": "Tue Sep 27 10:39:09 2016"
          }
        },
        {
          "av": {
            "signature_name": ""
          }
        }
      ],
      "status": "complete"
    },
    "score": 100,
    "score_factors": {
      "detonation": {
        "score": 8,
        "verdict": "suspicious"
      },
      "strings_analysis": {},
      "subfile": {
        "score": 100,
        "verdict": "bad"
      },
      "yara": {
        "score": 100,
        "verdict": "bad"
      }
    },
    "strings_analysis": {
      "data": [
        {
          "generic": {
            "ascii_strings": [
              "!This program cannot be run in DOS mode."
            ],
            "unicode_strings": [
              "jjjjjjjjjj",
              "\\System32\\mrt100.dll"
            ]
          }
        }
      ],
      "status": "complete"
    },
    "subfile": {
      "data": [
        {
          "detail": "Found with XOR key 0x41",
          "md5": "234e22d3b7bba6c0891de0a19b79d7ea",
          "method": "XOR",
          "report_url": "https://analysis.carbonblack.com/report/gA1",
          "score": 100,
          "sha1": "9214239dea04dec5f33fd62602afde720b71d2d2",
          "sha256": "30a824155603c2e9d8bfd3adab8660e826d7e0681e28e46d102706a03e23e3a8"
        }
      ],
      "status": "complete"
    },
    "yara": {
      "data": [
        {
          "generic": {
            "matches": [
              {
                "meta": {
                  "confidence": 8,
                  "description": "Detects Sauron/Strider/Remsec based on rich trash headers",
                  "severity": 10
                },
                "namespace": "production.yar",
                "rule": "sauron_strider_trash"
              }
            ]
          }
        }
      ],
      "status": "complete"
    }
  },
  "status": {
    "analysis_summary": "bad",
    "completed": "2016-09-27T17:34:38",
    "requested": "2016-09-27T17:30:13",
    "score": 100,
    "status": "complete"
  }
}

Definitions

Yara

Schema

(object)
- data (array): Yara data results
  - (object)
    - matches (array): List of yara rules that matched on this binary
      - (object)
        
        meta (object): Metadata about Yara rule that fired
        
        condidence (integer: int32): Confidence factor in Yara rule
        
        description (string): Description of Yara rule
        
        severity (integer: int32)
        
        rule (string): Name of Yara rule
- status (string): Status of Yara analysis

SubFile

Schema

(object)
- data (array): SubFile data results
  - (object)
    - detail (string): details of how subfile was found
    - md5 (string): hex string of MD5 checksum of subfile
    - method (string): Method used to detect subfile
    - report_url (string): Url to CB Inspection portal for the analyzed sub file
    - score (integer: int32): CB Inspection score for sub file
    - sha1 (string): hex string of SHA1 checksum of subfile
    - sha256 (string): hex string of SHA256 checksum of subfile
- status (string): Status of SubFile analysis

Detonation

Schema

(object)
- data (array): List of data sections
  - (object)
    - te (object): Emulation telemetry data
      - System (object)
        
        OsInfo (string): Description of OS
        
        OsRev (string): OS Rev of Sandbox environment
        
        OsUID (string): unique identifier for Sandbox environment
        
        Osname (string): Name of OS (e.g. Windows 8.1)
      - Activities (object): Set of activities observed during execution on the sandbox
        
        Command (array): list of Commands performed during execution
        
        (object)
        
        Action (string): Name of action performed. e.g. QueryKey, Read,
        
        CommandName (string: RegistryEvent, FileSystemEvent, NetworkEvent, SuspiciousActivityEvent, ProcessEvent, NetworkHTTPEvent): Type of command performed. e.g. RegistryEvent, FileSystemEvent
      - SuspiciousActivities (object): Set of behaviours observed during execution on the sandbox
        
        SuspiciousEvent (object)
        
        Type (string): type of suspicious activity observed during execution
        
        SuspiciousActivity (array): list of observed behaviours during execution on sandbox
        
        (object)
        
        Path (string)
    - av (object): Antivirus Scanner Information
      - signature_name (string): Malware signature name
- status (string): Status of Detonation

StringsAnalysis

Schema

(object)
- data (array): generic object wrapper
  - (object)
    - ascii_strings (string): ascii strings
    - unicode_strings (string): unicode strings
- status (string): Status of StringsAnalysis

ScoreFactors

Schema

(object)
- detonation (object): Detonation score information
  - score (integer: int32): Score of detonation
  - verdict (string: good, bad, suspicious, unknown): Enum of verdict from detonation
- yara (object): Yara score information
  - score (integer: int32): Score of Yara
  - verdict (string: good, bad, suspicious, unknown): Enum of verdict from Yara
- cb_reputation (object)
  - score (integer: int32): Score of CB reputation
- prevalence (object): Prevalence
  - score (integer: int32): Factor for community prevalence

Status

Schema

(object)
- eta_to_complete (integer: int32): Estimated number of seconds remaining to complete inspection. Only populated if status is in submitted state.
- hash (object)
  - md5 (string): hex string of MD5 checksum of binary
  - sha1 (string): hex string of SHA1 checksum of binary
  - sha256 (string): hex string of SHA256 checksum of binary
- analysis_summary (string: good, bad, suspicoius, unknown): Overall verdict of analysis
- score (integer: int32): Overall score of the inspection result ranging from -100 (trusted) to 100 (malicious).
- status (string: complete, error, requested, submitted): Status of inspection.
- requested (string: dateTime): Date and time binary was last submitted for inspection
- completed (string: dateTime): Date and time binary inspection was last completed

Report

Schema

(object)
- report_url (string): Link to the CB Inpsection detail page
- metadata (object): Metadata section
  - magic (string): Magic file type
  - md5 (string): hex string of MD5 checksum of binary
  - sha1 (string): hex string of SHA1 checksum of binary
  - sha256 (string): hex string of SHA256 checksum of binary
  - size (integer): size of submitted binary in bytes
- results (object): Results of the Inspection
  - analysis_summary (string: good, bad, suspicious, unknown): Summary verdict for the Inspection.
  - score (integer: int32): Overall score of the inspection result ranging from -100 (trusted) to 100 (malicious).
  - score_factors ScoreFactors
  - detonation Detonation
  - strings_analysis StringsAnalysis
  - yara Yara
  - subfile SubFile
- status Status

Error

Schema

(object)
- code (integer: int32)
- message (string)

NotFound

Schema

(object)
- code (integer: int32)
- message (string)

Last modified on October 10, 2016

CB Collective Defense Cloud

API Reference

Page Contents

REST API Reference

Introduction

CB Inspection API, version 1.0.0

Endpoints

GET /status/{hash}

Response: 200

Response: 404

Response: default

Example

GET /report/{hash}

Response: 200

Response: 404

Response: default

Example

Definitions

Yara

SubFile

Detonation

StringsAnalysis

ScoreFactors

Status

Report

Error

NotFound