`pycti`

Functions 

get_config_variable(): [summary]

pycti.get_config_variable(env_var, yaml_path, config=None, isNumber=False, default=None, required=False)[source]

Retrieve a configuration variable from environment or YAML config.

Looks up configuration values with the following precedence: 1. Environment variable (highest priority) 2. YAML configuration file 3. Default value (lowest priority)

Boolean string values (“yes”, “true”, “True”, “no”, “false”, “False”) are automatically converted to Python bool.

Parameters:

env_var (str) – Name of the environment variable to check
yaml_path (List[str]) – Two-element list specifying [section, key] in YAML config
config (Dict) – Configuration dictionary loaded from YAML file
isNumber (bool) – If True, convert the value to integer
default (any) – Default value if not found in env or config
required (bool) – If True and no value found, raise ValueError

Returns:

The configuration value as bool, int, str, or None

Return type:

Union[bool, int, None, str]

Raises:

ValueError – If required=True and no value is found

Example

>>> get_config_variable("OPENCTI_URL", ["opencti", "url"], config)
'http://localhost:8080'
>>> get_config_variable("CONNECTOR_LOG_LEVEL", ["connector", "log_level"],
...                     config, default="INFO")
'INFO'

Classes 

AttackPattern: Main AttackPattern class for OpenCTI
Campaign: Main Campaign class for OpenCTI
CaseIncident: Main CaseIncident class for OpenCTI
CaseRfi: Main CaseRfi class for OpenCTI
CaseRft: Main CaseRft class for OpenCTI
Channel: Main Channel class for OpenCTI
Task: Main Task class for OpenCTI
ConnectorType: An enumeration.
CourseOfAction: Main CourseOfAction class for OpenCTI
DataComponent: Main DataComponent class for OpenCTI
DataSource: Main DataSource class for OpenCTI
ExternalReference: Main ExternalReference class for OpenCTI
Feedback: Main Feedback class for OpenCTI
Grouping: Main Grouping class for OpenCTI
Identity: Main Identity class for OpenCTI
Incident: Main Incident class for OpenCTI
Indicator: Main Indicator class for OpenCTI
Infrastructure: Main Infrastructure class for OpenCTI
IntrusionSet: Main IntrusionSet class for OpenCTI
KillChainPhase: Main KillChainPhase class for OpenCTI
Label: Main Label class for OpenCTI
Location: Main Location class for OpenCTI
Malware: Main Malware class for OpenCTI
MalwareAnalysis: Main MalwareAnalysis class for OpenCTI
MarkingDefinition: Main MarkingDefinition class for OpenCTI
Note: Main Note class for OpenCTI
ObservedData: Main ObservedData class for OpenCTI
OpenCTIApiClient: Main API client for OpenCTI
OpenCTIApiConnector: OpenCTI API Connector client
OpenCTIApiWork: OpenCTI API Work client
OpenCTIConnector: Main class for OpenCTI connector
OpenCTIConnectorHelper: Python API for OpenCTI connector
OpenCTIMetricHandler: Main OpenCTI Metric Handler class
OpenCTIStix2: Python API for Stix2 in OpenCTI
OpenCTIStix2Splitter: Main OpenCTI Stix2 Splitter class
OpenCTIStix2Update: Python API for Stix2 Update in OpenCTI
OpenCTIStix2Utils: Main OpenCTI Stix2 Utils class
Opinion: Main Opinion class for OpenCTI
Report: Main Report class for OpenCTI
StixCoreRelationship: Main StixCoreRelationship class for OpenCTI
StixCyberObservable: Deprecated StixCyberObservable class [>=6.2 & <6.5]
StixNestedRefRelationship: Main StixNestedRefRelationship class for OpenCTI
StixCyberObservableTypes: An enumeration.
StixDomainObject: Main StixDomainObject class for OpenCTI
StixMetaTypes: An enumeration.
MultipleRefRelationship: An enumeration.
StixObjectOrStixRelationship: Main StixObjectOrStixRelationship class for OpenCTI
StixSightingRelationship: Main StixSightingRelationship class for OpenCTI
ThreatActor: Main ThreatActor class for OpenCTI
ThreatActorGroup: Main ThreatActorGroup class for OpenCTI
ThreatActorIndividual: Main ThreatActorIndividual class for OpenCTI
Tool: Main Tool class for OpenCTI
Vulnerability: Main Vulnerability class for OpenCTI
CustomObjectCaseIncident: Case-Incident object.
CustomObjectTask: Task object.
CustomObjectChannel: Channel object.
CustomObservableCredential: Credential observable.
CustomObservableHostname: Hostname observable.
CustomObservableUserAgent: User-Agent observable.
CustomObservableBankAccount: Bank Account observable.
CustomObservableCryptocurrencyWallet: Cryptocurrency wallet observable.
CustomObservablePaymentCard: Payment card observable.
CustomObservablePhoneNumber: Phone number observable.
CustomObservableTrackingNumber: Tracking number observable.
CustomObservableText: Text observable.
CustomObservableMediaContent: Media-Content observable.
Capability: Represents a role capability on the OpenCTI platform
Role: Representation of a role in OpenCTI
Group: Representation of a Group in OpenCTI
User: Representation of a user on the OpenCTI platform
Settings: Represents the Settings object in OpenCTI

class pycti.AttackPattern(opencti)[source]

Main AttackPattern class for OpenCTI

Manages MITRE ATT&CK patterns and techniques in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the AttackPattern instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create an Attack Pattern object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the attack pattern is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Attack Pattern (required)
description (str) – (optional) description
aliases (list) – (optional) list of aliases
x_mitre_platforms (list) – (optional) list of MITRE platforms
x_mitre_permissions_required (list) – (optional) list of required permissions
x_mitre_detection (str) – (optional) detection guidance
x_mitre_id (str) – (optional) MITRE ATT&CK ID
killChainPhases (list) – (optional) list of kill chain phase IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Attack Pattern object

Return type:

dict or None

delete(**kwargs)[source]

Delete an Attack Pattern object.

Parameters:: id (str) – the id of the Attack Pattern to delete
Returns:: None

static generate_id(name, x_mitre_id=None)[source]

Generate a STIX ID for an Attack Pattern.

Parameters:

name (str) – The name of the attack pattern
x_mitre_id (str or None) – Optional MITRE ATT&CK ID

Returns:

STIX ID for the attack pattern

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from attack pattern data.

Parameters:: data (dict) – Dictionary containing ‘name’ and optionally ‘x_mitre_id’ keys
Returns:: STIX ID for the attack pattern
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Attack Pattern object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Attack Pattern object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Attack Pattern object

Return type:

dict or None

list(**kwargs)[source]

List Attack Pattern objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Attack Pattern objects

Return type:

list

read(**kwargs)[source]

Read an Attack Pattern object.

Parameters:

id (str) – the id of the Attack Pattern
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Attack Pattern object

Return type:

dict or None

class pycti.Campaign(opencti)[source]

Main Campaign class for OpenCTI

Manages threat campaigns in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Campaign instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Campaign object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the campaign is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Campaign (required)
description (str) – (optional) description
aliases (list) – (optional) list of aliases
first_seen (str) – (optional) first seen date
last_seen (str) – (optional) last seen date
objective (str) – (optional) objective of the campaign
objectOrganization (list) – (optional) list of organization IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Campaign object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Campaign.

Parameters:: name (str) – The name of the campaign
Returns:: STIX ID for the campaign
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from campaign data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the campaign
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Campaign object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Campaign object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Campaign object

Return type:

dict or None

list(**kwargs)[source]

List Campaign objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Campaign objects

Return type:

list

read(**kwargs)[source]

Read a Campaign object.

Parameters:

id (str) – the id of the Campaign
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Campaign object

Return type:

dict or None

class pycti.CaseIncident(opencti)[source]

Main CaseIncident class for OpenCTI

Manages incident response cases in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the CaseIncident instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Case Incident object (object_refs).

Parameters:

id (str) – the id of the Case Incident
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, False otherwise

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a case incident already contains a thing (Stix Object or Stix Relationship).

Parameters:

id (str) – the id of the Case Incident
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if contained, False otherwise

Return type:

bool or None

create(**kwargs)[source]

Create a Case Incident object

Parameters:

stix_id – (optional) the STIX ID
createdBy – (optional) the author ID
objects – (optional) list of STIX object IDs contained in the case
objectMarking – (optional) list of marking definition IDs
objectLabel – (optional) list of label IDs
externalReferences – (optional) list of external reference IDs
revoked – (optional) whether the case is revoked
confidence – (optional) confidence level (0-100)
lang – (optional) language
created – (optional) creation date
modified – (optional) modification date
name – the name of the Case Incident (required)
description – (optional) description
content – (optional) content
severity – (optional) severity level
priority – (optional) priority level
x_opencti_stix_ids – (optional) list of additional STIX IDs
objectAssignee – (optional) list of assignee IDs
objectParticipant – (optional) list of participant IDs
objectOrganization – (optional) list of organization IDs
response_types – (optional) list of response types
x_opencti_workflow_id – (optional) workflow ID
x_opencti_modified_at – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Case Incident object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Case Incident object.

Parameters:: id (str) – the id of the Case Incident to delete
Returns:: None

static generate_id(name, created)[source]

Generate a STIX ID for a Case Incident object.

Parameters:

name (str) – the name of the Case Incident
created (str or datetime.datetime) – the creation date of the Case Incident

Returns:

STIX ID for the Case Incident

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from Case Incident data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘created’ keys
Returns:: STIX ID for the Case Incident
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Case Incident object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Case Incident
name (str) – the name of the Case Incident
created (str) – the creation date of the Case Incident

Returns:

Case Incident object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Case Incident object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Case Incident
extras (dict) – additional parameters like created_by_id, object_marking_ids
update (bool) – whether to update existing object

Returns:

Case Incident object

Return type:

dict or None

list(**kwargs)[source]

List Case Incident objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of Case Incident objects

Return type:

list

read(**kwargs)[source]

Read a Case Incident object.

Parameters:

id (str) – the id of the Case Incident
filters (dict) – the filters to apply if no id provided

Returns:

Case Incident object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Case Incident object (object_refs).

Parameters:

id (str) – the id of the Case Incident
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, False otherwise

Return type:

bool

class pycti.CaseRfi(opencti)[source]

Main CaseRfi (Request for Information) class for OpenCTI

Manages RFI cases in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the CaseRfi instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Case RFI object (object_refs).

Parameters:

id (str) – the id of the Case RFI
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating success

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a Case RFI already contains a STIX Object or Relationship.

Parameters:

id (str) – the id of the Case RFI
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating if the entity is contained

Return type:

bool or None

create(**kwargs)[source]

Create a Case RFI (Request for Information) object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objects (list) – (optional) list of STIX object IDs contained in the case
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
objectAssignee (list) – (optional) list of assignee IDs
objectParticipant (list) – (optional) list of participant IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the case is revoked
severity (str) – (optional) severity level
priority (str) – (optional) priority level
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Case RFI (required)
content (str) – (optional) content
description (str) – (optional) description
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
information_types (list) – (optional) list of information types
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Case RFI object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Case RFI object.

Parameters:: id (str) – the id of the Case RFI to delete
Returns:: None

static generate_id(name, created)[source]

Generate a STIX ID for a Case RFI object.

Parameters:

name (str) – the name of the Case RFI
created (str or datetime.datetime) – the creation date of the Case RFI

Returns:

STIX ID for the Case RFI

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from Case RFI data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘created’ keys
Returns:: STIX ID for the Case RFI
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Case RFI object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Case RFI
name (str) – the name of the Case RFI
created (str) – the creation date of the Case RFI

Returns:

Case RFI object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Case RFI object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Case RFI object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Case RFI object

Return type:

dict or None

list(**kwargs)[source]

List Case RFI objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Case RFI objects

Return type:

list

read(**kwargs)[source]

Read a Case RFI object.

Parameters:

id (str) – the id of the Case RFI
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Case RFI object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Case RFI object (object_refs).

Parameters:

id (str) – the id of the Case RFI
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating success

Return type:

bool

class pycti.CaseRft(opencti)[source]

Main CaseRft (Request for Takedown) class for OpenCTI

Manages RFT cases in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the CaseRft instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Case RFT object (object_refs).

Parameters:

id (str) – the id of the Case RFT
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating success

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a Case RFT already contains a STIX Object or Relationship.

Parameters:

id (str) – the id of the Case RFT
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating if the entity is contained

Return type:

bool or None

create(**kwargs)[source]

Create a Case RFT (Request for Takedown) object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objects (list) – (optional) list of STIX object IDs contained in the case
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
objectAssignee (list) – (optional) list of assignee IDs
objectParticipant (list) – (optional) list of participant IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the case is revoked
severity (str) – (optional) severity level
priority (str) – (optional) priority level
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
content (str) – (optional) content
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Case RFT (required)
description (str) – (optional) description
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
takedown_types (list) – (optional) list of takedown types
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Case RFT object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Case RFT object.

Parameters:: id (str) – the id of the Case RFT to delete
Returns:: None

static generate_id(name, created)[source]

Generate a STIX ID for a Case RFT object.

Parameters:

name (str) – the name of the Case RFT
created (str or datetime.datetime) – the creation date of the Case RFT

Returns:

STIX ID for the Case RFT

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from Case RFT data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘created’ keys
Returns:: STIX ID for the Case RFT
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Case RFT object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Case RFT
name (str) – the name of the Case RFT
created (str) – the creation date
customAttributes (str) – custom attributes to return

Returns:

Case RFT object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Case RFT object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Case RFT object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Case RFT object

Return type:

dict or None

list(**kwargs)[source]

List Case RFT objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Case RFT objects

Return type:

list

read(**kwargs)[source]

Read a Case RFT object.

Parameters:

id (str) – the id of the Case RFT
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Case RFT object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Case RFT object (object_refs).

Parameters:

id (str) – the id of the Case RFT
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean indicating success

Return type:

bool

class pycti.Channel(opencti)[source]

Main Channel class for OpenCTI

Manages communication channels used by threat actors in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Channel instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Channel object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the channel is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Channel (required)
description (str) – (optional) description
aliases (list) – (optional) list of aliases
channel_types (list) – (optional) list of channel types
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Channel object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Channel.

Parameters:: name (str) – the name of the Channel
Returns:: STIX ID for the Channel
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from Channel data.

Parameters:: data (dict) – Dictionary containing a ‘name’ key
Returns:: STIX ID for the Channel
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Channel object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Channel object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Channel object

Return type:

dict or None

list(**kwargs)[source]

List Channel objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Channel objects

Return type:

list

read(**kwargs)[source]

Read a Channel object.

Parameters:

id (str) – the id of the Channel
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Channel object

Return type:

dict or None

class pycti.Task(opencti)[source]

Main Task class for OpenCTI

Manages tasks and to-do items in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Task instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Task object (object_refs).

Parameters:

id (str) – the id of the Task
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, None if parameters are missing

Return type:

bool or None

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a task already contains a thing (Stix Object or Stix Relationship).

Parameters:

id (str) – the id of the Task
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if the task contains the entity, False otherwise

Return type:

bool or None

create(**kwargs)[source]

Create a Task object.

Parameters:

name (str) – the name of the Task
description (str) – the description of the Task
due_date (str) – the due date of the Task
createdBy (str) – the creator of the Task
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Task object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Task object.

Parameters:: id (str) – the id of the Task to delete
Returns:: None

static generate_id(name, created)[source]

Generate a STIX ID for a Task object.

Parameters:

name (str) – the name of the Task
created (str or datetime.datetime) – the creation date of the Task

Returns:

STIX ID for the Task

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from Task data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘created’ keys
Returns:: STIX ID for the Task
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Task object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Task
name (str) – the name of the Task
created (str) – the creation date of the Task

Returns:

Task object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Task object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Task
extras (dict) – additional parameters like created_by_id, object_marking_ids
update (bool) – whether to update existing object

Returns:

Task object

Return type:

dict or None

list(**kwargs)[source]

List Task objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of Task objects

Return type:

list

read(**kwargs)[source]

Read a Task object.

Parameters:

id (str) – the id of the Task
filters (dict) – the filters to apply if no id provided

Returns:

Task object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Task object (object_refs).

Parameters:

id (str) – the id of the Task
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, False otherwise

Return type:

bool

update_field(**kwargs)[source]

Update a field of a Task object.

Parameters:

id (str) – the id of the Task
input (list) – the input containing field(s) to update

Returns:

Task object

Return type:

dict or None

class pycti.ConnectorType(*values)[source]

Enumeration of OpenCTI connector types.

Each connector type defines a specific data flow pattern:

EXTERNAL_IMPORT: Imports data from remote sources into OpenCTI as STIX2
INTERNAL_IMPORT_FILE: Converts files from OpenCTI file system to STIX2
INTERNAL_ENRICHMENT: Enriches existing STIX2 data with additional information
INTERNAL_ANALYSIS: Analyzes files or STIX2 data and produces file output
INTERNAL_EXPORT_FILE: Exports STIX2 data to files in OpenCTI file system
STREAM: Reads the event stream and performs custom actions

Scope definition varies by type:

EXTERNAL_IMPORT: None (imports everything)
INTERNAL_IMPORT_FILE: MIME types to support (e.g., application/json)
INTERNAL_ENRICHMENT: Entity types to support (e.g., Report, Hash)
INTERNAL_EXPORT_FILE: MIME types to generate (e.g., application/pdf)

Inheritance

class pycti.CourseOfAction(opencti)[source]

Main CourseOfAction class for OpenCTI

Manages courses of action (mitigations) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the CourseOfAction instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Course of Action object.

Parameters:

name (str) – the name of the Course of Action (required)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the course of action is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
description (str) – (optional) description
x_opencti_aliases (list) – (optional) list of aliases
x_mitre_id (str) – (optional) MITRE ATT&CK ID
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Course of Action object

Return type:

dict or None

static generate_id(name, x_mitre_id=None)[source]

Generate a STIX ID for a Course of Action.

Parameters:

name (str) – The name of the course of action
x_mitre_id (str or None) – Optional MITRE ATT&CK ID

Returns:

STIX ID for the course of action

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from course of action data.

Parameters:: data (dict) – Dictionary containing ‘name’ and optionally ‘x_mitre_id’ keys
Returns:: STIX ID for the course of action
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Course of Action object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Course of Action object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Course of Action object

Return type:

dict or None

list(**kwargs)[source]

List Course of Action objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Course of Action objects

Return type:

list

read(**kwargs)[source]

Read a Course of Action object.

Parameters:

id (str) – the id of the Course of Action
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Course of Action object

Return type:

dict or None

class pycti.DataComponent(opencti)[source]

Main DataComponent class for OpenCTI

Manages MITRE ATT&CK data components in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the DataComponent instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Data Component object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the data component is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Data Component (required)
description (str) – (optional) description
dataSource (str) – (optional) the data source ID
aliases (list) – (optional) list of aliases
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Data Component object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Data Component.

Parameters:: name (str) – the name of the Data Component
Returns:: STIX ID for the Data Component
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from Data Component data.

Parameters:: data (dict) – Dictionary containing a ‘name’ key
Returns:: STIX ID for the Data Component
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Data Component object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Data Component object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Data Component object

Return type:

dict or None

list(**kwargs)[source]

List Data Component objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Data Component objects

Return type:

list

process_multiple_fields(data)[source]

Process Data Component fields to extract related data source ID.

Parameters:: data (dict) – the Data Component data dictionary
Returns:: Processed data with dataSourceId field added
Return type:: dict

read(**kwargs)[source]

Read a Data Component object.

Parameters:

id (str) – the id of the Data Component
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Data Component object

Return type:

dict or None

class pycti.DataSource(opencti)[source]

Main DataSource class for OpenCTI

