# coding: utf-8
import json
import uuid
from stix2.canonicalization.Canonicalize import canonicalize
from pycti.utils.constants import IdentityTypes
[docs]
class Identity:
"""Main Identity class for OpenCTI
Manages individual, organization, and system identities in OpenCTI.
:param opencti: instance of :py:class:`~pycti.api.opencti_api_client.OpenCTIApiClient`
:type opencti: OpenCTIApiClient
"""
[docs]
def __init__(self, opencti):
"""Initialize the Identity instance.
:param opencti: OpenCTI API client instance
:type opencti: OpenCTIApiClient
"""
[docs]
self.properties = """
id
standard_id
entity_type
parent_types
spec_version
created_at
updated_at
status {
id
template {
id
name
color
}
}
createdBy {
... on Identity {
id
standard_id
entity_type
parent_types
spec_version
identity_class
name
description
roles
contact_information
x_opencti_aliases
x_opencti_reliability
created
modified
objectLabel {
id
value
color
}
}
... on Organization {
x_opencti_organization_type
x_opencti_score
}
... on Individual {
x_opencti_firstname
x_opencti_lastname
}
... on SecurityPlatform {
security_platform_type
}
}
objectMarking {
id
standard_id
entity_type
definition_type
definition
created
modified
x_opencti_order
x_opencti_color
}
objectOrganization {
id
standard_id
name
}
objectLabel {
id
value
color
}
externalReferences {
edges {
node {
id
standard_id
entity_type
source_name
description
url
hash
external_id
created
modified
}
}
}
revoked
confidence
created
modified
identity_class
name
description
x_opencti_aliases
x_opencti_reliability
contact_information
... on Individual {
x_opencti_firstname
x_opencti_lastname
}
... on Organization {
x_opencti_organization_type
x_opencti_score
}
... on SecurityPlatform {
security_platform_type
}
"""
[docs]
self.properties_with_files = """
id
standard_id
entity_type
parent_types
spec_version
created_at
updated_at
status {
id
template {
id
name
color
}
}
createdBy {
... on Identity {
id
standard_id
entity_type
parent_types
spec_version
identity_class
name
description
roles
contact_information
x_opencti_aliases
x_opencti_reliability
created
modified
objectLabel {
id
value
color
}
}
... on Organization {
x_opencti_organization_type
x_opencti_score
}
... on Individual {
x_opencti_firstname
x_opencti_lastname
}
... on SecurityPlatform {
security_platform_type
}
}
objectMarking {
id
standard_id
entity_type
definition_type
definition
created
modified
x_opencti_order
x_opencti_color
}
objectOrganization {
id
standard_id
name
}
objectLabel {
id
value
color
}
externalReferences {
edges {
node {
id
standard_id
entity_type
source_name
description
url
hash
external_id
created
modified
importFiles {
edges {
node {
id
name
size
metaData {
mimetype
version
}
}
}
}
}
}
}
revoked
confidence
created
modified
identity_class
name
description
x_opencti_aliases
x_opencti_reliability
contact_information
... on Individual {
x_opencti_firstname
x_opencti_lastname
}
... on Organization {
x_opencti_organization_type
x_opencti_score
}
... on SecurityPlatform {
security_platform_type
}
importFiles {
edges {
node {
id
name
size
metaData {
mimetype
version
}
objectMarking {
id
standard_id
entity_type
definition_type
definition
created
modified
x_opencti_order
x_opencti_color
}
}
}
}
"""
@staticmethod
[docs]
def generate_id(name, identity_class):
"""Generate a STIX ID for an Identity.
:param name: The name of the identity
:type name: str
:param identity_class: The class of the identity (individual, group, organization, etc.)
:type identity_class: str
:return: STIX ID for the identity
:rtype: str
"""
data = {"name": name.lower().strip(), "identity_class": identity_class.lower()}
data = canonicalize(data, utf8=False)
id = str(uuid.uuid5(uuid.UUID("00abedb4-aa42-466c-9c01-fed23315a9b7"), data))
return "identity--" + id
@staticmethod
[docs]
def generate_id_from_data(data):
"""Generate a STIX ID from identity data.
:param data: Dictionary containing 'name' and 'identity_class' keys
:type data: dict
:return: STIX ID for the identity
:rtype: str
"""
return Identity.generate_id(data["name"], data["identity_class"])
[docs]
def list(self, **kwargs):
"""List Identity objects.
:param types: the list of types
:type types: list
:param filters: the filters to apply
:type filters: dict
:param search: the search keyword
:type search: str
:param first: return the first n rows from the after ID (or the beginning if not set)
:type first: int
:param after: ID of the first row for pagination
:type after: str
:param orderBy: field to order results by
:type orderBy: str
:param orderMode: ordering mode (asc/desc)
:type orderMode: str
:param customAttributes: custom attributes to return
:type customAttributes: str
:param getAll: whether to retrieve all results
:type getAll: bool
:param withPagination: whether to include pagination info
:type withPagination: bool
:param withFiles: whether to include files
:type withFiles: bool
:return: List of Identity objects
:rtype: list
"""
types = kwargs.get("types", None)
filters = kwargs.get("filters", None)
search = kwargs.get("search", None)
first = kwargs.get("first", 500)
after = kwargs.get("after", None)
order_by = kwargs.get("orderBy", None)
order_mode = kwargs.get("orderMode", None)
custom_attributes = kwargs.get("customAttributes", None)
get_all = kwargs.get("getAll", False)
with_pagination = kwargs.get("withPagination", False)
with_files = kwargs.get("withFiles", False)
self.opencti.app_logger.info(
"Listing Identities with filters", {"filters": json.dumps(filters)}
)
query = (
"""
query Identities($types: [String], $filters: FilterGroup, $search: String, $first: Int, $after: ID, $orderBy: IdentitiesOrdering, $orderMode: OrderingMode) {
identities(types: $types, filters: $filters, search: $search, first: $first, after: $after, orderBy: $orderBy, orderMode: $orderMode) {
edges {
node {
"""
+ (
custom_attributes
if custom_attributes is not None
else (self.properties_with_files if with_files else self.properties)
)
+ """
}
}
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
globalCount
}
}
}
"""
)
result = self.opencti.query(
query,
{
"types": types,
"filters": filters,
"search": search,
"first": first,
"after": after,
"orderBy": order_by,
"orderMode": order_mode,
},
)
if get_all:
final_data = []
data = self.opencti.process_multiple(result["data"]["identities"])
final_data = final_data + data
while result["data"]["identities"]["pageInfo"]["hasNextPage"]:
after = result["data"]["identities"]["pageInfo"]["endCursor"]
self.opencti.app_logger.debug("Listing Identities", {"after": after})
result = self.opencti.query(
query,
{
"types": types,
"filters": filters,
"search": search,
"first": first,
"after": after,
"orderBy": order_by,
"orderMode": order_mode,
},
)
data = self.opencti.process_multiple(result["data"]["identities"])
final_data = final_data + data
return final_data
else:
return self.opencti.process_multiple(
result["data"]["identities"], with_pagination
)
[docs]
def read(self, **kwargs):
"""Read an Identity object.
:param id: the id of the Identity
:type id: str
:param filters: the filters to apply if no id provided
:type filters: dict
:param customAttributes: custom attributes to return
:type customAttributes: str
:param withFiles: whether to include files
:type withFiles: bool
:return: Identity object
:rtype: dict or None
"""
id = kwargs.get("id", None)
filters = kwargs.get("filters", None)
custom_attributes = kwargs.get("customAttributes", None)
with_files = kwargs.get("withFiles", False)
if id is not None:
self.opencti.app_logger.info("Reading Identity", {"id": id})
query = (
"""
query Identity($id: String!) {
identity(id: $id) {
"""
+ (
custom_attributes
if custom_attributes is not None
else (self.properties_with_files if with_files else self.properties)
)
+ """
}
}
"""
)
result = self.opencti.query(query, {"id": id})
return self.opencti.process_multiple_fields(result["data"]["identity"])
elif filters is not None:
result = self.list(filters=filters)
if len(result) > 0:
return result[0]
else:
return None
else:
self.opencti.app_logger.error(
"[opencti_identity] Missing parameters: id or filters"
)
return None
[docs]
def create(self, **kwargs):
"""Create an Identity object.
:param type: the type of identity (Organization, Individual, System, etc.) (required)
:param stix_id: (optional) the STIX ID
:param createdBy: (optional) the author ID
:param objectMarking: (optional) list of marking definition IDs
:param objectLabel: (optional) list of label IDs
:param externalReferences: (optional) list of external reference IDs
:param revoked: (optional) whether the identity is revoked
:param confidence: (optional) confidence level (0-100)
:param lang: (optional) language
:param created: (optional) creation date
:param modified: (optional) modification date
:param name: the name of the Identity (required)
:param description: (optional) description
:param contact_information: (optional) contact information
:param roles: (optional) list of roles
:param x_opencti_aliases: (optional) list of aliases
:param security_platform_type: (optional) type of security platform
:param x_opencti_organization_type: (optional) organization type
:param x_opencti_reliability: (optional) reliability level
:param x_opencti_score: (optional) score
:param x_opencti_firstname: (optional) first name for individuals
:param x_opencti_lastname: (optional) last name for individuals
:param x_opencti_stix_ids: (optional) list of additional STIX IDs
:param objectOrganization: (optional) list of organization IDs
:param x_opencti_workflow_id: (optional) workflow ID
:param x_opencti_modified_at: (optional) custom modification date
:param update: (optional) whether to update if exists (default: False)
:type update: bool
:param files: (optional) list of File objects to attach
:type files: list
:param filesMarkings: (optional) list of lists of marking definition IDs for each file
:type filesMarkings: list
:return: Identity object
:rtype: dict or None
"""
type = kwargs.get("type", None)
stix_id = kwargs.get("stix_id", None)
created_by = kwargs.get("createdBy", None)
object_marking = kwargs.get("objectMarking", None)
object_label = kwargs.get("objectLabel", None)
external_references = kwargs.get("externalReferences", None)
revoked = kwargs.get("revoked", None)
confidence = kwargs.get("confidence", None)
lang = kwargs.get("lang", None)
created = kwargs.get("created", None)
modified = kwargs.get("modified", None)
name = kwargs.get("name", None)
description = kwargs.get("description", None)
contact_information = kwargs.get("contact_information", None)
roles = kwargs.get("roles", None)
x_opencti_aliases = kwargs.get("x_opencti_aliases", None)
security_platform_type = kwargs.get("security_platform_type", None)
x_opencti_organization_type = kwargs.get("x_opencti_organization_type", None)
x_opencti_reliability = kwargs.get("x_opencti_reliability", None)
x_opencti_score = kwargs.get("x_opencti_score", None)
x_opencti_firstname = kwargs.get("x_opencti_firstname", None)
x_opencti_lastname = kwargs.get("x_opencti_lastname", None)
x_opencti_stix_ids = kwargs.get("x_opencti_stix_ids", None)
granted_refs = kwargs.get("objectOrganization", None)
x_opencti_workflow_id = kwargs.get("x_opencti_workflow_id", None)
x_opencti_modified_at = kwargs.get("x_opencti_modified_at", None)
update = kwargs.get("update", False)
files = kwargs.get("files", None)
files_markings = kwargs.get("filesMarkings", None)
no_trigger_import = kwargs.get("noTriggerImport", None)
embedded = kwargs.get("embedded", None)
upsert_operations = kwargs.get("upsert_operations", None)
if type is not None and name is not None:
self.opencti.app_logger.info("Creating Identity", {"name": name})
input_variables = {
"stix_id": stix_id,
"createdBy": created_by,
"objectMarking": object_marking,
"objectLabel": object_label,
"externalReferences": external_references,
"revoked": revoked,
"confidence": confidence,
"lang": lang,
"created": created,
"modified": modified,
"name": name,
"description": description,
"contact_information": contact_information,
"roles": roles,
"x_opencti_aliases": x_opencti_aliases,
"x_opencti_stix_ids": x_opencti_stix_ids,
"x_opencti_workflow_id": x_opencti_workflow_id,
"x_opencti_modified_at": x_opencti_modified_at,
"update": update,
"files": files,
"filesMarkings": files_markings,
"noTriggerImport": no_trigger_import,
"embedded": embedded,
"upsertOperations": upsert_operations,
}
if type == IdentityTypes.ORGANIZATION.value:
query = """
mutation OrganizationAdd($input: OrganizationAddInput!) {
organizationAdd(input: $input) {
id
standard_id
entity_type
parent_types
}
}
"""
input_variables["x_opencti_organization_type"] = (
x_opencti_organization_type
)
input_variables["x_opencti_reliability"] = x_opencti_reliability
input_variables["x_opencti_score"] = x_opencti_score
result_data_field = "organizationAdd"
elif type == IdentityTypes.SECURITYPLATFORM.value:
query = """
mutation SecurityPlatformAdd($input: SecurityPlatformAddInput!) {
securityPlatformAdd(input: $input) {
id
standard_id
entity_type
parent_types
}
}
"""
input_variables["security_platform_type"] = security_platform_type
# no need for these attributes for security platform
del input_variables["contact_information"]
del input_variables["lang"]
del input_variables["roles"]
del input_variables["x_opencti_aliases"]
result_data_field = "securityPlatformAdd"
elif type == IdentityTypes.INDIVIDUAL.value:
query = """
mutation IndividualAdd($input: IndividualAddInput!) {
individualAdd(input: $input) {
id
standard_id
entity_type
parent_types
}
}
"""
input_variables["objectOrganization"] = granted_refs
input_variables["x_opencti_firstname"] = x_opencti_firstname
input_variables["x_opencti_lastname"] = x_opencti_lastname
input_variables["x_opencti_reliability"] = x_opencti_reliability
result_data_field = "individualAdd"
elif type == IdentityTypes.SYSTEM.value:
query = """
mutation SystemAdd($input: SystemAddInput!) {
systemAdd(input: $input) {
id
standard_id
entity_type
parent_types
}
}
"""
input_variables["objectOrganization"] = granted_refs
input_variables["x_opencti_firstname"] = x_opencti_firstname
input_variables["x_opencti_lastname"] = x_opencti_lastname
input_variables["x_opencti_reliability"] = x_opencti_reliability
result_data_field = "systemAdd"
else:
query = """
mutation IdentityAdd($input: IdentityAddInput!) {
identityAdd(input: $input) {
id
standard_id
entity_type
parent_types
}
}
"""
input_variables["type"] = type
result_data_field = "identityAdd"
result = self.opencti.query(
query,
{
"input": input_variables,
},
)
return self.opencti.process_multiple_fields(
result["data"][result_data_field]
)
else:
self.opencti.app_logger.error(
"[opencti_identity] Missing parameters: type and name"
)
return None
[docs]
def import_from_stix2(self, **kwargs):
"""Import an Identity object from a STIX2 object.
:param stixObject: the STIX2 Identity object
:type stixObject: dict
:param extras: extra parameters including created_by_id, object_marking_ids, etc.
:type extras: dict
:param update: whether to update if the entity already exists
:type update: bool
:return: Identity object
:rtype: dict or None
"""
stix_object = kwargs.get("stixObject", None)
extras = kwargs.get("extras", {})
update = kwargs.get("update", False)
if stix_object is not None:
type = "Organization"
if "identity_class" in stix_object:
if stix_object["identity_class"] == "individual":
type = "Individual"
elif stix_object["identity_class"] == "class":
type = "Sector"
elif stix_object["identity_class"] == "system":
type = "System"
elif stix_object["identity_class"] == "securityplatform":
type = "SecurityPlatform"
# Search in extensions
if "x_opencti_aliases" not in stix_object:
stix_object["x_opencti_aliases"] = (
self.opencti.get_attribute_in_extension("aliases", stix_object)
)
if "x_opencti_organization_type" not in stix_object:
stix_object["x_opencti_organization_type"] = (
self.opencti.get_attribute_in_extension(
"organization_type", stix_object
)
)
if "security_platform_type" not in stix_object:
stix_object["security_platform_type"] = (
self.opencti.get_attribute_in_extension(
"security_platform_type", stix_object
)
)
if "x_opencti_reliability" not in stix_object:
stix_object["x_opencti_reliability"] = (
self.opencti.get_attribute_in_extension("reliability", stix_object)
)
if "x_opencti_score" not in stix_object:
stix_object["x_opencti_score"] = (
self.opencti.get_attribute_in_extension("score", stix_object)
)
if "x_opencti_firstname" not in stix_object:
stix_object["x_opencti_firstname"] = (
self.opencti.get_attribute_in_extension("firstname", stix_object)
)
if "x_opencti_lastname" not in stix_object:
stix_object["x_opencti_lastname"] = (
self.opencti.get_attribute_in_extension("lastname", stix_object)
)
if "x_opencti_stix_ids" not in stix_object:
stix_object["x_opencti_stix_ids"] = (
self.opencti.get_attribute_in_extension("stix_ids", stix_object)
)
if "x_opencti_granted_refs" not in stix_object:
stix_object["x_opencti_granted_refs"] = (
self.opencti.get_attribute_in_extension("granted_refs", stix_object)
)
if "x_opencti_workflow_id" not in stix_object:
stix_object["x_opencti_workflow_id"] = (
self.opencti.get_attribute_in_extension("workflow_id", stix_object)
)
if "x_opencti_modified_at" not in stix_object:
stix_object["x_opencti_modified_at"] = (
self.opencti.get_attribute_in_extension("modified_at", stix_object)
)
if "opencti_upsert_operations" not in stix_object:
stix_object["opencti_upsert_operations"] = (
self.opencti.get_attribute_in_extension(
"opencti_upsert_operations", stix_object
)
)
return self.create(
type=type,
stix_id=stix_object["id"],
createdBy=(
extras["created_by_id"] if "created_by_id" in extras else None
),
objectMarking=(
extras["object_marking_ids"]
if "object_marking_ids" in extras
else None
),
objectLabel=(
extras["object_label_ids"] if "object_label_ids" in extras else None
),
externalReferences=(
extras["external_references_ids"]
if "external_references_ids" in extras
else None
),
revoked=stix_object["revoked"] if "revoked" in stix_object else None,
confidence=(
stix_object["confidence"] if "confidence" in stix_object else None
),
lang=stix_object["lang"] if "lang" in stix_object else None,
created=stix_object["created"] if "created" in stix_object else None,
modified=stix_object["modified"] if "modified" in stix_object else None,
name=stix_object["name"],
description=(
self.opencti.stix2.convert_markdown(stix_object["description"])
if "description" in stix_object
else None
),
contact_information=(
self.opencti.stix2.convert_markdown(
stix_object["contact_information"]
)
if "contact_information" in stix_object
else None
),
roles=stix_object["roles"] if "roles" in stix_object else None,
x_opencti_aliases=self.opencti.stix2.pick_aliases(stix_object),
x_opencti_organization_type=(
stix_object["x_opencti_organization_type"]
if "x_opencti_organization_type" in stix_object
else None
),
security_platform_type=(
stix_object["security_platform_type"]
if "security_platform_type" in stix_object
else None
),
x_opencti_reliability=(
stix_object["x_opencti_reliability"]
if "x_opencti_reliability" in stix_object
else None
),
x_opencti_score=(
stix_object["x_opencti_score"]
if "x_opencti_score" in stix_object
else None
),
x_opencti_firstname=(
stix_object["x_opencti_firstname"]
if "x_opencti_firstname" in stix_object
else None
),
x_opencti_lastname=(
stix_object["x_opencti_lastname"]
if "x_opencti_lastname" in stix_object
else None
),
x_opencti_stix_ids=(
stix_object["x_opencti_stix_ids"]
if "x_opencti_stix_ids" in stix_object
else None
),
objectOrganization=(
stix_object["x_opencti_granted_refs"]
if "x_opencti_granted_refs" in stix_object
else None
),
x_opencti_workflow_id=(
stix_object["x_opencti_workflow_id"]
if "x_opencti_workflow_id" in stix_object
else None
),
x_opencti_modified_at=(
stix_object["x_opencti_modified_at"]
if "x_opencti_modified_at" in stix_object
else None
),
update=update,
files=extras.get("files"),
filesMarkings=extras.get("filesMarkings"),
noTriggerImport=extras.get("noTriggerImport", None),
embedded=extras.get("embedded", None),
upsert_operations=(
stix_object["opencti_upsert_operations"]
if "opencti_upsert_operations" in stix_object
else None
),
)
else:
self.opencti.app_logger.error(
"[opencti_identity] Missing parameters: stixObject"
)
return None