diff --git a/docs/guide/custom.ipynb b/docs/guide/custom.ipynb index d758550..8185269 100644 --- a/docs/guide/custom.ipynb +++ b/docs/guide/custom.ipynb @@ -175,9 +175,9 @@ ".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n", ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{\n",
        "    "type": "identity",\n",
-       "    "id": "identity--e7fd0fe0-25ff-4fcb-abe5-b6254a9d1a22",\n",
-       "    "created": "2019-07-25T18:18:18.241Z",\n",
-       "    "modified": "2019-07-25T18:18:18.241Z",\n",
+       "    "id": "identity--d6996982-5fb7-4364-b716-b618516989b6",\n",
+       "    "created": "2020-03-05T05:06:27.349Z",\n",
+       "    "modified": "2020-03-05T05:06:27.349Z",\n",
        "    "name": "John Smith",\n",
        "    "identity_class": "individual",\n",
        "    "x_foo": "bar"\n",
@@ -287,9 +287,9 @@
        ".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n",
        ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{\n",
        "    "type": "identity",\n",
-       "    "id": "identity--033b5f42-c94f-488f-8efa-2b6a167f0d6f",\n",
-       "    "created": "2019-07-25T18:18:21.352Z",\n",
-       "    "modified": "2019-07-25T18:18:21.352Z",\n",
+       "    "id": "identity--a167d2de-9fc4-4734-a1ae-57a548aad22a",\n",
+       "    "created": "2020-03-05T05:06:29.180Z",\n",
+       "    "modified": "2020-03-05T05:06:29.180Z",\n",
        "    "name": "John Smith",\n",
        "    "identity_class": "individual",\n",
        "    "x_foo": "bar"\n",
@@ -322,7 +322,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -403,7 +403,7 @@
        ""
       ]
      },
-     "execution_count": 3,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -511,7 +511,7 @@
        "    "type": "identity",\n",
        "    "id": "identity--311b2d2d-f010-4473-83ec-1edf84858f4c",\n",
        "    "created": "2015-12-21T19:59:11.000Z",\n",
-       "    "modified": "2019-07-25T18:18:25.927Z",\n",
+       "    "modified": "2020-03-05T05:06:32.934Z",\n",
        "    "name": "John Smith",\n",
        "    "identity_class": "individual"\n",
        "}\n",
@@ -544,7 +544,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -569,7 +569,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
@@ -645,9 +645,9 @@
        ".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n",
        ".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
{\n",
        "    "type": "x-animal",\n",
-       "    "id": "x-animal--b1e4fe7f-7985-451d-855c-6ba5c265b22a",\n",
-       "    "created": "2018-04-05T18:38:19.790Z",\n",
-       "    "modified": "2018-04-05T18:38:19.790Z",\n",
+       "    "id": "x-animal--1f7ce0ad-fd3a-4cf0-9cd7-13f7bef9ecd4",\n",
+       "    "created": "2020-03-05T05:06:38.010Z",\n",
+       "    "modified": "2020-03-05T05:06:38.010Z",\n",
        "    "species": "lion",\n",
        "    "animal_class": "mammal"\n",
        "}\n",
@@ -657,7 +657,7 @@
        ""
       ]
      },
-     "execution_count": 8,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -677,7 +677,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
@@ -703,7 +703,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
@@ -784,7 +784,7 @@
        ""
       ]
      },
-     "execution_count": 10,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -811,7 +811,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [
     {
@@ -846,7 +846,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [
     {
@@ -931,7 +931,7 @@
        ""
       ]
      },
-     "execution_count": 7,
+     "execution_count": 13,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -962,7 +962,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
@@ -1043,7 +1043,7 @@
        ""
       ]
      },
-     "execution_count": 13,
+     "execution_count": 14,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -1125,7 +1125,7 @@
        ""
       ]
      },
-     "execution_count": 13,
+     "execution_count": 14,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -1155,6 +1155,316 @@
     "print(obs_data.objects[\"0\"].property_2)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### ID-Contributing Properties for Custom Cyber Observables\n",
