Data Markings

Creating Objects With Data Markings

To create an object with a (predefined) TLP marking to an object, just provide it as a keyword argument to the constructor. The TLP markings can easily be imported from python-stix2.

from stix2 import Indicator, TLP_AMBER

indicator = Indicator(pattern_type="stix",
                      pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
                      object_marking_refs=TLP_AMBER)
print(indicator.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a315ce0b-1211-478e-812a-cd6d3eecc3c1",
    "created": "2021-04-09T13:59:48.911595Z",
    "modified": "2021-04-09T13:59:48.911595Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:48.911595Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ]
}

If you’re creating your own marking (for example, a Statement marking), first create the statement marking:

from stix2 import MarkingDefinition, StatementMarking

marking_definition = MarkingDefinition(
    definition_type="statement",
    definition=StatementMarking(statement="Copyright 2017, Example Corp")
)
print(marking_definition.serialize(pretty=True))

{
    "type": "marking-definition",
    "spec_version": "2.1",
    "id": "marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d",
    "created": "2021-04-09T13:59:50.587649Z",
    "definition_type": "statement",
    "definition": {
        "statement": "Copyright 2017, Example Corp"
    }
}

Then you can add it to an object as it’s being created (passing either full object or the the ID as a keyword argument, like with relationships).

indicator2 = Indicator(pattern_type="stix",
                       pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
                       object_marking_refs=marking_definition)
print(indicator2.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--91ed23a6-c5f0-4b16-8369-64cf39f974bf",
    "created": "2021-04-09T13:59:52.602254Z",
    "modified": "2021-04-09T13:59:52.602254Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:52.602254Z",
    "object_marking_refs": [
        "marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d"
    ]
}

indicator3 = Indicator(pattern_type="stix",
                       pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
                       object_marking_refs="marking-definition--f88d31f6-486f-44da-b317-01333bde0b82")
print(indicator3.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--42ae262e-4839-4c1a-a50a-3a6690623a9d",
    "created": "2021-04-09T13:59:54.207797Z",
    "modified": "2021-04-09T13:59:54.207797Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:54.207797Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ]
}

Granular markings work in the same way, except you also need to provide a full granular-marking object (including the selector).

from stix2 import Malware, TLP_WHITE

malware = Malware(name="Poison Ivy",
                  description="A ransomware related to ...",
                  is_family=False,
                  granular_markings=[
                      {
                          "selectors": ["description"],
                          "marking_ref": marking_definition
                      },
                      {
                          "selectors": ["name"],
                          "marking_ref": TLP_WHITE
                      }
                  ])
print(malware.serialize(pretty=True))

{
    "type": "malware",
    "spec_version": "2.1",
    "id": "malware--2658ac6a-44e9-44ea-8c8a-d67abae4d0d5",
    "created": "2021-04-09T13:59:56.556801Z",
    "modified": "2021-04-09T13:59:56.556801Z",
    "name": "Poison Ivy",
    "description": "A ransomware related to ...",
    "is_family": false,
    "granular_markings": [
        {
            "marking_ref": "marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d",
            "selectors": [
                "description"
            ]
        },
        {
            "marking_ref": "marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9",
            "selectors": [
                "name"
            ]
        }
    ]
}

Make sure that the selector is a field that exists and is populated on the object, otherwise this will cause an error:

Malware(name="Poison Ivy",
        description="A ransomware related to ...",
        is_family=False,
        granular_markings=[
            {
                "selectors": ["title"],
                "marking_ref": marking_definition
            }
        ])

InvalidSelectorError: Selector title in Malware is not valid!

Adding Data Markings To Existing Objects

Several functions exist to support working with data markings.

Both object markings and granular markings can be added to STIX objects which have already been created.

Note: Doing so will create a new version of the object (note the updated modified time).

indicator4 = indicator.add_markings(marking_definition)
print(indicator4.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a315ce0b-1211-478e-812a-cd6d3eecc3c1",
    "created": "2021-04-09T13:59:48.911595Z",
    "modified": "2021-04-09T14:00:01.165749Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:48.911595Z",
    "object_marking_refs": [
        "marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d",
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ]
}

You can also remove specific markings from STIX objects. This will also create a new version of the object.

indicator5 = indicator4.remove_markings(marking_definition)
print(indicator5.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a315ce0b-1211-478e-812a-cd6d3eecc3c1",
    "created": "2021-04-09T13:59:48.911595Z",
    "modified": "2021-04-09T14:00:03.00911Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:48.911595Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ]
}

The markings on an object can be replaced with a different set of markings:

from stix2 import TLP_GREEN

indicator6 = indicator5.set_markings([TLP_GREEN, marking_definition])
print(indicator6.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a315ce0b-1211-478e-812a-cd6d3eecc3c1",
    "created": "2021-04-09T13:59:48.911595Z",
    "modified": "2021-04-09T14:00:04.531083Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:48.911595Z",
    "object_marking_refs": [
        "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da",
        "marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d"
    ]
}