Manages MITRE ATT&CK data sources in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the DataSource instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Data Source object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the data source is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
name (str) – the name of the Data Source (required)
description (str) – (optional) description
aliases (list) – (optional) list of aliases
platforms (list) – (optional) list of platforms
collection_layers (list) – (optional) list of collection layers
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Data Source object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Data Source.

Parameters:: name (str) – the name of the Data Source
Returns:: STIX ID for the Data Source
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from Data Source data.

Parameters:: data (dict) – Dictionary containing a ‘name’ key
Returns:: STIX ID for the Data Source
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Data Source object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Data Source object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Data Source object

Return type:

dict or None

list(**kwargs)[source]

List Data Source objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Data Source objects

Return type:

list

read(**kwargs)[source]

Read a Data Source object.

Parameters:

id (str) – the id of the Data Source
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Data Source object

Return type:

dict or None

class pycti.ExternalReference(opencti)[source]

Main ExternalReference class for OpenCTI

Manages external references and citations in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the ExternalReference instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_file(**kwargs)[source]

Upload a file in this External-Reference.

Parameters:

id (str) – the External-Reference id
file_name (str) – the name of the file to upload
data (bytes or None) – the file data (if None, reads from file_name path)
version (datetime) – (optional) the file version date
fileMarkings (list) – (optional) list of marking definition IDs for the file
mime_type (str) – (optional) MIME type (default: text/plain)
no_trigger_import (bool) – (optional) don’t trigger import (default: False)
embedded (bool) – (optional) embed the file (default: False)

Returns:

File upload result

Return type:

dict or None

create(**kwargs)[source]

Create an External Reference object.

Parameters:

stix_id (str) – (optional) the STIX ID
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
source_name (str) – the source name of the External Reference (required if no url)
url (str) – (optional) the URL of the external reference (required if no source_name)
external_id (str) – (optional) the external ID
description (str) – (optional) description
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

External Reference object

Return type:

dict or None

delete(id)[source]

Delete an External-Reference object.

Parameters:: id (str) – the id of the External-Reference to delete
Returns:: None

static generate_id(url=None, source_name=None, external_id=None)[source]

Generate a STIX ID for an External Reference.

Parameters:

url (str or None) – The URL of the external reference
source_name (str or None) – The source name
external_id (str or None) – The external ID

Returns:

STIX ID for the external reference, or None if insufficient parameters

Return type:

str or None

static generate_id_from_data(data)[source]

Generate a STIX ID from external reference data.

Parameters:: data (dict) – Dictionary containing ‘url’, ‘source_name’, or ‘external_id’ keys
Returns:: STIX ID for the external reference
Return type:: str or None

list(**kwargs)[source]

List External-Reference objects.

Parameters:

filters (dict) – the filters to apply
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of External-Reference objects

Return type:

list

list_files(**kwargs)[source]

List files attached to an External-Reference.

Parameters:: id (str) – the id of the External-Reference
Returns:: List of files
Return type:: list

read(**kwargs)[source]

Read an External-Reference object.

Parameters:

id (str) – the id of the External-Reference
filters (dict) – the filters to apply if no id provided

Returns:

External-Reference object

Return type:

dict or None

update_field(**kwargs)[source]

Update an External Reference object field.

Parameters:

id (str) – the External Reference id
input (list) – the input of the field

Returns:

The updated External Reference object

Return type:

dict or None

class pycti.Feedback(opencti)[source]

Main Feedback class for OpenCTI

Manages feedback and analyst assessments in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Feedback instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Feedback object (object_refs).

Parameters:

id (str) – the id of the Feedback
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, False otherwise

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a feedback already contains a thing (Stix Object or Stix Relationship).

Parameters:

id (str) – the id of the Feedback
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if contained, False otherwise

Return type:

bool or None

create(**kwargs)[source]

Create a Feedback object.

Parameters:

stix_id (str) – the STIX ID (optional)
createdBy (str) – the author ID (optional)
objects (list) – list of STIX object IDs (optional)
objectMarking (list) – list of marking definition IDs (optional)
objectLabel (list) – list of label IDs (optional)
externalReferences (list) – list of external reference IDs (optional)
revoked (bool) – whether the feedback is revoked (optional)
confidence (int) – confidence level 0-100 (optional)
lang (str) – language (optional)
created (str) – creation date (optional)
modified (str) – modification date (optional)
name (str) – the name of the Feedback (required)
description (str) – description (optional)
rating (int) – rating value (optional)
x_opencti_stix_ids (list) – list of additional STIX IDs (optional)
objectOrganization (list) – list of organization IDs (optional)
x_opencti_workflow_id (str) – workflow ID (optional)
x_opencti_modified_at (str) – custom modification date (optional)
update (bool) – whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Feedback object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Feedback object.

Parameters:: id (str) – the id of the Feedback to delete
Returns:: None

static generate_id(name)[source]

Generate a STIX ID for a Feedback object.

Parameters:: name (str) – the name of the Feedback
Returns:: STIX ID for the Feedback
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from Feedback data.

Parameters:: data (dict) – Dictionary containing a ‘name’ key
Returns:: STIX ID for the Feedback
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Feedback object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Feedback
name (str) – the name of the Feedback
created (str) – the creation date of the Feedback

Returns:

Feedback object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Feedback object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Feedback object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Feedback object

Return type:

dict or None

list(**kwargs)[source]

List Feedback objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of Feedback objects

Return type:

list

read(**kwargs)[source]

Read a Feedback object.

Parameters:

id (str) – the id of the Feedback
filters (dict) – the filters to apply if no id provided

Returns:

Feedback object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Feedback object (object_refs).

Parameters:

id (str) – the id of the Feedback
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

True if successful, False otherwise

Return type:

bool

update_field(**kwargs)[source]

Update a field of a Feedback object.

Parameters:

id (str) – the id of the Feedback
input (list) – the input containing field(s) to update

Returns:

Feedback object

Return type:

dict or None

class pycti.Grouping(opencti)[source]

Main Grouping class for OpenCTI

Manages STIX grouping objects in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Grouping instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Grouping object (object_refs).

Parameters:

id (str) – the id of the Grouping
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a grouping already contains a thing (Stix Object or Stix Relationship).

Parameters:

id (str) – the id of the Grouping
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

create(**kwargs)[source]

Create a Grouping object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objects (list) – (optional) list of STIX object IDs
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the grouping is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
name (str) – the name of the Grouping (required)
context (str) – the grouping context (required)
content (str) – (optional) content
description (str) – (optional) description
x_opencti_aliases (list) – (optional) list of aliases
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (datetime) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Grouping object

Return type:

dict or None

static generate_id(name, context, created=None)[source]

Generate a STIX ID for a Grouping.

Parameters:

name (str) – The name of the grouping
context (str) – The grouping context
created (datetime or str or None) – Optional creation date

Returns:

STIX ID for the grouping

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from grouping data.

Parameters:: data (dict) – Dictionary containing ‘name’, ‘context’, and ‘created’ keys
Returns:: STIX ID for the grouping
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Grouping object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Grouping
name (str) – the name of the Grouping
context (str) – the context of the Grouping
customAttributes (list) – custom attributes to return

Returns:

Grouping object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Grouping object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Grouping
extras (dict) – extra dict
update (bool) – set the update flag on import

Returns:

Grouping object

Return type:

dict or None

list(**kwargs)[source]

List Grouping objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Grouping objects

Return type:

list

read(**kwargs)[source]

Read a Grouping object.

Parameters:

id (str) – the id of the Grouping
filters (dict) – the filters to apply if no id provided
customAttributes (list) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Grouping object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Grouping object (object_refs).

Parameters:

id (str) – the id of the Grouping
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

class pycti.Identity(opencti)[source]

Main Identity class for OpenCTI

Manages individual, organization, and system identities in OpenCTI.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Identity instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create an Identity object.

Parameters:

type – the type of identity (Organization, Individual, System, etc.) (required)
stix_id – (optional) the STIX ID
createdBy – (optional) the author ID
objectMarking – (optional) list of marking definition IDs
objectLabel – (optional) list of label IDs
externalReferences – (optional) list of external reference IDs
revoked – (optional) whether the identity is revoked
confidence – (optional) confidence level (0-100)
lang – (optional) language
created – (optional) creation date
modified – (optional) modification date
name – the name of the Identity (required)
description – (optional) description
contact_information – (optional) contact information
roles – (optional) list of roles
x_opencti_aliases – (optional) list of aliases
security_platform_type – (optional) type of security platform
x_opencti_organization_type – (optional) organization type
x_opencti_reliability – (optional) reliability level
x_opencti_score – (optional) score
x_opencti_firstname – (optional) first name for individuals
x_opencti_lastname – (optional) last name for individuals
x_opencti_stix_ids – (optional) list of additional STIX IDs
objectOrganization – (optional) list of organization IDs
x_opencti_workflow_id – (optional) workflow ID
x_opencti_modified_at – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Identity object

Return type:

dict or None

static generate_id(name, identity_class)[source]

Generate a STIX ID for an Identity.

Parameters:

name (str) – The name of the identity
identity_class (str) – The class of the identity (individual, group, organization, etc.)

Returns:

STIX ID for the identity

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from identity data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘identity_class’ keys
Returns:: STIX ID for the identity
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Identity object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Identity object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Identity object

Return type:

dict or None

list(**kwargs)[source]

List Identity objects.

Parameters:

types (list) – the list of types
filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Identity objects

Return type:

list

read(**kwargs)[source]

Read an Identity object.

Parameters:

id (str) – the id of the Identity
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Identity object

Return type:

dict or None

class pycti.Incident(opencti)[source]

Main Incident class for OpenCTI

Manages security incidents in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Incident instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create an Incident object.

Parameters:

name (str) – the name of the Incident (required)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the incident is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
description (str) – (optional) description
aliases (list) – (optional) list of aliases
first_seen (str) – (optional) first seen date
last_seen (str) – (optional) last seen date
objective (str) – (optional) objective of the incident
incident_type (str) – (optional) type of incident
severity (str) – (optional) severity level
source (str) – (optional) source of the incident
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Incident object

Return type:

dict or None

static generate_id(name, created)[source]

Generate a STIX ID for an Incident.

Parameters:

name (str) – The name of the incident
created (str or datetime.datetime) – The creation date of the incident

Returns:

STIX ID for the incident

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from incident data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘created’ keys
Returns:: STIX ID for the incident
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Incident object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Incident object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Incident object

Return type:

dict or None

list(**kwargs)[source]

List Incident objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Incident objects

Return type:

list

read(**kwargs)[source]

Read an Incident object.

Parameters:

id (str) – the id of the Incident
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Incident object

Return type:

dict or None

class pycti.Indicator(opencti)[source]

Main Indicator class for OpenCTI

Manages threat indicators and detection patterns in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Indicator instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_cyber_observable(**kwargs)[source]

Add a Stix-Cyber-Observable object to Indicator object (based-on).

Parameters:

id (str) – the id of the Indicator
indicator (dict) – Indicator object
stix_cyber_observable_id (str) – the id of the Stix-Observable

Returns:

True if there has been no import error

Return type:

bool

create(**kwargs)[source]

Create an Indicator object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the indicator is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
pattern_type (str) – the pattern type (required)
pattern_version (str) – (optional) the pattern version
pattern (str) – the indicator pattern (required)
name (str) – the name of the Indicator (defaults to pattern)
description (str) – (optional) description
indicator_types (list) – (optional) list of indicator types
valid_from (str) – (optional) valid from date
valid_until (str) – (optional) valid until date
x_opencti_score (int) – (optional) score (default: 50)
x_opencti_detection (bool) – (optional) detection flag (default: False)
x_opencti_main_observable_type (str) – the main observable type (required)
x_mitre_platforms (list) – (optional) list of MITRE platforms
killChainPhases (list) – (optional) list of kill chain phase IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
x_opencti_create_observables (bool) – (optional) create observables (default: False)
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Indicator object

Return type:

dict or None

static generate_id(pattern)[source]

Generate a STIX ID for an Indicator.

Parameters:: pattern (str) – The STIX pattern
Returns:: STIX ID for the indicator
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from indicator data.

Parameters:: data (dict) – Dictionary containing ‘pattern’ key
Returns:: STIX ID for the indicator
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Indicator object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Indicator
extras (dict) – extra dict
update (bool) – set the update flag on import

Returns:

Indicator object

Return type:

dict or None

list(**kwargs)[source]

List Indicator objects.

Parameters:

filters (dict) – (optional) the filters to apply
search (str) – (optional) a search keyword to apply for the listing
first (int) – (optional) return the first n rows from the after ID or the beginning if not set
after (str) – (optional) OpenCTI object ID of the first row for pagination
orderBy (str) – (optional) the field to order the response on
orderMode (str) – (optional) either “asc” or “desc”
customAttributes (str) – (optional) list of attributes keys to return
getAll (bool) – (optional) switch to return all entries (be careful to use this without any other filters)
withPagination (bool) – (optional) switch to use pagination
withFiles (bool) – (optional) include files in response
toStix (bool) – (optional) get in STIX format

Returns:

List of Indicators

Return type:

list

read(**kwargs)[source]

Read an Indicator object.

Read can be either used with a known OpenCTI entity id or by using a valid filter to search and return a single Indicator entity or None.

Note: either id or filters is required.

Parameters:

id (str) – the id of the Indicator
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Indicator object

Return type:

dict or None

update_field(**kwargs)[source]

Update an Indicator object field.

Parameters:

id (str) – the Indicator id
input (list) – the input of the field

Returns:

Updated indicator object

Return type:

dict or None

class pycti.Infrastructure(opencti)[source]

Main Infrastructure class for OpenCTI

Manages threat infrastructure (servers, domains, etc.) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Infrastructure instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create an Infrastructure object.

Parameters:

name (str) – the name of the Infrastructure (required)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the infrastructure is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
description (str) – (optional) description
aliases (list) – (optional) list of aliases
infrastructure_types (list) – (optional) list of infrastructure types
first_seen (str) – (optional) first seen date
last_seen (str) – (optional) last seen date
killChainPhases (list) – (optional) list of kill chain phase IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Infrastructure object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for an Infrastructure.

Parameters:: name (str) – The name of the infrastructure
Returns:: STIX ID for the infrastructure
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from infrastructure data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the infrastructure
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Infrastructure object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Infrastructure object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Infrastructure object

Return type:

dict or None

list(**kwargs)[source]

List Infrastructure objects.

Parameters:

filters (dict) – (optional) the filters to apply
search (str) – (optional) a search keyword to apply for the listing
first (int) – (optional) return the first n rows from the after ID or the beginning if not set
after (str) – (optional) OpenCTI object ID of the first row for pagination
orderBy (str) – (optional) the field to order the response on
orderMode (str) – (optional) either “asc” or “desc”
customAttributes (str) – (optional) list of attributes keys to return
getAll (bool) – (optional) switch to return all entries (be careful to use this without any other filters)
withPagination (bool) – (optional) switch to use pagination
withFiles (bool) – (optional) include files in response

Returns:

List of Infrastructure objects

Return type:

list

read(**kwargs)[source]

Read an Infrastructure object.

Read can be either used with a known OpenCTI entity id or by using a valid filter to search and return a single Infrastructure entity or None.

Note: either id or filters is required.

Parameters:

id (str) – the id of the Infrastructure
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Infrastructure object

Return type:

dict or None

class pycti.IntrusionSet(opencti)[source]

Main IntrusionSet class for OpenCTI

Manages intrusion sets (APT groups) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the IntrusionSet instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create an Intrusion Set object.

Parameters:

stix_id (str) – (optional) the STIX ID
name (str) – the name of the Intrusion Set (required)
description (str) – description of the intrusion set
aliases (list) – list of aliases
first_seen (str) – first seen date
last_seen (str) – last seen date
goals (list) – goals of the intrusion set
resource_level (str) – resource level
primary_motivation (str) – primary motivation
secondary_motivations (list) – secondary motivations
createdBy (str) – creator identity ID
objectMarking (list) – marking definition IDs
objectLabel (list) – label IDs
externalReferences (list) – external reference IDs
objectOrganization (list) – organization IDs
revoked (bool) – whether the intrusion set is revoked
confidence (int) – confidence level (0-100)
lang (str) – language
created (str) – creation date
modified (str) – modification date
x_opencti_stix_ids (list) – additional STIX IDs
x_opencti_workflow_id (str) – workflow ID
x_opencti_modified_at (str) – custom modification date
update (bool) – whether to update existing intrusion set
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Intrusion Set object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for an Intrusion Set.

Parameters:: name (str) – The name of the intrusion set
Returns:: STIX ID for the intrusion set
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from intrusion set data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the intrusion set
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Intrusion Set object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Intrusion Set object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Intrusion Set object

Return type:

dict or None

list(**kwargs)[source]

List Intrusion Set objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Intrusion Set objects

Return type:

list

read(**kwargs)[source]

Read an Intrusion Set object.

Parameters:

id (str) – the id of the Intrusion Set
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Intrusion Set object

Return type:

dict or None

class pycti.KillChainPhase(opencti)[source]

Main KillChainPhase class for OpenCTI

Manages kill chain phases (ATT&CK tactics) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the KillChainPhase instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Kill-Chain-Phase object.

Parameters:

stix_id (str) – (optional) the STIX ID
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
kill_chain_name (str) – the kill chain name (required)
phase_name (str) – the phase name (required)
x_opencti_order (int) – (optional) order (default: 0)
update (bool) – (optional) whether to update if exists (default: False)

Returns:

Kill-Chain-Phase object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Kill-Chain-Phase object.

Parameters:: id (str) – the id of the Kill-Chain-Phase to delete
Returns:: None

static generate_id(phase_name, kill_chain_name)[source]

Generate a STIX ID for a Kill Chain Phase.

Parameters:

phase_name (str) – The phase name
kill_chain_name (str) – The kill chain name

Returns:

STIX ID for the kill chain phase

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from kill chain phase data.

Parameters:: data (dict) – Dictionary containing ‘phase_name’ and ‘kill_chain_name’ keys
Returns:: STIX ID for the kill chain phase
Return type:: str

list(**kwargs)[source]

List Kill-Chain-Phase objects.

Parameters:

filters (dict) – the filters to apply
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
withPagination (bool) – whether to include pagination info

Returns:

List of Kill-Chain-Phase objects

Return type:

list

read(**kwargs)[source]

Read a Kill-Chain-Phase object.

Parameters:

id (str) – the id of the Kill-Chain-Phase
filters (dict) – the filters to apply if no id provided

Returns:

Kill-Chain-Phase object

Return type:

dict or None

update_field(**kwargs)[source]

Update a Kill Chain Phase object field.

Parameters:

id (str) – the Kill Chain Phase id
input (list) – the input of the field

Returns:

The updated Kill Chain Phase object

Return type:

dict or None

class pycti.Label(opencti)[source]

Main Label class for OpenCTI

Manages labels and tags in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Label instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Label object.

Parameters:

stix_id (str) – (optional) the STIX ID
value (str) – the label value (required)
color (str) – (optional) the label color
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
update (bool) – (optional) whether to update if exists (default: False)

Returns:

Label object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Label object.

Parameters:: id (str) – the id of the Label to delete
Returns:: None

static generate_id(value)[source]

Generate a STIX ID for a Label.

Parameters:: value (str) – The label value
Returns:: STIX ID for the label
Return type:: str

list(**kwargs)[source]

List Label objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info

Returns:

List of Label objects

Return type:

list

read(**kwargs)[source]

Read a Label object.

Parameters:

id (str) – the id of the Label
filters (dict) – the filters to apply if no id provided

Returns:

Label object

Return type:

dict or None

read_or_create_unchecked(**kwargs)[source]

Read or create a Label.

If the user has no rights to create the label, return None.

Parameters:: value (str) – the label value
Returns:: The available or created Label object
Return type:: dict or None

