DOCSEARCHbyAlgolia
Submit Docs

cti-python-stix2

repository·master·Indexed 19 days ago

https://github.com/oasis-open/cti-python-stix2

Python APIs for serializing and de-serializing STIX2 JSON content. The library provides tools for creating STIX Domain Objects, Relationships, and Bundles, as well as support for custom properties and custom object types. It includes a tiered DataStore API architecture consisting of DataSource, DataSink, and DataStore, with implementations for FileSystem, Memory, and TAXII, and a CompositeDataSource for federating multiple sources.

Tokens
24.5K
Snippets
67
Records
80
Agent score
65%

What's inside cti-python-stix2

  1. How immutability works in stix2

    master

    By design, all STIX 2 data structures in this library are immutable by default.

    • Creation: All properties must be provided at the time of object creation.
    • Modification: Attempting to change a property after the object has been created will trigger an Immutability error.
    • Exceptions: Certain data structures like Lists and Dictionaries allow for content modification (adding or removing items) without triggering an immutability error, providing flexibility when building complex objects.

  2. Understand the stix2 library architecture

    master

    The stix2 library is organized into three logical layers of increasing abstraction. You can use these layers individually or combine them in a single application.

    1. Object Layer: The lowest level. It provides Python objects representing STIX 2 data types (SDOs, SROs, Cyber Observables, etc.). It handles serialization and deserialization to/from JSON. Note that this layer does not maintain referential integrity; _ref properties are handled by matching id values rather than direct Python object references.
    2. Environment Layer: Adds components for managing STIX data within larger ecosystems. It includes Data Source (retrieval from TAXII, databases, or filesystems), Data Sink (destinations for sending data), and Object Factory (for injecting common properties like created_by_ref into all objects). These can be bundled into an Environment object.
    3. Workbench Layer: The highest level, optimized for interactive analytical environments like Jupyter Notebooks. It abstracts the complexity of the lower layers to allow users to quickly interact with STIX data from various sources.

  3. How stix2 objects behave as dictionaries and strings

    master

    Library objects are designed to integrate seamlessly with standard Python types:

    • Dictionary behavior: Where necessary, library objects act like Python dict objects.
    • String behavior: When a library object is treated as a str, it returns its JSON representation.
    • Data types: The library uses core Python types (e.g., numeric types, datetime) and automatically serializes them to the correct JSON formats required by the STIX 2 specification.

  4. STIX 2 Technical Specification Support

    master

    The library supports multiple versions of the STIX 2 Technical Specification. Current versions include support for STIX Version 2.1.

    For versions that are still in the Committee Specification Draft (CSD) stage, you must import the specific modules manually. Once a specification reaches the Committee Specification (CS) level, the import stix2 statement will automatically load the corresponding STIX Objects.

  5. Get started with the STIX 2 Python API

    master

    The cti-python-stix2 library is designed to help you work with STIX 2 content. To begin using the library, follow these steps:

    1. Understand the Library: Read the overview to understand the core design and purpose.
    2. Learn by Doing: Consult the guides and tutorials for practical examples and usage patterns.
    3. Detailed Reference: For specific technical details on classes, functions, or methods, refer to the API reference.

  8. Run tests with pytest

    master

    The project uses pytest for testing. You can run tests from the root project directory.

    • To run all tests: pytest
    • To run a specific test file: pytest stix2/test/test_<xxx>.py

    All testing tools are included in the requirements.txt file.

    # Run all tests
pytest

# Run a specific test file
pytest stix2/test/test_example.py

  9. Check test coverage with coverage.py

    master

    To ensure code contributions are adequately tested, use pytest with the coverage plugin and generate an HTML report to identify untested lines of code.

    1. Run coverage: pytest --cov=stix2
    2. Generate HTML report: coverage html
    3. View the report at: htmlcov/index.html
    pytest --cov=stix2
coverage html

  10. Set up a development environment for cti-python-stix2

    master

    To contribute to the project, follow these steps to set up your local environment:

    1. Fork and Clone: Fork the repository on GitHub and clone your fork.
    2. Install Dependencies: Install the development-related dependencies using pip.
    3. Install Git Hooks: Install pre-commit hooks to ensure code quality and consistent formatting.

    It is recommended to use a virtualenv for your development environment.

    # 1. Clone your fork
git clone https://github.com/yourusername/cti-python-stix2.git

# 2. Install development dependencies
cd cti-python-stix2
pip install -r requirements.txt

# 3. Install pre-commit hooks
pre-commit install

  12. What is an Environment and how to use it

    master

    An Environment object acts as an abstraction layer for managing STIX 2 content within an application. It simplifies the process of sending and receiving STIX data by managing data sources (where data is read from) and data sinks (where data is written to). It also allows for the creation of STIX objects with predefined default values via an ObjectFactory.

    from stix2 import Environment, MemoryStore

env = Environment(store=MemoryStore())