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

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

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)