update_field(**kwargs)[source]

Update a Label object field.

Parameters:

id (str) – the Label id
input (list) – the input of the field

Returns:

The updated Label object

Return type:

dict or None

class pycti.Location(opencti)[source]

Main Location class for OpenCTI

Manages geographic locations (countries, cities, regions) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Location instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Location object.

Parameters:

type (str) – the type of location (Country, City, Region, Position)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the location is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
name (str) – the name of the Location (required)
description (str) – (optional) description
latitude (float) – (optional) latitude coordinate
longitude (float) – (optional) longitude coordinate
precision (float) – (optional) precision in meters
x_opencti_aliases (list) – (optional) list of aliases
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (datetime) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Location object

Return type:

dict or None

static generate_id(name, x_opencti_location_type, latitude=None, longitude=None)[source]

Generate a STIX ID for a Location.

Parameters:

name (str) – The name of the location
x_opencti_location_type (str) – The type of location (Country, City, Region, Position)
latitude (float or None) – Optional latitude coordinate
longitude (float or None) – Optional longitude coordinate

Returns:

STIX ID for the location

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from location data.

Parameters:: data (dict) – Dictionary containing ‘name’, ‘x_opencti_location_type’, and optionally ‘latitude’/’longitude’
Returns:: STIX ID for the location
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Location object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Location
extras (dict) – extra dict
update (bool) – set the update flag on import

Returns:

Location object

Return type:

dict or None

list(**kwargs)[source]

List Location objects.

Parameters:

types (list) – the list of location types to filter by
filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Location objects

Return type:

list

read(**kwargs)[source]

Read a Location object.

Parameters:

id (str) – the id of the Location
filters (dict) – the filters to apply if no id provided
customAttributes (list) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Location object

Return type:

dict or None

class pycti.Malware(opencti)[source]

Main Malware class for OpenCTI

Manages malware families and variants in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Malware instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Malware object.

Parameters:

stix_id (str) – (optional) the STIX ID
name (str) – the name of the Malware (required)
description (str) – description of the malware
aliases (list) – list of aliases
malware_types (list) – types of malware
is_family (bool) – whether this is a malware family
first_seen (str) – first seen date
last_seen (str) – last seen date
architecture_execution_envs (list) – execution environments
implementation_languages (list) – implementation languages
capabilities (list) – malware capabilities
killChainPhases (list) – kill chain phases
samples (list) – malware samples
createdBy (str) – creator identity ID
objectMarking (list) – marking definition IDs
objectLabel (list) – label IDs
externalReferences (list) – external reference IDs
objectOrganization (list) – organization IDs
revoked (bool) – whether the malware is revoked
confidence (int) – confidence level (0-100)
lang (str) – language
created (str) – creation date
modified (str) – modification date
x_opencti_stix_ids (list) – additional STIX IDs
x_opencti_workflow_id (str) – workflow ID
x_opencti_modified_at (str) – custom modification date
update (bool) – whether to update existing malware
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Malware object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Malware.

Parameters:: name (str) – The name of the malware
Returns:: STIX ID for the malware
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from malware data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the malware
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Malware object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Malware object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Malware object

Return type:

dict or None

list(**kwargs)[source]

List Malware objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Malware objects

Return type:

list

read(**kwargs)[source]

Read a Malware object.

Parameters:

id (str) – the id of the Malware
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Malware object

Return type:

dict or None

class pycti.MalwareAnalysis(opencti)[source]

Main MalwareAnalysis class for OpenCTI

Manages malware analysis reports and results in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the MalwareAnalysis instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Malware analysis object.

Parameters:

product (str) – the product that performed the analysis (required)
result_name (str) – the result name of the analysis (required)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the malware analysis is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
result (str) – (optional) result of the analysis
submitted (str) – (optional) submission date
analysis_started (str) – (optional) analysis start date
analysis_ended (str) – (optional) analysis end date
version (str) – (optional) version of the analysis
configuration_version (str) – (optional) configuration version
analysis_engine_version (str) – (optional) analysis engine version
analysis_definition_version (str) – (optional) analysis definition version
modules (list) – (optional) list of analysis modules
hostVm (str) – (optional) host VM reference ID
operatingSystem (str) – (optional) operating system reference ID
installedSoftware (list) – (optional) list of installed software reference IDs
sample (str) – (optional) sample reference ID
analysisSco (list) – (optional) list of analysis SCO reference IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Malware analysis object

Return type:

dict or None

static generate_id(result_name, product=None, submitted=None)[source]

Generate a STIX ID for a Malware Analysis.

Parameters:

result_name (str) – the result name of the analysis
product (str) – the product that performed the analysis (optional)
submitted (str) – the submission date (optional)

Returns:

STIX ID for the Malware Analysis

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from Malware Analysis data.

Parameters:: data (dict) – Dictionary containing ‘result_name’, ‘product’, and optionally ‘submitted’ keys
Returns:: STIX ID for the Malware Analysis
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Malware analysis object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Malware analysis
extras (dict) – additional parameters like created_by_id, object_marking_ids
update (bool) – whether to update existing object

Returns:

Malware analysis object

Return type:

dict or None

list(**kwargs)[source]

List Malware analysis objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of MalwareAnalysis objects

Return type:

list

read(**kwargs)[source]

Read a Malware analysis object.

Parameters:

id (str) – the id of the Malware analysis
filters (dict) – the filters to apply if no id provided

Returns:

Malware analysis object

Return type:

dict or None

class pycti.MarkingDefinition(opencti)[source]

Main MarkingDefinition class for OpenCTI

Manages marking definitions (TLP, statements) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the MarkingDefinition instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Marking-Definition object.

Parameters:

stix_id (str) – (optional) the STIX ID
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
definition_type (str) – the definition type (required)
definition (str) – the definition value (required)
x_opencti_order (int) – (optional) order (default: 0)
x_opencti_color (str) – (optional) color
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
update (bool) – (optional) whether to update if exists (default: False)

Returns:

Marking-Definition object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Marking-Definition object.

Parameters:: id (str) – the id of the Marking-Definition to delete
Returns:: None

static generate_id(definition_type, definition)[source]

Generate a STIX ID for a Marking Definition.

Parameters:

definition_type (str) – The type of marking (TLP, statement, etc.)
definition (str) – The definition value

Returns:

STIX ID for the marking definition

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from marking definition data.

Parameters:: data (dict) – Dictionary containing ‘definition_type’ and ‘definition’ keys
Returns:: STIX ID for the marking definition
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Marking Definition object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Marking Definition
update (bool) – set the update flag on import

Returns:

Marking Definition object

Return type:

dict or None

list(**kwargs)[source]

List Marking-Definition objects.

Parameters:

filters (dict) – the filters to apply
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
withPagination (bool) – whether to include pagination info

Returns:

List of Marking-Definition objects

Return type:

list

read(**kwargs)[source]

Read a Marking-Definition object.

Parameters:

id (str) – the id of the Marking-Definition
filters (dict) – the filters to apply if no id provided

Returns:

Marking-Definition object

Return type:

dict or None

update_field(**kwargs)[source]

Update a Marking Definition object field.

Parameters:

id (str) – the Marking Definition id
input (list) – the input of the field

Returns:

The updated Marking Definition object

Return type:

dict or None

class pycti.Note(opencti)[source]

Main Note class for OpenCTI

Manages notes and annotations in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Note instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Note object (object_refs).

Parameters:

id (str) – the id of the Note
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a note already contains a STIX entity.

Parameters:

id (str) – the id of the Note
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

create(**kwargs)[source]

Create a Note object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objects (list) – (optional) list of STIX object IDs
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the note is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
abstract (str) – (optional) abstract summary
content (str) – the content of the Note (required)
authors (list) – (optional) list of authors
note_types (list) – (optional) list of note types
likelihood (int) – (optional) likelihood value
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (datetime) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Note object

Return type:

dict or None

static generate_id(created, content, abstract=None)[source]

Generate a STIX ID for a Note.

Parameters:

created (datetime or str or None) – The creation date of the note
content (str) – The content of the note (required)
abstract (str or None) – A brief summary of the note content

Returns:

STIX ID for the note

Return type:

str

Raises:

ValueError – If content is None

static generate_id_from_data(data)[source]

Generate a STIX ID from note data.

Parameters:: data (dict) – Dictionary containing ‘content’ and optionally ‘created’ and ‘attribute_abstract’ keys
Returns:: STIX ID for the note
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Note object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Note
extras (dict) – extra dict
update (bool) – set the update flag on import

Returns:

Note object

Return type:

dict or None

list(**kwargs)[source]

List Note objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Note objects

Return type:

list

read(**kwargs)[source]

Read a Note object.

Parameters:

id (str) – the id of the Note
filters (dict) – the filters to apply if no id provided
customAttributes (list) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Note object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Note object (object_refs).

Parameters:

id (str) – the id of the Note
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

class pycti.ObservedData(opencti)[source]

Main ObservedData class for OpenCTI

Manages observed data and raw intelligence in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the ObservedData instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Core-Object or stix_relationship to ObservedData object (object).

Parameters:

id (str) – the id of the ObservedData
stixObjectOrStixRelationshipId (str) – the id of the Stix-Core-Object or stix_relationship

Returns:

True if successful, False otherwise

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if an observedData already contains a STIX entity.

Parameters:

id (str) – the id of the ObservedData
stixObjectOrStixRelationshipId (str) – the id of the STIX entity

Returns:

True if contained, False otherwise

Return type:

bool or None

create(**kwargs)[source]

Create an ObservedData object.

Parameters:

stix_id (str) – the STIX ID (optional)
createdBy (str) – the author ID (optional)
objects (list) – list of STIX object IDs (required)
objectMarking (list) – list of marking definition IDs (optional)
objectLabel (list) – list of label IDs (optional)
externalReferences (list) – list of external reference IDs (optional)
revoked (bool) – whether the observed data is revoked (optional)
confidence (int) – confidence level 0-100 (optional)
lang (str) – language (optional)
created (str) – creation date (optional)
modified (str) – modification date (optional)
first_observed (str) – the first observed datetime (required)
last_observed (str) – the last observed datetime (required)
number_observed (int) – number of times observed (optional)
x_opencti_stix_ids (list) – list of additional STIX IDs (optional)
objectOrganization (list) – list of organization IDs (optional)
x_opencti_workflow_id (str) – workflow ID (optional)
x_opencti_modified_at (str) – custom modification date (optional)
update (bool) – whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

ObservedData object

Return type:

dict or None

static generate_id(object_ids)[source]

Generate a STIX ID for an Observed Data object.

Parameters:: object_ids (list) – list of object IDs contained in the observed data
Returns:: STIX ID for the Observed Data
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from Observed Data data.

Parameters:: data (dict) – Dictionary containing an ‘object_refs’ key
Returns:: STIX ID for the Observed Data
Return type:: str

import_from_stix2(**kwargs)[source]

Import an ObservedData object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object ObservedData
extras (dict) – additional parameters like created_by_id, object_marking_ids
update (bool) – whether to update existing object

Returns:

ObservedData object

Return type:

dict or None

list(**kwargs)[source]

List ObservedData objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of ObservedData objects

Return type:

list

read(**kwargs)[source]

Read an ObservedData object.

Parameters:

id (str) – the id of the ObservedData
filters (dict) – the filters to apply if no id provided

Returns:

ObservedData object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Core-Object or stix_relationship from Observed-Data object.

Parameters:

id (str) – the id of the Observed-Data
stixObjectOrStixRelationshipId (str) – the id of the Stix-Core-Object or stix_relationship

Returns:

True if successful, False otherwise

Return type:

bool

class pycti.OpenCTIApiClient(url, token, log_level='info', ssl_verify=False, proxies=None, json_logging=False, bundle_send_to_queue=True, cert=None, custom_headers=None, perform_health_check=True, requests_timeout=300, provider=None)[source]

Main API client for OpenCTI

Parameters:

