pycti.utils.opencti_stix2

class pycti.utils.opencti_stix2.OpenCTIStix2(opencti)

Python API for Stix2 in OpenCTI.

Handles conversion between STIX2 format and OpenCTI internal format, including import/export operations and bundle processing.

Parameters:

opencti (OpenCTIApiClient) – OpenCTI API client instance

__init__(opencti)

Initialize the OpenCTIStix2 helper.

Parameters:

opencti (OpenCTIApiClient) – OpenCTI API client instance

apply_opencti_operation(item, operation, bundle_id)

Apply an OpenCTI operation to an item.

Parameters:

• item (dict) – Item to apply the operation to

• operation (str) – Operation to apply (delete, restore, merge, patch, etc.)

Raises:

ValueError – If the operation is not supported

apply_patch(item)

Apply field patches to an item.

Parameters:

item (dict) – Item containing field patch operations

apply_patch_files(item)

Apply file patches to an item.

Parameters:

item (dict) – Item containing file patch operations

convert_markdown(text)

Convert input text to markdown style code annotation.

Parameters:

text (str) – Input text to convert

Returns:

Sanitized text with markdown style code annotation

Return type:

str

element_add_groups(item)

Add groups to an element.

Parameters:

item (dict) – Item to add groups to

Raises:

ValueError – If the operation is not compatible with the item type

element_add_organizations(item)

Add organizations to an element.

Parameters:

item (dict) – Item to add organizations to

Raises:

ValueError – If the operation is not compatible with the item type

element_operation_delete(item, operation)

Delete an element.

Parameters:

• item (dict) – Item to delete

• operation (str) – Delete operation type (‘delete’ or ‘delete_force’)

Raises:

ValueError – If the delete operation fails or helper not found

element_remove_from_draft(item)

Remove an element from draft.

Parameters:

item (dict) – Item to remove from draft

element_remove_groups(item)

Remove groups from an element.

Parameters:

item (dict) – Item to remove groups from

Raises:

ValueError – If the operation is not compatible with the item type

element_remove_organizations(item)

Remove organizations from an element.

Parameters:

item (dict) – Item to remove organizations from

Raises:

ValueError – If the operation is not compatible with the item type

export_entities_list(entity_type, search=None, filters=None, orderBy=None, orderMode=None, getAll=True, withFiles=False)

List entities for export based on type and filters.

Parameters:

• entity_type (str) – Type of entities to list

• search (Dict, optional) – Search parameters, defaults to None

• filters (Dict, optional) – Filter parameters, defaults to None

• orderBy (str, optional) – Field to order results by, defaults to None

• orderMode (str, optional) – Order direction (‘asc’ or ‘desc’), defaults to None

• getAll (bool, optional) – Whether to get all results, defaults to True

• withFiles (bool, optional) – Whether to include files in the export, defaults to False

Returns:

List of entity dictionaries

Return type:

List[Dict]

export_entity(entity_type, entity_id, mode='simple', access_filter=None, no_custom_attributes=False, only_entity=False)

Export an entity as a STIX2 bundle.

Deprecated since version Use: get_stix_bundle_or_object_from_entity_id() instead.

Parameters:

• entity_type (str) – Type of the entity to export

• entity_id (str) – ID of the entity to export

• mode (str) – Export mode - ‘simple’ or ‘full’, defaults to ‘simple’

• access_filter (Dict, optional) – Access filter for the export, defaults to None

• no_custom_attributes (bool, optional) – Whether to exclude custom attributes, defaults to False

• only_entity (bool, optional) – If True, return only the entity object instead of a bundle

Returns:

STIX2 bundle dictionary or single STIX2 object

Return type:

Dict

export_list(entity_type, search=None, filters=None, order_by=None, order_mode=None, mode='simple', access_filter=None)

Export a list of entities as a STIX2 bundle.

Parameters:

• entity_type (str) – Type of entities to export

• search (Dict, optional) – Search parameters, defaults to None

• filters (Dict, optional) – Filter parameters, defaults to None

• order_by (str, optional) – Field to order results by, defaults to None

• order_mode (str, optional) – Order direction (‘asc’ or ‘desc’), defaults to None

• mode (str) – Export mode - ‘simple’ or ‘full’, defaults to ‘simple’

• access_filter (Dict, optional) – Access filter for the export, defaults to None

Returns:

STIX2 bundle containing all exported entities

Return type:

Dict

export_selected(entities_list, mode='simple', access_filter=None)

Export selected entities as a STIX2 bundle.

Parameters:

• entities_list (List[dict]) – List of entities to export

• mode (str) – Export mode (‘simple’ or ‘full’), defaults to ‘simple’

• access_filter (Dict) – Access filter for the export

Returns:

STIX2 bundle containing exported entities

Return type:

Dict

extract_embedded_relationships(stix_object, types=None)

Extract embedded relationship objects from a STIX2 entity.

Parameters:

• stix_object (Dict) – Valid STIX2 object

• types (list, optional) – List of STIX2 types to filter, defaults to None

Returns:

