{ "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", " value.__cause__ = None # suppress chained exceptions\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 The Workbench" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The [Workbench API](../api/stix2.workbench.rst) hides most of the complexity of the rest of the library to make it easy to interact with STIX data. To use it, just import everything from ``stix2.workbench``:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "from stix2.workbench import *" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Retrieving STIX Data\n", "\n", "To get some STIX data to work with, let's set up a DataSource and add it to our workbench." ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "scrolled": true }, "outputs": [], "source": [ "from taxii2client import Collection\n", "\n", "collection = Collection(\"http://127.0.0.1:5000/trustgroup1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/\", user=\"admin\", password=\"Password0\")\n", "tc_source = TAXIICollectionSource(collection)\n", "add_data_source(tc_source)" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "Now we can get all of the indicators from the data source." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "response = indicators()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similar functions are available for the other STIX Object types. See the full list [here](../api/stix2.workbench.rst#stix2.workbench.attack_patterns).\n", "\n", "If you want to only retrieve *some* indicators, you can pass in one or more [Filters](../api/datastore/stix2.datastore.filters.rst). This example finds all the indicators created by a specific identity:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "response = indicators(filters=Filter('created_by_ref', '=', 'identity--adede3e8-bf44-4e6f-b3c9-1958cbc3b188'))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The objects returned let you easily traverse their relationships. Get all Relationship objects involving that object with ``.relationships()``, all other objects related to this object with ``.related()``, and the Identity object for the creator of the object (if one exists) with ``.created_by()``. For full details on these methods and their arguments, see the [Workbench API](../api/stix2.workbench.rst) documentation." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
indicator--cd981c25-8042-4166-8945-51178443bdac\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" }, { "data": { "text/html": [ "
indicates\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" }, { "data": { "text/html": [ "
malware--c0931cc6-c75e-47e5-9036-78fabc95d4ec\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "for i in indicators():\n", " for rel in i.relationships():\n", " print(rel.source_ref)\n", " print(rel.relationship_type)\n", " print(rel.target_ref)" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "malware",\n",
       "    "spec_version": "2.1",\n",
       "    "id": "malware--c0931cc6-c75e-47e5-9036-78fabc95d4ec",\n",
       "    "created": "2017-01-27T13:49:53.997Z",\n",
       "    "modified": "2017-01-27T13:49:53.997Z",\n",
       "    "name": "Poison Ivy",\n",
       "    "description": "Poison Ivy",\n",
       "    "malware_types": [\n",
       "        "remote-access-trojan"\n",
       "    ],\n",
       "    "is_family": true\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "for i in indicators():\n", " for obj in i.related():\n", " print(obj.serialize(pretty=True))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If there are a lot of related objects, you can narrow it down by passing in one or more [Filters](../api/datastore/stix2.datastore.filters.rst) just as before. For example, if we want to get only the indicators related to a specific piece of malware (and not any entities that use it or are targeted by it):" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "spec_version": "2.1",\n",
       "    "id": "indicator--cd981c25-8042-4166-8945-51178443bdac",\n",
       "    "created": "2014-05-08T09:00:00.000Z",\n",
       "    "modified": "2014-05-08T09:00:00.000Z",\n",
       "    "name": "File hash for Poison Ivy variant",\n",
       "    "indicator_types": [\n",
       "        "file-hash-watchlist"\n",
       "    ],\n",
       "    "pattern": "[file:hashes.'SHA-256' = 'ef537f25c895bfa782526529a9b63d97aa631564d5d789c2b765448c8635fb6c']",\n",
       "    "pattern_type": "stix",\n",
       "    "pattern_version": "2.1",\n",
       "    "valid_from": "2014-05-08T09:00:00Z"\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "malware = get('malware--c0931cc6-c75e-47e5-9036-78fabc95d4ec')\n", "indicator = malware.related(filters=Filter('type', '=', 'indicator'))\n", "print(indicator[0].serialize(pretty=True))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Creating STIX Data\n", "\n", "To create a STIX object, just use that object's class constructor. Once it's created, add it to the workbench with [save()](../api/stix2.workbench.rst#stix2.workbench.save)." ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [], "source": [ "identity = Identity(name=\"ACME Threat Intel Co.\", identity_class=\"organization\")\n", "save(identity)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can also set defaults for certain properties when creating objects. For example, let's set the default creator to be the identity object we just created:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [], "source": [ "set_default_creator(identity)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now when we create an indicator (or any other STIX Domain Object), it will automatically have the right ``create_by_ref`` value." ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
ACME Threat Intel Co.\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "indicator = Indicator(pattern_type=\"stix\", pattern=\"[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']\")\n", "save(indicator)\n", "\n", "indicator_creator = get(indicator.created_by_ref)\n", "print(indicator_creator.name)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Defaults can also be set for the [created timestamp](../api/stix2.workbench.rst#stix2.workbench.set_default_created), [external references](../api/stix2.workbench.rst#stix2.workbench.set_default_external_refs) and [object marking references](../api/stix2.workbench.rst#stix2.workbench.set_default_object_marking_refs)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "\n", "**Warning**\n", "\n", "The workbench layer replaces STIX Object classes with special versions of them that use \"wrappers\" to provide extra functionality. Because of this, we recommend that you **either use the workbench layer or the rest of the library, but not both**. In other words, don't import from both ``stix2.workbench`` and any other submodules of ``stix2``.\n", "\n", "
" ] } ], "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.9.0a6" } }, "nbformat": 4, "nbformat_minor": 2 }