Using the API

From enterprise
Jump to: navigation, search

Introduction

Almost all data in ATT&CK can be accessed using the Semantic MediaWiki Ask API. URLs targeting the API are constructed in the following pattern /api.php?action=ask&format=<format specifier>&query=<query statement> where <format specifier> is a specific output format (usually json or jsonfm) and <query statement> refers to a query that specifies the data that will be retrieved. For users already familiar with Semantic MediaWiki, queries are structured as if they are targeting the Semantic MediaWiki #ask parser function

Constructing Query Statements

Queries are constructed by combining one or more page selectors with one or more display parameters. Page selectors are used to limit the scope of the query to specific sets of pages. A simple selector for all techniques is [[Category:Technique]]. Display parameters control what information is returned about the pages that have been selected by the page selector. A simple display parameter is ?Has display name which will cause the query to return the name of all the ATT&CK Techniques identified by the page selector. To construct the full query statement, the selector is combined with the display parameter by placing a | symbol in between. So a combined query looks like: [[Category:Technique]]|?Has display name. This query will retrieve all ATT&CK techniques along with their display name. To run this we just have to URL encode the combined query and place it in the URL. The final URL for this query is:

https://attack.mitre.org/api.php?action=ask&format=jsonfm&query=%5B%5BCategory%3ATechnique%5D%5D%7C%3FHas%20display%20name

Selectors are generally either Categories or Properties. Category selectors are always prefixed with Category:. Relevant category selectors are [[Category:Technique]], [[Category:Group]] and [[Category:Software]] which will select all techniques, groups, and software respectively. Properties can also be used as selectors. Notable properties are Has display name, Has ID, Has tactic, Has platform however there are many other queryable properties. In addition to being used as selectors, Properties are also used as display parameters. The below table illustrates some example uses of properties as both selectors and display parameters.

Property Example Selector Display Parameter
Has display name [[Has display name::Rootkit]]  ?Has display name
Has ID [[Has ID::!T1014]]  ?Has ID
Has tactic [[Has tactic::Execution]]  ?Has tactic
Has platform [[Has platform::Windows 7]]  ?Has platform

Selectors can be combined to build more specific queries. For example [[Has tactic::Privilege Escalation]][[Has tactic::Execution]] can be used to find all techniques that are used for both Privilege Escalation and Execution.

Example Queries

Below are some example queries.

A Specific Technique

This query matches the page with ID T1014 (Rootkit) and returns that technique's tactics, ID, display name, and technical description.

Original query: [[Has ID::T1014]]|?Has tactic|?Has ID|?Has display name|?Has technical description|limit=9999

URL Encoded: https://attack.mitre.org/api.php?action=ask&format=jsonfm&query=%5B%5BCategory%3ATechnique%5D%5D%5B%5BHas%20ID%3A%3AT1014%5D%5D%7C%3FHas%20tactic%7C%3FHas%20ID%7C%3FHas%20display%20name%7C%3FHas%20technical%20description%7Climit%3D9999

Listing All Techniques

This query matches all techniques and lists their tactics, ID and display name.

Original query: [[Category:Technique]]|?Has tactic|?Has ID|?Has display name|limit=9999

URL Encoded: https://attack.mitre.org/api.php?action=ask&format=jsonfm&query=%5B%5BCategory%3ATechnique%5D%5D%7C%3FHas%20tactic%7C%3FHas%20ID%7C%3FHas%20display%20name%7Climit%3D9999

Listing all Groups and their Technique Usage

This query gets all groups and their usage of ATT&CK Techniques, their ID and their aliases.

Original query: [[Category:Group]]|?Has technique|?Has ID|?Has alias|limit=9999

URL Encoded: https://attack.mitre.org/api.php?action=ask&format=jsonfm&query=%5B%5BCategory%3AGroup%5D%5D%7C%3FHas%20technique%7C%3FHas%20ID%7C%3FHas%20alias%7Climit%3D9999

Listing Groups that use a specific piece of software

This query matches against all the group that use a specific software (in this case "Software/S0002", Mimikatz) and return their name and ID.

Original Query: [[Uses software::Software/S0002]]|?Has ID|?Has display name|limit=9999

URL Encoded: https://attack.mitre.org/api.php?action=ask&format=jsonfm&query=%5B%5BUses%20software%3A%3ASoftware/S0002%5D%5D%7C%3FHas%20ID%7C%3FHas%20display%20name%7Climit%3D9999

Additional Information

Formatting

Although these examples show output being displayed as Formatted JSON, output can be returned in many different ways by modifying the format= keyword argument in the URL. For machine readable JSON, format=json should be used. MediaWiki has a full list of output options.

Dealing With Citations

Some properties, such as Has technical description or Has mitigation contain citations. Citations are made within ATT&CK by placing a [[CiteRef::<reference key>]] tag at the location where the citation should appear. The <reference key> in the citation refers to a global key that uniquely identifies references within ATT&CK. All references and their keys are listed on the References page and can additionally be accessed through special properties in the API.

NOTE: When using the API to query pages and properties that contain citations, #-ia should be appended to each display parameter that contains citations. For example, instead of using the display parameter ?Has technical description, use ?Has technical description#-ia. Leaving off the #-ia will prevent the citation from being returned correctly, the results will only show the <reference key> without the surrounding [[CiteRef::...]] declaration, which will make it hard to parse or recognize citations.

For more information on citations, please see the documentation for Semantic Cite.

Availability

We make our best effort to ensure enterprise is up, but don't make any guarantees on uptime and availability. For now, we caution against integrating direct API queries into a product unless it’s for non-critical periodic updates.

Legal

See the ATT&CK Terms of Use.