STIX objects can also be cleared of all markings with clear_markings():

indicator7 = indicator5.clear_markings()
print(indicator7.serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a315ce0b-1211-478e-812a-cd6d3eecc3c1",
    "created": "2021-04-09T13:59:48.911595Z",
    "modified": "2021-04-09T14:00:06.512465Z",
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T13:59:48.911595Z"
}

All of these functions can be used for granular markings by passing in a list of selectors. Note that they will create new versions of the objects.

Evaluating Data Markings

You can get a list of the object markings on a STIX object:

indicator6.get_markings()

['marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da',
 'marking-definition--4b8e86b5-d505-46a4-91b4-a8db17f4ff4d']

To get a list of the granular markings on an object, pass the object and a list of selectors to get_markings():

from stix2 import get_markings

get_markings(malware, 'name')

['marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9']

You can also call get_markings() as a method on the STIX object.

malware.get_markings('name')

['marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9']

Finally, you may also check if an object is marked by a specific markings. Again, for granular markings, pass in the selector or list of selectors.

indicator.is_marked(TLP_AMBER.id)

True

malware.is_marked(TLP_WHITE.id, 'name')

True

malware.is_marked(TLP_WHITE.id, 'description')

False

Extracting Lang Data Markings or marking-definition Data Markings

If you need a specific kind of marking, you can also filter them using the API. By default the library will get both types of markings by default. You can choose between lang=True/False or marking_ref=True/False depending on your use-case.

from stix2 import Indicator

v21_indicator = Indicator(
    description="Una descripcion sobre este indicador",
    pattern_type="stix",
    pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    object_marking_refs=['marking-definition--f88d31f6-486f-44da-b317-01333bde0b82'],
    indicator_types=['malware'],
    granular_markings=[
        {
            'selectors': ['description'],
            'lang': 'es'
        },
        {
            'selectors': ['description'],
            'marking_ref': 'marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da'
        }
    ]
)
print(v21_indicator.serialize(pretty=True))

# Gets both lang and marking_ref markings for 'description'
print(v21_indicator.get_markings('description'))

# Exclude lang markings from results
print(v21_indicator.get_markings('description', lang=False))

# Exclude marking-definition markings from results
print(v21_indicator.get_markings('description', marking_ref=False))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a2fd263a-ec46-4fff-84af-27419f0b9f15",
    "created": "2021-04-09T14:02:31.991141Z",
    "modified": "2021-04-09T14:02:31.991141Z",
    "description": "Una descripcion sobre este indicador",
    "indicator_types": [
        "malware"
    ],
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T14:02:31.991141Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ],
    "granular_markings": [
        {
            "lang": "es",
            "selectors": [
                "description"
            ]
        },
        {
            "marking_ref": "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da",
            "selectors": [
                "description"
            ]
        }
    ]
}

['marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da', 'es']

['marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da']

['es']

In this same manner, calls to clear_markings and set_markings also have the ability to operate in for one or both types of markings.

# By default, both types of markings will be removed
print(v21_indicator.clear_markings("description").serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a2fd263a-ec46-4fff-84af-27419f0b9f15",
    "created": "2021-04-09T14:02:31.991141Z",
    "modified": "2021-04-09T14:03:11.817032Z",
    "description": "Una descripcion sobre este indicador",
    "indicator_types": [
        "malware"
    ],
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T14:02:31.991141Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ]
}

# If lang is False, no lang markings will be removed
print(v21_indicator.clear_markings("description", lang=False).serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a2fd263a-ec46-4fff-84af-27419f0b9f15",
    "created": "2021-04-09T14:02:31.991141Z",
    "modified": "2021-04-09T14:03:24.701927Z",
    "description": "Una descripcion sobre este indicador",
    "indicator_types": [
        "malware"
    ],
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T14:02:31.991141Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ],
    "granular_markings": [
        {
            "lang": "es",
            "selectors": [
                "description"
            ]
        }
    ]
}

# If marking_ref is False, no marking-definition markings will be removed
print(v21_indicator.clear_markings("description", marking_ref=False).serialize(pretty=True))

{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a2fd263a-ec46-4fff-84af-27419f0b9f15",
    "created": "2021-04-09T14:02:31.991141Z",
    "modified": "2021-04-09T14:03:29.751985Z",
    "description": "Una descripcion sobre este indicador",
    "indicator_types": [
        "malware"
    ],
    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "valid_from": "2021-04-09T14:02:31.991141Z",
    "object_marking_refs": [
        "marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"
    ],
    "granular_markings": [
        {
            "marking_ref": "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da",
            "selectors": [
                "description"
            ]
        }
    ]
}