Using the API
- 1 Introduction
- 2 Constructing Query Statements
- 3 Example Queries
- 4 Additional Information
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
<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:
Selectors are generally either Categories or Properties. Category selectors are always prefixed with
Category:. Relevant category selectors are
[[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 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.
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.
[[Has ID::T1014]]|?Has tactic|?Has ID|?Has display name|?Has technical description|limit=9999
Listing All Techniques
This query matches all techniques and lists their tactics, ID and display name.
[[Category:Technique]]|?Has tactic|?Has ID|?Has display name|limit=9999
Listing all Groups and their Technique Usage
This query gets all groups and their usage of ATT&CK Techniques, their ID and their aliases.
[[Category:Group]]|?Has technique|?Has ID|?Has alias|limit=9999
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.
[[Uses software::Software/S0002]]|?Has ID|?Has display name|limit=9999
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.
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.