3. Querying Threat Grid¶

All of the Observables (IPs, Domains, Mutexes, Hashes, File Paths, Registry Keys, etc…) Threat Grid generates from analysis are indexed providing the ability to enrich and add context to Observables from other systems.

3.1. Requirements¶

There are two minimum required features for an integration to query Threat Grid:

Ability to enter an API key
Ability to change the URI to allow for regional and appliance operability.
- Use https://panacea.threatgrid.com/cloud.json to get a list of current regional clouds

Note

There are two additional features that make for a more thorough integration with an improved workflow and user experience:

Ability to query both cloud and appliance simultaneously
Allow users to search the global dataset, their organizational dataset, and their individual dataset

3.2. Example API Endpoints¶

Note

To view the complete and up to date Threat Grid documentation and release notes head to the help page in the Threat Grid portal here.

3.2.1. Querying for an Observable or Entity¶

Initial searches should always be done using the Submission Search API /api/v2/search/submissions. The scope of a search can be limited with various parameters. org_only=True or user_only=True will limit the searches to just their organization’s or user’s samples respectively. Examples of entities that can be queried for include:

Checksum
Path
URL
Registry Key
Domain
IP
Behavioral Indicator
Tag
Sample

http

GET https://panacea.threatgrid.com/api/v2/search/submissions?state=succ&q=a92ddbbaf6c9a50a7125595a4119ca38&api_key=12345abcde HTTP/1.1

Example response:

{
    "api_version": 2,
    "id": 3209394,
    "data": {
        "index": 0,
        "total": 1,
        "took": 725,
        "timed_out": false,
        "items_per_page": 100,
        "current_item_count": 1,
        "items": [
            {
                "matches": {},
                "score": 1000000,
                "item": {
                    "tags": [],
                    "vm_runtime": 300,
                    "md5": "a92ddbbaf6c9a50a7125595a4119ca38",
                    "private": false,
                    "organization_id": null,
                    "state": "succ",
                    "login": null,
                    "sha1": "2f9bc5c64eeca8c0504fd852032be29442f11ace",
                    "sample": "2163cc93b5daa51861397402eb94b6e3",
                    "filename": "sample.url",
                    "analysis": {
                        "behaviors": [
                            {
                                "name": "network-file-downloaded-to-disk",
                                "threat": 27,
                                "title": "File Downloaded to Disk"
                            },
                            {
                                "name": "js-uses-fromcharcode",
                                "threat": 40,
                                "title": "JavaScript Obfuscation Using \"fromCharCode()\" Function"
                            },
                            {
                                "name": "script-contains-url",
                                "threat": 60,
                                "title": "Script Contains URL"
                            },
                            {
                                "name": "network-communications-http-get-url",
                                "threat": 6,
                                "title": "Outbound HTTP GET Request From URL Submission"
                            },
                            {
                                "name": "modified-file-in-user-dir",
                                "threat": 56,
                                "title": "Process Modified File in a User Directory"
                            },
                            {
                                "name": "network-fast-flux-domain",
                                "threat": 7,
                                "title": "DNS Response Contains Low Time to Live (TTL) Value"
                            },
                            {
                                "name": "artifact-flagged-anomaly",
                                "threat": 48,
                                "title": "Static Analysis Flagged Artifact As Anomalous"
                            },
                            {
                                "name": "network-only-safe-domains-contacted",
                                "threat": 19,
                                "title": "Sample Communicates With Only Benign Domains"
                            }
                        ],
                        "threat_score": 60,
                        "metadata": {
                            "general_details": {
                                "report_created": "2020-09-29T15:19:19Z",
                                "sandbox_version": "pilot-d",
                                "sandbox_id": "-"
                            },
                            "sandcastle_env": {
                                "controlsubject": "-",
                                "vm": "win7-x64",
                                "vm_id": "2163cc93b5daa51861397402eb94b6e3",
                                "sample_executed": 1601392400,
                                "analysis_end": "2020-09-29T15:19:19Z",
                                "analysis_features": [],
                                "analysis_start": "2020-09-29T15:12:27Z",
                                "display_name": "Windows 7 64-bit",
                                "run_time": 300,
                                "sandcastle": "-",
                                "current_os": "7601.18798.amd64fre.win7sp1_gdr.150316-1654"
                            },
                            "analyzed_file": {
                                "md5": "a92ddbbaf6c9a50a7125595a4119ca38",
                                "filename": "sample.url",
                                "sha1": "2f9bc5c64eeca8c0504fd852032be29442f11ace",
                                "sha256": "76b523017eb04dc56b48e4c0585ded8746c11646238484e35710289e8a385af3",
                                "size": 129,
                                "type": "url",
                                "magic": "MS Windows 95 Internet shortcut text (URL=<https://landmarkventuresvip.com/l/NbTVz2HLyCUHH4ohIiqMow/RpVmK9nmdTjwWh5CiY892daA/AUleeeldeOx76>), ASCII text"
                            },
                            "submitted_file": {
                                "md5": "a92ddbbaf6c9a50a7125595a4119ca38",
                                "filename": "sample.url",
                                "sha1": "2f9bc5c64eeca8c0504fd852032be29442f11ace",
                                "sha256": "76b523017eb04dc56b48e4c0585ded8746c11646238484e35710289e8a385af3",
                                "size": 129,
                                "type": "url",
                                "magic": "MS Windows 95 Internet shortcut text (URL=<https://landmarkventuresvip.com/l/NbTVz2HLyCUHH4ohIiqMow/RpVmK9nmdTjwWh5CiY892daA/AUleeeldeOx76>), ASCII text"
                            },
                            "malware_desc": [
                                {
                                    "md5": "a92ddbbaf6c9a50a7125595a4119ca38",
                                    "filename": "sample.url",
                                    "sha1": "2f9bc5c64eeca8c0504fd852032be29442f11ace",
                                    "sha256": "76b523017eb04dc56b48e4c0585ded8746c11646238484e35710289e8a385af3",
                                    "size": 129,
                                    "type": "url",
                                    "magic": "MS Windows 95 Internet shortcut text (URL=<https://landmarkventuresvip.com/l/NbTVz2HLyCUHH4ohIiqMow/RpVmK9nmdTjwWh5CiY892daA/AUleeeldeOx76>), ASCII text"
                                }
                            ]
                        }
                    },
                    "status": "job_done",
                    "submitted_at": "2020-09-29T15:12:27Z",
                    "sha256": "76b523017eb04dc56b48e4c0585ded8746c11646238484e35710289e8a385af3"
                }
            }
        ]
    }
}

