Add information on API layers
parent
07ccf9ec03
commit
2c8efc93bb
|
@ -1,6 +1,9 @@
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
|
Goals
|
||||||
|
-----
|
||||||
|
|
||||||
High level goals/principles of the python-stix2 library:
|
High level goals/principles of the python-stix2 library:
|
||||||
|
|
||||||
1. It should be as easy as possible (but no easier!) to perform common tasks of
|
1. It should be as easy as possible (but no easier!) to perform common tasks of
|
||||||
|
@ -10,6 +13,9 @@ High level goals/principles of the python-stix2 library:
|
||||||
the STIX 2.0 spec, as well as associated best practices. The library should
|
the STIX 2.0 spec, as well as associated best practices. The library should
|
||||||
make it hard to do "the wrong thing".
|
make it hard to do "the wrong thing".
|
||||||
|
|
||||||
|
Design Decisions
|
||||||
|
----------------
|
||||||
|
|
||||||
To accomplish these goals, and to incorporate lessons learned while developing
|
To accomplish these goals, and to incorporate lessons learned while developing
|
||||||
python-stix (for STIX 1.x), several decisions influenced the design of
|
python-stix (for STIX 1.x), several decisions influenced the design of
|
||||||
python-stix2:
|
python-stix2:
|
||||||
|
@ -22,3 +28,70 @@ python-stix2:
|
||||||
3. Core Python data types (including numeric types, ``datetime``) 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
|
when appropriate, and serialized to the correct format in JSON as specified
|
||||||
in the STIX 2.0 spec.
|
in the STIX 2.0 spec.
|
||||||
|
|
||||||
|
Architecture
|
||||||
|
------------
|
||||||
|
|
||||||
|
The `stix2` library APIs are divided into three logical layers, representing
|
||||||
|
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
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The lowest layer, **Object Layer**, is where Python objects representing STIX 2
|
||||||
|
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.
|
||||||
|
|
||||||
|
*This layer is mostly complete.*
|
||||||
|
|
||||||
|
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,
|
||||||
|
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).
|
||||||
|
|
||||||
|
*This layer is currently being developed.*
|
||||||
|
|
||||||
|
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
|
||||||
|
designed to be used directly by end users. For users who are comfortable with,
|
||||||
|
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
|
||||||
|
scripts.
|
||||||
|
|
||||||
|
*This layer has not yet been started.*
|
||||||
|
|
Loading…
Reference in New Issue