Skip to content

Commit 37e9049

Browse files
gtbackgtback
authored
Merge pull request #93 from emmanvg/issue-91
Update stix2 Package Structure
2 parents f029a01 + b2ff169 commit 37e9049

File tree

16 files changed

+423
-102
lines changed

16 files changed

+423
-102
lines changed

‎MANIFEST.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
include LICENSE
2+
include CHANGELOG
3+
recursive-exclude stix2\test *

‎README.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,16 @@ To parse a STIX JSON string into a Python STIX object, use ``parse()``:
6262
6363
For more in-depth documentation, please see `https://stix2.readthedocs.io/ <https://stix2.readthedocs.io/>`__.
6464

65+
STIX 2.X Technical Specification Support
66+
----------------------------------------
67+
68+
This version of python-stix2 supports STIX 2.0 by default. Although, the
69+
`stix2` Python library is built to support multiple versions of the STIX
70+
Technical Specification. With every major release of stix2 the ``import stix2``
71+
statement will automatically load the SDO/SROs equivalent to the most recent
72+
supported 2.X Technical Specification. Please see the library documentation
73+
for more details.
74+
6575
Governance
6676
----------
6777

‎docs/guide/ts_support.ipynb‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"## Technical Specification Support\n",
8+
"\n",
9+
"### How imports will work\n",
10+
"\n",
11+
"Imports can be used in different ways depending on the use case and support levels.\n",
12+
"\n",
13+
"People who want to (in general) support the latest version of STIX 2.X without making changes, implicitly using the latest version"
14+
]
15+
},
16+
{
17+
"cell_type": "code",
18+
"execution_count": null,
19+
"metadata": {},
20+
"outputs": [],
21+
"source": [
22+
"import stix2\n",
23+
"\n",
24+
"stix2.Indicator()"
25+
]
26+
},
27+
{
28+
"cell_type": "markdown",
29+
"metadata": {},
30+
"source": [
31+
"or,"
32+
]
33+
},
34+
{
35+
"cell_type": "code",
36+
"execution_count": null,
37+
"metadata": {},
38+
"outputs": [],
39+
"source": [
40+
"from stix2 import Indicator\n",
41+
"\n",
42+
"Indicator()"
43+
]
44+
},
45+
{
46+
"cell_type": "markdown",
47+
"metadata": {},
48+
"source": [
49+
"People who want to use an explicit version"
50+
]
51+
},
52+
{
53+
"cell_type": "code",
54+
"execution_count": null,
55+
"metadata": {},
56+
"outputs": [],
57+
"source": [
58+
"import stix2.v20\n",
59+
"\n",
60+
"stix2.v20.Indicator()"
61+
]
62+
},
63+
{
64+
"cell_type": "markdown",
65+
"metadata": {},
66+
"source": [
67+
"or,"
68+
]
69+
},
70+
{
71+
"cell_type": "code",
72+
"execution_count": null,
73+
"metadata": {},
74+
"outputs": [],
75+
"source": [
76+
"from stix2.v20 import Indicator\n",
77+
"\n",
78+
"Indicator()"
79+
]
80+
},
81+
{
82+
"cell_type": "markdown",
83+
"metadata": {},
84+
"source": [
85+
"or even,"
86+
]
87+
},
88+
{
89+
"cell_type": "code",
90+
"execution_count": null,
91+
"metadata": {},
92+
"outputs": [],
93+
"source": [
94+
"import stix2.v20 as stix2\n",
95+
"\n",
96+
"stix2.Indicator()"
97+
]
98+
},
99+
{
100+
"cell_type": "markdown",
101+
"metadata": {},
102+
"source": [
103+
"The last option makes it easy to update to a new version in one place per file, once you've made the deliberate action to do this.\n",
104+
"\n",
105+
"People who want to use multiple versions in a single file:"
106+
]
107+
},
108+
{
109+
"cell_type": "code",
110+
"execution_count": null,
111+
"metadata": {},
112+
"outputs": [],
113+
"source": [
114+
"import stix2\n",
115+
"\n",
116+
"stix2.v20.Indicator()\n",
117+
"\n",
118+
"stix2.v21.Indicator()"
119+
]
120+
},
121+
{
122+
"cell_type": "markdown",
123+
"metadata": {},
124+
"source": [
125+
"or,"
126+
]
127+
},
128+
{
129+
"cell_type": "code",
130+
"execution_count": null,
131+
"metadata": {},
132+
"outputs": [],
133+
"source": [
134+
"from stix2 import v20, v21\n",
135+
"\n",
136+
"v20.Indicator()\n",
137+
"v21.Indicator()"
138+
]
139+
},
140+
{
141+
"cell_type": "markdown",
142+
"metadata": {},
143+
"source": [
144+
"or (less preferred):"
145+
]
146+
},
147+
{
148+
"cell_type": "code",
149+
"execution_count": null,
150+
"metadata": {},
151+
"outputs": [],
152+
"source": [
153+
"from stix2.v20 import Indicator as Indicator_v20\n",
154+
"from stix2.v21 import Indicator as Indicator_v21\n",
155+
"\n",
156+
"Indicator_v20()\n",
157+
"Indicator_v21()"
158+
]
159+
},
160+
{
161+
"cell_type": "markdown",
162+
"metadata": {},
163+
"source": [
164+
"### How parsing will work\n",
165+
"If the ``version`` positional argument is not provided. The data will be parsed using the latest version of STIX 2.X supported by the `stix2` library.\n",
166+
"\n",
167+
"You can lock your `parse()` method to a specific STIX version by"
168+
]
169+
},
170+
{
171+
"cell_type": "code",
172+
"execution_count": null,
173+
"metadata": {},
174+
"outputs": [],
175+
"source": [
176+
"from stix2 import parse\n",
177+
"\n",
178+
"indicator = parse(\"\"\"{\n",
179+
" \"type\": \"indicator\",\n",
180+
" \"id\": \"indicator--dbcbd659-c927-4f9a-994f-0a2632274394\",\n",
181+
" \"created\": \"2017-09-26T23:33:39.829Z\",\n",
182+
" \"modified\": \"2017-09-26T23:33:39.829Z\",\n",
183+
" \"labels\": [\n",
184+
" \"malicious-activity\"\n",
185+
" ],\n",
186+
" \"name\": \"File hash for malware variant\",\n",
187+
" \"pattern\": \"[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']\",\n",
188+
" \"valid_from\": \"2017-09-26T23:33:39.829952Z\"\n",
189+
"}\"\"\", version=\"2.0\")\n",
190+
"print(indicator)"
191+
]
192+
},
193+
{
194+
"cell_type": "markdown",
195+
"metadata": {},
196+
"source": [
197+
"Keep in mind that if a 2.1 or higher object is parsed, the operation will fail."
198+
]
199+
},
200+
{
201+
"cell_type": "markdown",
202+
"metadata": {},
203+
"source": [
204+
"### How will custom work\n",
205+
"\n",
206+
"CustomObject, CustomObservable, CustomMarking and CustomExtension must be registered explicitly by STIX version. This is a design decision since properties or requirements may change as the STIX Technical Specification advances.\n",
207+
"\n",
208+
"You can perform this by,"
209+
]
210+
},
211+
{
212+
"cell_type": "code",
213+
"execution_count": null,
214+
"metadata": {},
215+
"outputs": [],
216+
"source": [
217+
"import stix2\n",
218+
"\n",
219+
"# Make my custom observable available in STIX 2.0\n",
220+
"@stix2.v20.CustomObservable('x-new-object-type',\n",
221+
" ((\"prop\", stix2.properties.BooleanProperty())))\n",
222+
"class NewObject2(object):\n",
223+
" pass\n",
224+
"\n",
225+
"\n",
226+
"# Make my custom observable available in STIX 2.1\n",
227+
"@stix2.v21.CustomObservable('x-new-object-type',\n",
228+
" ((\"prop\", stix2.properties.BooleanProperty())))\n",
229+
"class NewObject2(object):\n",
230+
" pass"
231+
]
232+
}
233+
],
234+
"metadata": {},
235+
"nbformat": 4,
236+
"nbformat_minor": 0
237+
}

