Introduction

This document describes how to query and manipulate CAPEC data in this repository. Machine-readable CAPEC data is available in a JSON-based STIX 2.0 and STIX 2.1 formats. See Release Notes for any changes to the generation of the STIX CAPEC data.

STIX 2.x is just JSON and so should be very accessible from Python and other programming languages. If you are using Python, the python-stix2 library can help you work with the content as shown in the examples below.

Mapping Concepts

First, we must describe how CAPEC objects and properties map to STIX 2.x objects and properties.

Objects

In CAPEC, the main object is the Attack Pattern. Most Attack Pattern also have Mitigations. There are other types of objects in CAPEC (e.g, Category, View, etc.), but these are not (currently) part of the repository.

The STIX types are found as literal strings assigned to the

type

property of the STIX JSON object. The STIX 2.x object called “Attack Pattern” corresponds to a CAPEC attack pattern. In STIX 2.x, there are objects called “Course(s) of Action” which can be used to describe CAPEC Mitigations.

Properties

The following is a table mapping of CAPEC properties to STIX properties. Some of these properties are standard STIX properties, while others were custom-created for compatibility with CAPEC. These properties are accessed from STIX objects as JSON properties.

Attack Pattern Properties

| CAPEC 3.6 Property | STIX Properties | STIX type | | ————— | ————— | ————— | Name |

name

| string | Description |

1
description

| string Extended_Definition |

1
x_capec_extended_definition

| string Abstraction |

1
x_capec_abstraction

| enumeration(

1
Meta, Standard, Detailed

) Alternate_Terms |

1
x_capec_alternate_terms

| list(string) Consequences |

1
x_capec_consequences

| dictionary(enumeration(

1
High, Medium, Low

), string) Example_Instances |

1
x_capec_example_instances

| list(string) Execution_Flows |

1
x_capec_execution_flows

| (XHTML) string Likelihood_Of_Attack |

1
x_capec_likelihood_of_attack

| enumeration(

1
High, Medium, Low

) Notes | Other_Notes |

1
x_capec_notes

| list(string) Prerequisites |

1
x_capec_prerequisites

| list(string) Skills_Required |

1
x_capec_skills_required

| dictionary(string, enumeration(

1
High, Medium, Low

)) Typical_Severity |

1
x_capec_typical_severity

| enumeration(

1
High, Medium, Low

) ID |

1
external_references[i].external_id where external_references[i].source_name == "capec"

| integer Related_Weaknesses |

1
external_references[i].external_id where external_references[i].source_name == "cwe"

| integer References |

1
external_references[i].external_id where external_references[i].source_name == "reference_from_CAPEC"

1
external-reference

Mitigation |

1
relationship_type == "mitigates"

1
relationship

Attack Pattern Relationships

| CAPEC 3.6 Relationship | STIX Properties | STIX type | | ————— | ————— | ————— | parent_of |

1	x_capec_parent_of_refs

| list(identifier) child_of |

1
x_capec_child_of_refs

| list(identifier) can_precede |

1
x_capec_can_precede_refs

| list(identifier) can_follow |

1
x_capec_can_follow_refs

| list(identifier) peer_of |

1
x_capec_peer_of_refs

| list(identifier)

CAPEC 3.6 properties not mapped (at this time): Indicators, Taxonomy_Mappings, Content_History

CAPEC 3.6 properties not appropriate to map: Status

Using Python and STIX 2.x

In this section, we will describe how to query and manipulate CAPEC data that has been stored in a STIX 2.x repository. A Python library has been created for using and creating STIX 2.x data by the OASIS Technical Committee for Cyber Threat Intelligence, which develops the STIX standard. This library abstracts storage and transport details so that the same code can be used to interact with data locally on the filesystem or in memory, or remotely via TAXII. The source code, installation instructions, and basic documentation for the library can be found here. There is a more thorough API documentation as well.

Python Library

To begin querying STIX 2.x data, you must first have a DataSource. For these examples, we will simply use a FileSystemSource. The CAPEC corpus must first be cloned or downloaded from GitHub.

