pycti.utils.opencti_stix2
Attributes
Classes
Python API for Stix2 in OpenCTI. |
Module Contents
- pycti.utils.opencti_stix2.STIX_EXT_OCTI: str = 'extension-definition--ea279b3e-5c71-4632-ac08-831c66a786ba'[source]
- pycti.utils.opencti_stix2.STIX_EXT_OCTI_SCO: str = 'extension-definition--f93e2c80-4231-4f9a-af8b-95c9bd566a82'[source]
- pycti.utils.opencti_stix2.STIX_EXT_MITRE: str = 'extension-definition--322b8f77-262a-4cb8-a915-1e441e00329b'[source]
- pycti.utils.opencti_stix2.MARKDOWN_EXPORT_FIELDS: Tuple[str, Ellipsis] = ('description', 'x_opencti_description', 'content')[source]
- class pycti.utils.opencti_stix2.OpenCTIStix2(opencti)[source]
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
Initialize the OpenCTIStix2 helper.
- Parameters:
opencti (OpenCTIApiClient) – OpenCTI API client instance
- get_in_cache(data_id)[source]
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
- set_in_cache(data_id, data)[source]
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: Dict) None[source]
Log an error for unknown STIX object types.
- Parameters:
stix_object (Dict) – STIX object with unknown type
- convert_markdown(text: str) str[source]
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
- format_date(date: Any = None) str[source]
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
- filter_objects(uuids: List, objects: List) List[source]
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
- pick_aliases(stix_object: Dict) List | None[source]
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
- import_bundle_from_file(file_path: str, update: bool = False, types: List = None) Tuple[list, list] | None[source]
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: str | bytes, update: bool = False, types: List = None, work_id: str = None, objects_max_refs: int = 0) Tuple[list, list][source]
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]
- resolve_author(title: str) pycti.entities.opencti_identity.Identity | None[source]
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
- get_author(name: str) pycti.entities.opencti_identity.Identity[source]
Get or create an author identity by name.
- Parameters:
name (str) – Name of the author organization
- Returns:
Identity object for the author
- Return type:
- extract_embedded_relationships(stix_object: Dict, types: List = None) Dict[source]
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
- get_readers()[source]
Get a dictionary mapping entity types to their read methods.
- Returns:
Dictionary mapping entity types to read functions
- Return type:
dict
- get_reader(entity_type: str)[source]
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_stix_helper()[source]
Get a dictionary mapping STIX types to their helper functions.
- Returns:
Dictionary mapping STIX types to generate_id functions
- Return type:
dict
- get_internal_helper()[source]
Get a dictionary mapping internal types to their helper functions.
- Returns:
Dictionary mapping internal types to generate_id functions
- Return type:
dict
- generate_standard_id_from_stix(data)[source]
Generate a standard ID from STIX data.
- Parameters:
data (dict) – STIX data dictionary
- Returns:
Generated standard ID or None
- Return type:
str or None
- import_object(stix_object: Dict, update: bool = False, types: List = None) List | None[source]
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: Dict, update: bool = False, types: List = None) None[source]
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
- import_relationship(stix_relation: Dict, update: bool = False, types: List = None) None[source]
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
- import_sighting(stix_sighting: Dict, from_id: str, to_id: str, update: bool = False, types: List = None) None[source]
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
- generate_export(entity: Dict, no_custom_attributes: bool = False) Dict[source]
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
- static prepare_id_filters_export(entity_id: str | List[str], access_filter: Dict = None) Dict[source]
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
- prepare_export(entity: Dict, mode: str = 'simple', access_filter: Dict = None, no_custom_attributes: bool = False) List[source]
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
- get_stix_bundle_or_object_from_entity_id(entity_type: str, entity_id: str, mode: str = 'simple', access_filter: Dict = None, no_custom_attributes: bool = False, only_entity: bool = False) Dict[source]
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
- export_entity(entity_type: str, entity_id: str, mode: str = 'simple', access_filter: Dict = None, no_custom_attributes: bool = False, only_entity: bool = False) Dict[source]
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_entities_list(entity_type: str, search: Dict = None, filters: Dict = None, orderBy: str = None, orderMode: str = None, getAll: bool = True, withFiles: bool = False) List[Dict][source]
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_list(entity_type: str, search: Dict = None, filters: Dict = None, order_by: str = None, order_mode: str = None, mode: str = 'simple', access_filter: Dict = None) Dict[source]
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: List[dict], mode: str = 'simple', access_filter: Dict = None) Dict[source]
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
- apply_patch_files(item)[source]
Apply file patches to an item.
- Parameters:
item (dict) – Item containing file patch operations
- apply_patch(item)[source]
Apply field patches to an item.
- Parameters:
item (dict) – Item containing field patch operations
- rule_apply(item, bundle_id)[source]
Apply a rule to an item.
- Parameters:
item (dict) – Item to apply the rule to
- rule_clear(item)[source]
Clear a rule from an item.
- Parameters:
item (dict) – Item to clear the rule from
- rules_rescan(item, bundle_id)[source]
Rescan rules for an item.
- Parameters:
item (dict) – Item to rescan rules for
Share an item with organizations.
- Parameters:
item (dict) – Item to share
Unshare an item from organizations.
- Parameters:
item (dict) – Item to unshare
- element_add_organizations(item)[source]
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_remove_organizations(item)[source]
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
- element_add_groups(item)[source]
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_remove_groups(item)[source]
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
- send_email(item)[source]
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
- element_operation_delete(item, operation)[source]
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)[source]
Remove an element from draft.
- Parameters:
item (dict) – Item to remove from draft
- apply_opencti_operation(item, operation, bundle_id)[source]
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
- import_item(item, update: bool = False, types: List = None, work_id: str = None, bundle_id: str = None)[source]
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: bool = False, types: List = None, work_id: str = None, bundle_id: str = None)[source]
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_bundle(stix_bundle: Dict, update: bool = False, types: List = None, work_id: str = None, objects_max_refs: int = 0) Tuple[list, list][source]
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
- static put_attribute_in_extension(stix_object, extension_id, key, value, multiple=False) any[source]
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