APIs and example scripts for earlier releases can be found at:
- Cb v3.0 (zip) (tgz) - initial API docs
- Cb v3.1 (zip) (tgz) - added
segment_id
- Cb v3.2 (zip) (tgz) - no changes from v3.1
The following APIs are versioned. Backwards compatibility will be maintained for at least two major version revisions.
/api/v1/process
- Process search/api/v1/process/(id)/(segment)
- Process summary data/api/v1/process/(id)/(segment)/event
- Events for the selected process/api/v1/process/(id)/(segment)/preview
- Preview for the selected process
/api/v1/binary
- Binary search/api/v1/binary/(md5)
- Download the binary/api/v1/binary/(md5)/icon
- Binary's icon/api/v1/binary/(md5)/summary
- Binary's metadata
/api/v1/sensor/
- Sensor details
The following APIs are beta. Backwards compatibility will not be supported. Contents are not expected to widely change.
Process search. Parameters passed as a query string.
Supports:: GET
q
: REQUIRED Query string. Accepts the same data as the search box on the Process Search page.TODO
: link to query syntax docrows
: OPTIONAL Return this many rows, 10 by default.start
: OPTIONAL Start at this row, 0 by default.sort
: OPTIONAL Sort rows by this field and order.last_update desc
by default.facets
: OPTIONAL Return facet results. 'false' by default, set to 'true' for facets.
JSON object with the following elements:
results
: a list of matching processes (see below for process object)terms
: a list of strings, each representing a token as parsed by the query parsertotal_results
: number of matching processesstart
: index of first rowelapsed
: clock time elapsed resolving this requestevents
: a list of event objects matching the query string (see below for event object)facets
: a list of facet entries if requested. (see below for facet object)tagged_pids
: a list of process IDs in this result set that have one or more events tagged as part of an investigationfiltered
: count of results filtered due to security settings
Process Object
A process contains the following fields:
process_md5
: the md5 of the binary image backing the processprocess_name
: the name of the processstart
: the start time of the process in remote computer's GMT timelast_update
: the time of the most recently received event for this process in remote computer's GMT timehostname
: the hostname of the computer for this processmodload_count
: the count of modules loaded in this processregmod_count
: the count of registry modifications in this processfilemod_count
: the count of file modifications in this processnetconn_count
: count of network connections in this processchildproc_count
: the count of child processes launched by this processgroup
: the CB Host group this sensor is assigned tosensor_id
: the internal CB id for this computer's sensorid
: the internal CB process GUID for this process (processes are identified by this GUID and their segment id)segment_id
: the process segment id (processes are identified by this segment id and their process ID id)unique_id
: internal CB process id combining of the process GUID and segment GUID
Event Object
An event object contains the following fields:
name
: the full value containing a match. The matching substring is bracketed with PREPREPRE and POSTPOSTPOSTids
: a list of processunique_id
s containingname
Facet Object
The facet object is a list of dictionaries with the following keys. Each key is a list of facet results objects that contain the top 200 name, value and percentage for the unique set of results matching the search.
process_md5
: the top unique process_md5s for the processes matching the searchhostname
: the top unique hostnames matching the searchgroup
: the top unique host groups for hosts matching this searchpath_full
: the top unique paths for the processes matching this searchparent_name
: the top unique parent process names for the processes matching this searchprocess_name
: the top unique process names for the processes matching this searchhost_type
: the distribution of host types matching this search: one of workstation, server, domain_controllerhour_of_day
: the distribution of process start times by hour of day in computer local timeday_of_week
: the distribution of process start times by day of week in computer local timestart
: the distribution of process start times by day for the last 30 days
Each facet result object has three values:
name
: the facet valuevalue
: the count of occurrences of this valuepercent
: the ratio of this value to the total set of values in the result set
A complete example:
GET http://192.168.206.151/api/v1/process/?q=notepad.exe
{
"results": [
{
"process_md5": "ac4c51eb24aa95b77f705ab159189e24",
"process_name": "explorer.exe",
"group": "Default Group",
"segment_id": 1,
"netconn_count": 0,
"hostname": "WIN-EP7RMLTCLAJ",
"last_update": "2013-08-22T15:00:02Z",
"start": "2013-08-14T13:41:57Z",
"sensor_id": 2,
"modload_count": 103,
"path": "c:\\windows\\explorer.exe",
"regmod_count": 355,
"filemod_count": 10,
"id": "-3748189368838069954",
"unique_id": "cbfbc1a0-b782-e13e-0000-000000000001",
"childproc_count": 7
},
],
"terms": [
"notepad.exe"
],
"total_results": 1,
"elapsed": 0.8763120174407959,
"start": 0,
"facets": {},
"events": [
{
"name": "\\registry\\user\\s-1-5-21-2445116603-3509627529-3207332553-1000_classes\\local settings\\software\\microsoft\\windows\\shell\\muicache\\c:\\windows\\system32\\PREPREPREnotepad.exePOSTPOSTPOST",
"ids": [
"cbfbc1a0-b782-e13e-0000-000000000001"
]
},
]
"tagged_pids": { },
"filtered": {},
}
Gets basic process information for segment (segment) of process (guid)
Supports: GET
id
: REQUIRED the internal CB process guid, theid
field in search resultssegment
: REQUIRED the process segment, thesegment_id
field in search results.
A JSON object with the following structure:
process
: a process summary object with metadata for the selected processsiblings
: a list of process summary objects for the first 15 sibiling processeschildren
: a list of process summary objects for each child processparent
: a process summary object with metadata for the parent process
Each process summary object contains the following structure:
process_md5
: the MD5 of the executable backing this processsensor_id
: the sensor id of the host this process executed ongroup
: the sensor group the sensor was assigned toparent_id
: the process guid of the parent processprocess_name
: the name of this process, e.g., svchost.exepath
: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.exelast_update
: the time of the last event received from this process, as recorded by the remote hoststart
: the start time of this process, as recorded by the remote hosthostname
: the hostname of the computer this process executed onid
: the internal CB process guid of this processsegment_id
: the segment id of this process
A complete example:
GET http://192.168.206.154/api/v1/process/2032659773721368929/1
{
"process": {
"process_md5": "517110bd83835338c037269e603db55d",
"sensor_id": 2,
"group": "Default Group",
"start": "2013-09-19T22:07:07Z",
"process_name": "taskhost.exe",
"segment_id": 1,
"last_update": "2013-09-19T22:09:07Z",
"cmdline": "taskhost.exe $(arg0)",
"hostname": "WIN-EP7RMLTCLAJ",
"parent_id": "5856845119039539348",
"path": "c:\\windows\\system32\\taskhost.exe",
"id": "2032659773721368929"
},
"siblings": [
{
"process_md5": "c78655bc80301d76ed4fef1c1ea40a7d",
"sensor_id": 2,
"group": "Default Group",
"parent_id": "5856845119039539348",
"process_name": "svchost.exe",
"segment_id": 1,
"last_update": "2013-09-19T22:34:49Z",
"start": "2013-09-10T04:10:07Z",
"hostname": "WIN-EP7RMLTCLAJ",
"path": "c:\\windows\\system32\\svchost.exe",
"id": "5286285292765095481"
},
],
"children": [],
"parent": {
"process_md5": "24acb7e5be595468e3b9aa488b9b4fcb",
"sensor_id": 2,
"group": "Default Group",
"parent_id": "4245649408199694328",
"process_name": "services.exe",
"segment_id": 1,
"last_update": "2013-09-19T22:09:07Z",
"start": "2013-09-10T04:09:51Z",
"hostname": "WIN-EP7RMLTCLAJ",
"path": "c:\\windows\\system32\\services.exe",
"id": "5856845119039539348"
}
}
Gets the events for the process with id (id) and segment (segment)
Supports:: GET
id
: REQUIRED the internal CB process guid, theid
field in search resultssegment
: REQUIRED the process segment, thesegment_id
field in search results.
A JSON object with the following structure:
process
: a process summary object with metadata and events for the selected processelapsed
: the clock time required to get this structure
The process object may contain the following entries.
process_md5
: the MD5 of the executable backing this processsensor_id
: the sensor id of the host this process executed ongroup
: the sensor group the sensor was assigned toparent_id
: the process guid of the parent processprocess_name
: the name of this process, e.g., svchost.exepath
: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.execmdline
: the command line of the processlast_update
: the time of the last event received from this process, as recorded by the remote hoststart
: the start time of this process, as recorded by the remote hosthostname
: the hostname of the computer this process executed onid
: the internal CB process guid of this processsegment_id
: the segment id of this processregmod_complete
: a pipe-delimited list of regmod stringsfilemod_complete
: a pipe-delimited list of filemod stringsmodload_complete
: a pipe-delimited list of modload stringsnetconn_complete
: a pipe-delimited list of netconn stringschildproc_complete
: a pipe-delimited list of childproc strings
Each xxx_complete record is a string similar to:
2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll"
The pipe character (|
) delimits the fields.
"1|2013-09-16 07:11:58.000000|c:\\documents and settings\\administrator\\local settings\\temp\\hsperfdata_administrator\\3704|"
- field 0: operation type, an integer 1, 2, 4 or 8
- 1: Created the file
- 2: First wrote to the file
- 4: Deleted the file
- 8: Last wrote to the file
- field 1: event time
- field 2: file path
- field 3: if operation type (field 0) is 8, last write, this value is the md5 of the file after the last write
2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll"
- field 0: event time
- field 1: MD5 of the loaded module
- field 2: Full path of the loaded module
"2|2013-09-19 22:07:07.000000|\\registry\\user\\s-1-5-19\\software\\microsoft\\sqmclient\\reliability\\adaptivesqm\\manifestinfo\\version"
- field 0: operation type, an integer 1, 2, 4 or 8
- 1: Created the registry key
- 2: First wrote to the registry key
- 4: Deleted the key
- 8: Deleted the value
- field 1: event time
- field 3: the registry key path
"2013-09-16 07:11:59.000000|-1979811809|80|6|dl.javafx.com|true"
- field 0: event time
- field 1: remote IP address as a 32-bit signed long
- field 2: remote port
- field 3: protocol: 6 is TCP, 17 is UDP
- field 4: domain name associated with the IP address, from the client's perspective at the time of the network connection
- field 5: boolean "true" if the connection was outbound; "false" if the connection was inbound
A complete example:
GET http://192.168.206.154/api/v1/process/2032659773721368929/1/event
{"process":
{"process_md5": "517110bd83835338c037269e603db55d",
"sensor_id": 2,
"group": "Default Group",
"start": "2013-09-19T22:07:07Z",
"process_name": "taskhost.exe",
"segment_id": 1,
"regmod_complete": [
"2|2013-09-19 22:07:07.000000|\\registry\\user\\s-1-5-19\\software\\microsoft\\sqmclient\\reliability\\adaptivesqm\\manifestinfo\\version",
"2|2013-09-19 22:09:07.000000|\\registry\\machine\\software\\microsoft\\reliability analysis\\rac\\wmilasttime"
],
"parent_id": "5856845119039539348",
"cmdline": "taskhost.exe $(arg0)",
"filemod_complete": [
"2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racmetadata.dat|",
"2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4475.tmp|",
"2|2013-09-19 22:07:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4486.tmp|",
"2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racwmidatabookmarks.dat|",
"2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\publisheddata\\racwmidatabase.sdf|",
"4|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4486.tmp|",
"2|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\statedata\\racdatabase.sdf|",
"4|2013-09-19 22:09:07.000000|c:\\programdata\\microsoft\\rac\\temp\\sql4475.tmp|"
],
"hostname": "WIN-EP7RMLTCLAJ",
"modload_complete": [
"2013-09-19 22:07:07.000000|517110bd83835338c037269e603db55d|c:\\windows\\system32\\taskhost.exe",
"2013-09-19 22:07:07.000000|3556d5a8bf2cc508bdab51dec38d7c61|c:\\windows\\system32\\ntdll.dll",
"2013-09-19 22:07:07.000000|7a6326d96d53048fdec542df23d875a0|c:\\windows\\system32\\kernel32.dll",
"2013-09-19 22:07:07.000000|9c75cb8b98610f0cd85d99bb5876308b|c:\\windows\\system32\\sqlcese30.dll",
"2013-09-19 22:07:07.000000|e5744d18c88737c6356d0a8d6d49d512|c:\\windows\\system32\\sqlceqp30.dll",
"2013-09-19 22:07:07.000000|021287c2050fd5db4a8b084e2c38139c|c:\\windows\\system32\\winsatapi.dll",
"2013-09-19 22:07:07.000000|f404e59db6a0f122ab26bf4f3e2fd0fa|c:\\windows\\system32\\dxgi.dll",
"2013-09-19 22:07:07.000000|da1b7075260f3872585bfcdd668c648b|c:\\windows\\system32\\dwmapi.dll",
"2013-09-19 22:07:07.000000|497bfeddaf3950dd909c3b0c5558a25d|c:\\windows\\winsxs\\amd64_microsoft.windows.gdiplus_6595b64144ccf1df_1.1.7601.17514_none_2b24536c71ed437a\\gdiplus.dll",
"2013-09-19 22:07:07.000000|5d8e6c95156ed1f79a63d1eade6f9ed5|c:\\windows\\system32\\setupapi.dll",
"2013-09-19 22:07:07.000000|2a86e54b441ad41557f75dc5609b9793|c:\\windows\\system32\\sspicli.dll",
"2013-09-19 22:07:07.000000|d6f630c1fd7f436316093ae500363b19|c:\\windows\\system32\\xmllite.dll"
],
"path": "c:\\windows\\system32\\taskhost.exe",
"last_update": "2013-09-19T22:09:07Z",
"id": "2032659773721368929"
},
"elapsed": 0.0126001834869
}
Process preview. Requires id and segment id.
Supports: GET
id
: REQUIRED the internal CB process guid, theid
field in search resultssegment
: REQUIRED the process segment, thesegment_id
field in search results.query
: OPTIONAL a process query string. If present, preview results will highlight matching terms
A process preview structure with the following fields:
process_md5
: the MD5 of the executable backing this processsensor_id
: the sensor id of the host this process executed ongroup
: the sensor group the sensor was assigned toprocess_name
: the name of this process, e.g., svchost.exepath
: the full path of the executable backing this process, e.g., c:\windows\system32\svchost.exelast_update
: the time of the last event received from this process, as recorded by the remote hoststart
: the start time of this process, as recorded by the remote hosthostname
: the hostname of the computer this process executed onid
: the internal CB process guid of this processsegment_id
: the segment id of this processregmod_complete
: a pipe-delimited summary list of regmod strings (see spec above)filemod_complete
: a pipe-delimited summary list of filemod strings (see spec above)modload_complete
: a pipe-delimited summary list of modload strings (see spec above)netconn_complete
: a pipe-delimited summary list of netconn strings (see spec above)childproc_complete
: a pipe-delimited list of summary childproc strings (see spec above)modload_count
: the total count of modules loaded in this processregmod_count
: the total count of registry modifications in this processfilemod_count
: the total count of file modifications in this processnetconn_count
: total count of network connections in this processchildproc_count
: the total count of child processes launched by this process
If a query string is provided, the endpoint will highlight all matching strings. Highlighted results will
be surrounded with PREPREPRE
and POSTPOSTPOST
to designate the start and end of a matching substring.
Where the full process API endpoint will return all xxx_complete
records in the process (possibly 10s of thousands),
the preview endpoint will have 10s of events for this process.
A complete example:
GET http://192.168.206.132/api/v1/process/7078511340675742078/1/preview/?q=windows
{
"parent_name": "",
"hostname": "J-8205A0C27A0C4",
"group": "Default Group",
"process_md5": "5e7f3968069d32b26af0d7af0ec5dd97",
"netconn_count": 1,
"process_name": "svchost.exe",
"last_update": "2013-10-07T15:07:09Z",
"cmdline": "\"c:\\docume~1\\admini~1\\locals~1\\temp\\rad17929.tmp\\svchost.exe\" ",
"start": "2013-10-07T15:07:09Z",
"sensor_id": 1,
"modload_count": 15,
"modload_complete": [
"2013-10-07 15:07:09.000000|27d9ed8cb8b62d1e0a8e5ace6cf52e2f|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ntdll.dll",
"2013-10-07 15:07:09.000000|c24b983d211c34da8fcc1ac38477971d|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\kernel32.dll",
"2013-10-07 15:07:09.000000|355edbb4d412b01f1740c17e3f50fa00|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\msvcrt.dll",
"2013-10-07 15:07:09.000000|bab489a5fe26f2d0c910cf7af7e4cf92|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\advapi32.dll",
"2013-10-07 15:07:09.000000|b979d9d1c8073da21a7f80345f306a1d|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\rpcrt4.dll",
"2013-10-07 15:07:09.000000|7459c16cc3ef4651cab7c9260e43fc58|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\secur32.dll",
"2013-10-07 15:07:09.000000|67156d5a9ac356dc99d7bccb388e3316|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\wsock32.dll",
"2013-10-07 15:07:09.000000|2ccc474eb85ceaa3e1fa1726580a3e5a|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ws2_32.dll",
"2013-10-07 15:07:09.000000|9789e95e1d88eeb4b922bf3ea7779c28|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\ws2help.dll",
"2013-10-07 15:07:09.000000|b4138e99236f0f57d4cf49bae98a0746|c:\\PREPREPREwindowsPOSTPOSTPOST\\system32\\mswsock.dll"
],
"path": "c:\\documents and settings\\administrator\\local settings\\temp\\rad17929.tmp\\svchost.exe",
"regmod_count": 0,
"filemod_count": 0,
"segment": "",
"id": "7078511340675742078",
"unique_id": "623bec8f-8f8d-397e-0000-000000000001"
}
Binary search. Parameters passed as query string.
Supports:: GET
q
: REQUIRED Query string. Accepts the same data as the search box on the Binary Search page.TODO
: link to query syntax docrows
: OPTIONAL Return this many rows, 10 by default.start
: OPTIONAL Start at this row, 0 by default.sort
: OPTIONAL Sort rows by this field and order.server_added_timestamp desc
by default.facets
: OPTIONAL Return facet results. 'false' by default, set to 'true' for facets.
JSON object with the following elements:
results
: a list of matching binaries (see below for binary object)terms
: a list of strings, each representing a token as parsed by the query parsertotal_results
: number of matching binariesstart
: index of first rowelapsed
: clock time elapsed resolving this requesthighlights
: a list of highlight objects matching the query string. Format the same as the process event object.facets
: a list of facet entries if requested. (see below for facet object)
Binary Object
A binary object contains the following fields:
md5
: the md5 hash of this binaryserver_added_timestamp
: the first time this binary was received on the server in the server's GMT timeorig_mod_len
: Filesize in bytescopied_mod_len
: Bytes copied from remote host, if file is > 25MB this will be less thanorig_mod_len
observed_filename
: The set of unique filenames this binary has been seen asis_executable_image:
'true' or 'false' - 'true' if an EXEis_64bit
: 'true' or 'false' - 'true' if x64product_version
: If present, Product version from FileVersionInformationproduct_name
: If present, Product name from FileVersionInformationfile_Version
: If present, File version from FileVersionInformationcompany_name
: If present, Company name from FileVersionInformationinternal_name
: If present, Internal name from FileVersionInformationproduct_name
: If present, Product name from FileVersionInformationlegal_copyright
: If present, Legal copyright from FileVersionInformationlegal_trademark
: If present, Legal trademark from FileVersionInformationfile_desc
: If present, File description from FileVersionInformationoriginal_filename
: If present, Original filename from FileVersionInformationprivate_build
: If present, Private build from FileVersionInformationspecial_build
: If present, Special build from FileVersionInformationsigned
: Digital signature status: One ofSigned
,Unsigned
,Expired
,Bad Signature
,Invalid Signature
,Invalid Chain
,Untrusted Root
,Explicit Distrust
digsig_result
: Digital signature status: One ofSigned
,Unsigned
,Expired
,Bad Signature
,Invalid Signature
,Invalid Chain
,Untrusted Root
,Explicit Distrust
digsig_result_code
: HRESULT_FROM_WIN32 for the result of the digital signature operation via WinVerifyTrustdigsig_sign_time
: If signed, the timestamp of the signature in GMTdigsig_publisher
: If signed and present, the publisher namedigsig_prog_name
: If signed and present, the program namedigsig_issuer
: If signed and present, the issuer namedigsig_subject
: If signed and present, the subjectalliance_score_virustotal
: If enabled and the hit count > 1, the number of VirusTotal hits for this md5
Facet object
The facet object is a list of dictionaries with the following keys. Each key is a list of facet results objects that contain the top 200 name, value and percentage for the unique set of results matching the search.
product_name_facet
: the top unique product names for the binaries matching the searchfile_version_facet
: the top unique file versions for the binaries matching the searchalliance_score_virustotal
: the distribution of VirusTotal scores for binaries matching the searchdigsig_result
: the distribution of signature status results for binaries matching the searchcompany_name_facet
: the top unique company names for the binaries matching the searchdigsig_publisher_facet
: the top unique publisher names for the binaries matching the searchproduct_name_facet
: the top unique company anmes for the binaries matching the searchdigsig_sign_time
: the distribution of signature times per month for the last 48 months for binaries matching the searchserver_added_timestamp
: the distribution of server_added_timestamps per day for the last 30 daysobserved_filename_facet
: the top unique observed filenames for the binaries matching the search
The facet result objects have the same format as the process facet result objects above.
A complete example:
GET http://192.168.206.151/api/binary?q=notepad.exe
{
"total_results": 1,
"facets": {},
"elapsed": 0.046832799911499023,
"start": 0,
"results": [
{
"md5": "F2C7BB8ACC97F92E987A2D4087D021B1",
"digsig_result": "Signed",
"observed_filename": [
"c:\\windows\\system32\\notepad.exe"
],
"product_version": "6.1.7600.16385",
"signed": "Signed",
"digsig_sign_time": "2009-07-14T10:17:00Z",
"orig_mod_len": 193536,
"is_executable_image": true,
"is_64bit": true,
"digsig_publisher": "Microsoft Corporation",
"file_version": "6.1.7600.16385 (win7_rtm.090713-1255)",
"company_name": "Microsoft Corporation",
"internal_name": "Notepad",
"product_name": "Microsoft\u00ae Windows\u00ae Operating System",
"digsig_result_code": "0",
"timestamp": "2013-08-16T11:26:48.321Z",
"copied_mod_len": 193536,
"server_added_timestamp": "2013-08-16T11:26:48.321Z",
"legal_copyright": "\u00a9 Microsoft Corporation. All rights reserved.",
"original_filename": "NOTEPAD.EXE",
"file_desc": "Notepad"
}
],
"terms": [
"notepad.exe"
],
"highlights": [
{
"name": "PREPREPRENOTEPAD.EXEPOSTPOSTPOST",
"ids": [
"F2C7BB8ACC97F92E987A2D4087D021B1"
]
},
{
"name": "c:\\windows\\system32\\PREPREPREnotepad.exePOSTPOSTPOST",
"ids": [
"F2C7BB8ACC97F92E987A2D4087D021B1"
]
}
],
}
Download the binary with this md5 hash.
Supports:: GET
md5
: REQUIRED the md5 hash of the binary
A zipfile with the binary bytes and a text file with metadata.
Returns the icon for the binary with the provided md5
Supports:: GET
md5
: REQUIRED the md5 of the binary
A PNG with the icon. If the icon is not found, it returns the default Windows icon.
Returns the metadata for the binary with the provided md5
Supports: GET
md5
: REQUIRED the md5 of the binary
A structure with the following fields:
md5
: the md5 hash of this binaryserver_added_timestamp
: the first time this binary was received on the server in the server's GMT timeorig_mod_len
: Filesize in bytescopied_mod_len
: Bytes copied from remote host, if file is > 25MB this will be less thanorig_mod_len
observed_filename
: A list of strings, one per unique filename this binary has been seen asis_executable_image:
'true' or 'false' - 'true' if an EXEis_64bit
: 'true' or 'false' - 'true' if x64product_version
: If present, Product version from FileVersionInformationproduct_name
: If present, Product name from FileVersionInformationfile_Version
: If present, File version from FileVersionInformationcompany_name
: If present, Company name from FileVersionInformationinternal_name
: If present, Internal name from FileVersionInformationproduct_name
: If present, Product name from FileVersionInformationlegal_copyright
: If present, Legal copyright from FileVersionInformationlegal_trademark
: If present, Legal trademark from FileVersionInformationfile_desc
: If present, File description from FileVersionInformationoriginal_filename
: If present, Original filename from FileVersionInformationprivate_build
: If present, Private build from FileVersionInformationspecial_build
: If present, Special build from FileVersionInformationsigned
: Digital signature status: One ofSigned
,Unsigned
,Expired
,Bad Signature
,Invalid Signature
,Invalid Chain
,Untrusted Root
,Explicit Distrust
digsig_result
: Digital signature status: One ofSigned
,Unsigned
,Expired
,Bad Signature
,Invalid Signature
,Invalid Chain
,Untrusted Root
,Explicit Distrust
digsig_result_code
: HRESULT_FROM_WIN32 for the result of the digital signature operation via WinVerifyTrustdigsig_sign_time
: If signed, the timestamp of the signature in GMTdigsig_publisher
: If signed and present, the publisher namedigsig_prog_name
: If signed and present, the program namedigsig_issuer
: If signed and present, the issuer namedigsig_subject
: If signed and present, the subjectalliance_score_virustotal
: If enabled and the hit count > 1, the number of VirusTotal hits for this md5
A complete example:
GET http://192.168.206.154/api/binary/1C8B787BAA52DEAD1A6FEC1502D652f0/summary
{
"product_version_facet": "8.00.7600.16385",
"digsig_result": "Signed",
"observed_filename": [
"c:\\windows\\system32\\mshtml.dll"
],
"product_version": "8.00.7600.16385",
"product_name_facet": "Windows\u00ae Internet Explorer",
"signed": "Signed",
"digsig_sign_time": "2010-11-21T03:36:00Z",
"orig_mod_len": 8988160,
"is_executable_image": false,
"is_64bit": true,
"observed_filename_facet": [
"c:\\windows\\system32\\mshtml.dll"
],
"file_version_facet": "8.00.7600.16385 (win7_rtm.090713-1255)",
"digsig_publisher": "Microsoft Corporation",
"file_version": "8.00.7600.16385 (win7_rtm.090713-1255)",
"company_name": "Microsoft Corporation",
"internal_name": "MSHTML",
"_version_": 1446430562211332096,
"product_name": "Windows\u00ae Internet Explorer",
"digsig_result_code": "0",
"timestamp": "2013-09-17T13:14:37.636Z",
"company_name_facet": "Microsoft Corporation",
"copied_mod_len": 8988160,
"server_added_timestamp": "2013-09-17T13:14:37.636Z",
"md5": "1C8B787BAA52DEAD1A6FEC1502D652F0",
"legal_copyright": "\u00a9 Microsoft Corporation. All rights reserved.",
"digsig_publisher_facet": "Microsoft Corporation",
"original_filename": "MSHTML.DLL.MUI",
"file_desc": "Microsoft (R) HTML Viewer"
}
Sensor / remote client details
Supports: GET
for all variations, PUT
for /api/v1/sensor/(id)
to update event_log_flush_time
id
: OPTIONAL the sensor idhostname
: OPTIONAL returns the sensor record(s) with matching hostnameipaddr
: OPTIONAL returns the sensor record(s) with specified IP address
- With no parameters (
GET /api/v1/sensor/
) returns a list of sensor structures, one per registered sensor. - With a sensor id, (
GET /api/v1/sensor/12
) returns a sensor structure for the specified sensor. - With a query string, (
GET /api/v1/sensor?hostname=foo
) returns a list of all sensors matching criteria
Sensor query strings are case-sensitive substring searches, for both hostname
and ip
fields. If both
hostname
and ip
fields are specified, only ip
is used.
A sensor structure has the following fields:
id
: this sensor's idbuild_id
: the sensor version installed on this endpoint. From the/api/builds/
endpointbuild_version_string
: Human-readable string of the host's installed sensor versionuptime
: Host's uptime in secondssystemvolume_total_size
: size in bytes of the computer's system volumnsystemvolume_free_size
: bytes free on the system volumeos_environment_display_string
: Human-readable string of the installed OSos_environment_id
: the operating system installed on this computer. From the internal table.physical_memory_size
: size in bytes of physical memorycomputer_dns_name
: this computer's DNS namecomputer_name
: NetBIOS name of this computersensor_health_message
: Human-readable string indicating sensor's self-reported statuscomputer_sid
: Machine SID of this hostevent_log_flush_time
: See below.last_checkin_time
: Last communication with this computer in server-local time and zonenetwork_adapters
: A pipe-delimited list list of IP,MAC pairs for each network interfacesensor_health_status
: sensor's self-reported health score, from 0 to 100. Higher numbers betterregistration_time
: Time this sensor originally registered in server-local time and zonenext_checkin_time
: Next expected communication from this computer in server-local time and zoneboot_id
: A sequential counter of boots since the sensor was installedgroup_id
: The sensor group id this sensor is assigned todisplay
: If this sensor is shown on the hosts page. Sensors details are never deleted, just hidden.uninstall
: true if this sensor has been told to uninstall.cookie
: cb internal
If event_log_flush_time
is set, the server will instruct the sensor to immediately send all data before this date,
ignoring all other throttling mechansims. To force a host current, set this value to a value far in the future.
When the sensor has finished sending it's queued data, this value will be null.
A complete example:
GET http://192.168.206.154/api/v1/sensor/1
{
"systemvolume_total_size": "42939584512",
"os_environment_display_string": "Windows XP Professional Service Pack 3",
"sensor_uptime": "638",
"physical_memory_size": "536330240",
"build_id": 1,
"uptime": "666",
"computer_dns_name": "j-8205a0c27a0c4",
"id": 1,
"systemvolume_free_size": "40167079936",
"sensor_health_message": "Healthy",
"build_version_string": "003.002.000.30829",
"computer_sid": "S-1-5-21-1715567821-507921405-682003330",
"event_log_flush_time": null,
"computer_name": "J-8205A0C27A0C4",
"last_checkin_time": "2013-09-10 07:08:37.378860-07:00",
"license_expiration": "1990-01-01 00:00:00-08:00",
"network_adapters": "192.168.206.156,000c298a3613|",
"sensor_health_status": 100,
"registration_time": "2013-09-10 06:49:21.261157-07:00",
"next_checkin_time": "2013-09-10 07:09:07.368285-07:00",
"notes": null,
"os_environment_id": 1,
"boot_id": "5",
"cookie": 1291426991,
"group_id": 1,
"display": true,
"uninstall": false
}
http://192.168.206.132/api/v1/sensor?hostname=A0C4
[
{
"systemvolume_total_size": "42939584512",
"os_environment_display_string": "Windows XP Professional Service Pack 3",
"sensor_uptime": "480763",
"physical_memory_size": "536330240",
"build_id": 1,
"uptime": "480862",
"event_log_flush_time": null,
"computer_dns_name": "j-8205a0c27a0c4",
"id": 1,
"power_state": 0,
"uninstalled": null,
"systemvolume_free_size": "40083230720",
"status": "Online",
"num_eventlog_bytes": "22717",
"sensor_health_message": "Healthy",
"build_version_string": "004.000.000.30910",
"computer_sid": "S-1-5-21-1715567821-507921405-682003330",
"next_checkin_time": "2013-10-07 07:54:36.909657-07:00",
"node_id": 0,
"cookie": 556463980,
"computer_name": "J-8205A0C27A0C4",
"license_expiration": "1990-01-01 00:00:00-08:00",
"network_adapters": "192.168.206.156,000c298a3613|",
"sensor_health_status": 100,
"registration_time": "2013-02-04 06:40:04.632053-08:00",
"restart_queued": false,
"notes": null,
"num_storefiles_bytes": "446464",
"os_environment_id": 1,
"boot_id": "8",
"last_checkin_time": "2013-10-07 07:54:06.919446-07:00",
"group_id": 1,
"display": true,
"uninstall": false
}
]