Skip to content

Commit

Permalink
Merge pull request #521 from oasis-open/fix-custom-markings
Browse files Browse the repository at this point in the history 
Fix custom markings
  • Loading branch information
@rpiazza
rpiazza authored Jul 12, 2021
2 parents 3150cde + 295037f commit eaf578f
Show file tree
Hide file tree
Showing 6 changed files with 203 additions and 245 deletions.
188 changes: 33 additions & 155 deletions docs/guide/extensions.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,11 @@
"source": [
"## STIX Extensions\n",
"\n",
"This page is specific for the STIX Extensions mechanism defined in STIX 2.1 CS 02. For the deprecated STIX Customization mechanisms see the [Custom](custom.ipynb) section.\n",
"This page is specific for the STIX Extensions mechanism defined in STIX 2.1 CS 03. For the deprecated STIX Customization mechanisms see the [Custom](custom.ipynb) section.\n",
"\n",
"### Top Level Property Extensions\n",
"\n",
"The example below shows how to create an `indicator` object with a `top-level-property-extension`. "
"The example below shows how to create an `indicator` object with a `toplevel-property-extension`. Because an unregistered toplevel property extension is present, any unrecognized toplevel properties are assumed to be extension properties. So the library lets them pass. "
]
},
{
Expand All @@ -74,116 +74,11 @@
{
"data": {
"text/html": [
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
".highlight .hll { background-color: #ffffcc }\n",
".highlight { background: #f8f8f8; }\n",
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
".highlight .err { border: 1px solid #FF0000 } /* Error */\n",
".highlight .k { color: #008000; font-weight: bold } /* Keyword */\n",
".highlight .o { color: #666666 } /* Operator */\n",
".highlight .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
".highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
".highlight .cp { color: #BC7A00 } /* Comment.Preproc */\n",
".highlight .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
".highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
".highlight .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
".highlight .gd { color: #A00000 } /* Generic.Deleted */\n",
".highlight .ge { font-style: italic } /* Generic.Emph */\n",
".highlight .gr { color: #FF0000 } /* Generic.Error */\n",
".highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
".highlight .gi { color: #00A000 } /* Generic.Inserted */\n",
".highlight .go { color: #888888 } /* Generic.Output */\n",
".highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
".highlight .gs { font-weight: bold } /* Generic.Strong */\n",
".highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
".highlight .gt { color: #0044DD } /* Generic.Traceback */\n",
".highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
".highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
".highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
".highlight .kp { color: #008000 } /* Keyword.Pseudo */\n",
".highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
".highlight .kt { color: #B00040 } /* Keyword.Type */\n",
".highlight .m { color: #666666 } /* Literal.Number */\n",
".highlight .s { color: #BA2121 } /* Literal.String */\n",
".highlight .na { color: #7D9029 } /* Name.Attribute */\n",
".highlight .nb { color: #008000 } /* Name.Builtin */\n",
".highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
".highlight .no { color: #880000 } /* Name.Constant */\n",
".highlight .nd { color: #AA22FF } /* Name.Decorator */\n",
".highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
".highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
".highlight .nf { color: #0000FF } /* Name.Function */\n",
".highlight .nl { color: #A0A000 } /* Name.Label */\n",
".highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
".highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
".highlight .nv { color: #19177C } /* Name.Variable */\n",
".highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
".highlight .w { color: #bbbbbb } /* Text.Whitespace */\n",
".highlight .mb { color: #666666 } /* Literal.Number.Bin */\n",
".highlight .mf { color: #666666 } /* Literal.Number.Float */\n",
".highlight .mh { color: #666666 } /* Literal.Number.Hex */\n",
".highlight .mi { color: #666666 } /* Literal.Number.Integer */\n",
".highlight .mo { color: #666666 } /* Literal.Number.Oct */\n",
".highlight .sa { color: #BA2121 } /* Literal.String.Affix */\n",
".highlight .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
".highlight .sc { color: #BA2121 } /* Literal.String.Char */\n",
".highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
".highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
".highlight .s2 { color: #BA2121 } /* Literal.String.Double */\n",
".highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
".highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
".highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
".highlight .sx { color: #008000 } /* Literal.String.Other */\n",
".highlight .sr { color: #BB6688 } /* Literal.String.Regex */\n",
".highlight .s1 { color: #BA2121 } /* Literal.String.Single */\n",
".highlight .ss { color: #19177C } /* Literal.String.Symbol */\n",
".highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
".highlight .fm { color: #0000FF } /* Name.Function.Magic */\n",
".highlight .vc { color: #19177C } /* Name.Variable.Class */\n",
".highlight .vg { color: #19177C } /* Name.Variable.Global */\n",
".highlight .vi { color: #19177C } /* Name.Variable.Instance */\n",
".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n",
".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */</style><div class=\"highlight\"><pre><span></span><span class=\"p\">{</span>\n",
" <span class=\"nt\">&quot;type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;extension-definition&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;spec_version&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2.1&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;id&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;extension-definition--dd73de4f-a7f3-49ea-8ec1-8e884196b7a8&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;created_by_ref&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;identity--11b76a96-5d2b-45e0-8a5a-f6994f370731&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;created&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2014-02-20T09:16:08.000Z&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;modified&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2014-02-20T09:16:08.000Z&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;name&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;New SDO 1&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;description&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;This schema adds two properties to a STIX object at the toplevel&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;schema&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;https://www.example.com/schema-foo-1a/v1/&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;version&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;1.2.1&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;extension_types&quot;</span><span class=\"p\">:</span> <span class=\"p\">[</span>\n",
" <span class=\"s2\">&quot;toplevel-property-extension&quot;</span>\n",
" <span class=\"p\">],</span>\n",
" <span class=\"nt\">&quot;extension_properties&quot;</span><span class=\"p\">:</span> <span class=\"p\">[</span>\n",
" <span class=\"s2\">&quot;toxicity&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"s2\">&quot;rank&quot;</span>\n",
" <span class=\"p\">]</span>\n",
"<span class=\"p\">}</span>\n",
"</pre></div>\n"
],
"text/plain": [
"<IPython.core.display.HTML object>"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"text/html": [
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
"<style type=\"text/css\">pre { line-height: 125%; }\n",
"td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
"span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
"td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
"span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
".highlight .hll { background-color: #ffffcc }\n",
".highlight { background: #f8f8f8; }\n",
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
Expand Down Expand Up @@ -289,22 +184,6 @@
"source": [
"import stix2\n",
"\n",
"extension_definition1 = stix2.v21.ExtensionDefinition(\n",
" id=\"extension-definition--dd73de4f-a7f3-49ea-8ec1-8e884196b7a8\",\n",
" created_by_ref=\"identity--11b76a96-5d2b-45e0-8a5a-f6994f370731\",\n",
" created=\"2014-02-20T09:16:08.000Z\",\n",
" modified=\"2014-02-20T09:16:08.000Z\",\n",
" name=\"New SDO 1\",\n",
" description=\"This schema adds two properties to a STIX object at the toplevel\",\n",
" schema=\"https://www.example.com/schema-foo-1a/v1/\",\n",
" version=\"1.2.1\",\n",
" extension_types=[\"toplevel-property-extension\"],\n",
" extension_properties=[\n",
" \"toxicity\",\n",
" \"rank\",\n",
" ],\n",
")\n",
"\n",
"indicator = stix2.v21.Indicator(\n",
" id='indicator--e97bfccf-8970-4a3c-9cd1-5b5b97ed5d0c',\n",
" created='2014-02-20T09:16:08.989000Z',\n",
Expand All @@ -320,13 +199,12 @@
" pattern_type='stix',\n",
" valid_from='2014-02-20T09:00:00.000000Z',\n",
" extensions={\n",
" extension_definition1.id : {\n",
" \"extension-definition--dd73de4f-a7f3-49ea-8ec1-8e884196b7a8\" : {\n",
" 'extension_type': 'toplevel-property-extension',\n",
" },\n",
" }\n",
")\n",
"\n",
"print(extension_definition1.serialize(pretty=True))\n",
"print(indicator.serialize(pretty=True))"
]
},
Expand All @@ -336,7 +214,7 @@
"source": [
"### Using CustomExtension decorator\n",
"\n",
"However, in order to prevent repetitive instantiation of the same extension, the `@CustomExtension` decorator can be used to register the `extension-definition` with stix2. Use the `extension_type` class variable to define what kind of extension it is. Then its id can be passed into objects that use this extension."
"However, in order to define which properties are actually included with an extension, the `@CustomExtension` decorator can be used to register an extension type and its properties with stix2. Use the `extension_type` class variable to define what kind of extension it is. Then its id can be passed into objects that use this extension."
]
},
{
Expand Down Expand Up @@ -500,7 +378,7 @@
"\n",
"---\n",
"**Note:**\n",
"Creating an instance of an extension-definition object **does not** mean it is registered in the library. Please use the appropriate decorator for this step: `@CustomExtension`, `@CustomObject`, `@CustomObservable`, `@CustomMarking`\n",
"Creating an instance of an extension object **does not** mean it is registered in the library. Please use the appropriate decorator for this step: `@CustomExtension`, `@CustomObject`, `@CustomObservable`, `@CustomMarking`\n",
"\n",
"---"
]
Expand Down Expand Up @@ -632,9 +510,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Using CustomMarking for Extension Definition\n",
"### Custom Markings\n",
"\n",
"The example below shows the use for MarkingDefinition extensions. Currently this is only supported as a `property-extension`. Now, as another option to building the `extensions` as a dictionary, it can also be built with objects as shown below by extracting the registered class."
"The example below show how to create a user-defined marking based on an extension. The STIX `marking-definition` object is essentially a base upon which you build the particulars of your marking, via an extension. This is done in the same way as any other extension. Marking definitions are no different in this regard. The below example illustrates an alternative to building the extension entirely as a dictionary: it can also be built by instantiating the registered class."
]
},
{
Expand All @@ -645,11 +523,11 @@
{
"data": {
"text/html": [
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
"<style type=\"text/css\">pre { line-height: 125%; }\n",
"td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
"span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
"td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
"span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
".highlight .hll { background-color: #ffffcc }\n",
".highlight { background: #f8f8f8; }\n",
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
Expand Down Expand Up @@ -721,12 +599,13 @@
".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */</style><div class=\"highlight\"><pre><span></span><span class=\"p\">{</span>\n",
" <span class=\"nt\">&quot;type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;marking-definition&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;spec_version&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2.1&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;id&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;marking-definition--28417f9f-1963-4e7f-914d-233f8fd4829f&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;created&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2021-03-31T21:54:46.652069Z&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;id&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;marking-definition--9155f07c-dd4c-4320-be6a-0701311c3b84&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;created&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;2021-07-12T00:56:31.47566Z&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;name&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;This is the name of my favorite Marking&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;extensions&quot;</span><span class=\"p\">:</span> <span class=\"p\">{</span>\n",
" <span class=\"nt\">&quot;extension-definition--a932fcc6-e032-176c-126f-cb970a5a1fff&quot;</span><span class=\"p\">:</span> <span class=\"p\">{</span>\n",
" <span class=\"nt\">&quot;extension_type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;property-extension&quot;</span>\n",
" <span class=\"nt\">&quot;extension_type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;property-extension&quot;</span><span class=\"p\">,</span>\n",
" <span class=\"nt\">&quot;some_marking_field&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;value&quot;</span>\n",
" <span class=\"p\">}</span>\n",
" <span class=\"p\">}</span>\n",
"<span class=\"p\">}</span>\n",
Expand All @@ -742,24 +621,23 @@
}
],
"source": [
"from stix2 import registry\n",
"import stix2\n",
"import stix2.properties\n",
"\n",
"MARKING_EXTENSION_ID = 'extension-definition--a932fcc6-e032-176c-126f-cb970a5a1fff'\n",
"\n",
"@stix2.v21.CustomMarking(\n",
" 'my-favorite-marking', [\n",
" ('some_marking_field', stix2.properties.StringProperty(required=True)),\n",
" ], MARKING_EXTENSION_ID,\n",
")\n",
"@stix2.CustomExtension(MARKING_EXTENSION_ID, [\n",
" ('some_marking_field', stix2.properties.StringProperty(required=True))\n",
"])\n",
"class MyFavMarking:\n",
" pass\n",
"\n",
"ext_class = registry.class_for_type(MARKING_EXTENSION_ID, '2.1')\n",
" extension_type = 'property-extension'\n",
"\n",
"my_favorite_marking = MyFavMarking(\n",
"my_favorite_marking = stix2.MarkingDefinition(\n",
" name='This is the name of my favorite Marking',\n",
" extensions={\n",
" MARKING_EXTENSION_ID: ext_class(some_marking_field='value')\n",
" MARKING_EXTENSION_ID: MyFavMarking(\n",
" some_marking_field='value'\n",
" )\n",
" }\n",
")\n",
"\n",
Expand Down Expand Up @@ -908,7 +786,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
Expand All @@ -922,7 +800,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.2"
"version": "3.8.1"
}
},
"nbformat": 4,
Expand Down
Loading

0 comments on commit eaf578f

Please sign in to comment.