Get all Attack Patterns

Once the stix2 Python library is installed and the corpus is acquired, we need to open the DataStore for querying:

from stix2 import FileSystemSource
fs = FileSystemSource('./cti/capec')

When creating the DataSource, the keyword agrument

1	allow_custom

must be set to

1
True

. This is because the CAPEC data uses several custom properties which are not part of the STIX 2.x specification (

1
x_capec_prerequisites

1
x_capec_example_instances

, etc).

To perform a query, we must define a Filter. As of this writing, a filter must, at a minimum, specify object

id

’s or an object

1
type

. The following filter can be used to retrieve all CAPEC attack patterns:

from stix2 import Filter
filt = Filter('type', '=', 'attack-pattern')

Once this filter is defined, you can pass it to the DataSource

query

function in order to actually query the data:

attack_patterns = fs.query([filt])

Notice that the

query

function takes a list of filters. These filters are logically AND’d together during the query. As of this writing,

1
allow_custom

must be set to

1
True

in order to query CAPEC data. This is because the CAPEC data uses several custom properties which are not part of the STIX 2.0 specification (

1
x_capec_prerequisites

1
x_capec_example_instances

, etc).

For the remaining examples, these imports and the FileSystemStore initialization will be omitted.

Get any object by CAPEC ID

In this example, the STIX 2.x type must be passed into the function. Here we query for the attack pattern with ID

(SQL Injection).

def get_attack_pattern_by_capec_id(src, capec_id):
    filt = [
        Filter('type', '=', 'attack-pattern'),
        Filter('external_references.external_id', '=', 'CAPEC-' + capec_id),
        Filter('external_references.source_name', '=', 'capec'),
    ]
    return src.query(filt)

get_attack_pattern_by_capec_id(fs, '66')

Get all Mitigations for specific Attack Pattern

The mitigations for a technique are stored in objects separate from the technique. These objects are found through a

mitigates

relationship.

def get_mitigations_by_attack_pattern(src, ap_stix_id):
    relations = src.relationships(ap_stix_id, 'mitigates', target_only=True)
    return src.query([
        Filter('type', '=', 'course-of-action'),
        Filter('id', 'in', [r.source_ref for r in relations])])

ap = get_attack_pattern_by_capec_id(fs, '66')[0]
get_mitigations_by_attack_pattern(fs, ap.id)

Release Notes

The STIX CAPEC data is generated by a python script named

1	capec2stix

. In this section the changes to the script for each new CAPEC release is listed.

Release for CAPEC 3.6

Added the 1 x_capec_extended_definition property

Release for CAPEC 3.5

Added functionality to infer CAPEC ParentOf and CanFollow relationships:
- CAPEC does not explicitly state these relationships, so they needed to be inferred by looking at the children’s “ChildOf” relationship and the can follows’ “CanPrecede” relationship and work backwards
- A global map of CAPEC ids to STIX ids was created by iterating through all CAPEC objects and creating STIX ids
- Global maps of CAPEC ids to list of children CAPEC ids and list of CAPEC ids that can follow was created by iterating through all CAPEC objects
- When creating STIX Attack Pattern objects, the child and can follow maps are used to find the relationships that are not explicitly stated in the CAPEC object and the STIX id map is used to get the STIX ID for the related CAPECs
Added the following properties to the Attack Pattern STIX object:
- 1 x_capec_child_of_refs: contains a list of STIX ids of the Attack Pattern objects which the current object is a child of
- 1 x_capec_parent_of_refs: contains a list of STIX ids of the Attack Pattern objects which the current object is a parent of
- 1 x_capec_can_precede_refs: contains a list of STIX ids of the Attack Pattern objects which the current object can precede
- 1 x_capec_can_follow_refs: contains a list of STIX ids of the Attack Pattern objects which the current object can follow
- 1 x_capec_peer_of_refs: contains a list of STIX ids of the Attack Pattern objects which the current object is a peer of
Added “allow_custom=True” as a flag when creating STIX bundles to satisfy the requirements for the new STIX release