Threat Grid Documentation - Main API

2/21/2017 Threat Grid Documentation
ThreatGRID Data API (Version 2.0)

Last Updated 9/7/2016
Contents
Intro
API Access
Authentication
JSON Response Format
Pagination
Error Handling
Experimental API Calls
Samples API
Sample Info Record
Samples API Endpoint Summary Table
Submission
POST /samples
Querying Samples
GET /samples
GET /samples/ID
GET /samples/ID/state
POST/GET /samples/state
Samples Search API
GET /samples/search
Analysis Results
GET /samples/ID/video.webm
GET /samples/ID/analysis.json
GET /samples/ID/processes.json
GET /samples/ID/network.pcap
GET /samples/ID/warnings.json
GET /samples/ID/summary
GET /samples/ID/threat
GET /samples/ID/report.html
GET /samples/id/sample.zip
Access to Specic Elements of analysis.json
GET /samples/ID/analysis/iocs
GET /samples/ID/analysis/iocs/IOC
GET /samples/ID/analysis/network_streams
GET /samples/ID/analysis/network_streams/NSID
GET /samples/ID/analysis/artifacts
GET /samples/ID/analysis/artifacts/AID
GET /samples/ID/analysis/processes
GET /samples/ID/analysis/processes/PID
GET /samples/ID/analysis/annotations
GET /samples/ID/analysis/metadata
Indicator of Compromise Feeds
IP Address Feed - GET /iocs/feeds/ips
Domain/Hostname Feed - GET /iocs/feeds/domains
URL Feed - GET /iocs/feeds/urls
Artifact Feed - GET /iocs/feeds/artifacts
Path Feed - GET /iocs/feeds/paths
Network Stream Feed - GET /iocs/feeds/network_streams
Registry Key Feed - GET /iocs/feeds/registry_keys
Sample Feeds
GET /samples/feeds/paths
GET /samples/feeds/checksums
GET /samples/feeds/domains
GET /samples/feeds/ips
Entity Search
Get /search/registry-keys
GET /search/paths
GET /search/ips
GET /search/domains
GET /search/artifacts
GET /search/samples
GET /search/urls
https://panacea.threatgrid.com/doc/main/api.html#post-samples 1/29
Entity Queries
GET /domains/NAME
GET /paths/ID
GET /registry_keys/ID
GET /registry_keys/ID/name/ID
GET /urls/id
GET /artifacts/ID
GET /artifacts/ID/threat
GET /artifacts/ID/download
Flags - GET /ENTITY-PATH/ags
Tags
GET /ENTITY-PATH/tag
POST /ENTITY-PATH/tag
DELETE /ENTITY-PATH/tag/TAG
Federation
GET /samples/feeds/federated
GET /samples/ID/federated.json
GET /samples/ID/Federated.dijon
Intro
This is the developers reference document for the main Application

Programming Interface to Threat Grid.
API Access
ALL API Access is done over HTTPS, and the URLs start with:
https://<threatgridurl>/api/v2/
The version string ( v2 ) will be iterated whenever a non-backwards

compatible change is made. Backwards compatible changes WILL NOT
iterate the version number. We consider all URL, data eld, or query
parameter additions to be backwards compatible. That means your
JSON parser and response processing should tolerate unknown elds.
Authentication
All API requests require an api_key parameter. This identies the

user and authorizes their access to the API. When authentication
fails, we will return a HTTP 401 response.
JSON Response Format
All API responses are JSON objects; that includes errors. The form of
these objects is:
api_version String identifying the API version
id A randomly generated string token to identify the response.
data The result of the API call, as a JSON object.

* If the result is a single object, then the rest of the attributes will be that of the result object.
* If the result is a list, the the following keys will be present:
* items A JSON list containing the results.
* current\_item\_count The number of items in this result set.
* index The index into the full result set that is contained in this response.
* items\_per\_page The current limit on the number of items in a response.
error JSON object representing an error; if present, there will be no data object.
* message A user readable message describing the rst error.
* code A numeric code identifying the rst error.
* errors A list of error objects:
* code The numeric code for this error.
* message The user readable message describing this error.
* report (optional) A URL or email address to report the error to.
* help (optional) A URL for user documentation regarding this error.
Pagination
Most of these API requests can return very large data sets, so
pagination/segmentation of the results is implied in each API call.
When a request is made, a default per page value will be used.
Users can override it, up to a ceiling value we pick.
All calls which return multiple results will support the following
parameters to control pagination:
Parameter
Description
Name
limit The most results to be returned in the response. The server will put a cap
on this value as well.
offset The number of records to skip.
So if you want to page through results 100 at a time, a limit

