{ "cells": [ { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": true, "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": { "collapsed": true, "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\n", "from pygments.formatters import HtmlFormatter\n", "from IPython.display import HTML\n", "\n", "original_print = print\n", "\n", "def json_print(inpt):\n", " string = str(inpt)\n", " if string[0] == '{':\n", " formatter = HtmlFormatter()\n", " return HTML('{}'.format(\n", " formatter.get_style_defs('.highlight'),\n", " highlight(string, JsonLexer(), formatter)))\n", " else:\n", " original_print(inpt)\n", "\n", "print = json_print" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Using Environments\n", "\n", "An ``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`` can be set up with a ``DataStore`` if you want to store and retrieve STIX content from the same place. " ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": true }, "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`` with different data sources and sinks. In the following example we set up an environment that retrieves objects from memory and a directory on the filesystem, and stores objects in a different directory on the filesystem." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "ename": "RuntimeError", "evalue": "maximum recursion depth exceeded while calling a Python object", "output_type": "error", "traceback": [ "\u001b[0;31mRuntimeError\u001b[0m\u001b[0;31m:\u001b[0m maximum recursion depth exceeded while calling a Python object\n" ] } ], "source": [ "from stix2 import CompositeDataSource, FileSystemSink, FileSystemSource, MemorySource\n", "\n", "src = CompositeDataSource()\n", "src.add_data_source([MemorySource(), FileSystemSource(\"stix_source\")])\n", "env2 = Environment(source=src,\n", " sink=FileSystemSink(\"stix_sink\"))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once you have an ``Environment`` you can store some STIX content in it with ``add()``:" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "ename": "KeyError", "evalue": "'objects'", "output_type": "error", "traceback": [ "\u001b[0;31mKeyError\u001b[0m\u001b[0;31m:\u001b[0m 'objects'\n" ] } ], "source": [ "from stix2 import Indicator\n", "\n", "indicator = Indicator(id=\"indicator--01234567-89ab-cdef-0123-456789abcdef\",\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 in the Environment with ``get()``, ``query()``, and ``all_versions()``, just as you would for a DataSource." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "ename": "IndexError", "evalue": "list index out of range", "output_type": "error", "traceback": [ "\u001b[0;31mIndexError\u001b[0m\u001b[0;31m:\u001b[0m list index out of range\n" ] } ], "source": [ "print(env.get(\"indicator--01234567-89ab-cdef-0123-456789abcdef\"))" ] }, { "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``. 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": 7, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from stix2 import Indicator, ObjectFactory\n", "\n", "factory = ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-5473-83ec-1edf84858f4c\")" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "Once you've set up the Object Factory, use its ``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": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--cc2faac7-3c29-4912-bfff-d87935791d17",\n",
       "    "created_by_ref": "identity--311b2d2d-f010-5473-83ec-1edf84858f4c",\n",
       "    "created": "2017-09-26T23:35:34.669Z",\n",
       "    "modified": "2017-09-26T23:35:34.669Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ],\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2017-09-26T23:35:34.669764Z"\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 8, "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`` 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`` 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": 9, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--fc423952-2088-4182-a5da-65bcc989c0cc",\n",
       "    "created": "2017-09-25T18:07:46.255Z",\n",
       "    "modified": "2017-09-25T18:07:46.255Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ],\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2017-09-26T23:35:37.083918Z"\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "factory2 = ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-5473-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": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--4850716c-7ff2-4f01-9bef-72c873f8bd29",\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",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ],\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2017-09-26T23:35:39.049647Z"\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 10, "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 with both a DataStore/Source/Sink and an Object Factory:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "ename": "KeyError", "evalue": "'objects'", "output_type": "error", "traceback": [ "\u001b[0;31mKeyError\u001b[0m\u001b[0;31m:\u001b[0m 'objects'\n" ] } ], "source": [ "environ = Environment(ObjectFactory(created_by_ref=\"identity--311b2d2d-f010-5473-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 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 }