cti-python-stix2/docs/overview.rst

93 lines
4.3 KiB
ReStructuredText
Raw Normal View History

2017-02-15 00:33:15 +01:00
Overview
========
2017-06-29 14:51:17 +02:00
Goals
-----
2018-04-09 19:29:53 +02:00
High level goals/principles of the Python ``stix2`` library:
2017-02-15 00:33:15 +01:00
1. It should be as easy as possible (but no easier!) to perform common tasks of
producing, consuming, and processing STIX 2 content.
2. It should be hard, if not impossible, to emit invalid STIX 2.
3. The library should default to doing "the right thing", complying with both
the STIX 2.0 spec, as well as associated best practices. The library should
make it hard to do "the wrong thing".
2017-06-29 14:51:17 +02:00
Design Decisions
----------------
2017-02-15 00:33:15 +01:00
To accomplish these goals, and to incorporate lessons learned while developing
2018-04-09 19:29:53 +02:00
``python-stix`` (for STIX 1.x), several decisions influenced the design of the
``stix2`` library:
2017-02-15 00:33:15 +01:00
1. All data structures are immutable by default. In contrast to python-stix,
where users would create an object and then assign attributes to it, in
2018-04-09 19:29:53 +02:00
``stix2`` all properties must be provided when creating the object.
2017-02-15 00:33:15 +01:00
2. Where necessary, library objects should act like ``dict``'s. When treated as
a ``str``, the JSON reprentation of the object should be used.
3. Core Python data types (including numeric types, ``datetime``) should be used
when appropriate, and serialized to the correct format in JSON as specified
2018-04-09 19:29:53 +02:00
in the STIX 2 spec.
2017-06-29 14:51:17 +02:00
Architecture
------------
2018-04-09 19:29:53 +02:00
The ``stix2`` library is divided into three logical layers, representing
2017-06-29 14:51:17 +02:00
different levels of abstraction useful in different types of scripts and larger
applications. It is possible to combine multiple layers in the same program,
and the higher levels build on the layers below.
Object Layer
^^^^^^^^^^^^
2018-04-09 19:29:53 +02:00
The lowest layer, the **Object Layer**, is where Python objects representing STIX 2
2017-06-29 14:51:17 +02:00
data types (such as SDOs, SROs, and Cyber Observable Objects, as well as
non-top-level objects like External References, Kill Chain phases, and Cyber
Observable extensions) are created, and can be serialized and deserialized
to and from JSON representation.
This layer is appropriate for stand-alone scripts that produce or consume STIX
2 content, or can serve as a low-level data API for larger applications that
need to represent STIX objects as Python classes.
At this level, non-embedded reference properties (those ending in ``_ref``, such
as the links from a Relationship object to its source and target objects) are
not implemented as references between the Python objects themselves, but by
simply having the same values in ``id`` and reference properties. There is no
referential integrity maintained by the ``stix2`` library.
Environment Layer
^^^^^^^^^^^^^^^^^
The **Environment Layer** adds several components that make it easier to handle
STIX 2 data as part of a larger application and as part of a larger cyber threat
intelligence ecosystem.
- ``Data Source``\s represent locations from which STIX data can be retrieved,
2017-06-29 14:51:17 +02:00
such as a TAXII server, database, or local filesystem. The Data Source API
abstracts differences between these storage location, giving a common API to
get objects by ID or query by various properties, as well as allowing
federated operations over multiple data sources.
- Similarly, ``Data Sink`` objects represent destinations for sending STIX data.
- An ``Object Factory`` provides a way to add common properties to all created
objects (such as the same ``created_by_ref``, or a ``StatementMarking`` with
copyright information or terms of use for the STIX data).
Each of these components can be used individually, or combined as part of an
``Environment``. These ``Environment`` objects allow different settings to be
used by different users of a multi-user application (such as a web application).
2018-04-09 19:29:53 +02:00
For more information, check out `this Environment tutorial <guide/environment.ipynb>`_.
2017-06-29 14:51:17 +02:00
Workbench Layer
^^^^^^^^^^^^^^^
The highest layer of the ``stix2`` APIs is the **Workbench Layer**, designed for
a single user in a highly-interactive analytical environment (such as a `Jupyter
Notebook <https://jupyter.org/>`_). It builds on the lower layers of the API,
while hiding most of their complexity. Unlike the other layers, this layer is
2018-04-09 19:29:53 +02:00
designed to be used directly by end users. For users who are comfortable with
2017-06-29 14:51:17 +02:00
Python, the Workbench Layer makes it easy to quickly interact with STIX data
from a variety of sources without needing to write and run one-off Python
2018-04-09 19:29:53 +02:00
scripts. For more information, check out `this Workbench tutorial <guide/workbench.ipynb>`_.