of 100, and an offset of 200 would get you the third page of
results.
Error Handling
When a request generates an error, we will set the appropriate HTTP

status code, normally HTTP 501. The response will have the error
key set, as described above.
Experimental API Calls
Since we are experimenting with exposing as much of our data model as
we can, we are going to be explicit in which parts of the API we
consider stable, and which parts we consider experimental.
Samples API
The core entity of ThreatGRID is the sample, a piece of malware
subjected to analysis. A piece of malware can be submitted multiple
times, and that will produce multiple samples. This is because sample
behavior often changes over time as malware interacts with the network
at large.
Sample Info Record
The canonical representation of a Sample in the API is a Sample Info record.
Sample Info
Description
Field
id The sample ID, globally unique, and the canonical identier of this
sample analysis
submission\_id A numeric identifer of the submission, not globally unique. Some

devices which submitted via the V1 api will only have this available.
Deprecated.
filename The lename for the sample, as provided or derived from the
submission
state The state of the sample, one of a stable set of strings pending,
running, succ, proc, fail, prep, wait, run
status A detailed status of the sample.
sha256 The SHA256 hash of the sample
md5 The MD5 hash of the sample, if available
sha1 The SHA1 hash of the sample, if available
os A string identifying the OS, as provided by the submitter.
osver A string identifying the OS version, as provided by the submitter.
private If the sample is marked private, will have the boolean value, true.
submitted\_at The time at which the sample was submitted (ISO 8601)
started\_at The time the sample analysis was started (ISO 8601)
completed\_at The time the sample analysis was completed (ISO 8601)
The following elds are guaranteed to be present: id, submission_id, submitted_at, lename, state, sha256
Example
Here is an example of a sample info record:
{
"timestamp":"2012-04-19T04:11:01-0500",
"state":"succ",
"started_at":"2012-04-19T04:00:55-0500",
"os":"",
"osver":"",
"submission_id":45212,
"filename":"a18e507b000ca0aa3d6ef2ffb67a6fa5",
"submitted_at":"2012-04-19T03:58:37-0500",
"id":"6042aae978338b8b52fbed9bf781490c",
"completed_at":"2012-04-19T04:11:05-0500",
"sha256":"b53cb9792e0ad3327425e2d744a2fb4821f1c3fd815fa0a63781c4d5602ef4f8"
}
Samples API Endpoint Summary Table
Method Endpoint Description
POST /samples Submits a sample to Threat

Grid for Analysis.
GET /samples Queries analyzed samples.
GET /samples/ID DESCRIPTION
GET /samples/ID/state DESCRIPTION
POST/GET /samples/state DESCRIPTION
GET /samples/search Supports an array of Query

Terms grouped by the entity
or value they refer to.
GET /samples/ID/video.webm Requests the samples

display output, transcoded to
WEBM format.
GET /samples/ID/analysis.json JSON object containing

detailed overview of analysis
results.
GET /samples/ID/processes.json JSON object containing a

timeline of process activity,
as determined by the
dynamic analysis engine.
GET /samples/ID/network.pcap tcpdump PCAP le of the

samples network activity
GET /samples/ID/warnings.json JSON structure describing

any warnings that occured
during analysis.
GET /samples/ID/summary Summary analysis

information.
Method Endpoint Description
GET /samples/ID/threat Summary of detected

threats.
GET /samples/ID/report.html report.html is a complete

report on the sample run.
GET /samples/ID/sample.zip sample.zip is an archive of

the sample in zip format as a
form of quarantine.
GET /samples/ID/analysis/iocs Returns a JSON list of the

Indicators of Compromise
from this sample run.
GET /samples/ID/analysis/iocs/IOC Returns data regarding the

specied Indicator of
Compromise.
GET /samples/ID/analysis/network_streams Returns a JSON object

whose attributes are
Network Stream IDs.
GET /samples/ID/analysis/network_streams/NSID Returns a JSON object

describing the specied
Network Stream.
GET /samples/ID/analysis/artifacts Returns a JSON object

whose attributes are Artifact
IDs.
GET /samples/ID/analysis/artifacts/AID Returns a JSON object that

is a summary of the static
analysis of this artifact.
GET /samples/ID/analysis/processes Returns a JSON object