3.2.2. Download Analysis Elements¶

You may want to retrieve detailed analysis results for the samples returned in the query.

3.2.2.1. Runtime Video¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/viedo.webm&api_key=12345abcde HTTP/1.1

3.2.2.2. Analysis JSON¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/analysis.json&api_key=12345abcde HTTP/1.1

3.2.2.3. Process Timeline JSON¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/processes.json&api_key=12345abcde HTTP/1.1

3.2.2.4. Network PCAP¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/network.pcap&api_key=12345abcde HTTP/1.1

3.2.3. Access Specific Elements of analysis.json¶

Instead of fetching analysis.json in its entirety you can query for individual sections from a given sample:

3.2.3.1. Behavioral Indicators¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/analysis/iocs&api_key=12345abcde HTTP/1.1

3.2.3.2. Network Streams¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/analysis/network_streams&api_key=12345abcde HTTP/1.1

3.2.3.3. Processes¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/analysis/processes&api_key=12345abcde HTTP/1.1

3.2.3.4. Annotations¶

http

GET https://panacea.threatgrid.com/api/v2/samples/$ID/analysis/annotations&api_key=12345abcde HTTP/1.1

3.2.4. Entity Searches¶

These calls enable searches for the existence of things such as “Does this domain exist in TG?”. They also enable the ability of searching basic relationships between entities (domains that have resolved to this IP). A comprehensive list of entity searches can be found in the API documentation. See the search in the UI for detailed examples for each query: https://panacea.threatgrid.com/mask/search

3.2.4.1. IPs Threat Grid Has Observed a Domain Resolving To¶

http

GET https://panacea.threatgrid.com/api/v2/search/ips?query=cisco.com&term=domain&api_key=12345abcde HTTP/1.1

Example Response:

{
    "api_version": 2,
    "id": 8531444,
    "data": {
        "index": 0,
        "items_per_page": 100,
        "current_item_count": 1,
        "items": [
            {
                "result": "72.163.4.185",
                "details": "/api/v2/ips/72.163.4.185"
            }
        ]
    }
}

3.2.4.2. Domains Threat Grid Has Observed Resolving to an IP¶

http

GET https://panacea.threatgrid.com/api/v2/search/domains?query=72.163.4.185&term=ip&api_key=12345abcde HTTP/1.1

Example Response:

{
    "api_version": 2,
    "id": 9288081,
    "data": {
        "index": 0,
        "items_per_page": 1000,
        "current_item_count": 1,
        "items": [
            {
                "result": "cisco.com",
                "details": "/api/v2/domains/cisco.com"
            }
        ]
    }
}

3.2.4.3. Existence of a File Artifact by MD5¶

http

GET https://panacea.threatgrid.com/api/v2/search/artifacts?query=f2adb5f1cfa13fbce8dcc8f3087732d9&term=md5&api_key=12345abcde HTTP/1.1

Example Response:

{
    "api_version": 2,
    "id": 9293412,
    "data": {
        "index": 0,
        "items_per_page": 1000,
        "current_item_count": 1,
        "items": [
            {
                "result": "a2ed6cb1653b0fa64b2f53aedaafa7ea98ff895cbaee1da32bbdba6ad80587aa",
                "details": "/api/v2/artifacts/a2ed6cb1653b0fa64b2f53aedaafa7ea98ff895cbaee1da32bbdba6ad80587aa"
            }
        ]
    }
}

3.2.5. Advanced Search¶

Note

Advance search is currently not supported in the API, but the following steps explain how to successfully do this through the UI.

Navigate to this website https://panacea.threatgrid.com/mask/advanced_search
Click on API next to the Copy Query and Import Query fields

3.2.6. On-Demand Organization Metrics¶

When on the dashboard all of the tiles (Threat Scores, Total Submission by Threat Score, Total Convictions, etc…) have an API link in the upper right that show how to get the info in that tile

Documentation for those endpoints is located here.