Skip to content

Commit eaf578f

Browse files
rpiazzarpiazza
authored
Merge pull request #521 from oasis-open/fix-custom-markings
Fix custom markings
2 parents 3150cde + 295037f commit eaf578f

File tree

6 files changed

+203
-245
lines changed

6 files changed

+203
-245
lines changed

‎docs/guide/extensions.ipynb‎

Lines changed: 33 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -59,11 +59,11 @@
5959
"source": [
6060
"## STIX Extensions\n",
6161
"\n",
62-
"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",
62+
"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",
6363
"\n",
6464
"### Top Level Property Extensions\n",
6565
"\n",
66-
"The example below shows how to create an `indicator` object with a `top-level-property-extension`. "
66+
"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. "
6767
]
6868
},
6969
{
@@ -74,116 +74,11 @@
7474
{
7575
"data": {
7676
"text/html": [
77-
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
78-
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
79-
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
80-
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
81-
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
82-
".highlight .hll { background-color: #ffffcc }\n",
83-
".highlight { background: #f8f8f8; }\n",
84-
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
85-
".highlight .err { border: 1px solid #FF0000 } /* Error */\n",
86-
".highlight .k { color: #008000; font-weight: bold } /* Keyword */\n",
87-
".highlight .o { color: #666666 } /* Operator */\n",
88-
".highlight .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
89-
".highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
90-
".highlight .cp { color: #BC7A00 } /* Comment.Preproc */\n",
91-
".highlight .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
92-
".highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
93-
".highlight .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
94-
".highlight .gd { color: #A00000 } /* Generic.Deleted */\n",
95-
".highlight .ge { font-style: italic } /* Generic.Emph */\n",
96-
".highlight .gr { color: #FF0000 } /* Generic.Error */\n",
97-
".highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
98-
".highlight .gi { color: #00A000 } /* Generic.Inserted */\n",
99-
".highlight .go { color: #888888 } /* Generic.Output */\n",
100-
".highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
101-
".highlight .gs { font-weight: bold } /* Generic.Strong */\n",
102-
".highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
103-
".highlight .gt { color: #0044DD } /* Generic.Traceback */\n",
104-
".highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
105-
".highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
106-
".highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
107-
".highlight .kp { color: #008000 } /* Keyword.Pseudo */\n",
108-
".highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
109-
".highlight .kt { color: #B00040 } /* Keyword.Type */\n",
110-
".highlight .m { color: #666666 } /* Literal.Number */\n",
111-
".highlight .s { color: #BA2121 } /* Literal.String */\n",
112-
".highlight .na { color: #7D9029 } /* Name.Attribute */\n",
113-
".highlight .nb { color: #008000 } /* Name.Builtin */\n",
114-
".highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
115-
".highlight .no { color: #880000 } /* Name.Constant */\n",
116-
".highlight .nd { color: #AA22FF } /* Name.Decorator */\n",
117-
".highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
118-
".highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
119-
".highlight .nf { color: #0000FF } /* Name.Function */\n",
120-
".highlight .nl { color: #A0A000 } /* Name.Label */\n",
121-
".highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
122-
".highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
123-
".highlight .nv { color: #19177C } /* Name.Variable */\n",
124-
".highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
125-
".highlight .w { color: #bbbbbb } /* Text.Whitespace */\n",
126-
".highlight .mb { color: #666666 } /* Literal.Number.Bin */\n",
127-
".highlight .mf { color: #666666 } /* Literal.Number.Float */\n",
128-
".highlight .mh { color: #666666 } /* Literal.Number.Hex */\n",
129-
".highlight .mi { color: #666666 } /* Literal.Number.Integer */\n",
130-
".highlight .mo { color: #666666 } /* Literal.Number.Oct */\n",
131-
".highlight .sa { color: #BA2121 } /* Literal.String.Affix */\n",
132-
".highlight .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
133-
".highlight .sc { color: #BA2121 } /* Literal.String.Char */\n",
134-
".highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
135-
".highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
136-
".highlight .s2 { color: #BA2121 } /* Literal.String.Double */\n",
137-
".highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
138-
".highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
139-
".highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
140-
".highlight .sx { color: #008000 } /* Literal.String.Other */\n",
141-
".highlight .sr { color: #BB6688 } /* Literal.String.Regex */\n",
142-
".highlight .s1 { color: #BA2121 } /* Literal.String.Single */\n",
143-
".highlight .ss { color: #19177C } /* Literal.String.Symbol */\n",
144-
".highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
145-
".highlight .fm { color: #0000FF } /* Name.Function.Magic */\n",
146-
".highlight .vc { color: #19177C } /* Name.Variable.Class */\n",
147-
".highlight .vg { color: #19177C } /* Name.Variable.Global */\n",
148-
".highlight .vi { color: #19177C } /* Name.Variable.Instance */\n",
149-
".highlight .vm { color: #19177C } /* Name.Variable.Magic */\n",
150-
".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */</style><div class=\"highlight\"><pre><span></span><span class=\"p\">{</span>\n",
151-
" <span class=\"nt\">&quot;type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;extension-definition&quot;</span><span class=\"p\">,</span>\n",
152-
" <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",
153-
" <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",
154-
" <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",
155-
" <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",
156-
" <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",
157-
" <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",
158-
" <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",
159-
" <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",
160-
" <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",
161-
" <span class=\"nt\">&quot;extension_types&quot;</span><span class=\"p\">:</span> <span class=\"p\">[</span>\n",
162-
" <span class=\"s2\">&quot;toplevel-property-extension&quot;</span>\n",
163-
" <span class=\"p\">],</span>\n",
164-
" <span class=\"nt\">&quot;extension_properties&quot;</span><span class=\"p\">:</span> <span class=\"p\">[</span>\n",
165-
" <span class=\"s2\">&quot;toxicity&quot;</span><span class=\"p\">,</span>\n",
166-
" <span class=\"s2\">&quot;rank&quot;</span>\n",
167-
" <span class=\"p\">]</span>\n",
168-
"<span class=\"p\">}</span>\n",
169-
"</pre></div>\n"
170-
],
171-
"text/plain": [
172-
"<IPython.core.display.HTML object>"
173-
]
174-
},
175-
"execution_count": 3,
176-
"metadata": {},
177-
"output_type": "execute_result"
178-
},
179-
{
180-
"data": {
181-
"text/html": [
182-
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
183-
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
184-
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
185-
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
186-
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
77+
"<style type=\"text/css\">pre { line-height: 125%; }\n",
78+
"td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
79+
"span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
80+
"td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
81+
"span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
18782
".highlight .hll { background-color: #ffffcc }\n",
18883
".highlight { background: #f8f8f8; }\n",
18984
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
@@ -289,22 +184,6 @@
289184
"source": [
290185
"import stix2\n",
291186
"\n",
292-
"extension_definition1 = stix2.v21.ExtensionDefinition(\n",
293-
" id=\"extension-definition--dd73de4f-a7f3-49ea-8ec1-8e884196b7a8\",\n",
294-
" created_by_ref=\"identity--11b76a96-5d2b-45e0-8a5a-f6994f370731\",\n",
295-
" created=\"2014-02-20T09:16:08.000Z\",\n",
296-
" modified=\"2014-02-20T09:16:08.000Z\",\n",
297-
" name=\"New SDO 1\",\n",
298-
" description=\"This schema adds two properties to a STIX object at the toplevel\",\n",
299-
" schema=\"https://www.example.com/schema-foo-1a/v1/\",\n",
300-
" version=\"1.2.1\",\n",
301-
" extension_types=[\"toplevel-property-extension\"],\n",
302-
" extension_properties=[\n",
303-
" \"toxicity\",\n",
304-
" \"rank\",\n",
305-
" ],\n",
306-
")\n",
307-
"\n",
308187
"indicator = stix2.v21.Indicator(\n",
309188
" id='indicator--e97bfccf-8970-4a3c-9cd1-5b5b97ed5d0c',\n",
310189
" created='2014-02-20T09:16:08.989000Z',\n",
@@ -320,13 +199,12 @@
320199
" pattern_type='stix',\n",
321200
" valid_from='2014-02-20T09:00:00.000000Z',\n",
322201
" extensions={\n",
323-
" extension_definition1.id : {\n",
202+
" \"extension-definition--dd73de4f-a7f3-49ea-8ec1-8e884196b7a8\" : {\n",
324203
" 'extension_type': 'toplevel-property-extension',\n",
325204
" },\n",
326205
" }\n",
327206
")\n",
328207
"\n",
329-
"print(extension_definition1.serialize(pretty=True))\n",
330208
"print(indicator.serialize(pretty=True))"
331209
]
332210
},
@@ -336,7 +214,7 @@
336214
"source": [
337215
"### Using CustomExtension decorator\n",
338216
"\n",
339-
"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."
217+
"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."
340218
]
341219
},
342220
{
@@ -500,7 +378,7 @@
500378
"\n",
501379
"---\n",
502380
"**Note:**\n",
503-
"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",
381+
"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",
504382
"\n",
505383
"---"
506384
]
@@ -632,9 +510,9 @@
632510
"cell_type": "markdown",
633511
"metadata": {},
634512
"source": [
635-
"### Using CustomMarking for Extension Definition\n",
513+
"### Custom Markings\n",
636514
"\n",
637-
"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."
515+
"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."
638516
]
639517
},
640518
{
@@ -645,11 +523,11 @@
645523
{
646524
"data": {
647525
"text/html": [
648-
"<style type=\"text/css\">pre { line-height: 125%; margin: 0; }\n",
649-
"td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
650-
"span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
651-
"td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
652-
"span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; }\n",
526+
"<style type=\"text/css\">pre { line-height: 125%; }\n",
527+
"td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
528+
"span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }\n",
529+
"td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
530+
"span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }\n",
653531
".highlight .hll { background-color: #ffffcc }\n",
654532
".highlight { background: #f8f8f8; }\n",
655533
".highlight .c { color: #408080; font-style: italic } /* Comment */\n",
@@ -721,12 +599,13 @@
721599
".highlight .il { color: #666666 } /* Literal.Number.Integer.Long */</style><div class=\"highlight\"><pre><span></span><span class=\"p\">{</span>\n",
722600
" <span class=\"nt\">&quot;type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;marking-definition&quot;</span><span class=\"p\">,</span>\n",
723601
" <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",
724-
" <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",
725-
" <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",
602+
" <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",
603+
" <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",
726604
" <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",
727605
" <span class=\"nt\">&quot;extensions&quot;</span><span class=\"p\">:</span> <span class=\"p\">{</span>\n",
728606
" <span class=\"nt\">&quot;extension-definition--a932fcc6-e032-176c-126f-cb970a5a1fff&quot;</span><span class=\"p\">:</span> <span class=\"p\">{</span>\n",
729-
" <span class=\"nt\">&quot;extension_type&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;property-extension&quot;</span>\n",
607+
" <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",
608+
" <span class=\"nt\">&quot;some_marking_field&quot;</span><span class=\"p\">:</span> <span class=\"s2\">&quot;value&quot;</span>\n",
730609
" <span class=\"p\">}</span>\n",
731610
" <span class=\"p\">}</span>\n",
732611
"<span class=\"p\">}</span>\n",
@@ -742,24 +621,23 @@
742621
}
743622
],
744623
"source": [
745-
"from stix2 import registry\n",
624+
"import stix2\n",
625+
"import stix2.properties\n",
746626
"\n",
747627
"MARKING_EXTENSION_ID = 'extension-definition--a932fcc6-e032-176c-126f-cb970a5a1fff'\n",
748628
"\n",
749-
"@stix2.v21.CustomMarking(\n",
750-
" 'my-favorite-marking', [\n",
751-
" ('some_marking_field', stix2.properties.StringProperty(required=True)),\n",
752-
" ], MARKING_EXTENSION_ID,\n",
753-
")\n",
629+
"@stix2.CustomExtension(MARKING_EXTENSION_ID, [\n",
630+
" ('some_marking_field', stix2.properties.StringProperty(required=True))\n",
631+
"])\n",
754632
"class MyFavMarking:\n",
755-
" pass\n",
756-
"\n",
757-
"ext_class = registry.class_for_type(MARKING_EXTENSION_ID, '2.1')\n",
633+
" extension_type = 'property-extension'\n",
758634
"\n",
759-
"my_favorite_marking = MyFavMarking(\n",
635+
"my_favorite_marking = stix2.MarkingDefinition(\n",
760636
" name='This is the name of my favorite Marking',\n",
761637
" extensions={\n",
762-
" MARKING_EXTENSION_ID: ext_class(some_marking_field='value')\n",
638+
" MARKING_EXTENSION_ID: MyFavMarking(\n",
639+
" some_marking_field='value'\n",
640+
" )\n",
763641
" }\n",
764642
")\n",
765643
"\n",
@@ -908,7 +786,7 @@
908786
],
909787
"metadata": {
910788
"kernelspec": {
911-
"display_name": "Python 3",
789+
"display_name": "Python 3 (ipykernel)",
912790
"language": "python",
913791
"name": "python3"
914792
},
@@ -922,7 +800,7 @@
922800
"name": "python",
923801
"nbconvert_exporter": "python",
924802
"pygments_lexer": "ipython3",
925-
"version": "3.9.2"
803+
"version": "3.8.1"
926804
}
927805
},
928806
"nbformat": 4,

0 commit comments

Comments
 (0)