Sie sind auf Seite 1von 29

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
2/21/2017 Threat Grid Documentation
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:

https://panacea.threatgrid.com/doc/main/api.html#post-samples 2/29
2/21/2017 Threat Grid Documentation
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 3/29
2/21/2017 Threat Grid Documentation
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 4/29
2/21/2017 Threat Grid Documentation

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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 5/29
2/21/2017 Threat Grid Documentation

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 6/29
2/21/2017 Threat Grid Documentation
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 7/29
2/21/2017 Threat Grid Documentation

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 8/29
2/21/2017 Threat Grid Documentation

Returns

A JSON response with a sample info object as the data.

GET /samples/ID/state

Parameters

Name Description

ID The sample ID

api_key A secret token identifying the user and providing authentication

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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 9/29
2/21/2017 Threat Grid Documentation

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

user_only If true, will only match against samples you submitted

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.

Query Term Description

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%

Query Term Description

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 10/29
2/21/2017 Threat Grid Documentation

URL

URL query terms can be complete URLs or fragments. To search for a


fragment, use the % character as a wildcard.

Query Term Description

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.

Query Term Description

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.

Query Term Description

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).

Query Term Description

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 11/29
2/21/2017 Threat Grid Documentation

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.

Query Term Description

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 12/29
2/21/2017 Threat Grid Documentation
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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 13/29
2/21/2017 Threat Grid Documentation

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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 14/29
2/21/2017 Threat Grid Documentation

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
api_key A secret token identifying the user and providing authentication
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 15/29
2/21/2017 Threat Grid Documentation
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.


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
api_key A secret token identifying the user and providing authentication
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

Record

domain The domain or hostname.


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.

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
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
api_key A secret token identifying the user and providing authentication
org_only If true, will only match against samples submitted by your organization

https://panacea.threatgrid.com/doc/main/api.html#post-samples 16/29
2/21/2017 Threat Grid Documentation
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

Record

url The URL


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.

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.
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
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

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
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

Path Feed

https://panacea.threatgrid.com/doc/main/api.html#post-samples 17/29
2/21/2017 Threat Grid Documentation

GET /iocs/feeds/paths

Params

path Restrict returned records to this path or path fragment.


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
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

Record

path The path the artifact was found at, may be partial or empty
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 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
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
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

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
timestamp The timestamp (ISO 8601) when this IOC occured
ioc The IOC name

https://panacea.threatgrid.com/doc/main/api.html#post-samples 18/29
2/21/2017 Threat Grid Documentation
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 of the sample that generated this IOC

Registry Key Feed

GET /iocs/feeds/registry_keys

Params

registry_key Restrict returned records to this registry_key


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
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted
sample A comma-separated list of sample IDs. Restrict results to these samples.

Record

registry_key The registry_key that was matched


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 of the sample that generated this IOC

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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 19/29
2/21/2017 Threat Grid Documentation

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.
sample A comma-separated list of sample IDs. Restrict results to these samples.
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)
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted

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",
"relation": "artifact",
"sample": "37df001fae491c6195e10e131b38ee8e",
"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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 20/29
2/21/2017 Threat Grid Documentation
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.
relation The relation to restrict returned record to.
sample A comma-separated list of sample IDs. Restrict results to these samples.
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)
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted

Returns

A JSON response with a list of checksum relationship records

{
"api_version": 2,
"id": 7312922
"data": {
"current_item_count": 2,
"index": 0,
"items": [
{
"data": {
"artifact-ids": [
22
]
},
"checksum": "5b3d171306707acab2d5681d171ca3784a53a1c1"
"relation": "artifact",
"sample": "ea7395f5ced420ea95394b8c204d83d8",
"ts": "2392-07-20T22:13:30-0500",
"type": "sha1"
},
{
"data": {
"artifact-ids": [
20
]
},
"relation": "artifact",
"checksum": "f3f824a57a7cb5b9e7f12bfe146dbf9179797df59e55624df62d3cbb3a20bb48"
"sample": "ea7395f5ced420ea95394b8c204d83d8",
"ts": "2392-07-20T22:13:30-0500",
"type": "sha256"
}
],
"items_per_page": 2
},
}

GET /samples/feeds/domains

https://panacea.threatgrid.com/doc/main/api.html#post-samples 21/29
2/21/2017 Threat Grid Documentation
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.
sample A comma-separated list of sample IDs. Restrict results to these samples.
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)
api_key A secret token identifying the user and providing authentication
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted

Returns

A JSON response with a list of domain relationship records

{
"api_version": 2,
"id": 132171
"data": {
"current_item_count": 2,
"index": 0,
"items": [
{
"data": {
"answers": [
"83.133.119.197"
]
},
"domain": "proxim.ircgalaxy.pl",
"relation": "dns-lookup",
"sample": "37df001fae491c6195e10e131b38ee8e",
"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",
"sample": "37df001fae491c6195e10e131b38ee8e",
"ts": "2391-11-23T09:36:30-0600"
}
],
"items_per_page": 2
},
}

https://panacea.threatgrid.com/doc/main/api.html#post-samples 22/29
2/21/2017 Threat Grid Documentation

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


relation The relation to restrict returned record to.
sample A comma-separated list of sample IDs. Restrict results to these samples.
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)
api_key A secret token identifying the user and providing authentication
org_only If true, will only match against samples submitted by your organization
user_only If true, will only match against samples you submitted

Returns

A JSON response with a list of IP relationship records

https://panacea.threatgrid.com/doc/main/api.html#post-samples 23/29
2/21/2017 Threat Grid Documentation

{
"api_version": 2,
"id": 2187681
"data": {
"current_item_count": 2,
"index": 0,
"items": [
{
"data": {
"queries": [
{
"query": "proxim.ircgalaxy.pl",
"type": "A"
}
]
},
"ip": "83.133.119.197/32",
"relation": "dns-lookup",
"sample": "37df001fae491c6195e10e131b38ee8e",
"ts": "2391-11-23T09:36:30-0600"
},
{
"data": {
"network-streams": [
2,
1
]
},
"ip": "22.31.45.6/32",
"relation": "network-stream-destination",
"sample": "37df001fae491c6195e10e131b38ee8e",
"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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 24/29
2/21/2017 Threat Grid Documentation
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 25/29
2/21/2017 Threat Grid Documentation
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
https://panacea.threatgrid.com/doc/main/api.html#post-samples 26/29
2/21/2017 Threat Grid Documentation

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
sha256 - the SHA256 hash of the key
md5 - the MD5 hash of the key

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
sha256 - the SHA256 hash of the key
md5 - the MD5 hash of the key

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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 27/29
2/21/2017 Threat Grid Documentation
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

https://panacea.threatgrid.com/doc/main/api.html#post-samples 28/29
2/21/2017 Threat Grid Documentation

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.

https://panacea.threatgrid.com/doc/main/api.html#post-samples 29/29