Dictionary containing embedded relationships and references

Return type:

dict

filter_objects(uuids, objects)

Filter objects based on UUIDs.

Parameters:

• uuids (list) – List of UUIDs to filter by

• objects (list) – List of objects to filter

Returns:

List of filtered objects not in the uuids list

Return type:

list

format_date(date=None)

Convert multiple input date formats to OpenCTI style dates.

Parameters:

date (Any) – Input date (datetime, date, str or None)

Returns:

ISO 8601 formatted date string

Return type:

str

generate_export(entity, no_custom_attributes=False)

Generate a STIX2 export from an OpenCTI entity.

Parameters:

• entity (Dict) – OpenCTI entity dictionary to export

• no_custom_attributes (bool, optional) – Whether to exclude custom x_opencti attributes, defaults to False

Returns:

STIX2 formatted entity dictionary

Return type:

Dict

generate_standard_id_from_stix(data)

Generate a standard ID from STIX data.

Parameters:

data (dict) – STIX data dictionary

Returns:

Generated standard ID or None

Return type:

str or None

get_author(name)

Get or create an author identity by name.

Parameters:

name (str) – Name of the author organization

Returns:

Identity object for the author

Return type:

Identity

get_in_cache(data_id)

Get an item from the cache.

Parameters:

data_id (str) – ID of the data to retrieve

Returns:

Cached data or None if not found

Return type:

dict or None

get_internal_helper()

Get a dictionary mapping internal types to their helper functions.

Returns:

Dictionary mapping internal types to generate_id functions

Return type:

dict

get_reader(entity_type)

Get the appropriate reader function for a given entity type.

Parameters:

entity_type (str) – Type of the entity

Returns:

Reader function for the entity type

Return type:

callable or None

get_readers()

Get a dictionary mapping entity types to their read methods.

Returns:

Dictionary mapping entity types to read functions

Return type:

dict

get_stix_bundle_or_object_from_entity_id(entity_type, entity_id, mode='simple', access_filter=None, no_custom_attributes=False, only_entity=False)

Get a STIX2 bundle or single object from an entity ID.

Parameters:

• entity_type (str) – Type of the entity to export

• entity_id (str) – ID of the entity to export

• mode (str) – Export mode - ‘simple’ or ‘full’, defaults to ‘simple’

• access_filter (Dict, optional) – Access filter for the export, defaults to None

• no_custom_attributes (bool, optional) – Whether to exclude custom attributes, defaults to False

• only_entity (bool, optional) – If True, return only the entity object instead of a bundle

Returns:

STIX2 bundle dictionary or single STIX2 object if only_entity is True

Return type:

Dict

get_stix_helper()

Get a dictionary mapping STIX types to their helper functions.

Returns:

Dictionary mapping STIX types to generate_id functions

Return type:

dict

import_bundle(stix_bundle, update=False, types=None, work_id=None, objects_max_refs=0)

Import a complete STIX2 bundle into OpenCTI.

Parameters:

• stix_bundle (Dict) – STIX2 bundle dictionary to import

• update (bool, optional) – Whether to update existing data, defaults to False

• types (List, optional) – List of STIX2 types to filter, defaults to None

• work_id (str, optional) – Work ID for tracking import progress, defaults to None

• objects_max_refs (int, optional) – Maximum number of object references allowed; objects exceeding this limit will be rejected. Set to 0 to disable the limit.

Returns:

Tuple of (list of successfully imported elements, list of failed/too-large elements)

Return type:

Tuple[list, list]

Raises:

ValueError – If the bundle is not properly formatted or empty

import_bundle_from_file(file_path, update=False, types=None)

Import a STIX2 bundle from a file.

Parameters:

• file_path (str) – Valid path to the file

• update (bool, optional) – Whether to update data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

Returns:

Tuple of (imported objects, failed objects) or None if file not found

Return type:

Tuple[list, list] or None

import_bundle_from_json(json_data, update=False, types=None, work_id=None, objects_max_refs=0)

Import a STIX2 bundle from JSON data.

Parameters:

• json_data (str or bytes) – JSON data as string or bytes

• update (bool, optional) – Whether to update data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

• work_id (str, optional) – Work ID for tracking import progress

• objects_max_refs (int, optional) – Maximum object references; rejects import if exceeded

Returns:

Tuple of (imported objects, objects with too many dependencies)

Return type:

Tuple[list, list]

import_item(item, update=False, types=None, work_id=None, bundle_id=None)

Import a single STIX2 item into OpenCTI.

Parameters:

• item (dict) – STIX2 item to import

• update (bool, optional) – Whether to update existing data, defaults to False

• types (List, optional) – List of STIX2 types to filter, defaults to None

• work_id (str, optional) – Work ID for tracking import progress, defaults to None

Returns:

True on success

Return type:

bool

import_item_with_retries(item, update=False, types=None, work_id=None, bundle_id=None)

Import a single STIX2 item with automatic retry on failures.

Handles various error types including timeouts, lock errors, missing references, and bad gateway errors with appropriate retry strategies.