+    "STIX 2.1 Cyber Observables (SCOs) have deterministic IDs, meaning that the ID of a SCO is based on the values of some of its properties. Thus, if multiple cyber observables of the same type have the same values for their ID-contributing properties, then these SCOs will have the same ID. UUIDv5 is used for the deterministic IDs, using the namespace `\"00abedb4-aa42-466c-9c01-fed23315a9b7\"`. A SCO's ID-contributing properties may consist of a combination of required properties and optional properties.\n",
+    "\n",
+    "If a SCO type does not have any ID contributing properties defined, or all of the ID-contributing properties are not present on the object, then the SCO uses a randomly-generated UUIDv4. Thus, you can optionally define which 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 when defining your custom SCO with the `CustomObservable` decorator. 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": 15,
+   "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": 15,
+     "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": 15,
+     "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": 15,
+     "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": [
+    "In this example, `a_property` is the only id-contributing property. Notice that 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."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -1479,721 +1789,25 @@
     "print(obs_data2.objects[\"0\"].extensions[\"x-new-ext\"].property1)\n",
     "print(obs_data2.objects[\"0\"].extensions[\"x-new-ext\"].property2)"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Deterministic IDs for Cyber Observables\n",
-    "### Deterministic IDs\n",
-    "STIX 2.1 Cyber Observables (SCOs) have an ID property since SCOs are now top-level objects. However, SCOs have deterministic IDs, meaning that the ID of a SCO is based on the values of its properties. Thus, if multiple cyber observables of the same type have the same values for their ID-contributing properties (explained below), then these SCOs will have the same ID; the SCOs' ID is deterministic because the ID will not change if the values of the ID contributing properties do not change. \n",
-    "\n",
-    "A UUIDv5 is generated for the deterministic IDs, using the namespace `\"00abedb4-aa42-466c-9c01-fed23315a9b7\"`.\n",
-    "\n",
-    "In the case where a SCO does not have any defined ID contributing properties, or in the case where all of the values for the ID-contributing properties are not specified, then the SCO will be assigned a randomly-generated UUIDv4.\n",
-    "\n",
-    "### ID-Contributing Properties\n",
-    "So, what are ID-contributing properties? \n",
-    "Every SCO has multiple defined properties, but the values of only some of those properties will contribute to the determination of the SCO's ID. \n",
-    "\n",
-    "A SCO's ID-contributing properties may contain a combination of required properties and optional properties. And it is possible for all of the ID-contributing properties to be optional, which means the corresponding SCO could be created without values for any of those properties, which would lead the SCO to have a randomly-generated UUIDv4 ID.\n",
-    "\n",
-    "\n",
-    "We will demonstrate deterministic IDs by creating four `EmailAddress` SCOs. The `EmailAddress` SCO has one ID contributing property: `value`."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 6,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/html": [
-       "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
-       "
\n"
-      ],
-      "text/plain": [
-       ""
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
-    },
-    {
-     "data": {
-      "text/html": [
-       "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
-       "
\n"
-      ],
-      "text/plain": [
-       ""
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
-    },
-    {
-     "data": {
-      "text/html": [
-       "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
-       "
\n"
-      ],
-      "text/plain": [
-       ""
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
-    },
-    {
-     "data": {
-      "text/html": [
-       "
email-addr--d3742ef4-9452-5935-bc42-e8c35a119757\n",
-       "
\n"
-      ],
-      "text/plain": [
-       ""
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "from stix2.v21 import EmailAddress\n",
-    "\n",
-    "email_addr_1 = EmailAddress(value=\"johnnydoe@matching.com\", display_name=\"Johnny Doe\")\n",
-    "print (email_addr_1.id)\n",
-    "\n",
-    "email_addr_2 = EmailAddress(value=\"johnnydoe@matching.com\", display_name=\"Johnny Doe\")\n",
-    "print (email_addr_2.id)\n",
-    "\n",
-    "email_addr_3 = EmailAddress(value=\"johnnydoe@matching.com\", display_name=\"Johnathon Doe\")\n",
-    "print (email_addr_3.id)\n",
-    "\n",
-    "email_addr_4 = EmailAddress(value=\"johnnydoe@notmatching.com\", display_name=\"Johnny Doe\")\n",
-    "print (email_addr_4.id)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Notice that the ID for the first three `EmailAddress` objects is the same while the ID for the fourth is different. This is because the first three objects all have the same value for the ID-contributing property. And this is despite having a different value for the `display_name` property, since it is not an ID-contributing property for the `EmailAddress` SCO.\n",
-    "\n",
-    "Also note that the fourth object has a different ID despite having the same `display_name` as the first two objects; the value for the fourth object's ID-contributing property is different."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### 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 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."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 2",
    "language": "python",
-   "name": "python3"
+   "name": "python2"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
-    "version": 3
+    "version": 2
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.6.7"
+   "pygments_lexer": "ipython2",
+   "version": "2.7.15+"
   }
  },
  "nbformat": 4,