whose attributes are PIDs,
and whose values are
process summaries.
GET /samples/ID/analysis/processes/PID Returns a JSON object that

is the process summary of
the specied PID.
GET /samples/ID/analysis/annotations Returns a JSON object that

represents the annotation
information in the report.
Get /samples/ID/analysis/metadata Returns a JSON object that

represents the metadata
information in the report.
Submission
POST /samples
Submits a sample to ThreatGRID for analysis. The request parameters
should be encoded as multipart/form-data .
Parameters
Name Description
sample the sample le
filename the original lename of the sample, as a string
os a string identifying the source OS
osver a string dening the OS version.
vm a string identifying a specic VM to use
private if present, and set to any value but false the sample will be marked private
source a string identifying the source (user dened)
api_key A secret token identifying the user and providing authentication
tags A comma-separated list of tags applied to this sample.
Returns
A JSON Response with a single Sample Info record as the data.
{
"state":"wait",
"os":"Unknown",
"osver":"Unknown",
"private":true,
"submission_id":1017050,
"filename":"trojan.exe",
"submitted_at":"2012-09-21T16:02:29-0500",
"id":"a3be3d3ed51a7ba60cd2e02c241cd4ac",
"sha256":"41e86455faa9a3dac193bdc95f74959d5ac9c05c64211e7e6e2d9d6b99a5ee3f"
}
Querying Samples
GET /samples
Params
Name Description
sha256 A sha256 of the submitted sample, only matches samples, not their
artifacts
md5 As above, but an MD5 checksum
sha1 As above, but a SHA1 checksum
id a sample ID
ids a comma-separated list of sample IDs
ioc an IOC name
submission\_id A numeric ID for the sample sessions, deprecated
submission\_ids A comma-separated list of numeric ID for the sample sessions,

deprecated
before A date/time (ISO 8601), restricting results to samples submitted

before it
after A date/time (ISO 8601), restricting results to samples submitted after

it
org_only If true, will only match against samples submitted by your

