{ "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": [ "## Technical Specification Support\n", "\n", "### How imports work\n", "\n", "Imports can be used in different ways depending on the use case and support levels.\n", "\n", "People who want to support the latest version of STIX 2 without having to make changes, can implicitly use the latest version:", "
\n", "\n", "**Warning**\n", "\n", "The implicit import method can cause the code to break between major releases to support a newer approved committee specification. Therefore, not recommended for large scale applications relying on specific object support.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import stix2\n", "\n", "stix2.Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or," ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from stix2 import Indicator\n", "\n", "Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "People who want to use an explicit version:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import stix2.v20\n", "\n", "stix2.v20.Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or," ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from stix2.v20 import Indicator\n", "\n", "Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or even, (less preferred)" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import stix2.v20 as stix2\n", "\n", "stix2.Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The last option makes it easy to update to a new version in one place per file, once you've made the deliberate action to do this.\n", "\n", "People who want to use multiple versions in a single file:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import stix2\n", "\n", "stix2.v20.Indicator()\n", "stix2.v21.Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or," ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from stix2 import v20, v21\n", "\n", "v20.Indicator()\n", "v21.Indicator()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "or (less preferred):" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from stix2.v20 import Indicator as Indicator_v20\n", "from stix2.v21 import Indicator as Indicator_v21\n", "\n", "Indicator_v20()\n", "Indicator_v21()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How parsing works\n", "If the ``version`` positional argument is not provided the library will make the best attempt using the \"spec_version\" property found on a Bundle, SDOs, SCOs, or SROs.\n", "\n", "You can lock your [parse()](../api/stix2.parsing.rst#stix2.parsing.parse) method to a specific STIX version by:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
{\n",
       "    "type": "indicator",\n",
       "    "id": "indicator--dbcbd659-c927-4f9a-994f-0a2632274394",\n",
       "    "created": "2017-09-26T23:33:39.829Z",\n",
       "    "modified": "2017-09-26T23:33:39.829Z",\n",
       "    "name": "File hash for malware variant",\n",
       "    "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",\n",
       "    "valid_from": "2017-09-26T23:33:39.829952Z",\n",
       "    "labels": [\n",
       "        "malicious-activity"\n",
       "    ]\n",
       "}\n",
       "
\n" ], "text/plain": [ "" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from stix2 import parse\n", "\n", "indicator = parse(\"\"\"{\n", " \"type\": \"indicator\",\n", " \"id\": \"indicator--dbcbd659-c927-4f9a-994f-0a2632274394\",\n", " \"created\": \"2017-09-26T23:33:39.829Z\",\n", " \"modified\": \"2017-09-26T23:33:39.829Z\",\n", " \"labels\": [\n", " \"malicious-activity\"\n", " ],\n", " \"name\": \"File hash for malware variant\",\n", " \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n", " \"valid_from\": \"2017-09-26T23:33:39.829952Z\"\n", "}\"\"\", version=\"2.0\")\n", "print(indicator)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In the example above if a 2.1 or higher object is parsed, the operation will fail." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How custom content works\n", "\n", "[CustomObject](../api/v21/stix2.v21.sdo.rst#stix2.v21.sdo.CustomObject), [CustomObservable](../api/v21/stix2.v21.observables.rst#stix2.v21.observables.CustomObservable), [CustomMarking](../api/v21/stix2.v21.common.rst#stix2.v21.common.CustomMarking) and [CustomExtension](../api/v21/stix2.v21.observables.rst#stix2.v21.observables.CustomExtension) must be registered explicitly by STIX version. This is a design decision since properties or requirements may change as the STIX Technical Specification advances.\n", "\n", "You can perform this by:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "import stix2\n", "\n", "# Make my custom observable available in STIX 2.0\n", "@stix2.v20.CustomObservable('x-new-object-type',\n", " [(\"prop\", stix2.properties.BooleanProperty())])\n", "class NewObject2(object):\n", " pass\n", "\n", "\n", "# Make my custom observable available in STIX 2.1\n", "@stix2.v21.CustomObservable('x-new-object-type',\n", " [(\"prop\", stix2.properties.BooleanProperty())])\n", "class NewObject2(object):\n", " pass" ] } ], "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": 1 }