‎setup.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ def get_version():
4545
'Programming Language :: Python :: 3.6',
4646
],
4747
keywords="stix stix2 json cti cyber threat intelligence",
48-
packages=find_packages(),
48+
packages=find_packages(exclude=['*.test']),
4949
install_requires=[
5050
'python-dateutil',
5151
'pytz',

‎stix2/__init__.py‎

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,27 +19,10 @@
1919

2020
# flake8: noqa
2121

22-
from . import exceptions
23-
from .common import (TLP_AMBER, TLP_GREEN, TLP_RED, TLP_WHITE, CustomMarking,
24-
ExternalReference, GranularMarking, KillChainPhase,
25-
MarkingDefinition, StatementMarking, TLPMarking)
26-
from .core import Bundle, _register_type, parse
22+
from .core import Bundle, _collect_stix2_obj_maps, _register_type, parse
2723
from .environment import Environment, ObjectFactory
2824
from .markings import (add_markings, clear_markings, get_markings, is_marked,
2925
remove_markings, set_markings)
30-
from .observables import (URL, AlternateDataStream, ArchiveExt, Artifact,
31-
AutonomousSystem, CustomExtension, CustomObservable,
32-
Directory, DomainName, EmailAddress, EmailMessage,
33-
EmailMIMEComponent, File, HTTPRequestExt, ICMPExt,
34-
IPv4Address, IPv6Address, MACAddress, Mutex,
35-
NetworkTraffic, NTFSExt, PDFExt, Process,
36-
RasterImageExt, SocketExt, Software, TCPExt,
37-
UNIXAccountExt, UserAccount, WindowsPEBinaryExt,
38-
WindowsPEOptionalHeaderType, WindowsPESection,
39-
WindowsProcessExt, WindowsRegistryKey,
40-
WindowsRegistryValueType, WindowsServiceExt,
41-
X509Certificate, X509V3ExtenstionsType,
42-
parse_observable)
4326
from .patterns import (AndBooleanExpression, AndObservationExpression,
4427
BasicObjectPathComponent, EqualityComparisonExpression,
4528
FloatConstant, FollowedByObservationExpression,
@@ -58,16 +41,17 @@
5841
ReferenceObjectPathComponent, RepeatQualifier,
5942
StartStopQualifier, StringConstant, TimestampConstant,
6043
WithinQualifier)
61-
from .sdo import (AttackPattern, Campaign, CourseOfAction, CustomObject,
62-
Identity, Indicator, IntrusionSet, Malware, ObservedData,
63-
Report, ThreatActor, Tool, Vulnerability)
6444
from .sources import CompositeDataSource
6545
from .sources.filesystem import (FileSystemSink, FileSystemSource,
6646
FileSystemStore)
6747
from .sources.filters import Filter
6848
from .sources.memory import MemorySink, MemorySource, MemoryStore
6949
from .sources.taxii import (TAXIICollectionSink, TAXIICollectionSource,
7050
TAXIICollectionStore)
71-
from .sro import Relationship, Sighting
7251
from .utils import get_dict, new_version, revoke
52+
from .v20 import * # This import will always be the latest STIX 2.X version
7353
from .version import __version__
54+
55+
_collect_stix2_obj_maps()
56+
57+
DEFAULT_VERSION = "2.0" # Default version will always be the latest STIX 2.X version

0 commit comments

Comments
 (0)