Parameters:

• item (dict) – STIX2 item to import

• update (bool, optional) – Whether to update existing data, defaults to False

• types (List, optional) – List of STIX2 types to filter, defaults to None

• work_id (str, optional) – Work ID for tracking import progress, defaults to None

Returns:

None on success, the failed item on permanent failure

Return type:

dict or None

import_object(stix_object, update=False, types=None)

Import a STIX2 object into OpenCTI.

Parameters:

• stix_object (Dict) – Valid STIX2 object to import

• update (bool, optional) – Whether to update data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

Returns:

List of imported STIX2 objects or None on failure

Return type:

list or None

import_observable(stix_object, update=False, types=None)

Import a STIX cyber observable into OpenCTI.

Parameters:

• stix_object (Dict) – Valid STIX2 cyber observable object

• update (bool, optional) – Whether to update existing data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

Return type:

None

import_relationship(stix_relation, update=False, types=None)

Import a STIX core relationship into OpenCTI.

Parameters:

• stix_relation (Dict) – Valid STIX2 relationship object

• update (bool, optional) – Whether to update existing data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

Return type:

None

import_sighting(stix_sighting, from_id, to_id, update=False, types=None)

Import a STIX sighting relationship into OpenCTI.

Parameters:

• stix_sighting (Dict) – Valid STIX2 sighting object

• from_id (str) – ID of the source entity (sighting_of_ref)

• to_id (str) – ID of the target entity (where_sighted_ref)

• update (bool, optional) – Whether to update existing data in the database, defaults to False

• types (list, optional) – List of STIX2 types to filter, defaults to None

Return type:

None

organization_share(item)

Share an item with organizations.

Parameters:

item (dict) – Item to share

organization_unshare(item)

Unshare an item from organizations.

Parameters:

item (dict) – Item to unshare

pick_aliases(stix_object)

Check STIX2 object for multiple aliases and return a list.

Parameters:

stix_object (Dict) – Valid STIX2 object

Returns:

List of aliases or None if no aliases found

Return type:

list or None

prepare_export(entity, mode='simple', access_filter=None, no_custom_attributes=False)

Prepare an entity for STIX2 export with related objects.

Parameters:

• entity (Dict) – Entity dictionary to prepare for export

• mode (str) – Export mode - ‘simple’ for entity only, ‘full’ for entity with relations

• access_filter (Dict, optional) – Access filter for the export, defaults to None

• no_custom_attributes (bool, optional) – Whether to exclude custom attributes, defaults to False

Returns:

List of STIX2 objects ready for export

Return type:

List

static prepare_id_filters_export(entity_id, access_filter=None)

Prepare filter configuration for entity ID-based export queries.

Parameters:

• entity_id (Union[str, List[str]]) – Single entity ID or list of entity IDs to filter

• access_filter (Dict, optional) – Additional access filter to combine, defaults to None

Returns:

Filter configuration dictionary for API queries

Return type:

Dict

static put_attribute_in_extension(stix_object, extension_id, key, value, multiple=False)

Add or update an attribute in a STIX object’s extension.

Parameters:

• stix_object (dict) – STIX object to modify

• extension_id (str) – ID of the extension to add the attribute to

• key (str) – Attribute key name

• value (any) – Attribute value to set

• multiple (bool) – If True, append value to a list; if False, replace the value

Returns:

Modified STIX object

Return type:

dict

resolve_author(title)

Resolve an author identity from a title string.

Parameters:

title (str) – Title to search for known author names

Returns:

Identity object if author found, None otherwise

Return type:

Identity or None

rule_apply(item, bundle_id)

Apply a rule to an item.

Parameters:

item (dict) – Item to apply the rule to

rule_clear(item)

Clear a rule from an item.

Parameters:

item (dict) – Item to clear the rule from

rules_rescan(item, bundle_id)

Rescan rules for an item.

Parameters:

item (dict) – Item to rescan rules for

send_email(item)

Send an email for an item.

Parameters:

item (dict) – Item to send email for

Raises:

ValueError – If the operation is not supported for the item type

set_in_cache(data_id, data)

Store an item in the cache.

Parameters:

• data_id (str) – ID of the data to store

• data (dict) – Data to cache

unknown_type(stix_object)

Log an error for unknown STIX object types.

Parameters:

stix_object (Dict) – STIX object with unknown type

Return type:

None

pycti.utils.opencti_stix2.STIX_EXT_MITRE: str = 'extension-definition--322b8f77-262a-4cb8-a915-1e441e00329b'

STIX Extension ID for MITRE ATT&CK framework objects

pycti.utils.opencti_stix2.STIX_EXT_OCTI: str = 'extension-definition--ea279b3e-5c71-4632-ac08-831c66a786ba'

STIX Extension ID for OpenCTI custom objects and properties

pycti.utils.opencti_stix2.STIX_EXT_OCTI_SCO: str = 'extension-definition--f93e2c80-4231-4f9a-af8b-95c9bd566a82'

STIX Extension ID for OpenCTI custom Cyber Observables (SCO)