url (str) – OpenCTI API url
token (str) – OpenCTI API token
log_level (str, optional) – log level for the client
ssl_verify (bool, str, optional) – Requiring the requests to verify the TLS certificate at the server.
proxies (dict, optional) – proxy configuration with “http” and “https” keys (e.g., {“http”: “http://my_proxy:8080”, “https”: “http://my_proxy:8080”})
json_logging (bool, optional) – format the logs as json if set to True
bundle_send_to_queue (bool, optional) – if bundle will be sent to queue
cert (str, tuple, optional) – If String, file path to pem file. If Tuple, a (‘path_to_cert.crt’, ‘path_to_key.key’) pair representing the certificate and the key.
custom_headers (str, optional must in the format header01:value;header02:value) – Add custom headers to use with the graphql queries
perform_health_check (bool, optional) – if client init must check the api access
requests_timeout (int, optional) – define the timeout for API requests in seconds
provider (string, optional) – define client provider, and is used to specify it in requests user agent header

Inheritance

__init__(url, token, log_level='info', ssl_verify=False, proxies=None, json_logging=False, bundle_send_to_queue=True, cert=None, custom_headers=None, perform_health_check=True, requests_timeout=300, provider=None)[source]

Initialize the OpenCTIApiClient instance.

Parameters:

url (str) – OpenCTI platform URL
token (str) – OpenCTI API authentication token
log_level (str) – logging level (default: “info”)
ssl_verify (Union[bool, str]) – SSL certificate verification setting
proxies (Dict[str, str] or None) – proxy configuration dictionary with “http” and “https” keys
json_logging (bool) – whether to format logs as JSON (default: False)
bundle_send_to_queue (bool) – whether bundles are sent to queue (default: True)
cert (str, tuple, or None) – client certificate path or tuple of (cert, key) paths
custom_headers (str or None) – custom headers in format “header01:value;header02:value”
perform_health_check (bool) – whether to check API access on init (default: True)
requests_timeout (int) – timeout for API requests in seconds (default: 300)
provider (str or None) – client provider for User-Agent header (format: provider/version)

Raises:

ValueError – If URL or token is missing or invalid

create_draft(**kwargs)[source]

Create a draft in OpenCTI API.

Parameters:

draft_name (str) – the name of the draft to create (required)
entity_id (str, optional) – the entity ID to associate with the draft

Returns:

returns the draft workspace ID

Return type:

str

fetch_opencti_file(fetch_uri, binary=False, serialize=False)[source]

Get file from the OpenCTI API.

Parameters:

fetch_uri (str) – download URI to use
binary (bool, optional) – if True, returns raw bytes; if False, returns text, defaults to False
serialize (bool, optional) – if True, returns base64-encoded content, defaults to False

Returns:

returns either the file content as text, bytes, base64-encoded string, or None on failure

Return type:

str, bytes, or None

static get_attribute_in_extension(key, stix_object)[source]

Get an attribute value from OpenCTI STIX extensions.

Searches for the key in OpenCTI extension definitions, or falls back to the object’s top-level attributes.

Parameters:

key (str) – the attribute key to retrieve
stix_object (dict) – the STIX object containing extensions

Returns:

the attribute value if found, None otherwise

Return type:

Any

static get_attribute_in_mitre_extension(key, stix_object)[source]

Get an attribute value from MITRE ATT&CK STIX extension.

Parameters:

key (str) – the attribute key to retrieve
stix_object (dict) – the STIX object containing extensions

Returns:

the attribute value if found, None otherwise

Return type:

Any

get_draft_id()[source]

Get the current draft ID.

Returns:: the current draft ID or empty string if not set
Return type:: str

get_logs_worker_config()[source]

Get the logs worker configuration from the OpenCTI platform.

Returns:: the logs worker configuration including Elasticsearch settings
Return type:: dict

get_request_headers(hide_token=True)[source]

Get a copy of current request headers.

Parameters:: hide_token (bool) – if True, masks the Authorization token with asterisks
Returns:: copy of request headers
Return type:: dict

get_stix_content(id)[source]

Get the STIX content of any entity.

Parameters:: id (str) – the ID of the entity
Returns:: the STIX content in JSON
Return type:: dict

health_check()[source]

Submit an example request to the OpenCTI API.

Returns:: returns True if the health check has been successful
Return type:: bool

not_empty(value)[source]

Check if a value is empty for str, list and int.

Parameters:: value (str or list or int or float or bool or datetime.date) – value to check
Returns:: returns True if the value is one of the supported types and not empty
Return type:: bool

process_multiple(data, with_pagination=False)[source]

Process data returned by the OpenCTI API with multiple entities.

Parameters:

data (dict) – data to process
with_pagination (bool, optional) – whether to use pagination with the API, defaults to False

Returns:

returns either a dict or list with the processed entities

Return type:

dict or list

process_multiple_fields(data)[source]

Process data returned by the OpenCTI API with multiple fields.

Parameters:: data (dict) – data to process
Returns:: returns the data dict with all fields processed
Return type:: dict

process_multiple_ids(data)[source]

Process data returned by the OpenCTI API with multiple ids.

Parameters:: data (list) – data to process
Returns:: returns a list of ids
Return type:: list

query(query, variables=None, disable_impersonate=False)[source]

Submit a query to the OpenCTI GraphQL API.

Parameters:

query (str) – GraphQL query string
variables (dict, optional) – GraphQL query variables, defaults to {}
disable_impersonate (bool, optional) – removes impersonate header if set to True, defaults to False

Returns:

returns the response JSON content

Return type:

dict

Raises:

ValueError – if the API returns an error or non-200 status code

send_bundle_to_api(**kwargs)[source]

Push a bundle to a queue through OpenCTI API.

Parameters:

connector_id (str) – the connector ID (required)
bundle (str) – the STIX bundle to push (required)
work_id (str, optional) – the work ID to associate with the bundle

Returns:

returns the query response for the bundle push

Return type:

dict

set_applicant_id_header(applicant_id)[source]

Set the applicant ID header for impersonation.

Parameters:: applicant_id (str) – the ID of the user to impersonate

set_draft_id(draft_id)[source]

Set the draft ID header for draft mode operations.

Parameters:: draft_id (str) – the ID of the draft workspace

set_event_id(event_id)[source]

Set the event ID header for event tracking.

Parameters:: event_id (str) – the ID of the event

set_playbook_id_header(playbook_id)[source]

Set the playbook ID header for tracking playbook execution.

Parameters:: playbook_id (str) – the ID of the playbook being executed

set_previous_standard_header(previous_standard)[source]

Set the previous standard header for update operations.

Parameters:: previous_standard (str) – the previous standard ID

set_retry_number(retry_number)[source]

Set the retry number header for tracking retries.

Parameters:: retry_number (int or None) – the current retry attempt number, or None to clear

set_synchronized_upsert_header(synchronized)[source]

Set the synchronized upsert header.

Parameters:: synchronized (bool) – whether upsert should be synchronized

set_work_id(work_id)[source]

Set the work ID header for work validation

Parameters:: work_id (str) – the ID of the work

upload_file(**kwargs)[source]

upload a file to OpenCTI API

Parameters:: **kwargs – arguments for file upload (required: file_name and data)
Returns:: returns the query response for the file upload
Return type:: dict

upload_pending_file(**kwargs)[source]

Upload a pending file to OpenCTI API.

Parameters:

file_name (str) – the name of the file to upload (required)
data (str or bytes, optional) – the file content, defaults to reading from file_name path
mime_type (str, optional) – the MIME type of the file, defaults to “text/plain”
entity_id (str, optional) – the entity ID to associate with the file
file_markings (list, optional) – list of marking definition IDs to apply

Returns:

returns the query response for the file upload

Return type:

dict

class pycti.OpenCTIApiConnector(api)[source]

OpenCTI Connector API class.

Manages connector operations including registration, pinging, and listing.

Parameters:: api (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(api)[source]

Initialize the OpenCTIApiConnector instance.

Parameters:: api (OpenCTIApiClient) – OpenCTI API client instance

list()[source]

List available connectors.

Returns:: list of connector dictionaries
Return type:: list[dict]

ping(connector_id, connector_state, connector_info)[source]

Ping a connector by ID and state.

Parameters:

connector_id (str) – the connector id
connector_state (Any) – state for the connector
connector_info (dict) – all details about the connector

Returns:

the response pingConnector data dict

Return type:

dict

read(connector_id)[source]

Read the connector and its details.

Parameters:: connector_id (str) – the id of the connector
Returns:: return all the connector details
Return type:: dict

register(connector)[source]

Register a connector with OpenCTI.

Parameters:: connector (OpenCTIConnector) – OpenCTIConnector connector object
Returns:: the response registerConnector data dict
Return type:: dict

unregister(_id)[source]

Unregister a connector with OpenCTI.

Parameters:: _id (str) – the connector id to unregister
Returns:: the response deleteConnector data dict
Return type:: dict

class pycti.OpenCTIApiWork(api)[source]

OpenCTI Work API class.

Manages work/job operations for connectors.

Parameters:: api (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(api)[source]

Initialize the OpenCTIApiWork instance.

Parameters:: api (OpenCTIApiClient) – OpenCTI API client instance

add_draft_context(work_id, draft_context)[source]

Add draft context to a work.

Parameters:

work_id (str) – the work id
draft_context (str) – the draft context to add

Returns:

None

Return type:

None

add_expectations(work_id, expectations)[source]

Add expectations to a work.

Parameters:

work_id (str) – the work id
expectations (int) – the number of expectations to add

Returns:

whether the work is still alive

Return type:

bool

delete(**kwargs)[source]

Delete a work by id.

Parameters:: id (str) – the work id
Returns:: the response data
Return type:: dict or None

delete_work(work_id)[source]

Delete a work.

Deprecated since version Use: delete() instead.

Parameters:: work_id (str) – the work id
Returns:: the response data
Return type:: dict

get_connector_works(connector_id)[source]

Get all works for a connector.

Parameters:: connector_id (str) – the connector id
Returns:: list of work dictionaries sorted by timestamp
Return type:: list[dict]

get_is_work_alive(work_id)[source]

Check if a work is alive.

Parameters:: work_id (str) – the work id
Returns:: whether the work is alive
Return type:: bool

get_work(work_id)[source]

Get a work by id.

Parameters:: work_id (str) – the work id
Returns:: the work data
Return type:: dict

initiate_work(connector_id, friendly_name, is_multipart=False)[source]

Initiate a new work for a connector.

Parameters:

connector_id (str) – the connector id
friendly_name (str) – the friendly name for the work
is_multipart (bool) – indicates whether multiple calls to add_expectations are to be expected during the lifetime of the work. In consequence the work won’t automatically transition to complete when the number of calls to report_expectation matches the expectations but only when an explicit call to to_processed is made. Should be set to True when sending multiple STIX bundles consecutively via send_stix2_bundle during the work’s lifetime. Defaults to False.

Returns:

the work id or None if bundle_send_to_queue is False

Return type:

str or None

ping(work_id)[source]

Ping a work to keep it alive.

Parameters:: work_id (str) – the work id
Returns:: None
Return type:: None

report_expectation(work_id, error)[source]

Report a work expectation.

Parameters:

work_id (str) – the work id
error (dict) – the error to report (WorkErrorInput format)

Returns:

None

Return type:

None

to_processed(work_id, message, in_error=False)[source]

Mark work as processed.

Parameters:

work_id (str) – the work id
message (str) – the message to report
in_error (bool, optional) – whether the work completed with error, defaults to False

Returns:

None

Return type:

None

to_received(work_id, message)[source]

Mark work as received.

Parameters:

work_id (str) – the work id
message (str) – the message to report

Returns:

None

Return type:

None

wait_for_work_to_finish(work_id)[source]

Wait for a work to finish.

Parameters:: work_id (str) – the work id
Returns:: empty string if error, None otherwise
Return type:: str or None

class pycti.OpenCTIConnector(connector_id, connector_name, connector_type, scope, auto, only_contextual, playbook_compatible, auto_update, enrichment_resolution, listen_callback_uri=None, xtm_one_intent=None)[source]

Main class for OpenCTI connector registration and configuration.

This class represents a connector instance that can be registered with the OpenCTI platform. It holds all configuration parameters needed for the connector to operate.

Parameters:

connector_id (str) – Unique identifier for the connector (valid UUID4)
connector_name (str) – Human-readable name for the connector
connector_type (str) – Type of connector (see ConnectorType)
scope (str) – Connector scope as a comma-separated string (e.g., “Report,Indicator”)
auto (bool) – Whether the connector runs automatically on matching entities
only_contextual (bool) – Whether the connector only processes contextual data
playbook_compatible (bool) – Whether the connector can be used in playbooks
auto_update (bool) – Whether to automatically update existing entities
enrichment_resolution (str) – Strategy for resolving enrichment conflicts
listen_callback_uri (str or None) – Optional callback URI for API-based listening

Raises:

ValueError – If the connector type is not a valid ConnectorType value

Example

>>> connector = OpenCTIConnector(
...     connector_id="550e8400-e29b-41d4-a716-446655440000",
...     connector_name="My Connector",
...     connector_type="EXTERNAL_IMPORT",
...     scope="Report,Indicator",
...     auto=False,
...     only_contextual=False,
...     playbook_compatible=True,
...     auto_update=False,
...     enrichment_resolution="none"
... )

Inheritance

__init__(connector_id, connector_name, connector_type, scope, auto, only_contextual, playbook_compatible, auto_update, enrichment_resolution, listen_callback_uri=None, xtm_one_intent=None)[source]

Initialize the OpenCTIConnector instance.

Parameters:

connector_id (str) – Unique identifier for the connector (valid UUID4)
connector_name (str) – Human-readable name for the connector
connector_type (str) – Type of connector (see ConnectorType)
scope (str) – Connector scope as a comma-separated string
auto (bool) – Whether the connector runs automatically
only_contextual (bool) – Whether to process only contextual data
playbook_compatible (bool) – Whether the connector works with playbooks
auto_update (bool) – Whether to auto-update existing entities
enrichment_resolution (str) – Enrichment conflict resolution strategy
listen_callback_uri (str or None) – Optional callback URI for API listening

Raises:

ValueError – If connector_type is not a valid ConnectorType

to_input()[source]

Convert connector configuration to API input format.

Generates a dictionary structure suitable for use in GraphQL API queries to register or update the connector.

Returns:: Dictionary containing connector data wrapped in an “input” key
Return type:: dict

Example

>>> connector.to_input()
{'input': {'id': '...', 'name': 'My Connector', ...}}

class pycti.OpenCTIConnectorHelper(config, playbook_compatible=False)[source]

Main helper class for developing OpenCTI connectors.

Provides a comprehensive API for connector development, handling: - Connector registration and configuration - Message queue communication (RabbitMQ/API) - SSE stream consumption - STIX2 bundle creation and submission - Scheduling and lifecycle management - Metrics and logging

Parameters:

config (Dict) – Configuration dictionary containing OpenCTI and connector settings
playbook_compatible (bool) – Whether the connector can be used in playbooks

Example

>>> config = {
...     "opencti": {"url": "http://localhost:8080", "token": "xxx"},
...     "connector": {"id": "xxx", "name": "My Connector", "type": "EXTERNAL_IMPORT"}
... }
>>> helper = OpenCTIConnectorHelper(config)
>>> helper.listen(my_callback_function)

api: OpenCTI API client for connector operations

api_impersonate: API client that impersonates the request applicant

connector_logger: Logger instance for connector messages

connector_info: Runtime information about the connector

metric: Prometheus metric handler

Inheritance

class TimeUnit(*values)[source]

Time unit enumeration for scheduling intervals (deprecated).

Use ISO 8601 duration format with schedule_iso() instead.

Variables:

SECONDS – 1 second
MINUTES – 60 seconds
HOURS – 3600 seconds
DAYS – 86400 seconds
WEEKS – 604800 seconds
YEARS – 31536000 seconds

__init__(config, playbook_compatible=False)[source]

Initialize the OpenCTIConnectorHelper.

Parameters:

config (Dict) – Configuration dictionary with OpenCTI and connector settings
playbook_compatible (bool) – Whether the connector can be used in playbooks

check_connector_buffering()[source]

Check if the RabbitMQ queue has exceeded the allowed threshold.

Returns:: True if queue size exceeds threshold, False otherwise
Return type:: bool

static check_max_tlp(tlp, max_tlp)[source]

Check if a TLP level is within the allowed maximum TLP level.

Validates that the given TLP marking is at or below the maximum allowed TLP level. Useful for filtering data based on sharing restrictions.

Parameters:

tlp (str) – The TLP level to check (e.g., “TLP:GREEN”, “TLP:AMBER”)
max_tlp (str) – The highest allowed TLP level for comparison

Returns:

True if the TLP level is within the allowed range, False otherwise

Return type:

bool

Example

>>> OpenCTIConnectorHelper.check_max_tlp("TLP:GREEN", "TLP:AMBER")
True
>>> OpenCTIConnectorHelper.check_max_tlp("TLP:RED", "TLP:GREEN")
False

create_batch_callback(batch_callback, batch_size=None, batch_timeout=None, max_per_minute=None)[source]

Create a callback wrapper that batches messages.

This factory method creates a BatchCallbackWrapper that can be used with listen_stream to enable batch processing of events.

For rate limiting, use the max_per_minute parameter (recommended).

Usage:

# Basic batch processing: batch_callback = helper.create_batch_callback(

process_batch_func, batch_size=100, batch_timeout=30

) helper.listen_stream(message_callback=batch_callback)

# With rate limiting (recommended): batch_callback = helper.create_batch_callback(

process_batch_func, batch_size=100, batch_timeout=30, max_per_minute=10

) helper.listen_stream(message_callback=batch_callback)

The batch callback receives a dictionary with the following structure:

{

“events”: [list of SSE messages], “batch_metadata”: {

“batch_size”: int, “trigger_reason”: str, # “size_limit”, “timeout”, “shutdown” “elapsed_time”: float, “timestamp”: float,

}

Parameters:

batch_callback (Callable[[dict], None]) – Function to call with batched events
batch_size (int or None) – Process batch when this many events accumulated (optional)
batch_timeout (float or None) – Process batch after this many seconds (optional)
max_per_minute (int or None) – Maximum batch callbacks per minute (optional)

Returns:

BatchCallbackWrapper instance for use with listen_stream

Return type:

BatchCallbackWrapper

Raises:

ValueError – If neither batch_size nor batch_timeout is specified
ValueError – If batch_size is not a positive integer
ValueError – If batch_timeout is not a positive number
ValueError – If max_per_minute is not a positive integer

create_rate_limiter(max_per_minute)[source]

Create a rate limiter that can wrap any callback.

The rate limiter uses a sliding window algorithm to enforce a maximum number of calls per minute. It can be used with both batch and non-batch callbacks.

Usage:

# With batch callback: batch_callback = helper.create_batch_callback(

process_batch_func, batch_size=100, batch_timeout=30

) rate_limiter = helper.create_rate_limiter(max_per_minute=10) rate_limited = rate_limiter.wrap(batch_callback) helper.listen_stream(message_callback=rate_limited)

# With non-batch callback: rate_limiter = helper.create_rate_limiter(max_per_minute=100) rate_limited = rate_limiter.wrap(process_message) helper.listen_stream(message_callback=rate_limited)

Parameters:: max_per_minute (int) – Maximum number of calls allowed per 60-second window
Returns:: RateLimiter instance that can wrap callbacks
Return type:: RateLimiter
Raises:: ValueError – If max_per_minute is not a positive integer

date_now()[source]

Get the current UTC datetime in ISO 8601 format.

Returns the current time with timezone offset notation (+00:00).

Returns:: Current UTC datetime as ISO 8601 string (e.g., “2024-01-15T10:30:00+00:00”)
Return type:: str

Example

>>> helper.date_now()
'2024-01-15T10:30:00+00:00'

date_now_z()[source]

Get the current UTC datetime in ISO 8601 format with Z suffix.

Returns the current time with ‘Z’ suffix instead of ‘+00:00’. This format is commonly used in STIX objects.

Returns:: Current UTC datetime as ISO 8601 string (e.g., “2024-01-15T10:30:00Z”)
Return type:: str

Example

>>> helper.date_now_z()
'2024-01-15T10:30:00Z'

force_ping()[source]

Force a ping to the OpenCTI API to update connector state.

This method manually triggers a ping to synchronize the connector state with the OpenCTI platform.

static get_attribute_in_extension(key, stix_object)[source]

Get an attribute from OpenCTI STIX extensions.

Retrieves a value from OpenCTI’s custom STIX extension definitions. Checks both the primary OpenCTI extension and the SDO extension, falling back to the object’s root attributes if not found in extensions.

Parameters:

key (str) – The attribute key to retrieve
stix_object (Dict) – A STIX object dictionary

Returns:

The attribute value, or None if not found

Return type:

any

Example

>>> obj = {"extensions": {"extension-definition--ea279b3e-...": {"score": 85}}}
>>> OpenCTIConnectorHelper.get_attribute_in_extension("score", obj)
85

static get_attribute_in_mitre_extension(key, stix_object)[source]

Get an attribute from MITRE ATT&CK STIX extension.

Retrieves a value from the MITRE ATT&CK custom STIX extension definition used for attack patterns and techniques.

Parameters:

key (str) – The attribute key to retrieve
stix_object (Dict) – A STIX object dictionary

Returns:

The attribute value, or None if not found

Return type:

any

Example

>>> obj = {"extensions": {"extension-definition--322b8f77-...": {"x_mitre_version": "1.0"}}}
>>> OpenCTIConnectorHelper.get_attribute_in_mitre_extension("x_mitre_version", obj)
'1.0'

get_connector()[source]

Get the OpenCTIConnector instance.

Returns:: The OpenCTIConnector instance
Return type:: OpenCTIConnector

get_data_from_enrichment(data, standard_id, opencti_entity)[source]

Extract STIX entity and objects from enrichment data.

Parameters:

data (dict) – The enrichment data containing a bundle
standard_id (str) – The STIX standard ID of the entity
opencti_entity (dict) – The OpenCTI entity object

Returns:

Dictionary containing stix_entity and stix_objects

Return type:

dict

get_name()[source]

Get the connector name.

Returns:: The name of the connector
Return type:: Optional[Union[bool, int, str]]

get_only_contextual()[source]

Get the only_contextual configuration value.

Returns:: Whether the connector processes only contextual data
Return type:: Optional[Union[bool, int, str]]

get_opencti_token()[source]

Get the OpenCTI API token.

Returns:: The API token for OpenCTI authentication
Return type:: Optional[Union[bool, int, str]]

get_opencti_url()[source]

Get the OpenCTI URL.

Returns:: The URL of the OpenCTI platform
Return type:: Optional[Union[bool, int, str]]

get_run_and_terminate()[source]

Get the run_and_terminate configuration value.

Returns:: Whether the connector should run once and terminate
Return type:: Optional[Union[bool, int, str]]

get_state()[source]

Get the connector state.

Retrieves the current connector state that was previously stored. The state is used to track progress and resume operations across runs.

Returns:: The current state of the connector, or None if no state exists
Return type:: Optional[Dict]

get_stream_collection()[source]

Get the stream collection configuration.

Returns:: Stream collection configuration dictionary
Return type:: dict
Raises:: ValueError – If no stream is connected

get_validate_before_import()[source]

Get the validate_before_import configuration value.

Returns:: Whether to validate data before importing
Return type:: Optional[Union[bool, int, str]]

last_run_datetime()[source]

Set the last run datetime to the current UTC time in ISO format.

Return type:: None

listen(message_callback)[source]

Listen for messages from the queue and process them via callback.

Starts a listener thread that consumes messages from RabbitMQ or HTTP API (depending on configured listen protocol) and processes each message through the provided callback function. This method blocks until the listener is stopped.

Parameters:: message_callback (Callable[[Dict], str]) – Function to process incoming messages. Receives event data dict and should return a status message string.
Return type:: None

listen_stream(message_callback, url=None, token=None, verify_ssl=None, start_timestamp=None, live_stream_id=None, listen_delete=None, no_dependencies=None, recover_iso_date=None, with_inferences=None)[source]

Start listening to an OpenCTI event stream.

Connects to an SSE stream and processes events through the callback. Parameters default to connector configuration values if not specified.

Parameters:

message_callback (Callable) – Function to call for each stream event
url (str or None) – Base URL for stream (defaults to opencti_url)
token (str or None) – Authentication token (defaults to opencti_token)
verify_ssl (bool or None) – Whether to verify SSL certificates
start_timestamp (str or None) – Stream position to start from
live_stream_id (str or None) – Specific stream ID to connect to
listen_delete (bool or None) – Whether to receive delete events
no_dependencies (bool or None) – Whether to exclude dependencies
recover_iso_date (str or None) – ISO date to recover events from
with_inferences (bool or None) – Whether to include inferred data

Returns:

The started ListenStream thread

Return type:

ListenStream

next_run_datetime(duration_period_in_seconds)[source]

Calculate and set the next scheduled run datetime in ISO format.

Parameters:: duration_period_in_seconds (Union[int, float]) – Duration in seconds until next run
Return type:: None

schedule_iso(message_callback, duration_period)[source]

Schedule connector execution using ISO 8601 duration format.

Parameters:

message_callback (Callable[[], None]) – The connector process callback function
duration_period (str) – Duration in ISO 8601 format (e.g., “P18Y9W4DT11H9M8S”)

Return type:

None

schedule_process(message_callback, duration_period)[source]

Schedule the execution of a connector process.

If duration_period is zero or connect_run_and_terminate is True, the process will run once and terminate. Otherwise, it schedules the next run based on the interval.

Parameters:

message_callback (Callable[[], None]) – The connector process callback function
duration_period (Union[int, float]) – The connector’s interval in seconds

Return type:

None

schedule_unit(message_callback, duration_period, time_unit)[source]

Schedule connector execution with a time unit (deprecated).

This method manages backward compatibility of intervals on connectors. Use schedule_iso method instead.

Parameters:

message_callback (Callable[[], None]) – The connector process callback function
duration_period (Union[int, float, str]) – The connector interval value
time_unit (TimeUnit) – The unit of time (YEARS, WEEKS, DAYS, HOURS, MINUTES, SECONDS)

Return type:

None

send_stix2_bundle(bundle, **kwargs)[source]

Send a STIX2 bundle to the OpenCTI platform.

Processes and sends a STIX2 bundle to OpenCTI via the message queue or API. The bundle is split into smaller chunks and sent with proper sequencing. Supports validation workflows, draft mode, and directory export.

Parameters:

bundle (str) – Valid STIX2 bundle as a JSON string
work_id (str, optional) – Work ID for tracking the import job (default: self.work_id)
validation_mode (str, optional) – Validation mode - “workbench” or “draft” (default: self.validation_mode)
draft_id (str, optional) – Draft context ID to send the bundle to (default: self.draft_id)
entities_types (list, optional) – List of entity types to filter (default: None)
update (bool, optional) – Whether to update existing data in the database (default: False)
event_version (str, optional) – Event version for the bundle (default: None)
bypass_validation (bool, optional) – Skip validation workflow (default: False)
force_validation (bool, optional) – Force validation even if not configured (default: self.force_validation)
entity_id (str, optional) – Entity ID for context (default: None)
file_markings (list, optional) – File markings to apply (default: None)
file_name (str, optional) – File name for workbench upload (default: None)
send_to_queue (bool, optional) – Whether to send to message queue (default: self.bundle_send_to_queue)
cleanup_inconsistent_bundle (bool, optional) – Clean up inconsistent bundle data (default: False)
send_to_directory (bool, optional) – Whether to write bundle to directory (default: self.bundle_send_to_directory)
send_to_directory_path (str, optional) – Directory path for bundle export (default: self.bundle_send_to_directory_path)
send_to_directory_retention (int, optional) – Days to retain exported files (default: self.bundle_send_to_directory_retention)
send_to_s3 (bool, optional) – Whether to upload bundle to S3 (default: self.bundle_send_to_s3)
no_split (bool, optional) – Whether to send without splitting (default: False)

Returns:

List of processed bundle chunks

Return type:

list

Raises:

ValueError – If the bundle is empty or contains no valid objects

set_state(state)[source]

Set the connector state.

Stores the connector state as a JSON string for persistence across runs. The state can be retrieved later using get_state().

Parameters:: state (Dict or None) – State object to store, or None to clear the state
Return type:: None

static stix2_create_bundle(items)[source]

Create a STIX2 bundle from a list of objects.

Wraps STIX2 objects in a valid bundle structure with a generated UUID. Automatically serializes objects if they are STIX2 library instances.

Parameters:: items (list) – List of STIX2 objects (dicts or STIX2 library objects)
Returns:: JSON string of the STIX2 bundle, or None if items is empty
Return type:: Optional[str]

static stix2_deduplicate_objects(items)[source]

Deduplicate STIX2 objects by their ID.

Removes duplicate STIX2 objects from a list, keeping only the first occurrence of each unique ID.

Parameters:: items (list) – List of STIX2 objects to deduplicate
Returns:: Deduplicated list of STIX2 objects
Return type:: list

stop()[source]

Stop the connector and clean up resources.

This method stops all running threads (listen queue, ping thread) and unregisters the connector from OpenCTI.

Return type:: None

class pycti.OpenCTIMetricHandler(connector_logger, activated=False, namespace='', subsystem='', port=9095)[source]

Handler for Prometheus metrics in OpenCTI connectors.

This class manages Prometheus metrics for monitoring connector behavior, including bundle sends, records processed, run counts, API pings, and errors.

When activated, it starts an HTTP server to expose metrics for scraping by Prometheus or compatible monitoring systems.

Parameters:

connector_logger (logging.Logger) – Logger instance for the connector
activated (bool) – Whether to enable metrics collection and exposure
namespace (str) – Prometheus metrics namespace prefix
subsystem (str) – Prometheus metrics subsystem prefix
port (int) – Port number for the Prometheus HTTP server

Example

>>> handler = OpenCTIMetricHandler(
...     connector_logger=logger,
...     activated=True,
...     namespace="opencti",
...     subsystem="connector",
...     port=9095
... )
>>> handler.inc("bundle_send")
>>> handler.state("running")

Inheritance

__init__(connector_logger, activated=False, namespace='', subsystem='', port=9095)[source]

Initialize the OpenCTIMetricHandler instance.

Parameters:

connector_logger (logging.Logger) – Logger instance for the connector
activated (bool) – Whether to enable metrics (default: False)
namespace (str) – Prometheus metrics namespace prefix (default: “”)
subsystem (str) – Prometheus metrics subsystem prefix (default: “”)
port (int) – Port for Prometheus HTTP server (default: 9095)

inc(name, n=1)[source]

Increment a counter metric by a specified amount.

Increments the named counter metric. If metrics are not activated or the metric does not exist, this method does nothing.

Available counter metrics:

bundle_send: Number of bundles sent
record_send: Number of records sent
run_count: Number of connector runs
ping_api_count: Number of API pings
ping_api_error: Number of API ping errors
error_count: Total number of errors
client_error_count: Number of client errors

Parameters:

name (str) – Name of the counter metric to increment
n (int) – Amount to increment the counter by (default: 1)

Return type:

None

Example

>>> handler.inc("bundle_send")
>>> handler.inc("record_send", 10)

state(state, name='state')[source]

Set the state of an Enum metric.

Updates the named Enum metric to the specified state value. If metrics are not activated or the metric does not exist, this method does nothing.

Available states for the default “state” metric:

idle: Connector is idle
running: Connector is running
stopped: Connector is stopped

Parameters:

state (str) – State value to set (must be a valid state for the metric)
name (str) – Name of the Enum metric to update (default: “state”)

Return type:

None

Example

>>> handler.state("running")
>>> handler.state("idle", "state")

class pycti.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

Inheritance

__init__(opencti)[source]

Initialize the OpenCTIStix2 helper.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

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

apply_patch(item)[source]

Apply field patches to an item.

Parameters:: item (dict) – Item containing field patch operations

apply_patch_files(item)[source]

Apply file patches to an item.

Parameters:: item (dict) – Item containing file patch operations

convert_markdown(text)[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

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_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_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

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

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

export_entities_list(entity_type, search=None, filters=None, orderBy=None, orderMode=None, getAll=True, withFiles=False)[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_entity(entity_type, entity_id, mode='simple', access_filter=None, no_custom_attributes=False, only_entity=False)[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_list(entity_type, search=None, filters=None, order_by=None, order_mode=None, mode='simple', access_filter=None)[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, mode='simple', access_filter=None)[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

extract_embedded_relationships(stix_object, types=None)[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

filter_objects(uuids, objects)[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

format_date(date=None)[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

generate_export(entity, no_custom_attributes=False)[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

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

get_author(name)[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:: Identity

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

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

get_reader(entity_type)[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_readers()[source]

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)[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

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

import_bundle(stix_bundle, update=False, types=None, work_id=None, objects_max_refs=0)[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

import_bundle_from_file(file_path, update=False, types=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, update=False, types=None, work_id=None, objects_max_refs=0)[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]

import_item(item, update=False, types=None, work_id=None, bundle_id=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=False, types=None, work_id=None, bundle_id=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_object(stix_object, update=False, types=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, update=False, types=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

Return type:

None

import_relationship(stix_relation, update=False, types=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

Return type:

None

import_sighting(stix_sighting, from_id, to_id, update=False, types=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

Return type:

None

organization_share(item)[source]

Share an item with organizations.

Parameters:: item (dict) – Item to share

organization_unshare(item)[source]

Unshare an item from organizations.

Parameters:: item (dict) – Item to unshare

pick_aliases(stix_object)[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

prepare_export(entity, mode='simple', access_filter=None, no_custom_attributes=False)[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

static prepare_id_filters_export(entity_id, access_filter=None)[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

static put_attribute_in_extension(stix_object, extension_id, key, value, multiple=False)[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

resolve_author(title)[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

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

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

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)[source]

Log an error for unknown STIX object types.

Parameters:: stix_object (Dict) – STIX object with unknown type
Return type:: None

class pycti.OpenCTIStix2Splitter[source]

STIX2 bundle splitter for OpenCTI.

Splits large STIX2 bundles into smaller chunks for processing, handling dependencies between objects and deduplicating references.

Inheritance

__init__()[source]

Initialize the STIX2 bundle splitter.

Sets up internal caches for tracking processed elements, references, and incompatible items.

enlist_element(item_id, raw_data, cleanup_inconsistent_bundle, parent_acc)[source]

Enlist an element and its dependencies for processing.

Parameters:

item_id (str) – the ID of the item to enlist
raw_data (dict) – the raw data dictionary of all items
cleanup_inconsistent_bundle (bool) – whether to cleanup inconsistent references
parent_acc (list) – accumulator of parent IDs to prevent circular references

Returns:

number of dependencies enlisted

Return type:

int

get_internal_ids_in_extension(item)[source]

Get internal IDs from OpenCTI extensions in a STIX object.

Parameters:: item (dict) – the STIX object to extract IDs from
Returns:: list of internal IDs found in extensions
Return type:: list

split_bundle(bundle, use_json=True, event_version=None)[source]

Split a valid STIX2 bundle into a list of bundles.

Deprecated since version Use: split_bundle_with_expectations() instead.

Parameters:

bundle (str or dict) – the STIX2 bundle to split
use_json (bool) – whether the bundle is JSON string (True) or dict (False)
event_version (str or None) – (optional) event version to include in bundles

Returns:

list of STIX2 bundles

Return type:

list

split_bundle_with_expectations(bundle, use_json=True, event_version=None, cleanup_inconsistent_bundle=False)[source]

Split a valid STIX2 bundle into a list of bundles.

Parameters:

bundle (str or dict) – the STIX2 bundle to split
use_json (bool) – whether the bundle is JSON string (True) or dict (False)
event_version (str or None) – (optional) event version to include in bundles
cleanup_inconsistent_bundle (bool) – whether to cleanup inconsistent references

Returns:

tuple of (number of expectations, incompatible items, list of bundles)

Return type:

Tuple[int, list, list]

static stix2_create_bundle(bundle_id, bundle_seq, items, use_json, event_version=None)[source]

Create a STIX2 bundle with items.

Parameters:

bundle_id (str) – the bundle ID
bundle_seq (int) – the bundle sequence number
items (list) – valid STIX2 items
use_json (bool) – whether to return JSON string (True) or dict (False)
event_version (str or None) – (optional) event version to include

Returns:

STIX2 bundle as JSON string or dict

Return type:

str or dict

class pycti.OpenCTIStix2Update(opencti)[source]

Python API for Stix2 Update in OpenCTI.

Provides methods to update STIX2 objects in OpenCTI, including adding/removing marking definitions, labels, external references, kill chain phases, and object references.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

Inheritance

__init__(opencti)[source]

Initialize the OpenCTIStix2Update helper.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_external_references(entity_type, entity_id, external_references, version=2)[source]

Add external references to an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
external_references (list) – List of external references
version (int) – Version of the patch format (default: 2)

add_kill_chain_phases(entity_type, entity_id, kill_chain_phases, version=2)[source]

Add kill chain phases to an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
kill_chain_phases (list) – List of kill chain phases
version (int) – Version of the patch format (default: 2)

add_labels(entity_type, entity_id, labels, version=2)[source]

Add labels to an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
labels (list) – List of labels to add
version (int) – Version of the patch format (default: 2)

add_object_marking_refs(entity_type, entity_id, object_marking_refs, version=2)[source]

Add marking definition references to an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
object_marking_refs (list) – List of marking definition references
version (int) – Version of the patch format (default: 2)

add_object_refs(entity_type, entity_id, object_refs, version=2)[source]

Add object references to a container entity.

Parameters:

entity_type (str) – Type of the container entity (report, note, etc.)
entity_id (str) – ID of the container entity
object_refs (list) – List of object references to add
version (int) – Version of the patch format (default: 2)

process_update(data)[source]

Process a STIX2 patch/update operation.

Parameters:: data (dict) – Data containing x_opencti_patch operations

remove_external_references(entity_type, entity_id, external_references)[source]

Remove external references from an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
external_references (list) – List of external references

remove_kill_chain_phases(entity_type, entity_id, kill_chain_phases)[source]

Remove kill chain phases from an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
kill_chain_phases (list) – List of kill chain phases

remove_labels(entity_type, entity_id, labels, version=2)[source]

Remove labels from an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
labels (list) – List of labels to remove
version (int) – Version of the patch format (default: 2)

remove_object_marking_refs(entity_type, entity_id, object_marking_refs, version=2)[source]

Remove marking definition references from an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
object_marking_refs (list) – List of marking definition references
version (int) – Version of the patch format (default: 2)

remove_object_refs(entity_type, entity_id, object_refs, version=2)[source]

Remove object references from a container entity.

Parameters:

entity_type (str) – Type of the container entity (report, note, etc.)
entity_id (str) – ID of the container entity
object_refs (list) – List of object references to remove
version (int) – Version of the patch format (default: 2)

replace_created_by_ref(entity_type, entity_id, created_by_ref, version=2)[source]

Replace the created_by reference of an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
created_by_ref (str or list) – New created_by reference
version (int) – Version of the patch format (default: 2)

update_attribute(entity_type, entity_id, field_input)[source]

Update an attribute of an entity.

Parameters:

entity_type (str) – Type of the entity
entity_id (str) – ID of the entity
field_input (list) – Input containing the attribute update

class pycti.OpenCTIStix2Utils[source]

Utility class for STIX2 operations in OpenCTI.

Provides helper methods for STIX2 conversions and pattern generation, including type mappings, observable pattern creation, and reference counting.

Inheritance

static compute_object_refs_number(entity)[source]

Compute the number of object references in an entity.

Parameters:: entity (Dict) – Entity dictionary to analyze
Returns:: Total number of references
Return type:: int

static create_stix_pattern(observable_type, observable_value)[source]

Create a STIX pattern from an observable type and value.

Parameters:

observable_type (str) – Type of the observable
observable_value (str) – Value of the observable

Returns:

STIX pattern string or None if type not supported

Return type:

str or None

static generate_random_stix_id(stix_type)[source]

Generate random stix id (uuid v1) - DEPRECATED.

This function is deprecated and should not be used anymore. Please use the generate_id function for SDO or proper SCO constructor.

Parameters:: stix_type – the stix type
Raises:: ValueError – Always raises an error as this function is deprecated

static retrieveClassForMethod(openCTIApiClient, entity, type_path, method)[source]

Retrieve the appropriate API class for a given entity type and method.

Deprecated since version Use: retrieve_class_for_method() instead.

Parameters:

openCTIApiClient (OpenCTIApiClient) – OpenCTI API client instance
entity (Dict) – Entity dictionary containing the type
type_path (str) – Path to the type field in the entity
method (str) – Name of the method to check for

Returns:

The API class that has the specified method, or None

Return type:

Any

static retrieve_class_for_method(opencti_api_client, entity, type_path, method)[source]

Retrieve the appropriate API class for a given entity type and method.

Parameters:

opencti_api_client (OpenCTIApiClient) – OpenCTI API client instance
entity (Dict) – Entity dictionary containing the type
type_path (str) – Path to the type field in the entity
method (str) – Name of the method to check for

Returns:

The API class that has the specified method, or None

Return type:

Any

static stix_observable_opencti_type(observable_type)[source]

Convert STIX observable type to OpenCTI type.

Parameters:: observable_type (str) – STIX observable type
Returns:: Corresponding OpenCTI type or “Unknown”
Return type:: str

class pycti.Opinion(opencti)[source]

Main Opinion class for OpenCTI

Manages analyst opinions and assessments in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Opinion instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a Stix-Entity object to Opinion object (object_refs).

Parameters:

id (str) – the id of the Opinion
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if an opinion already contains a STIX entity.

Parameters:

id (str) – the id of the Opinion
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

create(**kwargs)[source]

Create an Opinion object.

Parameters:

stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objects (list) – (optional) list of STIX object IDs
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the opinion is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (datetime) – (optional) creation date
modified (datetime) – (optional) modification date
explanation (str) – (optional) explanation text
authors (list) – (optional) list of authors
opinion (str) – the opinion value (required)
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_modified_at (datetime) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Opinion object

Return type:

dict or None

static generate_id(created, opinion)[source]

Generate a STIX ID for an Opinion.

Parameters:

created (datetime or str or None) – The creation date of the opinion
opinion (str) – The opinion value (required)

Returns:

STIX ID for the opinion

Return type:

str

Raises:

ValueError – If opinion is None

static generate_id_from_data(data)[source]

Generate a STIX ID from opinion data.

Parameters:: data (dict) – Dictionary containing ‘opinion’ and optionally ‘created’ keys
Returns:: STIX ID for the opinion
Return type:: str

import_from_stix2(**kwargs)[source]

Import an Opinion object from a STIX2 object.

Parameters:

stixObject (dict) – the Stix-Object Opinion
extras (dict) – extra dict
update (bool) – set the update flag on import

Returns:

Opinion object

Return type:

dict or None

list(**kwargs)[source]

List Opinion objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (list) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info

Returns:

List of Opinion objects

Return type:

list

read(**kwargs)[source]

Read an Opinion object.

Parameters:

id (str) – the id of the Opinion
filters (dict) – the filters to apply if no id provided
customAttributes (list) – custom attributes to return

Returns:

Opinion object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a Stix-Entity object from Opinion object (object_refs).

Parameters:

id (str) – the id of the Opinion
stixObjectOrStixRelationshipId (str) – the id of the Stix-Entity

Returns:

Boolean

Return type:

bool

class pycti.Report(opencti)[source]

Main Report class for OpenCTI

Manages threat intelligence reports in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Report instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_stix_object_or_stix_relationship(**kwargs)[source]

Add a STIX object or relationship to Report object (object_refs).

Parameters:

id (str) – the id of the Report
stixObjectOrStixRelationshipId (str) – the id of the STIX object or relationship

Returns:

True if successful, False otherwise

Return type:

bool

contains_stix_object_or_stix_relationship(**kwargs)[source]

Check if a report already contains a STIX object or relationship.

Parameters:

id (str) – the id of the Report
stixObjectOrStixRelationshipId (str) – the id of the STIX object or relationship

Returns:

True if the report contains the entity, False otherwise

Return type:

bool

create(**kwargs)[source]

Create a Report object.

Parameters:

stix_id – (optional) the STIX ID of the Report
createdBy – (optional) the author ID
objects – (optional) list of STIX object IDs contained in the report
objectMarking – (optional) list of marking definition IDs
objectAssignee – (optional) list of assignee IDs
objectParticipant – (optional) list of participant IDs
objectLabel – (optional) list of label IDs
externalReferences – (optional) list of external reference IDs
revoked – (optional) whether the report is revoked
confidence – (optional) confidence level (0-100)
lang – (optional) language of the report
created – (optional) creation date
modified – (optional) modification date
name – the name of the Report (required)
description – (optional) description of the report
content – (optional) content of the report
report_types – (optional) list of report types
published – the publication date (required)
x_opencti_reliability – (optional) reliability level
x_opencti_stix_ids – (optional) list of additional STIX IDs
objectOrganization – (optional) list of organization IDs
x_opencti_workflow_id – (optional) workflow ID
x_opencti_modified_at – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Report object

Return type:

dict or None

static generate_fixed_fake_id(name, published=None)[source]

Generate a fixed fake STIX ID for a Report (used for testing).

Parameters:

name (str) – The name of the report
published (str or datetime.datetime or None) – (optional) The published date of the report

Returns:

STIX ID for the report

Return type:

str

static generate_id(name, published)[source]

Generate a STIX ID for a Report.

Parameters:

name (str) – The name of the report
published (str or datetime.datetime) – The published date of the report

Returns:

STIX ID for the report

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from report data.

Parameters:: data (dict) – Dictionary containing ‘name’ and ‘published’ keys
Returns:: STIX ID for the report
Return type:: str

get_by_stix_id_or_name(**kwargs)[source]

Read a Report object by stix_id or name.

Parameters:

stix_id (str) – the STIX ID of the Report
name (str) – the name of the Report
published (str) – the published date of the Report
customAttributes (str) – custom attributes to return

Returns:

Report object

Return type:

dict or None

import_from_stix2(**kwargs)[source]

Import a Report object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Report object
extras (dict) – extra parameters including created_by_id, object_marking_ids, object_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Report object

Return type:

dict or None

list(**kwargs)[source]

List Report objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Report objects

Return type:

list

read(**kwargs)[source]

Read a Report object.

Parameters:

id (str) – the id of the Report
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Report object

Return type:

dict or None

remove_stix_object_or_stix_relationship(**kwargs)[source]

Remove a STIX object or relationship from Report object (object_refs).

Parameters:

id (str) – the id of the Report
stixObjectOrStixRelationshipId (str) – the id of the STIX object or relationship

Returns:

True if successful, False otherwise

Return type:

bool

class pycti.StixCoreRelationship(opencti)[source]

Main StixCoreRelationship class for OpenCTI

Manages STIX relationships between entities in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixCoreRelationship instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_external_reference(**kwargs)[source]

Add an External-Reference object to stix_core_relationship.

Parameters:

id (str) – the id of the stix_core_relationship
external_reference_id (str) – the id of the External-Reference

Returns:

True if successful, False otherwise

Return type:

bool

add_kill_chain_phase(**kwargs)[source]

Add a Kill-Chain-Phase object to stix_core_relationship object (kill_chain_phases).

Parameters:

id (str) – the id of the stix_core_relationship
kill_chain_phase_id (str) – the id of the Kill-Chain-Phase

Returns:

True if successful, False otherwise

Return type:

bool

add_label(**kwargs)[source]

Add a Label object to stix_core_relationship (labeling).

Parameters:

id (str) – the id of the stix_core_relationship
label_id (str) – the id of the Label
label_name (str) – (optional) the name of the Label (will create if not exists)

Returns:

True if successful, False otherwise

Return type:

bool

add_marking_definition(**kwargs)[source]

Add a Marking-Definition object to stix_core_relationship object (object_marking_refs).

Parameters:

id (str) – the id of the stix_core_relationship
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

create(**kwargs)[source]

Create a stix_core_relationship object.

Parameters:

fromId (str) – the id of the source entity
toId (str) – the id of the target entity
stix_id (str) – (optional) the STIX ID
relationship_type (str) – the type of relationship
description (str) – (optional) description
start_time (str) – (optional) start time of the relationship
stop_time (str) – (optional) stop time of the relationship
revoked (bool) – (optional) whether the relationship is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
killChainPhases (list) – (optional) list of kill chain phase IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
x_opencti_modified_at (str) – (optional) custom modification date
coverage_information (list) – (optional) coverage information
update (bool) – (optional) whether to update if exists (default: False)

Returns:

stix_core_relationship object

Return type:

dict or None

delete(**kwargs)[source]

Delete a stix_core_relationship.

Parameters:: id (str) – the stix_core_relationship id
Returns:: None

static generate_id(relationship_type, source_ref, target_ref, start_time=None, stop_time=None)[source]

Generate a STIX ID for a relationship.

Parameters:

relationship_type (str) – The type of relationship
source_ref (str) – The source entity reference ID
target_ref (str) – The target entity reference ID
start_time (str or datetime.datetime or None) – (optional) The start time of the relationship
stop_time (str or datetime.datetime or None) – (optional) The stop time of the relationship

Returns:

STIX ID for the relationship

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from relationship data.

Parameters:: data (dict) – Dictionary containing relationship_type, source_ref, target_ref, and optionally start_time/stop_time
Returns:: STIX ID for the relationship
Return type:: str

import_from_stix2(**kwargs)[source]

Import a stix_core_relationship from a STIX2 object.

Parameters:

stixRelation (dict) – the STIX2 relationship object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists
defaultDate (str or bool) – default date to use for start/stop times

Returns:

stix_core_relationship object

Return type:

dict or None

list(**kwargs)[source]

List stix_core_relationship objects.

Parameters:

fromOrToId (str) – the id of an entity (source or target)
elementWithTargetTypes (list) – filter by target types
fromId (str) – the id of the source entity of the relation
fromTypes (list) – filter by source entity types
toId (str) – the id of the target entity of the relation
toTypes (list) – filter by target entity types
relationship_type (str) – the relation type
startTimeStart (str) – the start_time date start filter
startTimeStop (str) – the start_time date stop filter
stopTimeStart (str) – the stop_time date start filter
stopTimeStop (str) – the stop_time date stop filter
filters (dict) – additional filters to apply
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
search (str) – search keyword

Returns:

List of stix_core_relationship objects

Return type:

list

organization_share(entity_id, organization_ids, sharing_direct_container)[source]

Share element to multiple organizations.

Parameters:

entity_id (str) – the stix_core_relationship id
organization_ids (list) – the organization IDs to share with
sharing_direct_container (bool) – whether to share direct container

Returns:

None

organization_unshare(entity_id, organization_ids, sharing_direct_container)[source]

Unshare element from multiple organizations.

Parameters:

entity_id (str) – the stix_core_relationship id
organization_ids (list) – the organization IDs to unshare from
sharing_direct_container (bool) – whether to unshare direct container

Returns:

None

read(**kwargs)[source]

Read a stix_core_relationship object.

Parameters:

id (str) – the id of the stix_core_relationship
fromOrToId (str) – the id of an entity (source or target)
fromId (str) – the id of the source entity of the relation
toId (str) – the id of the target entity of the relation
relationship_type (str) – the relation type
startTimeStart (str) – the start_time date start filter
startTimeStop (str) – the start_time date stop filter
stopTimeStart (str) – the stop_time date start filter
stopTimeStop (str) – the stop_time date stop filter
filters (dict) – filters to apply
customAttributes (str) – custom attributes to return

Returns:

stix_core_relationship object

Return type:

dict or None

remove_external_reference(**kwargs)[source]

Remove an External-Reference object from stix_core_relationship.

Parameters:

id (str) – the id of the stix_core_relationship
external_reference_id (str) – the id of the External-Reference

Returns:

True if successful, False otherwise

Return type:

bool

remove_from_draft(**kwargs)[source]

Remove a stix_core_relationship object from draft (revert).

Parameters:: id (str) – the stix_core_relationship id
Returns:: None

remove_kill_chain_phase(**kwargs)[source]

Remove a Kill-Chain-Phase object from stix_core_relationship.

Parameters:

id (str) – the id of the stix_core_relationship
kill_chain_phase_id (str) – the id of the Kill-Chain-Phase

Returns:

True if successful, False otherwise

Return type:

bool

remove_label(**kwargs)[source]

Remove a Label object from stix_core_relationship.

Parameters:

id (str) – the id of the stix_core_relationship
label_id (str) – the id of the Label
label_name (str) – (optional) the name of the Label

Returns:

True if successful, False otherwise

Return type:

bool

remove_marking_definition(**kwargs)[source]

Remove a Marking-Definition object from stix_core_relationship.

Parameters:

id (str) – the id of the stix_core_relationship
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

update_created_by(**kwargs)[source]

Update the Identity author of a stix_core_relationship (created_by).

Parameters:

id (str) – the id of the stix_core_relationship
identity_id (str) – the id of the Identity

Returns:

True if successful, False otherwise

Return type:

bool

update_field(**kwargs)[source]

Update a stix_core_relationship object field.

Parameters:

id (str) – the stix_core_relationship id
input (list) – the input of the field

Returns:

The updated stix_core_relationship object

Return type:

dict or None

class pycti.StixCyberObservable(opencti)[source]

Main StixCyberObservable class for OpenCTI

Manages STIX cyber observables (indicators of compromise) in the OpenCTI platform. Note: Deprecated methods are available through StixCyberObservableDeprecatedMixin.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixCyberObservable instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_external_reference(**kwargs)[source]

Add an External-Reference object to Stix-Cyber-Observable object.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
external_reference_id (str) – the id of the External-Reference

Returns:

True on success, False on failure

Return type:

bool

add_file(**kwargs)[source]

Upload a file in this Observable.

Parameters:

id (str) – the Stix-Cyber-Observable id
file_name (str) – name of the file to upload
data (bytes or str) – the file data
fileMarkings (list) – list of marking definition IDs for the file
version (str) – file version
mime_type (str) – MIME type of the file (default: text/plain)
no_trigger_import (bool) – whether to skip import trigger
embedded (bool) – whether the file is embedded

Returns:

updated StixCyberObservable object

Return type:

dict or None

add_label(**kwargs)[source]

Add a Label object to Stix-Cyber-Observable object.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
label_id (str) – the id of the Label
label_name (str) – the name of the Label (will create if not exists)

Returns:

True on success, False on failure

Return type:

bool

add_marking_definition(**kwargs)[source]

Add a Marking-Definition object to Stix-Cyber-Observable object (object_marking_refs).

Parameters:

id (str) – the id of the Stix-Cyber-Observable
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True on success, False on failure

Return type:

bool

ask_for_enrichment(**kwargs)[source]

Ask for enrichment of a Stix-Cyber-Observable.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
connector_id (str) – the id of the enrichment connector

Returns:

The work ID

Return type:

str

create(**kwargs)[source]

Create a Stix-Cyber-Observable object.

Parameters:

observableData (dict) – the data of the observable (STIX2 structure)
simple_observable_id (str) – (optional) simple observable STIX ID
simple_observable_key (str) – (optional) simple observable key (e.g., “IPv4-Addr.value”)
simple_observable_value (str) – (optional) simple observable value
simple_observable_description (str) – (optional) simple observable description
x_opencti_score (int) – (optional) score (0-100)
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
objectOrganization (list) – (optional) list of organization IDs
update (bool) – (optional) whether to update if exists (default: False)
resolve_result_indicators (bool) – (optional) resolve result indicators (default: True)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Stix-Cyber-Observable object

Return type:

dict or None

delete(**kwargs)[source]

Delete a Stix-Observable.

Parameters:: id (str) – the Stix-Observable id
Returns:: None
Return type:: None

list(**kwargs)[source]

List StixCyberObservable objects.

Parameters:

types (list) – the array of types
filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of StixCyberObservable objects

Return type:

list

notes(**kwargs)[source]

Get the notes about a Stix-Cyber-Observable object.

Parameters:: id (str) – the id of the Stix-Cyber-Observable
Returns:: List of notes
Return type:: list or None

observed_data(**kwargs)[source]

Get the observed data of a Stix-Cyber-Observable object.

Parameters:: id (str) – the id of the Stix-Cyber-Observable
Returns:: List of observed data
Return type:: list or None

promote_to_indicator_v2(**kwargs)[source]

Promote a Stix-Observable to an Indicator.

Parameters:

id (str) – the Stix-Observable id
customAttributes (str) – custom attributes to return for the indicator

Returns:

The newly created indicator

Return type:

dict or None

push_list_export(entity_id, entity_type, file_name, file_markings, data, list_filters='', mime_type=None)[source]

Push a list export for Stix-Cyber-Observables.

Parameters:

entity_id (str) – the entity ID
entity_type (str) – the entity type
file_name (str) – the file name
file_markings (list) – list of marking definition IDs for the file
data (bytes) – the file data
list_filters (str) – the list filters (default: “”)
mime_type (str) – the MIME type (optional)

Returns:

None

Return type:

None

read(**kwargs)[source]

Read a StixCyberObservable object.

Parameters:

id (str) – the id of the StixCyberObservable
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

StixCyberObservable object

Return type:

dict or None

remove_external_reference(**kwargs)[source]

Remove an External-Reference object from Stix-Cyber-Observable object.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
external_reference_id (str) – the id of the External-Reference

Returns:

True on success, False on failure

Return type:

bool

remove_label(**kwargs)[source]

Remove a Label object from Stix-Cyber-Observable object.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
label_id (str) – the id of the Label
label_name (str) – the name of the Label (alternative to label_id)

Returns:

True on success, False on failure

Return type:

bool

remove_marking_definition(**kwargs)[source]

Remove a Marking-Definition object from Stix-Cyber-Observable object.

Parameters:

id (str) – the id of the Stix-Cyber-Observable
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True on success, False on failure

Return type:

bool

reports(**kwargs)[source]

Get the reports about a Stix-Cyber-Observable object.

Parameters:: id (str) – the id of the Stix-Cyber-Observable
Returns:: List of reports
Return type:: list or None

update_created_by(**kwargs)[source]

Update the Identity author of a Stix-Cyber-Observable object (created_by).

Parameters:

id (str) – the id of the Stix-Cyber-Observable
identity_id (str) – the id of the Identity

Returns:

True on success, False on failure

Return type:

bool

update_field(**kwargs)[source]

Update a Stix-Observable object field.

Parameters:

id (str) – the Stix-Observable id
input (list) – the input of the field to update

Returns:

The updated Stix-Observable object

Return type:

dict or None

upload_artifact(**kwargs)[source]

Upload an artifact.

Parameters:

file_name (str) – the file name or path
data (bytes) – the file data (optional, reads from file_name if not provided)
mime_type (str) – the MIME type (default: text/plain)
x_opencti_description (str) – description for the artifact
createdBy (str) – the author ID
objectMarking (list) – list of marking definition IDs
objectLabel (list) – list of label IDs
createIndicator (bool) – whether to create an indicator (default: False)

Returns:

Stix-Observable object

Return type:

dict or None

class pycti.StixNestedRefRelationship(opencti)[source]

Main StixNestedRefRelationship class for OpenCTI

Manages nested reference relationships in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixNestedRefRelationship instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a stix nested ref relationship object.

Parameters:

fromId (str) – the id of the source entity
toId (str) – the id of the target entity
relationship_type (str) – the type of the relationship
start_time (str) – (optional) the start time of the relationship
stop_time (str) – (optional) the stop time of the relationship
stix_id (str) – (optional) the STIX ID
created (str) – (optional) creation date
modified (str) – (optional) modification date
createdBy (str) – (optional) the creator ID
objectMarking (list) – (optional) list of marking definition IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
update (bool) – (optional) whether to update if exists

Returns:

stix nested ref relationship object

Return type:

dict

list(**kwargs)[source]

List stix nested ref relationship objects.

Parameters:

fromOrToId (str) – the id of either the source or target entity
fromId (str) – the id of the source entity of the relation
fromTypes (list) – the types of the source entities
toId (str) – the id of the target entity of the relation
toTypes (list) – the types of the target entities
relationship_type (str) – the relation type
startTimeStart (str) – the first_seen date start filter
startTimeStop (str) – the first_seen date stop filter
stopTimeStart (str) – the last_seen date start filter
stopTimeStop (str) – the last_seen date stop filter
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination

Returns:

List of stix nested ref relationship objects

Return type:

list

read(**kwargs)[source]

Read a stix nested ref relationship object.

Parameters:

id (str) – the id of the stix nested ref relationship
fromOrToId (str) – the id of either the source or target entity
fromId (str) – the id of the source entity of the relation
toId (str) – the id of the target entity of the relation
relationship_type (str) – the relation type
startTimeStart (str) – the first_seen date start filter
startTimeStop (str) – the first_seen date stop filter
stopTimeStart (str) – the last_seen date start filter
stopTimeStop (str) – the last_seen date stop filter
customAttributes (str) – custom attributes to return
filters (dict) – the filters to apply

Returns:

stix nested ref relationship object

Return type:

dict or None

update_field(**kwargs)[source]

Update a stix nested ref relationship object field.

Parameters:

id (str) – the stix nested ref relationship id
input (list) – the input of the field to update

Returns:

The updated stix nested ref relationship object

Return type:

dict or None

class pycti.StixCyberObservableTypes(*values)[source]

Enumeration of STIX Cyber Observable types supported by OpenCTI.

Inheritance

class pycti.StixDomainObject(opencti)[source]

Main StixDomainObject class for OpenCTI

Manages STIX Domain Objects in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixDomainObject instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_external_reference(**kwargs)[source]

Add an External-Reference object to Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
external_reference_id (str) – the id of the External-Reference

Returns:

True if successful, False otherwise

Return type:

bool

add_file(**kwargs)[source]

Upload a file to this Stix-Domain-Object.

Parameters:

id (str) – the Stix-Domain-Object id
file_name (str) – the file name or path
data (bytes or None) – the file data (optional, will read from file_name if not provided)
fileMarkings (list) – list of marking definition IDs for the file
version (str) – version datetime
mime_type (str) – MIME type of the file
no_trigger_import (bool) – whether to skip triggering import
embedded (bool) – whether the file is embedded

Returns:

File upload result

Return type:

dict or None

add_kill_chain_phase(**kwargs)[source]

Add a Kill-Chain-Phase object to Stix-Domain-Object object (kill_chain_phases).

Parameters:

id (str) – the id of the Stix-Domain-Object
kill_chain_phase_id (str) – the id of the Kill-Chain-Phase

Returns:

True if successful, False otherwise

Return type:

bool

add_label(**kwargs)[source]

Add a Label object to Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
label_id (str) – the id of the Label
label_name (str) – the name of the Label (alternative to label_id)

Returns:

True if successful, False otherwise

Return type:

bool

add_marking_definition(**kwargs)[source]

Add a Marking-Definition object to Stix-Domain-Object object (object_marking_refs).

Parameters:

id (str) – the id of the Stix-Domain-Object
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

delete(**kwargs)[source]

Delete a Stix-Domain-Object.

Parameters:: id (str) – the Stix-Domain-Object id
Returns:: None

get_by_stix_id_or_name(**kwargs)[source]

Get a Stix-Domain-Object object by stix_id or name.

Parameters:

types (list) – a list of Stix-Domain-Object types
stix_id (str) – the STIX ID of the Stix-Domain-Object
name (str) – the name of the Stix-Domain-Object
aliases (list) – list of aliases to search
fieldName (str) – the field name to use for alias search
customAttributes (str) – custom attributes to return

Returns:

Stix-Domain-Object object

Return type:

dict or None

list(**kwargs)[source]

List Stix-Domain-Object objects.

Parameters:

types (list) – the list of types
filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
withFiles (bool) – whether to include files

Returns:

List of Stix-Domain-Object objects

Return type:

list

notes(**kwargs)[source]

Get the notes about a Stix-Domain-Object object.

Parameters:: id (str) – the id of the Stix-Domain-Object
Returns:: List of notes
Return type:: list or None

observed_data(**kwargs)[source]

Get the observed data of a Stix-Domain-Object object.

Parameters:: id (str) – the id of the Stix-Domain-Object
Returns:: List of observed data
Return type:: list or None

push_entity_export(entity_id, file_name, data, file_markings=None, mime_type=None)[source]

Push an entity export file.

Parameters:

entity_id (str) – the entity id
file_name (str) – the file name
data (bytes or str) – the file data
file_markings (list or None) – list of marking definition IDs
mime_type (str or None) – MIME type of the file

Returns:

None

push_list_export(entity_id, entity_type, file_name, file_markings, data, list_filters='', mime_type=None)[source]

Push a list export file.

Parameters:

entity_id (str) – the entity id
entity_type (str) – the entity type
file_name (str) – the file name
file_markings (list) – list of marking definition IDs
data (bytes or str) – the file data
list_filters (str) – filters applied to the list export
mime_type (str or None) – MIME type of the file

Returns:

None

read(**kwargs)[source]

Read a Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
types (list) – list of Stix Domain Entity types
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return
withFiles (bool) – whether to include files

Returns:

Stix-Domain-Object object

Return type:

dict or None

remove_external_reference(**kwargs)[source]

Remove an External-Reference object from Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
external_reference_id (str) – the id of the External-Reference

Returns:

True if successful, False otherwise

Return type:

bool

remove_kill_chain_phase(**kwargs)[source]

Remove a Kill-Chain-Phase object from Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
kill_chain_phase_id (str) – the id of the Kill-Chain-Phase

Returns:

True if successful, False otherwise

Return type:

bool

remove_label(**kwargs)[source]

Remove a Label object from Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
label_id (str) – the id of the Label
label_name (str) – the name of the Label (alternative to label_id)

Returns:

True if successful, False otherwise

Return type:

bool

remove_marking_definition(**kwargs)[source]

Remove a Marking-Definition object from Stix-Domain-Object object.

Parameters:

id (str) – the id of the Stix-Domain-Object
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

reports(**kwargs)[source]

Get the reports about a Stix-Domain-Object object.

Parameters:: id (str) – the id of the Stix-Domain-Object
Returns:: List of reports
Return type:: list or None

update_created_by(**kwargs)[source]

Update the Identity author of a Stix-Domain-Object object (created_by).

Parameters:

id (str) – the id of the Stix-Domain-Object
identity_id (str) – the id of the Identity

Returns:

True if successful, False otherwise

Return type:

bool

update_field(**kwargs)[source]

Update a Stix-Domain-Object object field.

Parameters:

id (str) – the Stix-Domain-Object id
input (list) – the input of the field

Returns:

Updated Stix-Domain-Object object

Return type:

dict or None

class pycti.StixMetaTypes(*values)[source]

Enumeration of STIX Meta Object types supported by OpenCTI.

Inheritance

class pycti.MultipleRefRelationship(*values)[source]

Enumeration of relationship types that can have multiple references.

Inheritance

class pycti.StixObjectOrStixRelationship(opencti)[source]

Main StixObjectOrStixRelationship class for OpenCTI

Manages generic STIX objects and relationships in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixObjectOrStixRelationship instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

list(**kwargs)[source]

List StixObjectOrStixRelationship objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
getAll (bool) – whether to retrieve all results
with_pagination (bool) – whether to include pagination info
customAttributes (str) – custom attributes to return

Returns:

List of StixObjectOrStixRelationship objects

Return type:

list

read(**kwargs)[source]

Read a StixObjectOrStixRelationship object.

Parameters:

id (str) – the id of the StixObjectOrStixRelationship
customAttributes (str) – custom attributes to return
filters (dict) – the filters to apply

Returns:

StixObjectOrStixRelationship object

Return type:

dict or None

class pycti.StixSightingRelationship(opencti)[source]

Main StixSightingRelationship class for OpenCTI

Manages STIX sighting relationships in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the StixSightingRelationship instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_marking_definition(**kwargs)[source]

Add a Marking-Definition object to stix_sighting_relationship object (object_marking_refs).

Parameters:

id (str) – the id of the stix_sighting_relationship
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

create(**kwargs)[source]

Create a stix_sighting_relationship object.

Parameters:

fromId (str) – the id of the source entity
toId (str) – the id of the target entity
stix_id (str) – (optional) the STIX ID
description (str) – (optional) description
first_seen (str) – (optional) first seen date
last_seen (str) – (optional) last seen date
count (int) – (optional) sighting count
x_opencti_negative (bool) – (optional) whether this is a negative sighting
created (str) – (optional) creation date
modified (str) – (optional) modification date
confidence (int) – (optional) confidence level (0-100)
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
objectOrganization (list) – (optional) list of organization IDs
update (bool) – (optional) whether to update if exists (default: False)

Returns:

stix_sighting_relationship object

Return type:

dict or None

delete(**kwargs)[source]

Delete a stix_sighting_relationship.

Parameters:: id (str) – the stix_sighting_relationship id
Returns:: None

static generate_id(sighting_of_ref, where_sighted_refs, first_seen=None, last_seen=None)[source]

Generate a STIX ID for a Sighting relationship.

Parameters:

sighting_of_ref (str) – The STIX ID of the entity being sighted
where_sighted_refs (list) – The STIX IDs of where the sighting occurred
first_seen (str or datetime.datetime or None) – (optional) The first seen date
last_seen (str or datetime.datetime or None) – (optional) The last seen date

Returns:

STIX ID for the sighting

Return type:

str

static generate_id_from_data(data)[source]

Generate a STIX ID from sighting data.

Parameters:: data (dict) – Dictionary containing sighting_of_ref, where_sighted_refs, and optionally first_seen/last_seen
Returns:: STIX ID for the sighting
Return type:: str

list(**kwargs)[source]

List stix_sighting_relationship objects.

Parameters:

fromOrToId (str) – the id of an entity (source or target)
fromId (str) – the id of the source entity of the relation
fromTypes (list) – filter by source entity types
toId (str) – the id of the target entity of the relation
toTypes (list) – filter by target entity types
firstSeenStart (str) – the first_seen date start filter
firstSeenStop (str) – the first_seen date stop filter
lastSeenStart (str) – the last_seen date start filter
lastSeenStop (str) – the last_seen date stop filter
filters (dict) – additional filters to apply
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info
search (str) – search keyword

Returns:

List of stix_sighting_relationship objects

Return type:

list

organization_share(entity_id, organization_ids, sharing_direct_container)[source]

Share element to multiple organizations.

Parameters:

entity_id (str) – the stix_sighting_relationship id
organization_ids (list) – the organization IDs to share with
sharing_direct_container (bool) – whether to share direct container

Returns:

None

organization_unshare(entity_id, organization_ids, sharing_direct_container)[source]

Unshare element from multiple organizations.

Parameters:

entity_id (str) – the stix_sighting_relationship id
organization_ids (list) – the organization IDs to unshare from
sharing_direct_container (bool) – whether to unshare direct container

Returns:

None

read(**kwargs)[source]

Read a stix_sighting_relationship object.

Parameters:

id (str) – the id of the stix_sighting_relationship
fromOrToId (str) – the id of an entity (source or target)
fromId (str) – the id of the source entity of the relation
toId (str) – the id of the target entity of the relation
firstSeenStart (str) – the first_seen date start filter
firstSeenStop (str) – the first_seen date stop filter
lastSeenStart (str) – the last_seen date start filter
lastSeenStop (str) – the last_seen date stop filter
customAttributes (str) – custom attributes to return
filters (dict) – filters to apply

Returns:

stix_sighting_relationship object

Return type:

dict or None

remove_from_draft(**kwargs)[source]

Remove a stix_sighting_relationship object from draft (revert).

Parameters:: id (str) – the stix_sighting_relationship id
Returns:: None

remove_marking_definition(**kwargs)[source]

Remove a Marking-Definition object from stix_sighting_relationship.

Parameters:

id (str) – the id of the stix_sighting_relationship
marking_definition_id (str) – the id of the Marking-Definition

Returns:

True if successful, False otherwise

Return type:

bool

update_created_by(**kwargs)[source]

Update the Identity author of a stix_sighting_relationship object (created_by).

Parameters:

id (str) – the id of the stix_sighting_relationship
identity_id (str) – the id of the Identity

Returns:

True if successful, False otherwise

Return type:

bool

update_field(**kwargs)[source]

Update a stix_sighting_relationship object field.

Parameters:

id (str) – the stix_sighting_relationship id
input (list) – the input of the field

Returns:

The updated stix_sighting_relationship object

Return type:

dict or None

class pycti.ThreatActor(opencti)[source]

Main ThreatActor class for OpenCTI

Manages threat actor entities (groups and individuals) in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the ThreatActor instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]: Create a Threat-Actor-Group object (deprecated).

Deprecated since version Use: threat_actor_group.create() or threat_actor_individual.create() instead.

static generate_id(name, opencti_type)[source]

Generate a STIX ID for a Threat Actor.

Parameters:

name (str) – the name of the Threat Actor
opencti_type (str) – the type of the Threat Actor (e.g., ‘Threat-Actor-Group’)

Returns:

STIX ID for the Threat Actor

Return type:

str

generate_id_from_data(data)[source]

Generate a STIX ID from Threat Actor data.

Parameters:: data (dict) – Dictionary containing ‘name’ and optionally ‘x_opencti_type’ keys
Returns:: STIX ID for the Threat Actor
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Threat-Actor object from a STIX2 object.

Parameters:: stixObject (dict) – the STIX2 Threat-Actor object
Returns:: Threat-Actor object
Return type:: dict or None

list(**kwargs)[source]

List Threat-Actor objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info

Returns:

List of Threat-Actor objects

Return type:

list

read(**kwargs)[source]

Read a Threat-Actor object.

Parameters:

id (str) – the id of the Threat-Actor
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return

Returns:

Threat-Actor object

Return type:

dict or None

class pycti.ThreatActorGroup(opencti)[source]

Main ThreatActorGroup class for OpenCTI

Manages threat actor group entities in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the ThreatActorGroup instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Threat-Actor-Group object

The Threat-Actor-Group entity will only be created if it doesn’t exists By setting update to True it acts like an upsert and updates fields of an existing Threat-Actor-Group entity.

Note: name and description or stix_id is required.

Parameters:

stix_id (str) – stix2 id reference for the Threat-Actor-Group entity
createdBy (str) – (optional) id of the organization that created the knowledge
objectMarking (list) – (optional) list of OpenCTI marking definition ids
objectLabel (list) – (optional) list of OpenCTI label ids
externalReferences (list) – (optional) list of OpenCTI external references ids
revoked (bool) – is this entity revoked
confidence (int) – confidence level
lang (str) – language
created (str) – (optional) date in OpenCTI date format
modified (str) – (optional) date in OpenCTI date format
name (str) – name of the threat actor group
description (str) – description of the threat actor group
aliases (list) – (optional) list of alias names for the Threat-Actor-Group
threat_actor_types (list) – (optional) list of threat actor types
first_seen (str) – (optional) date in OpenCTI date format
last_seen (str) – (optional) date in OpenCTI date format
roles (list) – (optional) list of roles
goals (list) – (optional) list of goals
sophistication (str) – (optional) describe the actors sophistication in text
resource_level (str) – (optional) describe the actors resource_level in text
primary_motivation (str) – (optional) describe the actors primary_motivation in text
secondary_motivations (list) – (optional) describe the actors secondary_motivations in list of string
personal_motivations (list) – (optional) describe the actors personal_motivations in list of strings
update (bool) – (optional) choose to updated an existing Threat-Actor-Group entity, default False
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Threat-Actor-Group object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Threat Actor Group.

Parameters:: name (str) – The name of the threat actor group
Returns:: STIX ID for the threat actor group
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from threat actor group data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the threat actor group
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Threat Actor Group object from a STIX2 object.

Parameters:

stixObject – the STIX2 Threat Actor object
extras – extra parameters including created_by_id, object_marking_ids, etc.
update – whether to update if the entity already exists

Returns:

Threat Actor Group object

Return type:

dict or None

list(**kwargs)[source]

List Threat-Actor-Group objects

Parameters:

filters (list) – (optional) the filters to apply
search (str) – (optional) a search keyword to apply for the listing
first (int) – (optional) return the first n rows from the after ID or the beginning if not set
after (str) – (optional) OpenCTI object ID of the first row for pagination
orderBy (str) – (optional) the field to order the response on
orderMode (str) – (optional) either “asc” or “desc”
withPagination (bool) – (optional) switch to use pagination

Returns:

List of Threat-Actor-Group objects

Return type:

list

read(**kwargs)[source]

Read a Threat-Actor-Group object

read can be either used with a known OpenCTI entity id or by using a valid filter to search and return a single Threat-Actor-Group entity or None.

Note: either id or filters is required.

Parameters:

id (str) – the id of the Threat-Actor-Group
filters (list) – the filters to apply if no id provided

Returns:

Threat-Actor-Group object

Return type:

dict or None

class pycti.ThreatActorIndividual(opencti)[source]

Main ThreatActorIndividual class for OpenCTI

Manages individual threat actor entities in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the ThreatActorIndividual instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Threat-Actor-Individual object

The Threat-Actor-Individual entity will only be created if it doesn’t exists By setting update to True it acts like an upsert and updates fields of an existing Threat-Actor-Individual entity.

Note: name and description or stix_id is required.

Parameters:

stix_id (str) – stix2 id reference for the Threat-Actor-Individual entity
createdBy (str) – (optional) id of the organization that created the knowledge
objectMarking (list) – (optional) list of OpenCTI marking definition ids
objectLabel (list) – (optional) list of OpenCTI label ids
externalReferences (list) – (optional) list of OpenCTI external references ids
revoked (bool) – is this entity revoked
confidence (int) – confidence level
lang (str) – language
created (str) – (optional) date in OpenCTI date format
modified (str) – (optional) date in OpenCTI date format
name (str) – name of the threat actor individual
description (str) – description of the threat actor individual
aliases (list) – (optional) list of alias names for the Threat-Actor-Individual
threat_actor_types (list) – (optional) list of threat actor types
first_seen (str) – (optional) date in OpenCTI date format
last_seen (str) – (optional) date in OpenCTI date format
roles (list) – (optional) list of roles
goals (list) – (optional) list of goals
sophistication (str) – (optional) describe the actors sophistication in text
resource_level (str) – (optional) describe the actors resource_level in text
primary_motivation (str) – (optional) describe the actors primary_motivation in text
secondary_motivations (list) – (optional) describe the actors secondary_motivations in list of string
personal_motivations (list) – (optional) describe the actors personal_motivations in list of strings
update (bool) – (optional) choose to updated an existing Threat-Actor-Individual entity, default False
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Threat-Actor-Individual object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Threat Actor Individual.

Parameters:: name (str) – The name of the threat actor individual
Returns:: STIX ID for the threat actor individual
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from threat actor individual data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the threat actor individual
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Threat-Actor-Individual object from a STIX2 object.

Parameters:

stixObject – the STIX2 Threat-Actor-Individual object
extras – extra parameters including created_by_id, object_marking_ids, files, filesMarkings, etc.
update – whether to update if the entity already exists

Returns:

Threat-Actor-Individual object

Return type:

dict or None

list(**kwargs)[source]

List Threat-Actor-Individual objects

The list method accepts the following kwargs:

Parameters:

filters (list) – (optional) the filters to apply
search (str) – (optional) a search keyword to apply for the listing
first (int) – (optional) return the first n rows from the after ID or the beginning if not set
after (str) – (optional) OpenCTI object ID of the first row for pagination
orderBy (str) – (optional) the field to order the response on
orderMode (str) – (optional) either “asc” or “desc”
withPagination (bool) – (optional) switch to use pagination

Returns:

List of Threat-Actor-Individual objects

Return type:

list

read(**kwargs)[source]

Read a Threat-Actor-Individual object

read can be either used with a known OpenCTI entity id or by using a valid filter to search and return a single Threat-Actor-Individual entity or None.

Note: either id or filters is required.

Parameters:

id (str) – the id of the Threat-Actor-Individual
filters (list) – the filters to apply if no id provided

Returns:

Threat-Actor-Individual object

Return type:

dict or None

class pycti.Tool(opencti)[source]

Main Tool class for OpenCTI

Manages tools used by threat actors in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Tool instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Tool object.

Parameters:

stix_id (str) – (optional) the STIX ID
name (str) – the name of the Tool (required)
description (str) – description of the tool
aliases (list) – list of aliases
tool_types (list) – types of tool
tool_version (str) – version of the tool
killChainPhases (list) – kill chain phases
createdBy (str) – creator identity ID
objectMarking (list) – marking definition IDs
objectLabel (list) – label IDs
externalReferences (list) – external reference IDs
objectOrganization (list) – organization IDs
revoked (bool) – whether the tool is revoked
confidence (int) – confidence level (0-100)
lang (str) – language
created (str) – creation date
modified (str) – modification date
x_opencti_stix_ids (list) – additional STIX IDs
x_opencti_workflow_id (str) – workflow ID
x_opencti_modified_at (str) – custom modification date
update (bool) – whether to update existing tool
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Tool object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Tool.

Parameters:: name (str) – The name of the tool
Returns:: STIX ID for the tool
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from tool data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the tool
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Tool object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Tool object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Tool object

Return type:

dict or None

list(**kwargs)[source]

List Tool objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info

Returns:

List of Tool objects

Return type:

list

read(**kwargs)[source]

Read a Tool object.

Parameters:

id (str) – the id of the Tool
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return

Returns:

Tool object

Return type:

dict or None

class pycti.Vulnerability(opencti)[source]

Main Vulnerability class for OpenCTI

Manages vulnerability information including CVE data in the OpenCTI platform.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Vulnerability instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

create(**kwargs)[source]

Create a Vulnerability object.

Parameters:

name (str) – the name of the Vulnerability (required)
stix_id (str) – (optional) the STIX ID
createdBy (str) – (optional) the author ID
objectMarking (list) – (optional) list of marking definition IDs
objectLabel (list) – (optional) list of label IDs
externalReferences (list) – (optional) list of external reference IDs
revoked (bool) – (optional) whether the vulnerability is revoked
confidence (int) – (optional) confidence level (0-100)
lang (str) – (optional) language
created (str) – (optional) creation date
modified (str) – (optional) modification date
description (str) – (optional) description
x_opencti_aliases (list) – (optional) list of aliases
x_opencti_cvss_vector_string (str) – (optional) CVSS v3 vector string
x_opencti_cvss_base_score (float) – (optional) CVSS v3 base score
x_opencti_cvss_base_severity (str) – (optional) CVSS v3 base severity
x_opencti_cwe (str) – (optional) CWE ID
x_opencti_cisa_kev (bool) – (optional) CISA KEV flag
x_opencti_epss_score (float) – (optional) EPSS score
x_opencti_epss_percentile (float) – (optional) EPSS percentile
x_opencti_score (int) – (optional) OpenCTI score
x_opencti_first_seen_active (str) – (optional) first seen active date
x_opencti_stix_ids (list) – (optional) list of additional STIX IDs
objectOrganization (list) – (optional) list of organization IDs
x_opencti_workflow_id (str) – (optional) workflow ID
x_opencti_modified_at (str) – (optional) custom modification date
update (bool) – (optional) whether to update if exists (default: False)
files (list) – (optional) list of File objects to attach
filesMarkings (list) – (optional) list of lists of marking definition IDs for each file

Returns:

Vulnerability object

Return type:

dict or None

static generate_id(name)[source]

Generate a STIX ID for a Vulnerability.

Parameters:: name (str) – The name of the vulnerability (e.g., CVE ID)
Returns:: STIX ID for the vulnerability
Return type:: str

static generate_id_from_data(data)[source]

Generate a STIX ID from vulnerability data.

Parameters:: data (dict) – Dictionary containing ‘name’ key
Returns:: STIX ID for the vulnerability
Return type:: str

import_from_stix2(**kwargs)[source]

Import a Vulnerability object from a STIX2 object.

Parameters:

stixObject (dict) – the STIX2 Vulnerability object
extras (dict) – extra parameters including created_by_id, object_marking_ids, etc.
update (bool) – whether to update if the entity already exists

Returns:

Vulnerability object

Return type:

dict or None

list(**kwargs)[source]

List Vulnerability objects.

Parameters:

filters (dict) – the filters to apply
search (str) – the search keyword
first (int) – return the first n rows from the after ID (or the beginning if not set)
after (str) – ID of the first row for pagination
orderBy (str) – field to order results by
orderMode (str) – ordering mode (asc/desc)
customAttributes (str) – custom attributes to return
getAll (bool) – whether to retrieve all results
withPagination (bool) – whether to include pagination info

Returns:

List of Vulnerability objects

Return type:

list

read(**kwargs)[source]

Read a Vulnerability object.

Parameters:

id (str) – the id of the Vulnerability
filters (dict) – the filters to apply if no id provided
customAttributes (str) – custom attributes to return

Returns:

Vulnerability object

Return type:

dict or None

class pycti.CustomObjectCaseIncident

Custom STIX2 Case-Incident object for OpenCTI.

Represents a case-incident container with associated metadata including name, description, severity, priority, and response types.

Parameters:

name (str) – Name of the case incident (required)
spec_version (str) – STIX specification version, fixed to “2.1”
description (str) – Description of the case incident
severity (str) – Severity level of the incident
priority (str) – Priority level of the incident
response_types (list) – List of response types
x_opencti_workflow_id (str) – OpenCTI workflow identifier
x_opencti_assignee_ids (list) – List of assignee identifiers
external_references (list) – List of external references
object_refs (list) – List of referenced STIX objects

Inheritance

class pycti.CustomObjectTask

Custom STIX2 Task object for OpenCTI.

Represents a task with associated metadata including name, description, due date, and assignees.

Parameters:

name (str) – Name of the task (required)
spec_version (str) – STIX specification version, fixed to “2.1”
description (str) – Description of the task
due_date (datetime) – Due date timestamp for the task
x_opencti_workflow_id (str) – OpenCTI workflow identifier
x_opencti_assignee_ids (list) – List of assignee identifiers
object_refs (list) – List of referenced STIX objects

Inheritance

class pycti.CustomObjectChannel

Custom STIX2 Channel object for OpenCTI.

Represents a communication channel with associated metadata including name, description, aliases, and channel types.

Parameters:

name (str) – Name of the channel (required)
spec_version (str) – STIX specification version, fixed to “2.1”
description (str) – Description of the channel
aliases (list) – List of alternative names for the channel
channel_types (list) – List of channel types
x_opencti_workflow_id (str) – OpenCTI workflow identifier
x_opencti_assignee_ids (list) – List of assignee identifiers
external_references (list) – List of external references

Inheritance

class pycti.CustomObservableCredential

Custom STIX2 Credential observable for OpenCTI.

Represents a credential cyber observable such as a password or access token.

Parameters:

value (str) – The credential value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableHostname

Custom STIX2 Hostname observable for OpenCTI.

Represents a hostname cyber observable with its associated value.

Parameters:

value (str) – The hostname value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableUserAgent

Custom STIX2 User-Agent observable for OpenCTI.

Represents a User-Agent string cyber observable from HTTP headers.

Parameters:

value (str) – The User-Agent string value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableBankAccount

Custom STIX2 Bank Account observable for OpenCTI.

Represents a bank account cyber observable with account details.

Parameters:

value (str) – Display value for the bank account (required)
iban (str) – International Bank Account Number (required)
bic (str) – Bank Identifier Code
account_number (str) – Bank account number
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableCryptocurrencyWallet

Custom STIX2 Cryptocurrency Wallet observable for OpenCTI.

Represents a cryptocurrency wallet address cyber observable.

Parameters:

value (str) – The wallet address value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservablePaymentCard

Custom STIX2 Payment Card observable for OpenCTI.

Represents a payment card cyber observable with card details.

Parameters:

value (str) – Display value for the payment card (required)
card_number (str) – The payment card number (required)
expiration_date (str) – Card expiration date
cvv (str) – Card verification value
holder_name (str) – Name of the card holder
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservablePhoneNumber

Custom STIX2 Phone Number observable for OpenCTI.

Represents a phone number cyber observable.

Parameters:

value (str) – The phone number value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableTrackingNumber

Custom STIX2 Tracking Number observable for OpenCTI.

Represents a tracking number cyber observable (e.g., package tracking).

Parameters:

value (str) – The tracking number value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableText

Custom STIX2 Text observable for OpenCTI.

Represents a generic text cyber observable with its associated value.

Parameters:

value (str) – The text value (required)
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.CustomObservableMediaContent

Custom STIX2 Media-Content observable for OpenCTI.

Represents a media content cyber observable such as articles or posts.

Parameters:

title (str) – Title of the media content
description (str) – Description of the media content
content (str) – The actual content body
media_category (str) – Category of the media
url (str) – URL of the media content (required)
publication_date (datetime) – Publication date timestamp
spec_version (str) – STIX specification version, fixed to “2.1”
object_marking_refs (list) – List of marking definition references

Inheritance

class pycti.Capability(opencti)[source]

Represents a role capability on the OpenCTI platform

See the properties attribute to understand which properties are fetched by default from the graphql queries.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Capability instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

list(**kwargs)[source]

Lists all capabilities available on the platform

Parameters:: customAttributes (str, optional) – Custom attributes to retrieve from the GraphQL query.
Returns:: List of capabilities
Return type:: List[Dict]

class pycti.Role(opencti)[source]

Representation of a role in OpenCTI

Roles can have capabilities. Groups have roles, and the combined capabilities of those roles determine what a group of users can do on the platform.

Check the properties attribute of the class to understand what default properties are fetched.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Role instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_capability(**kwargs)[source]

Adds a capability to a role

Parameters:

id (str) – ID of the role.
capability_id (str) – ID of the capability to add.

Returns:

Representation of the relationship, including the role and capability

Return type:

Optional[Dict]

create(**kwargs)[source]

Add a new role to OpenCTI.

Parameters:

name (str) – Name to assign to the role.
description (str, optional) – Optional. Description of the role, defaults to None.
customAttributes (str, optional) – Custom attributes to return on role

Returns:

Representation of the role.

Return type:

Optional[Dict]

delete(**kwargs)[source]

Delete a role given its ID

Parameters:: id (str) – ID for the role on the platform.

delete_capability(**kwargs)[source]

Removes a capability from a role

Parameters:

id (str) – ID of the role
capability_id (str) – ID of the capability to remove

Returns:

Representation of the role after removing the capability

Return type:

Optional[Dict]

list(**kwargs)[source]

Search or list the roles on the server.

Parameters:

search (str, optional) – Defaults to None.
first (int, optional) – Defaults to 500 Return the first x results from ID or beginning if $after is not specified.
after (str, optional) – Return all results after the given ID, useful for pagination. Ignored if returning all results, defaults to None.
orderBy (str, optional) – Field to order by. Must be one of “name”, “created_at”, “updated_at”, or “_score”. Defaults to “name”, defaults to “name”.
orderMode (str, optional) – Direction to order in, either “asc” or “desc”, defaults to “asc”.
customAttributes (str, optional) – Defaults to None. Custom attributes to return from query. If None, defaults are used.
getAll (bool, optional) – Defaults to False. Retrieve all results. If true then the “first” param is ignored.
withPagination (bool, optional) – Defaults to False Whether to include pagination pageInfo properties in result.

Returns:

List of Python dictionaries with the properties of the role.

Return type:

List[Dict]

process_multiple_fields(data)[source]

Process and normalize fields in role data.

Parameters:: data (dict) – the role data dictionary to process
Returns:: the processed role data with normalized fields
Return type:: dict

read(**kwargs)[source]

Get a role given its ID or a search term

One of id or search must be provided.

Parameters:

id (str, optional) – ID of the role on the platform
search (str, optional) – Search term for a role, e.g. its name
customAttributes (str, optional) – Custom attributes on the role to return

Returns:

Representation of the role

Return type:

Optional[Dict]

update_field(**kwargs)[source]

Updates a given role with the given inputs

Example of input:

[
    {
        "key": "name",
        "value": "NewCustomRole"
    },
    {
        "key": "can_manage_sensitive_config",
        "value": False
    }
]

Parameters:

id (str) – ID for the role on the platform
input (List[Dict]) – List of EditInput objects
customAttributes (str, optional) – Custom attributes to return on the role

Returns:

Representation of the role

Return type:

Optional[Dict]

class pycti.Group(opencti)[source]

Representation of a Group in OpenCTI

Groups have members and also have assigned roles. Roles attached to a group determine what members of the group have permissions to do according to the capabilities the role has.

Additionally, groups have a confidence level which informs the effective confidence of members of the group.

Groups also have permissions on Marking Definitions. Assigned marking definitions allow users to apply their capabilities on objects with those definitions. Additionally, there are default markings added to all objects created by members of a group, and max shareable definitions which determine which objects users can export from the platform to share.

See the properties attribute to understand what properties are fetched by default from GraphQL queries.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Group instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_allowed_marking(**kwargs)[source]

Allow a group to access a marking

Parameters:

id (str) – ID of group to authorise
marking_id (str) – ID of marking to authorise

Returns:

Relationship from the group to the marking definition

Return type:

Optional[Dict]

add_member(**kwargs)[source]

Add a member to a given group.

Parameters:

id (str) – ID of the group to add a member to
user_id (str) – ID to add to the group

Returns:

Representation of the relationship

Return type:

Optional[Dict]

add_role(**kwargs)[source]

Add a role to a given group

Parameters:

id (str) – ID to add a role to
role_id – Role ID to add to the group

Returns:

Representation of the group after a role has been added

Return type:

Optional[Dict]

create(**kwargs)[source]

Create a group with required details

Groups can be configured after creation using other functions.

Parameters:

name (str) – Name of the group to create.
id_confidence_level (dict) – Confidence-level dictionary, with a max_confidence member between 0 and 100 (incl) and an overrides list with max_confidence and the entity_type it applies to.
description (str, optional) – Description of the group
default_assignation (bool, optional) – Defaults to False. Whether or not to assign this group by default to all new users.
no_creators (bool, optional) – Defaults to False. Whether or not to create authors for members of this group.
restrict_delete (bool, optional) – Defaults to False. Whether or not to restrict members deleting entities that are not their own.
auto_new_marking (bool, optional) – Defaults to False. Whether or not to allow members access to new markings automatically.
customAttributes (str, optional) – Attributes to retrieve from the new group

Returns:

Representation of the group.

Return type:

Optional[Dict]

delete(**kwargs)[source]

Delete a given group from OpenCTI

Parameters:: id (str) – ID of the group to delete.

delete_allowed_marking(**kwargs)[source]

Removes access to a marking for a group

Parameters:

id (str) – ID of group to forbid
marking_id (str) – ID of marking to deny

Returns:

Group after denying access to marking definition

Return type:

Optional[Dict]

delete_member(**kwargs)[source]

Remove a given user from a group

Parameters:

id (str) – ID to remove a user from
user (str) – ID to remove from the group

Returns:

Representation of the group after the member has been removed

Return type:

Optional[Dict]

delete_role(**kwargs)[source]

Removes a role from a given group

Parameters:

id (str) – ID to remove role from
role_id (str) – Role ID to remove from the group

Returns:

Representation of the group after role is removed

Return type:

Optional[Dict]

edit_default_marking(**kwargs)[source]

Adds a default marking to the group.

Parameters:

id (str) – ID of the group.
marking_ids (List[str]) – IDs of the markings to add, or an empty list to remove all default markings
entity (str, optional) – STIX entity type to add default marking for. If set to “GLOBAL” applies to all entity types, defaults to “GLOBAL”.

Returns:

Group after adding the default marking.

Return type:

Optional[Dict]

list(**kwargs)[source]

Lists groups based on a number of filters.

Parameters:

first (int, optional) – Retrieve this number of results. If 0 then fetches all results, defaults to 0.
after (str, optional) – ID of the group to fetch results after in the list of all results, defaults to None.
orderBy (str, optional) – Field by which to order results. Must be one of name, default_assignation, no_creators, restrict_delete, auto_new_marking, created_at, updated_at, group_confidence_level, and _score, defaults to “name”.
orderMode (str, optional) – Direction of ordering. Must be one of “asc” or “desc”, defaults to “asc”.
search (str, optional) – String to search groups for, defaults to None.
filters (dict, optional) – OpenCTI API FilterGroup object. This is an advanced parameter. To learn more please search for the FilterGroup object in the OpenCTI GraphQL Playground, defaults to {}.
customAttributes (str, optional) – Custom attributes to fetch from the GraphQL query
getAll (bool, optional) – Defaults to False. Whether or not to get all results from the search. If True then param first is ignored.
withPagination (bool, optional) – Defaults to False. Whether to return pagination info with results.

Returns:

List of groups in dictionary representation.

Return type:

list[dict]

process_multiple_fields(data)[source]

Process and normalize fields in group data.

Parameters:: data (dict) – the group data dictionary to process
Returns:: the processed group data with normalized fields
Return type:: dict

read(**kwargs)[source]

Fetch a given group from OpenCTI

One of id or filters is required.

Parameters:

id (str, optional) – ID of the group to fetch
filters (dict, optional) – Filters to apply to find single group
customAttributes (str) – Custom attributes to fetch for the group

Returns:

Representation of a group.

Return type:

Optional[Dict]

update_field(**kwargs)[source]

Update a group using fieldPatch

Parameters:

id (str) – ID of the group to update
input (List[Dict]) – FieldPatchInput object to edit group
customAttributes – Custom attributes to retrieve from group

Returns:

Representation of a group

Return type:

Optional[Dict]

class pycti.User(opencti)[source]

Representation of a user on the OpenCTI platform

Users can be member of multiple groups, from which its permissions (capabilities) are derived. Additionally, users are part of organisations, and sometimes administrating them (Enterprise edition).

They have configured confidence, and an effective confidence (which might be set by the group).

You can view the properties, session_properties, and me_properties attributes of a User object to view what attributes will be present in a User or MeUser object.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the User instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

add_membership(**kwargs)[source]

Adds the user to a given group.

Parameters:

id (str) – User ID to add to the group.
group_id (str) – Group ID to add the user to.

Returns:

Representation of the InternalRelationship

Return type:

Optional[Dict]

add_organization(**kwargs)[source]

Adds a user to an organization

Parameters:

id (str) – User ID to add to organization
organization_id (str) – ID of organization to add to

Returns:

Representation of user without sessions or API key

Return type:

Optional[Dict]

create(**kwargs)[source]

Creates a new user with basic details

Note that when SSO is connected users generally do not need to be manually created.

Additionally note that if there is no password passed to this function then a random password will be created and will not be returned. This is useful for creating service accounts and connector accounts.

Parameters:

name (str) – Name to assign to the user.
user_email (str) – Email address for the user.
password (str, optional) – Password that should be assigned to the user. If one is not provided then a random one will be generated, defaults to None.
firstname (str, optional) – First name of the user
lastname (str, optional) – Last name of the user
description (str, optional) – Description for the user
language (str, optional) – Language the user should use
theme (str, optional) – Theme to set for the user, either light or dark
objectOrganization – List of organization IDs to add the user to
account_status (str, optional) – The status of the account: Active, Expired, Inactive, or Locked
account_lock_after_date (str, optional) – ISO 8901 of when account should be locked
unit_system (str, optional) – Unit system for the user, metric or imperial
submenu_show_icons (bool, optional) – Defaults to False. Whether or not to show icons in submenus on the left hand menu bar in the UI
submenu_auto_collaps – Defaults to False. Whether to auto- collapse the left hand menu bar in the UI
monochrome_labels (bool, optional) – Defaults to False. Whether to ignore colours and just show entity labels in monochrome.
groups (List[str], optional) – List of group IDs to add the user to
user_confidence_level (Dict) – Confidence level object to assign to the user. This may not impact effective confidence depending on group membership.
include_token (bool, optional) – Defaults to False. Whether to include the API token for the new user in the response.
customAttributes (str, optional) – Custom attributes to return for the user

Returns:

Representation of the user without sessions or API token.

Return type:

Optional[Dict]

create_token(**kwargs)[source]

Create an API token for the given user

Parameters:

user_id – User ID to rotate API token for.
token_name (str) – Token name to give the token
token_duration (str) – Token duration to give the token. Defaults to UNLIMITED.

Returns:

Representation of token

Return type:

Optional[Dict]

delete(**kwargs)[source]

Deletes the given user from the platform.

Parameters:: id (str) – ID of the user to delete.

delete_membership(**kwargs)[source]

Removes the user from the given group.

Parameters:

id (str) – User ID to remove from the group.
group_id (str) – Group ID to remove the user from.

Returns:

Representation of the user without sessions or API token

Return type:

Optional[Dict]

delete_organization(**kwargs)[source]

Delete a user from an organization

Parameters:

id (str) – User ID to remove from organization
organization_id (str) – ID of organization to remove from

Returns:

Representation of user without sessions or API key

Return type:

Optional[Dict]

list(**kwargs)[source]

Search/list users on the platform

Searches users given some conditions. Defaults to listing all users.

Parameters:

first (int, optional) – Defaults to 500. Retrieve this number of results.
after (str, optional) – Retrieves all results after the user with this ID. Ignored if None, empty, or if fetching all results, defaults to None.
orderBy (str, optional) – Orders results by this field. Can be one of user, user_email, firstname, lastname, language, external, created_at, updated_at, or _score, defaults to “name”.
orderMode (str, optional) – Ordering direction. Must be one of “asc” or “desc”, defaults to “asc”.
filters (dict, optional) – OpenCTI API FilterGroup object. This is an advanced parameter. To learn more please search for the FilterGroup object in the OpenCTI GraphQL Playground, defaults to {}.
search (str, optional) – String to search for when listing users, defaults to None.
include_sessions (bool, optional) – Whether or not to include a list of sessions with results, defaults to False.
customAttributes (str, optional) – Custom attributes to fetch from the GraphQL query
getAll (bool, optional) – Defaults to False. Whether or not to get all results from the search. If True then param first is ignored.
withPagination (bool, optional) – Defaults to False. Whether to return pagination info with results.

Returns:

Returns a list of users, sorted as specified.

Return type:

list[dict]

me(**kwargs)[source]

Reads the currently authenticated user.

Parameters:: customAttributes (str, optional) – Custom attributes to return on the User
Returns:: Representation of the user.
Return type:: dict

process_multiple_fields(data)[source]

Process and normalize fields in user data.

Parameters:: data (dict) – the user data dictionary to process
Returns:: the processed user data with normalized fields
Return type:: dict

read(**kwargs)[source]

Reads user details from the platform.

Parameters:

id (str, optional) – ID of the user to fetch
include_sessions (bool, optional) – Whether or not to include a list of sessions for the given user, defaults to False.
include_tokens (bool, optional) – Whether or not to include the user’s API token, defaults to False.
customAttributes – Custom attributes to include instead of the defaults
filters (dict, optional) – Filters to apply to find a single user
search (str, optional) – Search term to use to find a single user

Returns:

Representation of the user as a Python dictionary.

Return type:

Optional[Dict]

remove_token(**kwargs)[source]

Remove an API token for the given user

Parameters:

user_id – User ID to rotate API token for.
token_id (str) – Token id to remove

Return type:

Optional[Dict]

send_mail(**kwargs)[source]

Send an email to a user using a template.

Parameters:

id (str) – the user ID to send the email to
template_id (str) – the email template ID to use

Returns:

None

update_field(**kwargs)[source]

Update a given user using fieldPatch

Parameters:

id (str) – ID of the user to update.
input (List[Dict]) – FieldPatchInput objects to edit user
customAttributes (str, optional) – Custom attributes to return from the mutation

Returns:

Representation of the user without sessions or API token.

Return type:

Optional[Dict]

class pycti.Settings(opencti)[source]

Represents the Settings object in OpenCTI

These are the properties which are viewable in the customization and security policies views on OpenCTI platform. This also includes all messages on the platform.

See the properties attribute to understand which properties are fetched by default on graphql queries.

Parameters:: opencti (OpenCTIApiClient) – instance of OpenCTIApiClient

Inheritance

__init__(opencti)[source]

Initialize the Settings instance.

Parameters:: opencti (OpenCTIApiClient) – OpenCTI API client instance

delete_message(**kwargs)[source]

Delete a message from the platform

Parameters:

id (str) – ID of the settings object on the platform
input (str) – ID of the message to delete

Returns:

Settings ID and message objects

Return type:

Optional[Dict]

edit_message(**kwargs)[source]

Edit or add a message to the platform

To add a message, don’t include an ID in the input object. To edit a message an ID must be provided.

Parameters:

id (str) – ID of the settings object on the platform
input (Dict) – SettingsMessageInput object

Returns:

Settings ID and message objects

Return type:

Optional[Dict]

process_multiple_fields(data)[source]

Process and normalize fields in settings data.

Parameters:: data (dict) – the settings data dictionary to process
Returns:: the processed settings data with normalized fields
Return type:: dict

read(**kwargs)[source]

Reads settings from the platform

Parameters:

customAttributes (str, optional) – Custom attribues to return from query
include_password_policy (bool, optional) – Defaults to False. Whether to include password policy properties in response.
include_messages (bool, optional) – Defaults to False. Whether to include messages in query response.

Returns:

Representation of the platform settings

Return type:

Dict

update_field(**kwargs)[source]

Update settings using input to fieldPatch

Parameters:

id (str) – ID of the settings object to update
input (List[Dict]) – List of EditInput objects
customAttributes (str, optional) – Custom attribues to return from query
include_password_policy (bool, optional) – Defaults to False. Whether to include password policy properties in response.
include_messages (bool, optional) – Defaults to False. Whether to include messages in query response.

Returns:

Representation of the platform settings

Return type:

Optional[Dict]

pycti.STIX_EXT_MITRE

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

'extension-definition--322b8f77-262a-4cb8-a915-1e441e00329b'

pycti.STIX_EXT_OCTI_SCO

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

'extension-definition--f93e2c80-4231-4f9a-af8b-95c9bd566a82'

pycti.STIX_EXT_OCTI

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

'extension-definition--ea279b3e-5c71-4632-ac08-831c66a786ba'

pycti

Functions

Classes

Variables

`pycti`

Functions 

Classes 

Variables 