diff --git a/docs/guide/ts_support.ipynb b/docs/guide/ts_support.ipynb new file mode 100644 index 0000000..d353dfb --- /dev/null +++ b/docs/guide/ts_support.ipynb @@ -0,0 +1,237 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Technical Specification Support\n", + "\n", + "### How imports will work\n", + "\n", + "Imports can be used in different ways depending on the use case and support levels.\n", + "\n", + "People who want to (in general) support the latest version of STIX 2.X without making changes, implicitly using the latest version" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import stix2\n", + "\n", + "stix2.Indicator()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "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": {}, + "outputs": [], + "source": [ + "import stix2.v20\n", + "\n", + "stix2.v20.Indicator()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from stix2.v20 import Indicator\n", + "\n", + "Indicator()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or even," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "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": {}, + "outputs": [], + "source": [ + "import stix2\n", + "\n", + "stix2.v20.Indicator()\n", + "\n", + "stix2.v21.Indicator()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "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": {}, + "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 will work\n", + "If the ``version`` positional argument is not provided. The data will be parsed using the latest version of STIX 2.X supported by the `stix2` library.\n", + "\n", + "You can lock your `parse()` method to a specific STIX version by" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "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": [ + "Keep in mind that if a 2.1 or higher object is parsed, the operation will fail." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### How will custom work\n", + "\n", + "CustomObjects, CustomObservable, CustomMarking and CustomExtensions 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": null, + "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": {}, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/docs/index.rst b/docs/index.rst index f865467..62d07ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,6 @@ Welcome to stix2's documentation! datastore_api roadmap contributing - ts_support Indices and tables diff --git a/docs/ts_support.rst b/docs/ts_support.rst deleted file mode 100644 index a62e59e..0000000 --- a/docs/ts_support.rst +++ /dev/null @@ -1,134 +0,0 @@ -How imports will work ---------------------- - -Imports can be used in different ways depending on the use case and support -levels. - -People who want to (in general) support the latest version of STIX 2.X without -making changes, implicitly using the latest version - -.. code:: python - - import stix2 - ... - stix2.Indicator(...) - -or - -.. code:: python - - from stix2 import Indicator - ... - Indicator(...) - -People who want to use an explicit version - -.. code:: python - - import stix2.v20 - ... - stix2.v20.Indicator(...) - -or - -.. code:: python - - from stix2.v20 import Indicator - ... - Indicator(...) - -or even, - -.. code:: python - - import stix2.v20 as stix2 - ... - stix2.Indicator(...) - -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. - -People who want to use multiple versions in a single file: - -.. code:: python - - import stix2 - ... - stix2.v20.Indicator(...) - ... - stix2.v21.Indicator(...) - -or - -.. code:: python - - from stix2 import v20, v21 - ... - v20.Indicator(...) - ... - v21.Indicator(...) - -or (less preferred): - -.. code:: python - - from stix2.v20 import Indicator as Indicator_v20 - from stix2.v21 import Indicator as Indicator_v21 - ... - Indicator_v20(...) - ... - Indicator_v21(...) - -How parsing will work ---------------------- - -If the ``version`` positional argument is not provided. The data will be parsed -using the latest version of STIX 2.X supported by the `stix2` library. - -You can lock your `parse()` method to a specific STIX version by - -.. code:: python - - from stix2 import parse - - indicator = parse("""{ - "type": "indicator", - "id": "indicator--dbcbd659-c927-4f9a-994f-0a2632274394", - "created": "2017-09-26T23:33:39.829Z", - "modified": "2017-09-26T23:33:39.829Z", - "labels": [ - "malicious-activity" - ], - "name": "File hash for malware variant", - "pattern": "[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']", - "valid_from": "2017-09-26T23:33:39.829952Z" - }""", version="2.0") - print(indicator) - -Keep in mind that if a 2.1 or higher object is parsed, the operation will fail. - -How will custom work --------------------- - -CustomObjects, CustomObservable, CustomMarking and CustomExtensions must be -registered explicitly by STIX version. This is a design decision since properties -or requirements may change as the STIX Technical Specification advances. - -You can perform this by, - -.. code:: python - - import stix2 - - # Make my custom observable available in STIX 2.0 - @stix2.v20.observables.CustomObservable('x-new-object-type', - (("prop", stix2.properties.BooleanProperty()))) - class NewObject2(object): - pass - - - # Make my custom observable available in STIX 2.1 - @stix2.v21.observables.CustomObservable('x-new-object-type', - (("prop", stix2.properties.BooleanProperty()))) - class NewObject2(object): - pass