Knowledge API

This API gets data about the computers that belong to the client’s IT infrastructure and the files they store.

Get the Details of a File

Gets the classification of a file assigned by Cytomic from its MD5 hash and other information.

Request

Command

GET

URL

/api/v1/applications/forensics/md5/{md5}/info

Required parameters in the URL

md5: File hash.

Headers

Accept: application/json

Format of the call to get a file details
Response

JSON object with a description of the file attributes.

JSON object field Description

filename

Name of the file.

filesize

Size of the file in bytes.

lastSeen

Date the file was last logged in the Cytomic global knowledge.

firstSeen

Date the file was first logged in the Cytomic global knowledge.

classification

Value indicated in the classificationName field.

classificationName

Classification of the file generated by Cytomic EDR:

  • -1: Unknown

  • 0: Unknown

  • 1: Goodware

  • 2: Malware

  • 3: Suspicious

  • 4: Compromised

  • 5: GWNotConfirmed

  • 6: PUP

  • 7: GwUnwanted

  • 8: GwRanked

Fields of the JSON object indicating the file attributes

Get the Details of Multiple Files

Gets the classification of a list of files assigned by Cytomic from their MD5 hashes and other information.

Request

Command

POST

URL

/api/v1/forensics/md5/batch/sample

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get information about a list of files
Response

List of JSON objects with descriptions of the attributes of the files

JSON object field Description

filename

Name of the file.

filesize

Size of the file in bytes.

lastSeen

Date the file was last logged in the Cytomic global knowledge.

firstSeen

Date the file was first logged in the Cytomic global knowledge.

classification

Value indicated in the classificationName field.

classificationName

Classification of the file generated by Cytomic EDR:

  • -1: Unknown

  • 0: Unknown

  • 1: Goodware

  • 2: Malware

  • 3: Suspicious

  • 4: Compromised

  • 5: GWNotConfirmed

  • 6: PUP

  • 7: GwUnwanted

  • 8: GwRanked

Fields of the JSON object indicating the file attributes

Get the Computers Where a File Was Detected

Gets a list of MUIDs of the client’s computers where a certain MD5 hash was detected.

Request

Command

GET

URL

/api/v1/applications/forensics/md5/{md5}/muids

Required parameters in the URL

MD5: File hash.

Headers

Accept: application/json

Format of the call to get the computers where a file was detected
Response

List of JSON objects with information about the computers where a file was detected.

JSON object field Description

MUID

Unique ID of the computer.

clientId

Unique ID of the client the computer belongs to.

lastSeen

Date the file was last seen on a computer on the client’s network.

firstSeen

Date the file was first seen on a computer on the client’s network.

lastPath

Path of the file on the computer where it was last seen.

Fields of the JSON object with the description of the computers where a file was detected

Get the Details of Multiple Computers

Gets information about one or more computers in the client’s IT infrastructure.

Request

Command

POST

URL

/api/v1/applications/forensics/muid/info

Required parameters in the HTTP message body

JSON object with the list of MUIDs of the computers.

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get information about computers
Response

List of JSON objects with details of the computers.

Field Description

MUID

Unique ID of the computer.

machineName

Name of the computer.

lastSeenUtc

UTC-0 date on which the computer last communicated with the Cytomic cloud.

creationDate

Date on which the Cytomic EDR protection was installed on the computer.

clientId

Unique ID of the client the computer belongs to.

clientName

Name of the client.

clientCreationDate

Date on which the client integrated their first computer onto the Cytomic Orion platform.

Format of the JSON object that describes a computer

Get a Computer MUID

Gets the MUID of a computer in the client’s IT infrastructure from the computer name.

Request

Command

GET

URL

/api/v1/applications/clients/{ClientId}/machine-name/{MachineName}/muid

Required parameters in the URL

  • ClientId: Unique ID of the client.

  • MachineName: Name of the computer whose MUID you want to get. It allows character substrings.

Headers

Accept: application/json

Format of the call to get a computer MUID
Response

List of JSON objects with the names and other additional information about the computers that match the substring specified in the MachineName field of the request.

Field Description

MUID

Unique ID of the computer.

machineName

Name: Full name of the computer.

lastSeenUtc

UTC-0 date on which the computer last communicated with the Cytomic cloud.

creationDate

Date on which the Cytomic EDR protection was installed on the computer.

Format of the JSON object that contains a computer MUID

Get the Details of a Computer

Gets the full details of a computer in the client’s IT infrastructure.

Request

Command

GET

URL

/api/v1/remediations/muids/{muid}/detail

Required parameters in the URL

MUID: Unique identifier of the computer.

Headers

Accept: application/json

Format of the call to get a computer details
Response

JSON object with a computer details. For a full description of the fields, see Computer Details.

Get the Date When One or More Computers Were Last Seen

Gets the date when a client’s computers were first seen and last seen.

  • If you do not send the optional parameter machineName, you get data for all of the client’s computers.

  • If you send the optional parameter machineName, you get data for the computer you specified.

Request

Command

GET

URL

/api/v1/clients/{pandaClientId}/machines

Required parameters in the URL

pandaClientId: Client ID.

Optional parameters in the URL

machineName: Name of the computer.

Headers

Accept: application/json

Format of the call to get dates for one or more computers
Response

List of JSON objects with data for the computers.

JSON object field Description

MUID

ID of the computer.

Machine Name

Name of the computer.

LastSeenUtc

Date the computer last connected to the Cytomic cloud.

CreationDate

Date the file was first logged in the Cytomic cloud.

Fields in the JSON object with the computer attributes

Example of How to Get Extended Information about Computers and Files

This example gets a list of all the computers where a file was detected, and shows information about the computers and the file.

#Headers for the API call including the access token

h_request_know = {

'Authorization': f'Bearer {access_token}',

'Accept': 'application/json'

#Aim: To get information about an MD5 hash

#File MD5 hash

md5='6cff0673ce2002a2fe2218642605187a'

#Call URL

url_md5_info = f'https://api.orion.cytomic.ai/api/v1/applications/forensics/md5/{md5}/info'

r = requests.get(url_md5_info, headers=h_request_know, verify=False)

#Returns a JSON object with information about the file

file=r.json()

#Aim: To get a list of computers where the MD5 hash was detected

#Call URL

url_computers = f'https://api.orion.cytomic.ai/api/v1/applications/forensics/md5/{md5}/muids'

r = requests.get(url_computers, headers=h_request_know, verify=False)

#Returns a list of JSON objects with information about each computer

computers=r.json()

#Aim: To get extended information about each computer where the MD5 hash was detected

#For each computer, the MUID is extracted from the JSON object and a call is made to the #extended information API.

for computer in computers:

#Computer MUID

muid=computer['muid']

#Call URL

url_computers_info = f'https://api.orion.cytomic.ai/api/v1/applications/forensics/muid/{muid}/info'

r = requests.get(url_computers_info, headers=h_request_know, verify=False)

#Returns a JSON object with information about the computer

computer_info=r.json()