From b9a4580a2e1354ee7f807fbf79d104004077deb8 Mon Sep 17 00:00:00 2001 From: Chris Lenk Date: Fri, 15 Sep 2017 13:14:54 -0400 Subject: [PATCH] Add Data Markings documentation (Jupyter) --- .gitignore | 1 + docs/markings.ipynb | 607 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 608 insertions(+) create mode 100644 docs/markings.ipynb diff --git a/.gitignore b/.gitignore index 3b953e1..395676e 100644 --- a/.gitignore +++ b/.gitignore @@ -53,6 +53,7 @@ coverage.xml # Sphinx documentation docs/_build/ +.ipynb_checkpoints # PyBuilder target/ diff --git a/docs/markings.ipynb b/docs/markings.ipynb new file mode 100644 index 0000000..041e17b --- /dev/null +++ b/docs/markings.ipynb @@ -0,0 +1,607 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [ + "# Delete this cell to re-enable tracebacks\n", + "import sys\n", + "ipython = get_ipython()\n", + "\n", + "def hide_traceback(exc_tuple=None, filename=None, tb_offset=None,\n", + " exception_only=False, running_compiled_code=False):\n", + " etype, value, tb = sys.exc_info()\n", + " return ipython._showtraceback(etype, value, ipython.InteractiveTB.get_exception_only(etype, value))\n", + "\n", + "ipython.showtraceback = hide_traceback" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Data Markings" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Creating Objects With Data Markings\n", + "\n", + "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." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--e459c8d7-09aa-41c5-968d-66bf8610687e\",\n", + " \"created\": \"2017-09-15T16:32:04.495Z\",\n", + " \"modified\": \"2017-09-15T16:32:04.495Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:04.495379Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--f88d31f6-486f-44da-b317-01333bde0b82\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "from stix2 import Indicator, TLP_AMBER\n", + "\n", + "indicator = Indicator(labels=[\"malicious-activity\"],\n", + " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " object_marking_refs=TLP_AMBER)\n", + "print(indicator)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you’re creating your own marking (for example, a ``Statement`` marking), first create the statement marking:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"marking-definition\",\n", + " \"id\": \"marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0\",\n", + " \"created\": \"2017-09-15T16:32:07.947008Z\",\n", + " \"definition_type\": \"statement\",\n", + " \"definition\": {\n", + " \"statement\": \"Copyright 2017, Example Corp\"\n", + " }\n", + "}\n" + ] + } + ], + "source": [ + "from stix2 import MarkingDefinition, StatementMarking\n", + "\n", + "marking_definition = MarkingDefinition( \n", + " definition_type=\"statement\", \n", + " definition=StatementMarking(statement=\"Copyright 2017, Example Corp\")\n", + ")\n", + "print(marking_definition)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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)." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--06eea9e3-ea6d-418b-a517-4b1fff96f4aa\",\n", + " \"created\": \"2017-09-15T16:32:10.859Z\",\n", + " \"modified\": \"2017-09-15T16:32:10.859Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:10.859197Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "indicator2 = Indicator(labels=[\"malicious-activity\"],\n", + " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " object_marking_refs=marking_definition)\n", + "print(indicator2)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--94457e6e-4282-4355-8f2a-a59be2192b31\",\n", + " \"created\": \"2017-09-15T16:32:13.322Z\",\n", + " \"modified\": \"2017-09-15T16:32:13.322Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:13.322982Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--f88d31f6-486f-44da-b317-01333bde0b82\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "indicator3 = Indicator(labels=[\"malicious-activity\"],\n", + " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " object_marking_refs=\"marking-definition--f88d31f6-486f-44da-b317-01333bde0b82\")\n", + "print(indicator3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Granular markings work in the same way, except you also need to provide a full granular-marking object (including the selector)." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"malware\",\n", + " \"id\": \"malware--c91e0491-ea7f-46e4-85cd-90004da16b8a\",\n", + " \"created\": \"2017-09-15T16:32:15.801Z\",\n", + " \"modified\": \"2017-09-15T16:32:15.801Z\",\n", + " \"name\": \"Poison Ivy\",\n", + " \"description\": \"A ransomware related to ...\",\n", + " \"labels\": [\n", + " \"remote-access-trojan\"\n", + " ],\n", + " \"granular_markings\": [\n", + " {\n", + " \"marking_ref\": \"marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0\",\n", + " \"selectors\": [\n", + " \"description\"\n", + " ]\n", + " },\n", + " {\n", + " \"marking_ref\": \"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9\",\n", + " \"selectors\": [\n", + " \"name\"\n", + " ]\n", + " }\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "from stix2 import Malware, TLP_WHITE\n", + "\n", + "malware = Malware(name=\"Poison Ivy\",\n", + " labels=['remote-access-trojan'],\n", + " description=\"A ransomware related to ...\",\n", + " granular_markings=[\n", + " {\n", + " \"selectors\": [\"description\"],\n", + " \"marking_ref\": marking_definition\n", + " },\n", + " {\n", + " \"selectors\": [\"name\"],\n", + " \"marking_ref\": TLP_WHITE\n", + " }\n", + " ])\n", + "print(malware)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Make sure that the selector is a field that exists and is populated on the object, otherwise this will cause an error:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "ename": "InvalidSelectorError", + "evalue": "Selector title in Malware is not valid!", + "output_type": "error", + "traceback": [ + "\u001b[0;31mInvalidSelectorError\u001b[0m\u001b[0;31m:\u001b[0m Selector title in Malware is not valid!\n" + ] + } + ], + "source": [ + "Malware(name=\"Poison Ivy\",\n", + " labels=['remote-access-trojan'],\n", + " description=\"A ransomware related to ...\",\n", + " granular_markings=[\n", + " {\n", + " \"selectors\": [\"title\"],\n", + " \"marking_ref\": marking_definition\n", + " }\n", + " ])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Adding Data Markings To Existing Objects" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Both object markings and granular markings can also be added to STIX objects which have already been created. Doing so will create a new version of the object (note the updated ``modified`` time)." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--e459c8d7-09aa-41c5-968d-66bf8610687e\",\n", + " \"created\": \"2017-09-15T16:32:04.495Z\",\n", + " \"modified\": \"2017-09-15T16:51:40.883Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:04.495379Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0\",\n", + " \"marking-definition--f88d31f6-486f-44da-b317-01333bde0b82\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "from stix2.markings import add_markings\n", + "\n", + "indicator4 = add_markings(indicator, marking_definition.id)\n", + "print(indicator4)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can also remove specific markings from STIX objects. This will also create a new version of the object." + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--e459c8d7-09aa-41c5-968d-66bf8610687e\",\n", + " \"created\": \"2017-09-15T16:32:04.495Z\",\n", + " \"modified\": \"2017-09-15T16:59:35.160Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:04.495379Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--f88d31f6-486f-44da-b317-01333bde0b82\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "from stix2.markings import remove_markings\n", + "\n", + "indicator5 = remove_markings(indicator4, marking_definition.id)\n", + "print(indicator5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The markings on an object can be replaced with a different set of markings:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--e459c8d7-09aa-41c5-968d-66bf8610687e\",\n", + " \"created\": \"2017-09-15T16:32:04.495Z\",\n", + " \"modified\": \"2017-09-15T16:59:42.906Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:04.495379Z\",\n", + " \"object_marking_refs\": [\n", + " \"marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0\",\n", + " \"marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da\"\n", + " ]\n", + "}\n" + ] + } + ], + "source": [ + "from stix2 import TLP_GREEN\n", + "from stix2.markings import set_markings\n", + "\n", + "indicator6 = set_markings(indicator5, [TLP_GREEN.id, marking_definition.id])\n", + "print(indicator6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "STIX objects can also be cleared of all markings:" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{\n", + " \"type\": \"indicator\",\n", + " \"id\": \"indicator--e459c8d7-09aa-41c5-968d-66bf8610687e\",\n", + " \"created\": \"2017-09-15T16:32:04.495Z\",\n", + " \"modified\": \"2017-09-15T17:04:48.386Z\",\n", + " \"labels\": [\n", + " \"malicious-activity\"\n", + " ],\n", + " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", + " \"valid_from\": \"2017-09-15T16:32:04.495379Z\"\n", + "}\n" + ] + } + ], + "source": [ + "from stix2.markings import clear_markings\n", + "\n", + "indicator7 = clear_markings(indicator5)\n", + "print(indicator7)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Evaluating Data Markings\n", + "\n", + "You can get a list of the object markings on a STIX object:" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['marking-definition--674e3f0f-8547-41df-80b4-784eb4c5b4d0',\n", + " 'marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da']" + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from stix2.markings import get_markings\n", + "\n", + "get_markings(indicator6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can also get a list of granular markings by passing a list of selectors to ``get_markings``:" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9']" + ] + }, + "execution_count": 25, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "get_markings(malware, 'name')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can also check if an object is marked by a specific markings. Again, for granular markings, pass in the selector or list of selectors." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from stix2.markings import is_marked\n", + "\n", + "is_marked(indicator, TLP_AMBER.id)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "is_marked(malware, TLP_WHITE.id, 'name')" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "data": { + "text/plain": [ + "False" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "is_marked(malware, TLP_WHITE.id, 'description')" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 2", + "language": "python", + "name": "python2" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 2 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython2", + "version": "2.7.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}