organization
user_only If true, will only match against samples you submitted
Parameters are ANDed together. We only search nished samples (that

is, ones that have a status of succ or fail .
Returns
A JSON response with a list of sample info objects as the data. The
list is ordered by submission data, descending (most recent rst).
GET /samples/ID
Parameters
Name Description
id The sample ID
Returns
A JSON response with a sample info object as the data.
GET /samples/ID/state
Parameters
Name Description
ID The sample ID
Returns
A JSON response with a state string as the data.
POST/GET /samples/state
Parameters
Name Description
ids JSON list of sample IDs
Returns
A JSON response with a list of {sample: ID state: STATE status: STATUS} objects as the data.
Sample Search API
The Sample Search API is provided to let users search for samples
which have a relationship to another entity, such as an IP address, a
checksum for an artifact, or a hostname.
GET /samples/search
This call supports an array of Query Terms which are grouped

according to the entity or value they refer to. Only one Query Term
can be provided currently, but in future revisions we will support
multiple query terms being ANDed together.
Restricted Scopes
Query Term Description
before A date/time (ISO 8601), restricting results to samples submitted before it
after A date/time (ISO 8601), restricting results to samples submitted after it
org_only If true, will only match against samples submitted by your organization
Checksum
Checksum query terms can be a SHA256/SHA1/MD5 hash. They will match

the checksums of samples or artifacts seen during the sample run.
checksum Match sample or artifacts
checksum_sample Match only the submitted sample.
Path
Path query terms can be complete paths/lenames, or fragments. To

search for a fragment, use the % character as a wildcard. For
example to search for paths starting with \foo\bar one would do
\foo\bar% . If you wanted to nd any path with the word foo in it,
you would provide the term %foo%
path Match any path modied by the sample, including its own lename.
path_sample Match only the sample lename
path_artifact Match only artifacts left on disk, or modied.
path_deleted Match only deleted paths
URL
URL query terms can be complete URLs or fragments. To search for a

fragment, use the % character as a wildcard.
url Match any URL requested by the sample
Registry Key
Registry key terms can be complete Registry Keys or fragments. To

search for a fragment, use the % character as a wildcard.
registry_key Match any registry key name created, modied, or deleted by the
sample.
Domain/Hostname
Domain query terms can be complete Domain/Hostname or fragments. To search for a

fragment, use the % character as a wildcard.
domain Match any Domain the sample is associated with
domain\_dns\_lookup Match any domain the sample looked up via DNS
domain\_http\_request Match any domain the sample used in a URL
IP
IP query terms can be an IP address, or a CIDR block (192.168.0/24).
ip Match any IP address associated with the sample
ip\_dns\_lookup Match any IP address returned as a DNS answer
ip_src Match any IP that was the source of a network stream
ip_dst Match any IP that was the the destination of a network stream
IOC
An IOC/BI (Indicator of Compromise/Behavioral Indicator) query term must match an IOC name.
Query
Description
Term
ioc The IOC name or title. To search for a partial match, use the % character as a
wildcard.
Tags
Searches for samples matching a tag name
Query
Description
Term
tag The tag name or title. To search for a partial match, use the % character as a
wildcard.
Returns
Sample searches return relation records, which are brief

descriptions of what matched, and how it related to the sample, as
well as some data needed to get more information about the match.
sample The sample id.
ts The analysis start time.
match_term The query term type which matched the sample, eg ip. The value will be
the matched value.
relation The relation to the sample, specic to the match type, see query terms
above.
data A JSON data structure, specic to the match type, see query terms above.
Analysis Results
GET /samples/ID/video.webm
Requests the samples display output, transcoded to WEBM format. May
only be used with samples with a state of succ. Future revisions may
provide support for fail samples. This returns the WEBM stream, as
video/webm content-type.
GET /samples/ID/analysis.json
The analysis.json le is a single JSON object which contains a

detailed overview of dynamic and static analysis results for the
sample.
GET /samples/ID/processes.json
The processes.json le is a single JSON object which contains a

timeline of all process activity as determined by the dynamic analysis
engine.
GET /samples/ID/network.pcap
The network.pcap is a tcpdump PCAP le, with all the network

activity of the sample.
GET /samples/ID/warnings.json
The warnings.json le is a JSON structure describing any warnings that occured

during the analysis.
GET /samples/ID/summary
Returns summary analysis information.
GET /samples/ID/threat
Returns a summary of the threats detected during analysis.
GET /samples/ID/report.html
The report.html le is a stand-alone, complete report on the sample

run. It is designed to be emailed or printed.
GET /samples/ID/sample.zip
The sample.zip le is an archive of the sample itself, in a zip

format to as a form of quarantine.
Access to Specic Elements of analysis.json
The analysis.json le can be very large, so ThreatGRID makes it

possible to retrieve small portions of it. These queries will return
JSON lists or JSON objects, depending on the value at the key
requested.
For detailed information about the contents of these JSON objects,

please consult the analysis.json documentation (/doc/main/Analysis_JSON_Spec.pdf).
GET /samples/ID/analysis/iocs
Returns a JSON list of the Indicators of Compromise identied in

this sample run.
GET /samples/ID/analysis/iocs/IOC
Returns data regarding the specied Indicator of Compromise.
GET /samples/ID/analysis/network_streams
Returns a JSON object whose attributes are Network Stream IDs,

sequential numeric identiers of network sessions. It will include
data about any decoded protocols within the session, such as HTTP, IRC
and DNS trac.
GET /samples/ID/analysis/network_streams/NSID
Returns the JSON object describing the specied Network Stream.
GET /samples/ID/analysis/artifacts
Returns a JSON object whose attributes are Artifact IDs, sequential

numeric identiers of artifact produced by the sample. These can be
from the disk, network, or memory.
GET /samples/ID/analysis/artifacts/AID
Returns a JSON object, which is a summary of the static analysis of this artifact.
GET /samples/ID/analysis/processes
Returns a JSON object whose attributes are PIDs, and whose values are
process summaries.
GET /samples/ID/analysis/processes/PID
Returns a JSON object, which is the process summary of the specied PID.
GET /samples/ID/analysis/annotations
Returns a JSON object, representing the annotation information in the report.
GET /samples/ID/analysis/metadata
Returns a JSON object, representing the metadata information in the report.
Indicator of Compromise (IOC) Feeds

IOC feeds are lists of paths, artifact checksums, urls, IPs, registry
keys, etc. which have been associated with an IOC. An IP IOC feed
could be used to identify network communication associated with
malware, and tie it back to samples in Threat Grid.
IP Address Feed
GET /iocs/feeds/ips
Params
ip Restrict returned records to this IP or CIDR block

after Restrict returned records to events at or after this time (ISO 8601)
before Restrict returned records to events at or before this time (ISO 8601)
condence Restrict to IOCs with this condence score or higher, defaults to 80
severity Restrict to IOCs with this severity score or higher, defaults to 80
ioc Restrict returned records to events of this type
sample A comma-separated list of sample IDs. Restrict results to these samples.
Record
ip The IP address
port OPTIONAL The destination port on the IP address associated with the IOC
reverse_lookup OPTIONAL The hostname returned by a reverse lookup of this IP at sample runtime
city OPTIONAL The city associated with this IP in a GeoIP database
country OPTIONAL The country associated with this IP in a GeoIP database
timestamp The timestamp (ISO 8601) when this IOC occured
ioc The IOC name
condence The IOC condence (see IOC documentation for details)
severity The IOC severity (see IOC documentation for details)
sample_id The ID of the sample that generated this IOC
sample_sha256 The sha256 hash of the sample that generated this IOC.
Domain/Hostname Feed
GET /iocs/feeds/domains
Params
domain Restrict returned records to this domain or hostname.

Record
domain The domain or hostname.

ioc The IOC name
sample_sha256 The Sha256 hash of the sample that generated this IOC.
URL Feed
GET /iocs/feeds/urls
Params
url Restrict returned records to this URL or URL fragment

domain Restrict returned records to URLs with this domain
path Restrict returned records to URLs with this path
Record
url The URL

ioc The IOC name
sample_sha256 The Sha256 hash of the sample that generated this IOC.
Artifact Feed
GET /iocs/feeds/artifacts
Params
sha256 Restrict returned records with this sha256

sha1 Restrict returned records with this sha1
md5 Restrict returned records with this md5
path Restrict returned records to this path or path fragment.
Record
aid The artifact id

path The path the artifact was found at, may be partial or empty
sha256 A sha256 checksum of the artifact
md5 A md5 checksum of the artifact
ioc The IOC name
Path Feed
GET /iocs/feeds/paths
Params
path Restrict returned records to this path or path fragment.

Record
path The path the artifact was found at, may be partial or empty
ioc The IOC name
sample_sha256 The sha256 of the sample that generated this IOC
Network Stream Feed
GET /iocs/feeds/network_streams
Params
ip Restrict returned records to this IP address

port Restrict returned records to this port number
Record
src The source IP adress of the network stream

src_port The source port number of the network stream
dst The destination IP address of the network stream
dst_port The destination port number of the network stream
ioc The IOC name
Registry Key Feed
GET /iocs/feeds/registry_keys
Params
registry_key Restrict returned records to this registry_key

Record
registry_key The registry_key that was matched

ioc The IOC name
Sample Feeds
A sample feed is a straight dump of sample information, with no tie to
indicators of compromise, or other analysis of its maliciousness.
GET /samples/feeds/paths
This is a feed of all paths created/modied or deleted by samples.

The relation eld indicated the source of the path. An artifact
relation means its a creted or modied le that we recovered from
the lesystem. In this case the data eld will be information
identifying the artifact(s) associated with the path Artifact ID, as
well as a sha256 hash of the le. A deleted relation means it was
deleted by a process, and the data eld will be a list of PIDs of
the processes which were observed deleted the le.
Params
path Restrict returned records to this Path or Path fragment.

Use the % character as a wildcard.
relation The relation to restrict returned record to.
whitelisted - A boolean indicating whether to include whitelisted results (default true)
whitelisted_only - A boolean indicating whether to include only whitelisted results
(default false)
blacklisted - A boolean indicating whether to include blacklisted results (default true)
blacklisted_only - A boolean indicating whether to include only blacklisted results
(default false)
tag Restrict to items matching the given tag
ag Restrict to items agged (blacklisted or whitelisted) for the given reason
after Restrict returned records to sample run at or after this time (ISO 8601)
before Restrict returned records to samples run at or before this time (ISO 8601)
Returns
A JSON response with a list of path relationship records
{
"api_version": 2,
"id": 5111262
"data": {
"current_item_count": 2,
"index": 0,
"items": [
{
"data": {
"artifacts": [
{
"aid": 13,
"sha256": "2eea7f88077bd134c2412d2e18bf63417bc6595ca1bcc92700bda037367182fe"
}
]
},
"path": "\\Documents and Settings\\Joe Maldive\\NTUSER.DAT",
"relation": "artifact",
"sample": "37df001fae491c6195e10e131b38ee8e",
"ts": "2391-11-23T09:36:30-0600"
},
{
"data": {
"artifacts": [
{
"aid": 27,
"sha256": "fa1e9645152d5f9510fe9a00cdfd63fe160be70ff094d5205c7a3161c981f921"
}
]
},
"path": "\\WINDOWS\\system32\\config\\software.LOG",
"ts": "2391-11-23T09:36:30-0600"
}
],
"items_per_page": 2
},
}
GET /samples/feeds/checksums
This is a feed of all the checksums derived from artifacts generated

by samples. The relation eld indicates the source of the path. An
artifact relation means its a created or modied le that we
recovered from the lesystem. In this case the data eld will be
Artifact ID. A sample relation means it was the submitted sample
data eld will be empty.
Params
checksum Restrict returned records to this Path or Path fragment.

type The type of checksum to restrict returned record to.
(default false)
(default false)
Returns
A JSON response with a list of checksum relationship records
{
"api_version": 2,
"id": 7312922
"data": {
"index": 0,
"items": [
{
"data": {
"artifact-ids": [
22
]
},
"checksum": "5b3d171306707acab2d5681d171ca3784a53a1c1"
"sample": "ea7395f5ced420ea95394b8c204d83d8",
"ts": "2392-07-20T22:13:30-0500",
"type": "sha1"
},
{
"data": {
"artifact-ids": [
20
]
},
"checksum": "f3f824a57a7cb5b9e7f12bfe146dbf9179797df59e55624df62d3cbb3a20bb48"
"sample": "ea7395f5ced420ea95394b8c204d83d8",
"ts": "2392-07-20T22:13:30-0500",
"type": "sha256"
}
],
"items_per_page": 2
},
}
GET /samples/feeds/domains
This is a feed of all the domains seen during the analysis of samples.
The relation eld indicates the source of the path. A dns-lookup
relation means this domain was part of a DNS query, and the data eld
will contain the answers associated with the query. An
http-requests relation indicates the domain was seen as part of a
URL in one or more HTTP requests. The data will be the network stream
ID and http transaction IDs it was seen in, as well as the URL.
Params
domain Restrict returned records to this domain or domain fragment

relation The relation to restrict returned records to.
(default false)
(default false)
Returns
A JSON response with a list of domain relationship records
{
"api_version": 2,
"id": 132171
"data": {
"index": 0,
"items": [
{
"data": {
"answers": [
"83.133.119.197"
]
},
"domain": "proxim.ircgalaxy.pl",
"relation": "dns-lookup",
"ts": "2391-11-23T09:36:30-0600"
},
{
"data": [
{
"nsid": 7,
"tid": 0,
"url": "http://www.sedfr56.com:80/plkoi75.txt"
},
{
"nsid": 8,
"tid": 0,
"url": "http://www.sedfr56.com:80/temp/fast.exe"
}
],
"domain": "www.sedfr56.com",
"relation": "http-requests",
"ts": "2391-11-23T09:36:30-0600"
}
],
"items_per_page": 2
},
}
GET /samples/feeds/ips
This is a feed of all the domains seen during the analysis of samples.
The relation eld indicates the source of the path. A dns-lookup
relation means this IP was part of an answer to a DNS query, and the
data eld will contain the queries associated with the answer. A
network-stream-[source|destination] relation indicates the IP was
seen as the source or destination of a packet, and the data eld will
contain information about the network stream.
Params
ip Restrict returned records to this IP or CIDR block

(default false)
(default false)
Returns
A JSON response with a list of IP relationship records
{
"api_version": 2,
"id": 2187681
"data": {
"index": 0,
"items": [
{
"data": {
"queries": [
{
"query": "proxim.ircgalaxy.pl",
"type": "A"
}
]
},
"ip": "83.133.119.197/32",
"relation": "dns-lookup",
"ts": "2391-11-23T09:36:30-0600"
},
{
"data": {
"network-streams": [
2,
1
]
},
"ip": "22.31.45.6/32",
"relation": "network-stream-destination",
"ts": "2391-11-23T09:36:30-0600"
}
],
"items_per_page": 2
},
}
<a name=entity-search-api
Entity Search API

The Entity Search APIs are single-term searches for a specic entity data type.
Each query takes the following parameters:

term The entity-specic search term
query The query text for the search term
GET /search/registry_keys
The registry key search terms are

key - any registry key by name
key-modied - modied registry keys by name
key-created - created registry keys by name
key-deleted - deleted registry keys by name
tag registry keys by tag
GET /search/paths
The path search terms are:

path - a path name
sha256 - paths related to an artifact sha256
md5 - paths related to an artifact md5
sha1 - paths related to an artifact sha2
mime-type - paths related to artifacts with given mime type
magic-type - paths related to artifacts with the given magic type
tag - paths with a given tag
GET /search/ips
The IP search terms are:

network_dst - search by destination IP
network_src - search by source IP
artifact - search by artifact sha256
domain - search by domain name
url - search by url
asn - search by IP ASN
geo_location - search by IP geo location information
cidr - search by IP/CIDR
ioc - search by IOC name
tag - search by tag
GET /search/domains
The domain search terms are:

name - search by domain name
ip - search by IP address
sha256 - search by sha256 equivalent of the domain name
sha1 - search by sample sha1
md5 - search by sample md5
cname - search by DNS CNAME
tag - search by tag
GET /search/artifacts
ip - search by IP
url - search by URL
sha256 - search by sha256 hash
md5 - search by MD5 hash
sha1 - search by SHA1 hash
mime-type - search by MIME type
magic-type - search by magic type
path - search by path
source - search by source
tag - search by tag
GET /search/samples
ioc - search by IOC name

checksum - search by checksum (sha256, md5 or sha1)
checksum_sample - search by checksum of sample
path - search by path name
path_sample - search by sample path name
path_artifact - search by artifact name
path_deleted - search by path names that were deleted
url - search by url
registry_key - search by registry key accessed
domain - search by domain name
domain_dns_lookup - search by domain name used for DNS lookups
domain_http_request - search by domain name used in HTTP request
ip - search by IP address
ip_dns_lookup - search by IP address returned in DNS lookup
ip_src - search by network stream source IP address
ip_dst - search by network stream destination IP address
tag - search by sample tag
GET /search/urls
url - search by URL pattern

sibling - search by URL pattern prex
neighbor - search by hostname of URL
sha256 - search by SHA56 of URL
md5 - search by MD5 of URL
sha1 - search by SHA1 of URL
protocol - search by protocol name
host - search by hostname
port - search by port number
path - search by path name
query - search by query
reference - search by fragment identier
ip - search by IP address of network stream
artifact - search by artifact downloaded
tag - search by URL tag
Entity Queries
GET /domains/NAME
Returns information for a domain, by name. The data elds returned are:
domain - the domain name
sha256 - the SHA256 hash of the domain
md5 - the MD5 hash of the domain
GET /paths/ID
Returns information on a path. The data elds returned are:

domain - the domain name
sha256 - the SHA256 hash of the path
md5 - the MD5 hash of the path
GET /registry_keys/ID
Returns information on a registry key. The data elds returned are:

key - the registry key
sha256 - the SHA256 hash of the key
md5 - the MD5 hash of the key
GET /registry_keys/ID/name/ID
Returns information on a registry key. The data elds returned are:

key - the registry key
name - the registry key name
GET /urls/ID
Returns information on URLs, by SHA256 of the URL. The data elds returned are:
url - the an object representing the URL
url - the URL
protocol - the protocol of the URL
host - the hostname of the URL
port - the port number of the URL
path - the path of the url
query - the query string of the url
query-params - the query parameters, as a map of parameter to value
GET /artifacts/ID
Returns information on an artifact, by hash. The data elds returned are:

sha256 - The SHA256 hash of the artifact
sha1 - The SHA1 hash of the artifact
md5 - The MD5 hash of the artifact
fuzzy_hash - The SSDEEP fuzzy hash of the artifact
size - The artifact size
type - The artifact type
mime_type - The artifact MIME type
magic_type - The artifact magic type
GET /artifacts/ID/threat
Returns information on an artifact, including threat information. The data elds returned
include the primary artifact details along with the threat details
samples - an array of samples that include the artifact
iocs - a list of IOCs for the artifact
GET /artifacts/ID/download
Returns the artifact.
Flags
Flags allow for blacklisting and whitelisting of entities. The following paths allow agging:
/samples/ID
/ips/IP
/domains/DOMAIN
/artifacts/SHA256
/paths/PATH
/registry_keys/KEY
/registry_keys/KEY/name/VALUENAME
/urls/SHA256
GET /ENTITY-PATH/ags
Returns a data section with a flags array of ag maps containing the following attributes:
ag - An integer. -1 for a blacklist entry, 1 for a whitelist entry.
reason - The reason text
mine - A boolean indicating ownership of the ag.
Tags
Tags can be attached to the following entity paths:
/samples/ID
/ips/IP
/domains/DOMAIN
/artifacts/SHA256
/paths/PATH
/registry_keys/KEY
/registry_keys/KEY/name/VALUENAME
/urls/SHA256
GET /ENTITY-PATH/tags
Returns a data section with a tags array of tag maps containing the following attributes:
tag - The tag name.
count - An integer, the number of times this tag has been applied.
mine - A boolean indicating the querying user has applied this tag to the entity.
POST /ENTITY-PATH/tag
Tag an entity. The posted content should contain the following parameter;
tag - The tag text
DELETE /ENTITY-PATH/tag/TAG
Removes a users tag of an entity. If other users have tagged the entity with the same tag, the
tag may still remain.
Federation
GET /samples/feeds/federated
GET /samples/ID/federated.json
GET /samples/ID/federated.don
support@threatgrid.com (mailto:support@threatgrid.com) threatgrid.com (http://www.threatgrid.com/) Terms of Service (/eula.html)
All information contained in this report is condential and proprietary information belonging solely to Cisco Systems, Inc. and/or its aliates.
This document is for internal customer use only. The information contained herein may not be disclosed to a third party, in whole or in part, or otherwise stored in a retrieval system or transmitted to a third
party in any form or by any means (electronic, mechanical, reprographic, recording or otherwise) without the prior written permission of Cisco.

Threat Grid Documentation - Main API

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Threat Grid Documentation - Main API

Hochgeladen von

Copyright:

Verfügbare Formate

2/21/2017 Threat Grid Documentation

ThreatGRID Data API (Version 2.0)

This is the developers reference document for the main Application

The version string ( v2 ) will be iterated whenever a non-backwards

All API requests require an api_key parameter. This identies the

JSON Response Format

id A randomly generated string token to identify the response.

data The result of the API call, as a JSON object.

offset The number of records to skip.

So if you want to page through results 100 at a time, a limit

When a request generates an error, we will set the appropriate HTTP

Experimental API Calls

Sample Info Record

The canonical representation of a Sample in the API is a Sample Info record.

submission\_id A numeric identifer of the submission, not globally unique. Some

status A detailed status of the sample.

sha256 The SHA256 hash of the sample

md5 The MD5 hash of the sample, if available

sha1 The SHA1 hash of the sample, if available

os A string identifying the OS, as provided by the submitter.

osver A string identifying the OS version, as provided by the submitter.

Here is an example of a sample info record:

Samples API Endpoint Summary Table

Method Endpoint Description

POST /samples Submits a sample to Threat

GET /samples Queries analyzed samples.

GET /samples/ID DESCRIPTION

GET /samples/ID/state DESCRIPTION

POST/GET /samples/state DESCRIPTION

GET /samples/search Supports an array of Query

GET /samples/ID/video.webm Requests the samples

GET /samples/ID/analysis.json JSON object containing

GET /samples/ID/processes.json JSON object containing a

GET /samples/ID/network.pcap tcpdump PCAP le of the

GET /samples/ID/warnings.json JSON structure describing

GET /samples/ID/summary Summary analysis

Method Endpoint Description

GET /samples/ID/threat Summary of detected

GET /samples/ID/report.html report.html is a complete

GET /samples/ID/sample.zip sample.zip is an archive of

GET /samples/ID/analysis/iocs Returns a JSON list of the

GET /samples/ID/analysis/iocs/IOC Returns data regarding the

GET /samples/ID/analysis/network_streams Returns a JSON object

GET /samples/ID/analysis/network_streams/NSID Returns a JSON object

GET /samples/ID/analysis/artifacts Returns a JSON object

GET /samples/ID/analysis/artifacts/AID Returns a JSON object that

GET /samples/ID/analysis/processes Returns a JSON object

GET /samples/ID/analysis/processes/PID Returns a JSON object that

GET /samples/ID/analysis/annotations Returns a JSON object that

Get /samples/ID/analysis/metadata Returns a JSON object that

sample the sample le

filename the original lename of the sample, as a string

os a string identifying the source OS

osver a string dening the OS version.

vm a string identifying a specic VM to use

source a string identifying the source (user dened)

api_key A secret token identifying the user and providing authentication

tags A comma-separated list of tags applied to this sample.

A JSON Response with a single Sample Info record as the data.

md5 As above, but an MD5 checksum

sha1 As above, but a SHA1 checksum

ids a comma-separated list of sample IDs

ioc an IOC name

submission\_id A numeric ID for the sample sessions, deprecated