{ "cells": [ { "cell_type": "code", "execution_count": 1, "metadata": { "nbsphinx": "hidden" }, "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": "code", "execution_count": 2, "metadata": { "nbsphinx": "hidden" }, "outputs": [], "source": [ "# JSON output syntax highlighting\n", "from __future__ import print_function\n", "from pygments import highlight\n", "from pygments.lexers import JsonLexer, TextLexer\n", "from pygments.formatters import HtmlFormatter\n", "from IPython.display import display, HTML\n", "from IPython.core.interactiveshell import InteractiveShell\n", "\n", "InteractiveShell.ast_node_interactivity = \"all\"\n", "\n", "def json_print(inpt):\n", " string = str(inpt)\n", " formatter = HtmlFormatter()\n", " if string[0] == '{':\n", " lexer = JsonLexer()\n", " else:\n", " lexer = TextLexer()\n", " return HTML('{}'.format(\n", " formatter.get_style_defs('.highlight'),\n", " highlight(string, lexer, formatter)))\n", "\n", "globals()['print'] = json_print" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Using Environments\n", "\n", "An [Environment](../api/stix2.environment.rst#stix2.environment.Environment) object makes it easier to use STIX 2 content as part of a larger application or ecosystem. It allows you to abstract away the nasty details of sending and receiving STIX data, and to create STIX objects with default values for common properties.\n", "\n", "### Storing and Retrieving STIX Content\n", "\n", "An [Environment](../api/stix2.environment.rst#stix2.environment.Environment) can be set up with a [DataStore](../api/stix2.datastore.rst#stix2.datastore.DataStoreMixin) if you want to store and retrieve STIX content from the same place. " ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from stix2 import Environment, MemoryStore\n", "\n", "env = Environment(store=MemoryStore())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If desired, you can instead set up an [Environment](../api/stix2.environment.rst#stix2.environment.Environment) with different data sources and sinks. In the following example we set up an environment that retrieves objects from [memory](../api/datastore/stix2.datastore.memory.rst) and a directory on the [filesystem](../api/datastore/stix2.datastore.filesystem.rst), and stores objects in a different directory on the filesystem." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "from stix2 import CompositeDataSource, FileSystemSink, FileSystemSource, MemorySource\n", "\n", "src = CompositeDataSource()\n", "src.add_data_sources([MemorySource(), FileSystemSource(\"/tmp/stix2_source\")])\n", "env2 = Environment(source=src,\n", " sink=FileSystemSink(\"/tmp/stix2_sink\"))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once you have an [Environment](../api/stix2.environment.rst#stix2.environment.Environment) you can store some STIX content in its [DataSinks](../api/stix2.datastore.rst#stix2.datastore.DataSink) with [add()](../api/stix2.environment.rst#stix2.environment.Environment.add):" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": [ "from stix2 import Indicator\n", "\n", "indicator = Indicator(id=\"indicator--a740531e-63ff-4e49-a9e1-a0a3eed0e3e7\",\n", " labels=[\"malicious-activity\"],\n", " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "env.add(indicator)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can retrieve STIX objects from the [DataSources](../api/stix2.datastore.rst#stix2.datastore.DataSource) in the [Environment](../api/stix2.environment.rst#stix2.environment.Environment) with [get()](../api/stix2.environment.rst#stix2.environment.Environment.get), [query()](../api/stix2.environment.rst#stix2.environment.Environment.query), [all_versions()](../api/stix2.environment.rst#stix2.environment.Environment.all_versions), [creator_of()](../api/stix2.datastore.rst#stix2.datastore.DataSource.creator_of), [related_to()](../api/stix2.datastore.rst#stix2.datastore.DataSource.related_to), and [relationships()](../api/stix2.datastore.rst#stix2.datastore.DataSource.relationships) just as you would for a [DataSource](../api/stix2.datastore.rst#stix2.datastore.DataSource)." ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--a740531e-63ff-4e49-a9e1-a0a3eed0e3e7",\n",
       "    "created": "2018-04-05T19:27:53.923Z",\n",
       "    "modified": "2018-04-05T19:27:53.923Z",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2018-04-05T19:27:53.923548Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "print(env.get(\"indicator--a740531e-63ff-4e49-a9e1-a0a3eed0e3e7\"))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Creating STIX Objects With Defaults\n", "\n", "To create STIX objects with default values for certain properties, use an [ObjectFactory](../api/stix2.environment.rst#stix2.environment.ObjectFactory). For instance, say we want all objects we create to have a ``created_by_ref`` property pointing to the ``Identity`` object representing our organization." ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [], "source": [ "from stix2 import Indicator, ObjectFactory\n", "\n", "factory = ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-4473-83ec-1edf84858f4c\")" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "Once you've set up the [ObjectFactory](../api/stix2.environment.rst#stix2.environment.ObjectFactory), use its [create()](../api/stix2.environment.rst#stix2.environment.ObjectFactory.create) method, passing in the class for the type of object you wish to create, followed by the other properties and their values for the object." ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--c1b421c0-9c6b-4276-9b73-1b8684a5a0d2",\n",
       "    "created_by_ref": "identity--311b2d2d-f010-4473-83ec-1edf84858f4c",\n",
       "    "created": "2018-04-05T19:28:48.776Z",\n",
       "    "modified": "2018-04-05T19:28:48.776Z",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2018-04-05T19:28:48.776442Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "ind = factory.create(Indicator,\n", " labels=[\"malicious-activity\"],\n", " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "print(ind)" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "All objects we create with that [ObjectFactory](../api/stix2.environment.rst#stix2.environment.ObjectFactory) will automatically get the default value for ``created_by_ref``. These are the properties for which defaults can be set:\n", "\n", "- ``created_by_ref``\n", "- ``created``\n", "- ``external_references``\n", "- ``object_marking_refs``\n", "\n", "These defaults can be bypassed. For example, say you have an [Environment](../api/stix2.environment.rst#stix2.environment.Environment) with multiple default values but want to create an object with a different value for ``created_by_ref``, or none at all." ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--30a3b39c-5f57-4e7f-9eaf-e1abcb643da4",\n",
       "    "created": "2017-09-25T18:07:46.255Z",\n",
       "    "modified": "2017-09-25T18:07:46.255Z",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2018-04-05T19:28:53.268567Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "factory2 = ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-4473-83ec-1edf84858f4c\",\n", " created=\"2017-09-25T18:07:46.255472Z\")\n", "env2 = Environment(factory=factory2)\n", "\n", "ind2 = env2.create(Indicator,\n", " created_by_ref=None,\n", " labels=[\"malicious-activity\"],\n", " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "print(ind2)" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--6c5bbaaf-6dac-44b0-a0df-86c27b3f6ecb",\n",
       "    "created_by_ref": "identity--962cabe5-f7f3-438a-9169-585a8c971d12",\n",
       "    "created": "2017-09-25T18:07:46.255Z",\n",
       "    "modified": "2017-09-25T18:07:46.255Z",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2018-04-05T19:29:56.55129Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "ind3 = env2.create(Indicator,\n", " created_by_ref=\"identity--962cabe5-f7f3-438a-9169-585a8c971d12\",\n", " labels=[\"malicious-activity\"],\n", " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "print(ind3)" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "For the full power of the Environment layer, create an [Environment](../api/stix2.environment.rst#stix2.environment.Environment) with both a [DataStore](../api/stix2.datastore.rst#stix2.datastore.DataStoreMixin)/[Source](../api/stix2.datastore.rst#stix2.datastore.DataSource)/[Sink](../api/stix2.datastore.rst#stix2.datastore.DataSink) and an [ObjectFactory](../api/stix2.environment.rst#stix2.environment.ObjectFactory):" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--d1b8c3f6-1de1-44c1-b079-3df307224a0d",\n",
       "    "created_by_ref": "identity--311b2d2d-f010-4473-83ec-1edf84858f4c",\n",
       "    "created": "2018-04-05T19:29:59.605Z",\n",
       "    "modified": "2018-04-05T19:29:59.605Z",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2018-04-05T19:29:59.605463Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "environ = Environment(ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-4473-83ec-1edf84858f4c\"),\n", " MemoryStore())\n", "\n", "i = environ.create(Indicator,\n", " labels=[\"malicious-activity\"],\n", " pattern=\"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "environ.add(i)\n", "print(environ.get(i.id))" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.3" } }, "nbformat": 4, "nbformat_minor": 2 }