From 47b28d11940a44ee7bf2dcff9977114a5963c965 Mon Sep 17 00:00:00 2001 From: "Desai, Kartikey H" Date: Tue, 18 Feb 2020 16:05:00 -0500 Subject: [PATCH] Fixes #323 --- docs/guide/custom.ipynb | 390 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 389 insertions(+), 1 deletion(-) diff --git a/docs/guide/custom.ipynb b/docs/guide/custom.ipynb index 7ceb33b..bdcc80e 100644 --- a/docs/guide/custom.ipynb +++ b/docs/guide/custom.ipynb @@ -1479,6 +1479,394 @@ "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": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "text/html": [ + "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "text/html": [ + "
email-addr--8fab0ad0-03c0-5cba-bf7b-c2bd41fb73a7\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "text/html": [ + "
email-addr--d3742ef4-9452-5935-bc42-e8c35a119757\n",
+       "
\n" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 3, + "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": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { @@ -1497,7 +1885,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.6.3" + "version": "3.6.7" } }, "nbformat": 4,