From 5df319bcbb2279dbda518401eac9a3840efb0ecd Mon Sep 17 00:00:00 2001 From: "Desai, Kartikey H" Date: Thu, 5 Mar 2020 13:33:45 -0500 Subject: [PATCH] Add documentation about id-contributing properties for 2.1 custom SCOs --- docs/guide/custom.ipynb | 320 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 309 insertions(+), 11 deletions(-) diff --git a/docs/guide/custom.ipynb b/docs/guide/custom.ipynb index 0609139..d758550 100644 --- a/docs/guide/custom.ipynb +++ b/docs/guide/custom.ipynb @@ -322,7 +322,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 3, "metadata": {}, "outputs": [ { @@ -403,7 +403,7 @@ "" ] }, - "execution_count": 6, + "execution_count": 3, "metadata": {}, "output_type": "execute_result" } @@ -544,7 +544,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 4, "metadata": {}, "outputs": [], "source": [ @@ -846,7 +846,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 7, "metadata": {}, "outputs": [ { @@ -931,7 +931,7 @@ "" ] }, - "execution_count": 12, + "execution_count": 7, "metadata": {}, "output_type": "execute_result" } @@ -1504,7 +1504,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 6, "metadata": {}, "outputs": [ { @@ -1585,7 +1585,7 @@ "" ] }, - "execution_count": 3, + "execution_count": 6, "metadata": {}, "output_type": "execute_result" }, @@ -1667,7 +1667,7 @@ "" ] }, - "execution_count": 3, + "execution_count": 6, "metadata": {}, "output_type": "execute_result" }, @@ -1749,7 +1749,7 @@ "" ] }, - "execution_count": 3, + "execution_count": 6, "metadata": {}, "output_type": "execute_result" }, @@ -1831,7 +1831,7 @@ "" ] }, - "execution_count": 3, + "execution_count": 6, "metadata": {}, "output_type": "execute_result" } @@ -1868,7 +1868,305 @@ "### ID-Contributing Properties for Custom Cyber Observables\n", "While all custom STIX 2.1 Cyber Observables (SCOs) have randomly-generated UUIDv4 IDs by default, you can optionally define which, if any, of your custom SCO's properties should be ID-contributing properties. Similar to standard SCOs, your custom SCO's ID-contributing properties can be any combination of the SCO's required and optional properties.\n", "\n", - "You define the ID-contributing properties right when creating your custom SCO. See the example below: (taken from `stix2/test/v21/test_custom.py` `test_custom_observable_object_det_id_1()` )" + "You define the ID-contributing properties right when creating the custom SCO; after the list of properties, you can optionally define the list of id-contributing properties. If you do not want to specify any id-contributing properties for your custom SCO, then you do not need to do anything additional. \n", + "\n", + "See the example below:" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
{\n",
+       "    "type": "x-new-observable-2",\n",
+       "    "id": "x-new-observable-2--6bc655d6-dcb8-52a3-a862-46848c17e599",\n",
+       "    "a_property": "A property",\n",
+       "    "property_2": 2000\n",
+       "}\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "text/html": [ + "
{\n",
+       "    "type": "x-new-observable-2",\n",
+       "    "id": "x-new-observable-2--6bc655d6-dcb8-52a3-a862-46848c17e599",\n",
+       "    "a_property": "A property",\n",
+       "    "property_2": 3000\n",
+       "}\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "text/html": [ + "
{\n",
+       "    "type": "x-new-observable-2",\n",
+       "    "id": "x-new-observable-2--1e56f9c3-a73b-5fbd-b348-83c76523c4df",\n",
+       "    "a_property": "A different property",\n",
+       "    "property_2": 3000\n",
+       "}\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from stix2.v21 import CustomObservable # IDs and Deterministic IDs are NOT part of STIX 2.0 Custom Observables\n", + "\n", + "@CustomObservable('x-new-observable-2', [\n", + " ('a_property', properties.StringProperty(required=True)),\n", + " ('property_2', properties.IntegerProperty()),\n", + "], [\n", + " 'a_property'\n", + "])\n", + "class NewObservable2():\n", + " pass\n", + "\n", + "new_observable_a = NewObservable2(a_property=\"A property\", property_2=2000)\n", + "print(new_observable_a)\n", + "\n", + "new_observable_b = NewObservable2(a_property=\"A property\", property_2=3000)\n", + "print(new_observable_b)\n", + "\n", + "new_observable_c = NewObservable2(a_property=\"A different property\", property_2=3000)\n", + "print(new_observable_c)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Notice how the ID for `new_observable_a` and `new_observable_b` is the same since they have the same value for the id-contributing `a_property` property." ] }, {