Developer Interface#

This part of the documentation covers all the public interfaces of Cybsi SDK.

Low-level client#

Client interface#

class cybsi.api.CybsiClient(config)[source]#

The main entry point for all actions with Cybsi REST API.

As the client is low-level, it is structured around Cybsi REST API routes. Use properties of the client to retrieve handles of API sections.

The client also follows Cybsi REST API input-output formats, providing little to no abstration from JSONs API uses. It’s relatively easy to construct an invalid request, so use client’s functions wisely.

Hint

Use CybsiClient properties to construct needed API handles. Don’t construct sub-APIs manually.

Do this:
>>> from cybsi.api import CybsiClient
>>> client = CybsiClient(config)
>>> client.observations.generics.view(observation_uuid)
Not this:
>>> from cybsi.api.observation import GenericObservationsAPI
>>> GenericObservationsAPI(connector).view(observation_uuid)
Parameters:

config (Config) – Client config.

Usage:
>>> from cybsi.api import APIKeyAuth, Config, CybsiClient
>>> api_url = "http://localhost:80/api"
>>> api_key = "8Nqjk6V4Q_et_Rf5EPu4SeWy4nKbVPKPzKJESYdRd7E"
>>> auth = APIKeyAuth(api_url, api_key)
>>> config = Config(api_url, auth)
>>> client = CybsiClient(config)
>>>
>>> client.observations.generics.filter()
>>> client.close()  # "with" syntax is also supported for CybsiClient
<cybsi_sdk.client.observation.ObservationsAPI object at 0x7f57a293c190>
close()[source]#

Close client and release connections.

Return type:

None

property artifacts#

Artifacts API handle.

property data_sources#

Data sources API handle.

property data_source_types#

Data source types API handle.

property enrichment#

Enrichment API handle.

property observable#

Observable API handle.

property observations#

Observations API handle.

property replists#

Reputation lists API handle.

property reports#

Reports API handle.

property search#

Search API handle.

property users#

Users API handle.

property api_keys#

API-Keys API handle.

property dictionaries#

Dictionaries API handle.

property licenses#

Licenses API handle.

property access_logs#

User access log API handle.

property custom_lists#

Custom list API handle.

property threat_landscapes#

Threat landscape API handle.

version()[source]#

Get API and server version information.

Note

Calls GET /version.

Return type:

VersionView

Returns:

Version view.

class cybsi.api.CybsiAsyncClient(config)[source]#

The asynchronous analog of CybsiClient.

As you can see, the asynchronous client has fewer features than synchronous one. This is because we don’t simply copy-paste features, but provide them only when they’re actually useful in asynchronous applications.

Parameters:

config (Config) – Client config.

async aclose()[source]#

Close client and release connections.

Return type:

None

property artifacts#

Artifacts API handle.

property enrichment#

Enrichment API handle.

property observations#

Observations API handle.

property reports#

Reports API handle.

property data_sources#

Data sources API handle.

property data_source_types#

Data source types API handle.

property replists#

Replists API handle.

property observable#

Observable API handle.

property search#

Search API handle.

property dictionaries#

Dictionaries API handle.

property threat_landscapes#

Threat landscape API handle.

property custom_lists#

Custom list API handle.

async version()[source]#

Get API and server version information.

Note

Calls GET /version.

Return type:

VersionView

Returns:

Version view.

class cybsi.api.VersionView(data=None)[source]#

Version view.

property api_version#

API specification version.

property server_version#

Server version.

class cybsi.api.Version(version)[source]#

Version.

property major#

Major part of version.

property minor#

Minor part of version.

property patch#

Patch part of version.

property prerelease#

Prerelease part of version.

property build#

Build part of version.

Client configuration#

class cybsi.api.Config(api_url, auth, ssl_verify=True, embed_object_url=False, timeouts=<cybsi.api.client_config.Timeouts object>, limits=<cybsi.api.client_config.Limits object>)[source]#

CybsiClient config.

Parameters:

  • api_url (str) – Base API URL.

  • auth (Union[APIKeyAuth, Callable]) – Optional callable CybsiClient can use to authenticate requests. In most cases it’s enough to pass api_key instead of this.

  • ssl_verify (bool) – Enable SSL certificate verification.

  • timeouts (Timeouts) – Timeout configuration. Default configuration is 60 sec on all operations.

  • limits (Limits) – Configuration for limits to various client behaviors. Default configuration is max_connections=100, max_keepalive_connections=20.

  • embed_object_url (bool) – Initialize URL property for all objects having uuid property (including RefView). Views are compact if it’s set to False.

class cybsi.api.Limits(*, max_connections=None, max_keepalive_connections=None, keepalive_expiry=5.0)[source]#

Configuration for limits to various client behaviors.

Parameters:

  • max_connections (Optional[int]) – The maximum number of concurrent connections that may be established.

  • max_keepalive_connections (Optional[int]) – Allow the connection pool to maintain keep-alive connections below this point. Should be less than or equal to max_connections.

  • keepalive_expiry (Optional[float]) – The maximum time (in second) to allow before closing a keep-alive connection.

class cybsi.api.Timeouts(*, default=<cybsi.api.api.NullType object>, connect=<cybsi.api.api.NullType object>, read=<cybsi.api.api.NullType object>, write=<cybsi.api.api.NullType object>)[source]#

Timeout configuration.

Note

Default parameters value is Null, it means “use default timeout”. None value means “infinite timeout”.

Please note those timeouts don’t restrict total execution time of SDK methods (like register, view and so on). Wrap calls to SDK methods with asyncio.wait_for or similar functions if you want to control total execution time.

Parameters:

  • default (Union[float, None, Timeouts, NullType]) – Timeout (in seconds) on all operations listed below.

  • connect (Union[float, None, NullType]) – The maximum amount of time (in seconds) to wait for a connection attempt to a server to succeed.

  • read (Union[float, None, NullType]) – The maximum amount of time (in seconds) to wait between consecutive read operations for a response from the server.

  • write (Union[float, None, NullType]) – The maximum amount of time (in seconds) to wait between consecutive write operations (send request) to the server.

Raises:

ValueError – Timeout must either default settings for all operations or set all three parameters explicitly.

Usage:
>>> # No timeouts.
>>> Timeouts(default=None)
>>> # 5s timeout on all operations.
>>> Timeouts(default=5.0)
>>> # 5s timeout on connect, no other timeouts.
>>> Timeouts(default=None, connect=5.0)
>>> # 10s timeout on connect. 5s timeout elsewhere.
>>> Timeouts(default=5.0, connect=10.0)

Artifacts#

Use this section of API to operate artifacts.

class cybsi.api.artifact.ArtifactsAPI(connector)[source]#

Artifact API.

view(artifact_uuid)[source]#

Get an artifact view.

Note

Calls GET /enrichment/artifacts/{artifact_uuid}.

Parameters:

artifact_uuid (UUID) – Artifact uuid.

Return type:

ArtifactView

Returns:

View of the artifact.

Raises:

NotFoundError – Artifact not found.

view_registrations(artifact_uuid)[source]#

Get artifact registrations.

Note

Calls GET /enrichment/artifacts/{artifact_uuid}/registrations.

Parameters:

artifact_uuid (UUID) – Artifact uuid.

Return type:

List[ArtifactRegistrationView]

Returns:

List of artifact registrations.

Raises:

NotFoundError – Artifact not found.

recognize_type(data)[source]#

Recognize artifact type by its first bytes.

The function allows to send the entire artifact, but it’s recommended to send 10KB or less to save time and bandwidth.

Note

Calls PUT /enrichment/artifact-type.

Parameters:

data (Any) – File-like object. If you have bytes, wrap them in BytesIO.

Return type:

ArtifactTypeRecognizedView

Returns:

Recognized artifact type.

See also

The function is similar to upload(). The example for upload() is applicable here too.

upload(filename, data, artifact_type=None, share_level=ShareLevels.White, timeout=300)[source]#

Upload an artifact.

Note

Calls POST /enrichment/artifacts.

Parameters:

  • filename (str) – Name of the artifact.

  • data (Any) – File-like object. If you have bytes, wrap them in BytesIO.

  • artifact_type (Optional[ArtifactTypes]) – Artifact type.

  • share_level (ShareLevels) – Artifact share level.

  • timeout (int) – Connection timeout in sec.

Return type:

RefView

Returns:

Reference to artifact in API.

Raises:

SemanticError – Semantic error. Possible code is InvalidShareLevel.

See also

See Upload and download an artifact for a complete example of this function usage.

get_content(artifact_uuid, *, archive=None, archive_password=None)[source]#

Get artifact content.

Note

Calls GET /enrichment/artifacts/{artifact_uuid}/content.

Parameters:
Return type:

ContextManager[ArtifactContent]

Returns:

Contextmanager of binary file content.

Raises:

NotFoundError – Artifact not found.

Examples

>>> with client.artifacts.get_content(artifact_uuid) as content:
>>>     with open("/tmp/artifact", "wb") as f:
>>>         shutil.copyfileobj(content.stream, f, length=1024 * 1024)

See also

See Upload and download an artifact for a complete example of this function usage.

filter(*, artifact_type=None, data_source_uuids=None, file_uuid=None, artifact_hash=None, cursor=None, limit=None)[source]#

Filter artifacts using provided parameters.

Note

Calls GET /enrichment/artifacts

Parameters:
Raises:

SemanticError – Query contains logic errors.

Note

Semantic error codes specific for this method:
Return type:

Page[ArtifactCommonView]

Returns:

Page containing artifact descriptions.

class cybsi.api.artifact.ArtifactsAsyncAPI(connector)[source]#

Asynchronous artifact API.

async view(artifact_uuid)[source]#

Get an artifact view.

Note

Calls GET /enrichment/artifacts/{artifact_uuid}.

Parameters:

artifact_uuid (UUID) – Artifact uuid.

Return type:

ArtifactView

Returns:

View of the artifact.

Raises:

NotFoundError – Artifact not found.

async view_registrations(artifact_uuid)[source]#

Get artifact registrations.

Note

Calls GET /enrichment/artifacts/{artifact_uuid}/registrations.

Parameters:

artifact_uuid (UUID) – Artifact uuid.

Return type:

List[ArtifactRegistrationView]

Returns:

List of artifact registrations.

Raises:

NotFoundError – Artifact not found.

async recognize_type(data)[source]#

Recognize artifact type by its first bytes.

The function allows to send the entire artifact, but it’s recommended to send 10KB or less to save time and bandwidth.

Note

Calls PUT /enrichment/artifact-type.

Parameters:

data (Any) – File-like object. If you have bytes, wrap them in BytesIO.

Return type:

ArtifactTypeRecognizedView

Returns:

Recognized artifact type.

See also

The function is similar to upload(). The example for upload() is applicable here too.

async upload(*, filename, data, data_size=0, artifact_type=None, share_level=ShareLevels.White, timeout=300)[source]#

Upload an artifact.

Note

Calls POST /enrichment/artifacts.

Parameters:

  • filename (str) – Name of the artifact.

  • data (Any) – File-like or async stream object. If you have bytes, wrap them in BytesIO.

  • data_size (int) – Total file size. Required for StreamReader or AsyncIterator data types.

  • artifact_type (Optional[ArtifactTypes]) – Artifact type.

  • share_level (ShareLevels) – Artifact share level.

  • timeout (int) – Connection timeout in sec.

Return type:

RefView

Returns:

Reference to artifact in API.

Raises:

SemanticError – Semantic error. Possible code is InvalidShareLevel.

See also

See Upload and download an artifact for a complete example of this function usage. See Advanced Usage for asynchronous multipart upload example.

Warning

Upload is synchronous if data_size is not provided.

get_content(*, artifact_uuid, archive=None, archive_password=None)[source]#

Get artifact content

Note

Calls GET /enrichment/artifacts/{artifact_uuid}/content.

Parameters:
Return type:

AsyncContextManager[ArtifactAsyncContent]

Returns:

Contextmanager of binary file content.

Raises:

NotFoundError – Artifact not found.

Examples

>>>    async with aiofiles.open("/tmp/artifact", "wb") as f, client.artifacts.get_content(
>>>        artifact_uuid
>>>    ) as content:
>>>        async for chunk in content.iter_chunks(size=8192):
>>>            await f.write(chunk)

See also

See Upload and download an artifact for a complete example of this function usage.

async filter(*, artifact_type=None, data_source_uuids=None, file_uuid=None, artifact_hash=None, cursor=None, limit=None)[source]#

Filter artifacts using provided parameters.

Note

Calls GET /enrichment/artifacts

Parameters:
Raises:

SemanticError – Query contains logic errors.

Note

Semantic error codes specific for this method:
Return type:

AsyncPage[ArtifactCommonView]

Returns:

Page containing artifact descriptions.

class cybsi.api.artifact.ArtifactView(resp)[source]#

Artifact view.

property types#

Artifact types.

property data_sources#

Data sources which registered the artifact.

property share_levels#

Artifact share levels, ordered from lowest to highest.

property content#

Artifact content meta information.

property file_names#

Artifact file names. Ordered by time of registration.

property entities#

List of file entities associated with this artifact.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.artifact.ArtifactCommonView(data=None)[source]#

Common artifact view.

property types#

Artifact types.

property data_sources#

Data sources which registered the artifact.

property share_levels#

Artifact share levels, ordered from lowest to highest.

property content#

Artifact content meta information.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.artifact.ArtifactContent(filename, raw)[source]#

Binary artifact content.

May be packed in archive, if it is requested in ArtifactsAPI.get_content().

property filename#

Artifact file name.

property stream#

Stream with binary artifact content.

File-like object, supports read() but does not support seek().

iter_chunks(size=4096)[source]#

Iterates over data chunks with maximum size limit.

Parameters:

size – chunk size.

Return type:

Iterator[bytes]

Returns:

Iterator over data chunks.

readall()[source]#

Read all content data.

Return type:

bytes

class cybsi.api.artifact.ArtifactAsyncContent(filename, raw)[source]#

Binary artifact content with asynchronous API.

May be packed in archive,

if it is requested in ArtifactsAsyncAPI.get_content().

property filename#

Artifact file name.

iter_chunks(size=4096)[source]#

Iterates over data chunks with maximum size limit.

Parameters:

size – chunk size.

Return type:

AsyncIterator[bytes]

Returns:

Asynchronous iterator over data chunks.

async readall()[source]#

Read all content data.

Return type:

bytes

class cybsi.api.artifact.ArtifactContentView(data=None)[source]#

Artifact content meta information.

property url#

Absolute URL of artifact content.

property size#

File size.

property md5_hash#

MD5 hash of file content.

property sha1_hash#

SHA1 hash of file content.

property sha256_hash#

SHA256 hash of file content.

property format_description#

File format description magically extracted from signature.

class cybsi.api.artifact.ArtifactRegistrationView(data=None)[source]#

Artifact registration view.

property data_source#

Data source which registered the artifact.

property type#

Artifact type.

property file_name#

Artifact file name

property share_level#

Artifact share level

class cybsi.api.artifact.ArtifactTypeRecognizedView(data=None)[source]#

Artifact type view, as recognized by Cybsi.

property type#

Artifact type.

property format_description#

Format description (magic).

Example

PE32 executable (GUI) Intel 80386, for MS Windows, Nullsoft Installer self-extracting archive

enum cybsi.api.artifact.enums.ArtifactTypes(value)[source]#

Bases: CybsiAPIEnum

Valid values are as follows:

Archive = <ArtifactTypes.Archive: 'Archive'>#

Archive.

FileSample = <ArtifactTypes.FileSample: 'FileSample'>#

File sample.

NetworkTraffic = <ArtifactTypes.NetworkTraffic: 'NetworkTraffic'>#

Network traffic.

enum cybsi.api.artifact.enums.ArtifactContentDownloadCompressionTypes(value)[source]#

Bases: CybsiAPIEnum

Artifact content download compression type.

Don’t confuse it with compression of original artifact content itself! Those values are used only for artifact content downloading. Uncompress the downloaded archive to get artifact content.

Valid values are as follows:

ZIP = <ArtifactContentDownloadCompressionTypes.ZIP: 'ZIP'>#

ZIP archive

Auth#

class cybsi.api.auth.APIKeyAuth(*, api_url, api_key, ssl_verify=True)[source]#

Authomatically handles authentication of CybsiClient or CybsiAsyncClient requests using API key.

Parameters:

  • api_url (str) – Cybsi auth API URL. Usually equal to CybsiClient config API URL.

  • api_key (str) – Cybsi API key.

  • ssl_verify (bool) – enable SSL verification. Deprecated, has no effect. Uses value set for CybsiClient config.

Usage:
>>> from cybsi.api import APIKeyAuth, Config, CybsiClient
>>> api_url = "http://localhost:80/api"
>>> api_key = "8Nqjk6V4Q_et_Rf5EPu4SeWy4nKbVPKPzKJESYdRd7E"
>>> auth = APIKeyAuth("", api_key)
>>> config = Config(api_url, auth)  # Consider using :attr:`Config.api_key`
>>> client = CybsiClient(config)
>>> client.observations
<cybsi_sdk.client.observation.ObservationsAPI object at 0x7f57a293c190>

API-Keys#

class cybsi.api.auth.api_key.APIKeysAPI(connector)[source]#

API-Keys API.

generate(user_uuid, form)[source]#

Generate API-Key for user.

Warning

Make sure to copy API key value because it is not stored on the server. Revoke API key if you suspect a leak.

Note

Calls POST /users/{userID}/api-keys.

Parameters:

  • user_uuid (UUID) – User identifier.

  • form (APIKeyForm) – APIKeyForm instance.

Return type:

APIKeyRefView

Returns:

Reference to the generated API-Key.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
filter(*, user_uuid, cursor=None, limit=None)[source]#

Get API keys created for user. Keys are ordered by creation timestamp, new first.

Note

Calls GET /users/{user_uuid}/api-keys.

Parameters:
Return type:

Page[APIKeyCommonView]

Returns:

Page with user API-Key common views and next page cursor.

filter_my(*, cursor=None, limit=None)[source]#

Get API keys which API-Client owns.

Note

Calls GET /users/me/api-keys. Doesn’t require any permissions.

Parameters:
Return type:

Page[APIKeyCommonView]

Returns:

Page with user API-Key common views and next page cursor.

New in version 2.8.

view(api_key_id)[source]#

Get the API-Key view.

Note

Calls GET /api-keys/{api_key_id}.

Parameters:

api_key_id (UUID) – API-Key identifier.

Return type:

APIKeyView

Returns:

Full view of the API-Key include ETag value.

Raises:

NotFoundError – User API-Key not found.

view_my(api_key_uuid)[source]#

Get the API-Key view which API-Client owns.

Note

Calls GET /users/me/api-keys/{api_key_id}. Doesn’t require any permissions.

Parameters:

api_key_uuid – API-Key identifier.

Return type:

APIKeyView

Returns:

Full view of the API-Key include ETag value.

Raises:

Note

Semantic error codes specific for this method:

New in version 2.8.

edit(api_key_id, tag, *, description=None, revoked=None)[source]#

Edit description and/or revoke API-Key.

Warning

Key revocation is an irreversible operation.

Note

Calls PATCH /api-keys/{api_key_id}.

Parameters:

  • api_key_id (UUID) – API-Key identifier.

  • tag (Tag) – APIKeyView.tag value. Use view() to retrieve it.

  • description (Optional[str]) – API-Key description.

  • revoked (Optional[bool]) – API-Key revoked flag. Key revocation is an irreversible operation.

Raises:
edit_my(api_key_id, tag, *, description=None, revoked=None)[source]#

Edit API-Key which API-Client owns.

Warning

Key revocation is an irreversible operation.

Note

Calls PATCH /users/me/api-keys/{api_key_id}. Doesn’t require any permissions.

Parameters:

  • api_key_id (UUID) – API-Key identifier.

  • tag (Tag) – APIKeyView.tag value. Use view() to retrieve it.

  • description (Optional[str]) – API-Key description.

  • revoked (Optional[bool]) – API-Key revoked flag. Key revocation is an irreversible operation.

Raises:

Note

Semantic error codes specific for this method:

New in version 2.8.

class cybsi.api.auth.api_key.APIKeyForm(expires_at, *, description=None, permissions=[])[source]#

API-Key form.

This is the form you need to fill to generate API-Key.

Parameters:

  • description (Optional[str]) – API-Key description.

  • expires_at (Optional[datetime]) – Expiration date. The API-Key is automatically revoked after the expiration date.

  • permissions (Iterable[Tuple[ResourceName, Literal['r', 'w', 'rw']]]) – List of permissions. If not set then the API-Key inherits permissions from the owner user.

class cybsi.api.auth.api_key.APIKeyRefView(data=None)[source]#

API-Key reference view.

property uuid#

API-Key identifier.

property url#

URL to get full API-Key view. Property is presented if Config embed_object_url is True.

property key#

API-Key.

class cybsi.api.auth.api_key.APIKeyCommonView(data=None)[source]#

API-Key common view.

property uuid#

API-Key identifier.

property url#

URL to get API-Key full view. Property is presented if Config embed_object_url is True.

property description#

API-Key description.

property created_at#

Creation date.

property expires_at#

Expiration date. None if it shouldn’t expire.

The API-Key is automatically revoked after the expiration date.

property last_used_at#

Last used date. None if it wasn’t used yet.

property revoked#

API-Key revoked flag.

property permissions#

List of permissions.

class cybsi.api.auth.api_key.APIKeyView(resp)[source]#

API-Key full view.

property uuid#

API-Key identifier.

property created_at#

Creation date.

property description#

API-Key description.

property expires_at#

Expiration date. None if it shouldn’t expire.

The API-Key is automatically revoked after the expiration date.

property last_used_at#

Last used date. None if it wasn’t used yet.

property permissions#

List of permissions.

property revoked#

API-Key revoked flag.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

Enrichment#

Use this section of API to control enrichment configuration and enrichment results.

class cybsi.api.enrichment.api.EnrichmentAPI(connector)[source]#

Enrichment API.

property config_rules#

Get config rules route.

property tasks#

Get enrichment tasks route.

property task_queue#

Get task queue route.

property external_dbs#

Get external databases route.

property analyzers#

Get analyzers route.

class cybsi.api.enrichment.api.EnrichmentAsyncAPI(connector)[source]#

Enrichment asynchronous API.

property tasks#

Get enrichment tasks route.

property task_queue#

Get task queue route.

enum cybsi.api.enrichment.enums.EnrichmentTypes(value)[source]#

Bases: CybsiAPIEnum

Enrichment type.

Valid values are as follows:

ArchiveUnpack = <EnrichmentTypes.ArchiveUnpack: 'ArchiveUnpack'>#

Archive unpack.

ArtifactAnalysis = <EnrichmentTypes.ArtifactAnalysis: 'ArtifactAnalysis'>#

Artifact analysis.

ArtifactDownload = <EnrichmentTypes.ArtifactDownload: 'ArtifactDownload'>#

Artifact download.

DNSLookup = <EnrichmentTypes.DNSLookup: 'DNSLookup'>#

DNS lookup.

ExternalDBLookup = <EnrichmentTypes.ExternalDBLookup: 'ExternalDBLookup'>#

External database lookup.

WhoisLookup = <EnrichmentTypes.WhoisLookup: 'WhoisLookup'>#

Whois lookup.

enum cybsi.api.enrichment.enums.EnrichmentTriggerTypes(value)[source]#

Bases: CybsiAPIEnum

Enrichment trigger type.

Valid values are as follows:

OnDemand = <EnrichmentTriggerTypes.OnDemand: 'OnDemand'>#

Enrichment starts on manual task creation through API.

OnRegistration = <EnrichmentTriggerTypes.OnRegistration: 'OnRegistration'>#

Enrichment starts automatically on artifact registration or entity mention.

enum cybsi.api.enrichment.enums.EnrichmentErrorCodes(value)[source]#

Bases: CybsiAPIEnum

Enrichment task error code.

Valid values are as follows:

FatalError = <EnrichmentErrorCodes.FatalError: 'FatalError'>#

Enricher internal error.

TemporaryError = <EnrichmentErrorCodes.TemporaryError: 'TemporaryError'>#

Task timed out, network connectivity issues and so on.

NotFound = <EnrichmentErrorCodes.NotFound: 'NotFound'>#

Requested entity wasn’t found in external database.

UnsupportedArtifact = <EnrichmentErrorCodes.UnsupportedArtifact: 'UnsupportedArtifact'>#

EnrichmentTypes.ArtifactAnalysis only. Enricher doesn’t support such artifacts (invalid archive format, artifact size is too big).

Unavailable = <EnrichmentErrorCodes.Unavailable: 'Unavailable'>#

EnrichmentTypes.ArtifactDownload, EnrichmentTypes.WhoisLookup only. Resource under provided URL is not available.

CorruptedArchive = <EnrichmentErrorCodes.CorruptedArchive: 'CorruptedArchive'>#

Only in task API. Archive is corrupted.

InvalidPassword = <EnrichmentErrorCodes.InvalidPassword: 'InvalidPassword'>#

EnrichmentTypes.ArchiveUnpack only in task API. An incorrect archive password is specified or a password is required to unpack (not specified).

enum cybsi.api.enrichment.enums.EnrichmentTaskPriorities(value)[source]#

Bases: CybsiAPIEnum

Enrichment task priority.

Valid values are as follows:

High = <EnrichmentTaskPriorities.High: 'High'>#

High.

Normal = <EnrichmentTaskPriorities.Normal: 'Normal'>#

Normal.

enum cybsi.api.enrichment.enums.EnrichmentTaskStatuses(value)[source]#

Bases: CybsiAPIEnum

Enrichment task status.

Valid values are as follows:

Pending = <EnrichmentTaskStatuses.Pending: 'Pending'>#

Task in the queue, awaiting execution (new or has been restarted).

Executing = <EnrichmentTaskStatuses.Executing: 'Executing'>#

The task is in progress.

Failed = <EnrichmentTaskStatuses.Failed: 'Failed'>#

An error has occurred, after a while another attempt will be made.

Completed = <EnrichmentTaskStatuses.Completed: 'Completed'>#

Final state. Task completed successfully.

Aborted = <EnrichmentTaskStatuses.Aborted: 'Aborted'>#

Final state. The task could not be completed due to an error.

Configuration#

Use this section of API to operate config rules.

class cybsi.api.enrichment.config_rules.ConfigRulesAPI(connector)[source]#

Config rules API.

view(rule_uuid)[source]#

Get the config rule view.

New in version 2.7.

Note

Calls GET /enrichment/config/rules/{rule_uuid}.

Parameters:

rule_uuid (UUID) – config rule uuid.

Return type:

ConfigRuleView

Returns:

View of the config rule.

Raises:

NotFoundError – Config rule not found.

register(rule)[source]#

Register config rule.

New in version 2.7.

Note

Calls POST /enrichment/config/rules.

Parameters:

rule (ConfigRuleForm) – Filled config rule form.

Return type:

RefView

Returns:

Reference to config rule in API.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
filter(*, data_source_uuids=None, trigger_data_source_uuids=None, enrichment_types=None, artifact_types=None, entity_types=None, trigger_types=None, is_disabled=None, name=None, cursor=None, limit=None)[source]#

Filter config rules.

Changed in version 2.8: Added new parameters: enrichment_types, artifact_types, entity_types, trigger_types,`is_disabled`, rule_name. Parameters data_source_uuids, trigger_data_source_uuids changed to list.

Note

Calls GET /enrichment/config/rules.

Parameters:
Return type:

Page[ConfigRuleCommonView]

Returns:

Page of config rules.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
edit(rule_uuid, tag, *, name=None, is_disabled=None, triggers=None, trigger_data_source_uuids=None, artifact_types=None, entity_types=None, data_source_uuids=None, throttling_interval=None, enrichment=None)[source]#

Edit config rule.

New in version 2.7.

Note

Calls PATCH /enrichment/config/rules/{rule_uuid}.

Parameters:
Raises:
Return type:

None

Note

Semantic error codes specific for this method:
class cybsi.api.enrichment.config_rules.ConfigRuleCommonView(data=None)[source]#

Config rule object view.

property name#

Config rule name.

property is_disabled#

Disabled config rule flag.

property is_builtin#

Builtin config rule flag.

Builtin rules can be set to disabled state, other attributes are immutable.

property triggers#

List of enrichment trigger types.

property enrichment#

Enrichment type.

property artifact_types#

List of artifact types.

Not empty for ArtifactAnalysis and ArchiveUnpack enrichment types.

property entity_types#

List of entity types.

Not empty for DNSLookup, WhoisLookup, ExternalDBLookup enrichment types.

property data_sources#

Data sources associated with enrichers.

The rule creates enrichment tasks for enrichers listed here.

property trigger_data_sources#

Entity/Artifact registrar associated datasource list.

The rule is applied only if entity was mentioned or artifact was registered by one of data sources from the list.

property throttling_interval#

Throttling interval in seconds.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.config_rules.ConfigRuleView(resp)[source]#

Config rule response view.

property artifact_types#

List of artifact types.

Not empty for ArtifactAnalysis and ArchiveUnpack enrichment types.

property data_sources#

Data sources associated with enrichers.

The rule creates enrichment tasks for enrichers listed here.

property enrichment#

Enrichment type.

property entity_types#

List of entity types.

Not empty for DNSLookup, WhoisLookup, ExternalDBLookup enrichment types.

property is_builtin#

Builtin config rule flag.

Builtin rules can be set to disabled state, other attributes are immutable.

property is_disabled#

Disabled config rule flag.

property name#

Config rule name.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property throttling_interval#

Throttling interval in seconds.

property trigger_data_sources#

Entity/Artifact registrar associated datasource list.

The rule is applied only if entity was mentioned or artifact was registered by one of data sources from the list.

property triggers#

List of enrichment trigger types.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.config_rules.ConfigRuleForm(name, triggers, *, data_source_uuids, enrichment, is_disabled=False, trigger_data_source_uuids=None, artifact_types=None, entity_types=None, throttling_interval=None)[source]#

Config rule form.

This is the form you need to fill to register config rule.

Parameters:

  • name (str) – Config rule name.

  • triggers (Iterable[EnrichmentTriggerTypes]) – Non-empty list of enrichment trigger types.

  • data_source_uuids (Iterable[UUID]) – Non-empty data source uuid list associated with enrichers.

  • enrichment (EnrichmentTypes) – Enrichment type. Must be ArtifactAnalysis or ExternalDBLookup type for rule registration.

  • is_disabled (Optional[bool]) – Disabled config rule flag.

  • trigger_data_source_uuids (Optional[Iterable[UUID]]) – Entity/Artifact registrar associated datasource list

  • artifact_types (Optional[Iterable[ArtifactTypes]]) – List of artifact types. Not-empty for ArtifactAnalysis enrichment type.

  • entity_types (Optional[Iterable[EntityTypes]]) – List of entity types. Not-empty for ExternalDBLookup enrichment type.

  • throttling_interval (Optional[int]) – Throttling interval in seconds. Required for OnRegistration trigger type and must be minimum 3600 sec.

Usage:
>>> import uuid
>>> from cybsi.api.enrichment import (
>>>     EnrichmentTypes,
>>>     EnrichmentTriggerTypes,
>>>     ConfigRuleForm,
>>> )
>>> from cybsi.api.artifact import ArtifactTypes
>>> rule = ConfigRuleForm(
>>>     name="test artifact analysis rule",
>>>     data_source_uuids=[uuid.UUID("3ab411dc-17ab-4169-8ea6-c08271fca49e")],
>>>     triggers=[EnrichmentTriggerTypes.OnRegistration],
>>>     enrichment=EnrichmentTypes.ArtifactAnalysis,
>>>     artifact_types=[ArtifactTypes.FileSample, ArtifactTypes.Archive],
>>>     is_disabled=True,
>>> )

Tasks#

Use this section of API operate enrichment tasks.

The API allows to fetch and filter enrichment tasks. It also allows registering enrichment task to start enrichment forcibly.

class cybsi.api.enrichment.tasks.TasksAPI(connector)[source]#

Enrichment task API.

register(form)[source]#

Register enrichment task to start enrichment forcibly.

Note

Calls POST /enrichment/tasks.

Parameters:

form (TaskForm) – Filled enrichment task form.

Return type:

RefView

Returns:

Reference to enrichment task in API.

Raises:

Note

Semantic error codes specific for this method:
view(task_uuid)[source]#

Get the enrichment task view.

Note

Calls GET /enrichment/tasks/{task_uuid}.

Parameters:

task_uuid (UUID) – enrichment task uuid.

Return type:

TaskView

Returns:

View of the enrichment task.

Raises:

NotFoundError – Enrichment task not found.

filter(*, artifact_uuid=None, entity_uuid=None, data_sources=None, statuses=None, cursor=None, limit=None)[source]#

Get enrichment task filtration list.

Returns Pending, Completed and Failed enrichment tasks.

Note

Calls GET /enrichment/tasks

Parameters:
Return type:

Page[TaskView]

Returns:

Page with enrichment tasks and cursor allowing to get next batch of enrichment tasks.

Raises:

  • InvalidRequestError – Artifact uuid and entity uuid parameters are missing. At least one of these parameters must be specified.

  • SemanticError – Request contains logic errors.

Note

Semantic error codes specific for this method:
class cybsi.api.enrichment.tasks.TasksAsyncAPI(connector)[source]#

Enrichment task API.

async register(form)[source]#

Register enrichment task to start enrichment forcibly.

Note

Calls POST /enrichment/tasks.

Parameters:

form (TaskForm) – Filled enrichment task form.

Return type:

RefView

Returns:

Reference to enrichment task in API.

Raises:

Note

Semantic error codes specific for this method:
async view(task_uuid)[source]#

Get the enrichment task view.

Note

Calls GET /enrichment/tasks/{task_uuid}.

Parameters:

task_uuid (UUID) – enrichment task uuid.

Return type:

TaskView

Returns:

View of the enrichment task.

Raises:

NotFoundError – Enrichment task not found.

async filter(*, artifact_uuid=None, entity_uuid=None, data_sources=None, statuses=None, cursor=None, limit=None)[source]#

Get enrichment task filtration list.

Returns Pending, Completed and Failed enrichment tasks.

Note

Calls GET /enrichment/tasks

Parameters:
Return type:

AsyncPage[TaskView]

Returns:

Page with enrichment tasks and cursor allowing to get next batch of enrichment tasks.

Raises:

  • InvalidRequestError – Artifact uuid and entity uuid parameters are missing. At least one of these parameters must be specified.

  • SemanticError – Request contains logic errors.

Note

Semantic error codes specific for this method:
class cybsi.api.enrichment.tasks.ArtifactAnalysisParamsForm(artifact_uuid, passwords=None)[source]#

Artifact analysis task parameters form.

Parameters:

  • artifact_uuid (UUID) – Artifact identifier.

  • passwords (Optional[Iterable[str]]) – Password list for unpacking artifact and/or its attachments (not all data sources).

class cybsi.api.enrichment.tasks.ArchiveUnpackParamsForm(artifact_uuid, register_nested_archive_as_file_sample=False, password=None)[source]#

Archive unpack task parameters form.

Parameters:

  • artifact_uuid (UUID) – Artifact identifier.

  • register_nested_archive_as_file_sample (Optional[bool]) – Flag that determines whether to register attached archives as FileSample artifacts during unpacking. Default value is false.

  • password (Optional[str]) – Archive password.

class cybsi.api.enrichment.tasks.ArtifactDownloadParamsForm(url, share_level, *, artifact_type=None)[source]#

Artifact download task parameters form.

Parameters:
class cybsi.api.enrichment.tasks.ExternalDBLookupParamsForm(entity_uuid)[source]#

External database task parameters form.

Parameters:

entity_uuid (UUID) – Entity identifier.

Note

Entity type depends on the data source. The applicability of the data source to given entity types can be verified by querying the enrichment configuration.

cybsi.api.enrichment.tasks.DNSLookupParamsForm#

DNS lookup task parameters form. (Alias of ExternalDBLookupParamsForm).

Parameters:

entity_uuid (UUID) – Entity identifier.

Note

For DNSLookup enrichment type can be only IPAddress, DomainName entity types.

cybsi.api.enrichment.tasks.WhoisLookupParamsForm#

Whois lookup task parameters form. (Alias of ExternalDBLookupParamsForm).

Parameters:

entity_uuid (UUID) – Entity identifier.

Note

For WhoisLookup enrichment type can be only IPAddress, DomainName entity types.

class cybsi.api.enrichment.tasks.ArtifactAnalysisParamsView(data=None)[source]#

Task parameters view of ArtifactAnalysis.

property artifact#

Artifact, enrichment target.

Note

Use ArtifactsAPI to retrieve complete artifact information and its binary content.

property image_id#

Analyzer-specific image id.

Deprecated since version 2.13: Always empty. Will be removed in future releases.

property passwords#

Password list for unpacking an artifact and/or its attachments.

class cybsi.api.enrichment.tasks.ArchiveUnpackParamsView(data=None)[source]#

Task parameters view of ArchiveUnpack.

property artifact#

Artifact, enrichment target.

Note

Use ArtifactsAPI to retrieve complete artifact information and its binary content.

property password#

Archive password.

property register_nested_archive_as_file_sample#

Flag that determines whether to register attached archives as FileSample artifacts during unpacking.

class cybsi.api.enrichment.tasks.ArtifactDownloadParamsView(data=None)[source]#

Task parameters view of ArtifactDownload.

property url#

URL of the resource to be loaded.

property share_level#

Share level.

property type#

Artifact type.

class cybsi.api.enrichment.tasks.ExternalDBLookupParamsView(data=None)[source]#

Task parameters view of ExternalDBLookup.

property entity#

Entity, enrichment target.

cybsi.api.enrichment.tasks.DNSLookupParamsView#

Task parameters view of DNSLookup. (Alias of ExternalDBLookupParamsView).

cybsi.api.enrichment.tasks.WhoisLookupParamsView#

Task parameters view of WhoisLookup. (Alias of ExternalDBLookupParamsView).

class cybsi.api.enrichment.tasks.ArtifactTaskResultView(data=None)[source]#

Artifact result task view for ArtifactDownload

class cybsi.api.enrichment.tasks.ReportTaskResultView(data=None)[source]#

Report result task view for ArtifactAnalysis

class cybsi.api.enrichment.tasks.ObservationTaskResultView(data=None)[source]#

Observation result task view for ExternalDBLookup, DNSLookup, WhoisLookup. ArchiveUnpack.

class cybsi.api.enrichment.tasks.EnrichmentTaskErrorView(data=None)[source]#

Enrichment task error view.

property code#

Error code.

property message#

Error massage.

class cybsi.api.enrichment.tasks.TaskForm(task_type, params, *, data_source=None)[source]#

Enrichment task form.

This is the form you need to fill to register enrichment task.

Parameters:
Usage:
>>> import uuid
>>> from cybsi.api.enrichment import (
>>>     EnrichmentTypes, TaskForm,
>>>     ArchiveUnpackParamsForm
>>> )
>>> params = ArchiveUnpackParamsForm(
>>>     artifact_uuid=uuid.UUID("4f9bc3d5-1f12-427e-bcd2-c83fdd09a90f")
>>> )
>>> task = TaskForm(
>>>     task_type=EnrichmentTypes.ArchiveUnpack,
>>>     params=params
>>> )
class cybsi.api.enrichment.tasks.TaskView(data=None)[source]#

Enrichment task view.

property priority#

Priority.

property created_at#

Date and time of task creation.

property updated_at#

Date and time of last task update.

property data_source#

Data source associated with enricher.

Not empty for ArtifactAnalysis, ExternalDBLookup enrichment type.

property type#

Enrichment type.

property params#

Parameters of task. Determine exact type of parameters using property type.

If enricher was a function, this would be function parameters.

Usage:
>>> from typing import cast
>>> from cybsi.api.enrichment import (
>>>     TaskView, EnrichmentTypes,
>>>     ExternalDBLookupParamsView
>>> )
>>> task_view = TaskView()
>>> if task_view.type == EnrichmentTypes.ExternalDBLookup:
>>>     lookup = cast(ExternalDBLookupParamsView, task_view.params)
>>>     print(lookup.entity)
property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

property status#

Enrichment task status.

property error#

Enrichment task error.

Can be filled only if the enrichment task status is Failed or Aborted.

property result#

Result of task. Determine exact type of result using property type.

If enricher was a function, this would be function parameters.

Usage:
>>> from typing import cast
>>> from cybsi.api.enrichment import (
>>>     TaskView, EnrichmentTypes,
>>>     ExternalDBLookupParamsView
>>> )
>>> task_view = TaskView()
>>> if task_view.type == EnrichmentTypes.ExternalDBLookup:
>>>     observation = cast(ObservationTaskResultView, task_view.result)
>>>     print(observation)

Task queue#

Use this section of API to implement a custom enricher.

The API allows to fetch tasks assigned to enricher. It also allows to publish task execution results and errors.

See also

See Implement an external database for a complete example of enricher capable of IP enrichment.

See Implement an analyzer for a complete example of enricher capable of File sample enrichment.

class cybsi.api.enrichment.task_queue.TaskQueueAPI(connector)[source]#

Task queue API.

New in version 2.7.

get_assigned_tasks(limit=1)[source]#

Assign a batch of pending enrichment tasks for execution by client.

New in version 2.7.

All returned tasks have status Executing.

Note

Calls POST /enrichment/task-queue/executing-tasks.

Parameters:

limit (int) – Maximum task batch size.

Return type:

List[AssignedTaskView]

Returns:

A batch of tasks for execution.

Warning

Please wait some time if get_assigned_tasks() returns empty list before calling it again.

complete_tasks(completed_tasks)[source]#

Register successful task results.

New in version 2.7.

Note

Calls POST /enrichment/task-queue/completed-tasks.

Parameters:

completed_tasks (Iterable[CompletedTaskForm]) – List of filled forms of completed tasks.

Return type:

None

Returns:

None on successful registration of results.

Raises:

Note

ForbiddenError error codes:

  • NotOwner – Task belongs to other enricher.

SemanticError codes specific for this method:
fail_tasks(failed_tasks)[source]#

Register failed task errors.

New in version 2.7.

Note

Calls POST /enrichment/task-queue/failed-tasks.

Parameters:

failed_tasks (Iterable[FailedTaskForm]) – List of filled forms of failed tasks.

Return type:

None

Returns:

None on successful registration of errors.

Raises:

Note

ForbiddenError codes:

  • NotOwner – Task belongs to other enricher.

SemanticError codes specific for this method:
class cybsi.api.enrichment.task_queue.TaskQueueAsyncAPI(connector)[source]#

Task queue API.

New in version 2.7.

async get_assigned_tasks(limit=1)[source]#

Assign a batch of pending enrichment tasks for execution by client.

New in version 2.7.

All returned tasks have status Executing.

Note

Calls POST /enrichment/task-queue/executing-tasks.

Parameters:

limit (int) – Maximum task batch size.

Return type:

List[AssignedTaskView]

Returns:

A batch of tasks for execution.

Warning

Please wait some time if get_assigned_tasks() returns empty list before calling it again.

async complete_tasks(completed_tasks)[source]#

Register successful task results.

New in version 2.7.

Note

Calls POST /enrichment/task-queue/completed-tasks.

Parameters:

completed_tasks (Iterable[CompletedTaskForm]) – List of filled forms of completed tasks.

Return type:

None

Returns:

None on successful registration of results.

Raises:

Note

ForbiddenError error codes:

  • NotOwner – Task belongs to other enricher.

SemanticError codes specific for this method:
async fail_tasks(failed_tasks)[source]#

Register failed task errors.

New in version 2.7.

Note

Calls POST /enrichment/task-queue/failed-tasks.

Parameters:

failed_tasks (Iterable[FailedTaskForm]) – List of filled forms of failed tasks.

Return type:

None

Returns:

None on successful registration of errors.

Raises:

Note

ForbiddenError codes:

  • NotOwner – Task belongs to other enricher.

SemanticError codes specific for this method:
class cybsi.api.enrichment.task_queue.AssignedTaskView(data=None)[source]#

Task assigned to enricher for execution.

property priority#

Priority.

property created_at#

Date and time of task creation.

property updated_at#

Date and time of last task update.

property data_source#

Data source associated with enricher.

property type#

Enrichment type.

Note

Possible values are subset of enums.EnrichmentTypes values. Only enums.EnrichmentTypes.ArtifactAnalysis and enums.EnrichmentTypes.ExternalDBLookup are possible here.

property params#

Parameters of task. Determine exact type of parameters using property type.

If enricher was a function, this would be function parameters.

Usage:
>>> from typing import cast
>>> from cybsi.api.enrichment import (
>>>     AssignedTaskView, EnrichmentTypes,
>>>     ExternalDBLookupParamsView
>>> )
>>> task_view = AssignedTaskView()
>>> if task_view.type == EnrichmentTypes.ExternalDBLookup:
>>>     lookup = cast(ExternalDBLookupParamsView, task_view.params)
>>>     print(lookup.entity)
property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.task_queue.CompletedTaskForm(task_uuid, result)[source]#

Completed task form. Use to register successful task result.

Parameters:
class cybsi.api.enrichment.task_queue.TaskResultObservationForm(observation_uuid)[source]#

Enrichment result containing observation.

Use Observations API to register observation and get its uuid.

Parameters:

observation_uuid (UUID) – Previously registered observation uuid.

class cybsi.api.enrichment.task_queue.TaskResultReportForm(report_uuid)[source]#

Enrichment result containing report.

Use Report API to register report and get its uuid.

Parameters:

report_uuid (UUID) – Previously registered report uuid.

class cybsi.api.enrichment.task_queue.TaskResultArtifactForm(artifact_uuid)[source]#

Enrichment result containing artifact.

Use Artifact API to register report and get its uuid.

Parameters:

artifact_uuid (UUID) – Previously registered artifact uuid.

class cybsi.api.enrichment.task_queue.FailedTaskForm(task_uuid, error_code, message)[source]#

Failed enrichment task form.

Parameters:

  • task_uuid (UUID) – UUID of task assigned for execution.

  • error_code (EnrichmentErrorCodes) – Enrichment error code.

  • message (str) – Error message.

External databases#

Use this section of API to operate external databases.

External databases are systems outside of Cybsi. They can be queried by Cybsi for information about entities. The result of such query an observation. The observation typically provides new attributes for the requested entity and relationships of the requested entity with other entities.

class cybsi.api.enrichment.external_dbs.ExternalDBsAPI(connector)[source]#

External databases API.

New in version 2.7.

view(db_uuid)[source]#

Get the external database view.

New in version 2.7.

Note

Calls GET /enrichment/external-dbs/{db_uuid}.

Parameters:

db_uuid (UUID) – External database uuid.

Return type:

ExternalDBView

Returns:

View of the external database.

Raises:

NotFoundError – External database not found.

register(form)[source]#

Register external database.

New in version 2.7.

Note

Calls POST /enrichment/external-dbs.

Parameters:

form (ExternalDBForm) – Filled external database form.

Return type:

RefView

Returns:

Reference to external database in API.

Raises:

Note

Semantic error codes::
edit(db_uuid, tag, *, entity_types=None, web_page_url=None, task_execution_timeout=None, task_execution_attempts_count=None)[source]#

Edit the external database.

New in version 2.7.

Note

Calls PATCH /enrichment/external-dbs/{db_uuid}.

Parameters:

  • db_uuid (UUID) – External database uuid.

  • tag (Tag) – ExternalDBView.tag value. Use view() to retrieve it.

  • entity_types (Optional[Iterable[EntityTypes]]) – Entity types list. Non-empty if not None.

  • web_page_url (Union[str, None, NullType]) – Link to the public page of the external database. Null resets URL to empty value. None means URL is left unchanged.

  • task_execution_timeout (Union[int, None, NullType]) – Enricher task execution timeout, sec. Timeout must be in range [1;864000]. Null means that Cybsi can use default timeout. None means timeout is left unchanged.

  • task_execution_attempts_count (Union[int, None, NullType]) – The maximum number of attempts to complete the task by the enricher. Count must be in range [1;1000]. Null means that Cybsi can use default count. None means that count is left unchanged.

Raises:
Return type:

None

filter(*, entity_types=None, data_source_uuid=None, cursor=None, limit=None)[source]#

Get page of filtered external databases list.

New in version 2.7.

Note

Calls GET /enrichment/external-dbs

Parameters:

  • entity_types (Optional[Iterable[EntityTypes]]) – Entity types list. Select external databases that accept any specified artifact type.

  • data_source_uuid (Optional[UUID]) – Data source identifier. Select analyzers by associated data source identifier.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[ExternalDBView]

Returns:

Page of filtered external databases list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
class cybsi.api.enrichment.external_dbs.ExternalDBView(resp)[source]#
property data_source#

Data source reference representing external database.

property entity_types#

Entity types we can enrich in the external database.

property web_page_url#

Link to the public page of the external database.

property task_execution_timeout#

Enricher task execution timeout, sec.

property task_execution_attempts_count#

The maximum number of attempts to complete the task by the enricher.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.external_dbs.ExternalDBForm(data_source_uuid, entity_types, *, web_page_url=None, task_execution_timeout=None, task_execution_attempts_count=None)[source]#

External database form.

This is the form you need to fill to register external database.

Parameters:

  • data_source_uuid (UUID) – Data source identifier representing external database. Unique for external database.

  • entity_types (Iterable[EntityTypes]) – Non-empty entity types list.

  • web_page_url (Optional[str]) – Link to the public page of the external database.

  • task_execution_timeout (Optional[int]) – Enricher task execution timeout, sec. Timeout must be in range [1;864000].

  • task_execution_attempts_count (Optional[int]) – The maximum number of attempts to complete the task by the enricher. Count must be in range [1;1000].

Usage:
>>> import uuid
>>> from cybsi.api.enrichment import ExternalDBForm
>>> from cybsi.api.observable import EntityTypes
>>> external_db = ExternalDBForm(
>>>     data_source_uuid=uuid.UUID("4fd3126f-a0e8-4613-8dc5-cb449641adf2"),
>>>     entity_types=[EntityTypes.DomainName, EntityTypes.IPAddress],
>>> )

Analyzers#

Use this section of API to operate analyzers.

Analyzers are systems outside Cybsi. They can be queried by Cybsi for information about artifacts. The result of such query is report. The reports can contain observations and artifacts. The artifact is a regular file with additional attributes that can be analyzed or unpacked by the system. The observation typically provides group of facts obtained after analyzing an artifact.

class cybsi.api.enrichment.analyzers.AnalyzersAPI(connector)[source]#

Analyzers API.

New in version 2.7.

view(analyzer_uuid)[source]#

Get the analyzer view.

New in version 2.7.

Note

Calls GET /enrichment/analyzers/{analyzer_uuid}.

Parameters:

analyzer_uuid (UUID) – Analyzer uuid.

Return type:

AnalyzerView

Returns:

View of the analyzer.

Raises:

NotFoundError – Analyzer not found.

register(form)[source]#

Register analyzer.

New in version 2.7.

Note

Calls POST /enrichment/analyzers.

Parameters:

form (AnalyzerForm) – Filled analyzer form.

Return type:

RefView

Returns:

Reference to analyzer in API.

Raises:

Note

Semantic error codes:
edit(analyzer_uuid, tag, *, artifact_types=None, artifact_size_limit=None, dashboard_url=None, task_execution_timeout=None, task_execution_attempts_count=None)[source]#

Edit the analyzer.

New in version 2.7.

Note

Calls PATCH /enrichment/analyzers/{analyzer_uuid}.

Parameters:

  • analyzer_uuid (UUID) – Analyzer uuid.

  • tag (Tag) – AnalyzerView.tag value. Use view() to retrieve it.

  • artifact_types (Optional[Iterable[ArtifactTypes]]) – Non-empty artifact types list, if not None.

  • artifact_size_limit (Union[int, None, NullType]) – Maximum allowable size of an artifact for analysis, bytes. Null means there is no limit. None means limit is left unchanged.

  • dashboard_url (Union[str, None, NullType]) – Analyzer panel link. Null resets dashboard URL to empty value. None means URL is left unchanged.

  • task_execution_timeout (Union[int, None, NullType]) – Enricher task execution timeout, sec. Timeout must be in range [1;864000]. Null means that Cybsi can use default timeout. None means timeout is left unchanged.

  • task_execution_attempts_count (Union[int, None, NullType]) – The maximum number of attempts to complete the task by the enricher. Count must be in range [1;1000]. Null means that Cybsi can use default count. None means that count is left unchanged.

Raises:
Return type:

None

filter(*, artifact_types=None, data_source_uuid=None, cursor=None, limit=None)[source]#

Get page of filtered analyzers list.

Note

Calls GET /enrichment/analyzers

Parameters:

  • artifact_types (Optional[Iterable[ArtifactTypes]]) – Artifact types list. Select analyzers that accept any specified artifact type.

  • data_source_uuid (Optional[UUID]) – Data source identifier. Select analyzers by associated data source identifier.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[AnalyzerCommonView]

Returns:

Page of filtered analyzers list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
class cybsi.api.enrichment.analyzers.AnalyzerCommonView(data=None)[source]#

Analyzer common view

property artifact_types#

Artifact types we can enrich in the analyzer.

property artifact_size_limit#

Maximum allowable size of an artifact for analysis, bytes.

property dashboard_url#

Analyzer panel link.

property task_execution_timeout#

Enricher task execution timeout, sec

property task_execution_attempts_count#

The maximum number of attempts to complete the task by the enricher.

property data_source#

Data source view representing analyzer.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.analyzers.AnalyzerView(resp)[source]#
property artifact_size_limit#

Maximum allowable size of an artifact for analysis, bytes.

property artifact_types#

Artifact types we can enrich in the analyzer.

property dashboard_url#

Analyzer panel link.

property data_source#

Data source view representing analyzer.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property task_execution_attempts_count#

The maximum number of attempts to complete the task by the enricher.

property task_execution_timeout#

Enricher task execution timeout, sec

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.enrichment.analyzers.AnalyzerForm(data_source_uuid, artifact_types, *, artifact_size_limit=None, dashboard_url=None, task_execution_timeout=None, task_execution_attempts_count=None)[source]#

Analyzer form.

This is the form you need to fill to register analyzer.

Parameters:

  • data_source_uuid (UUID) – Data source identifier representing analyzer. Unique for analyzer.

  • artifact_types (Iterable[ArtifactTypes]) – Non-empty artifact types list.

  • artifact_size_limit (Optional[int]) – Maximum allowable size of an artifact for analysis, bytes. Empty value means there is no limit.

  • dashboard_url (Optional[str]) – Analyzer panel link.

  • task_execution_timeout (Optional[int]) – Enricher task execution timeout, sec. Timeout must be in range [1;864000].

  • task_execution_attempts_count (Optional[int]) – The maximum number of attempts to complete the task by the enricher. Count must be in range [1;1000].

Usage:
>>> import uuid
>>> from cybsi.api.enrichment import AnalyzerForm
>>> from cybsi.api.artifact import ArtifactTypes
>>> analyzer = AnalyzerForm(
>>>     data_source_uuid=uuid.UUID("4fd3126f-a0e8-4613-8dc5-cb449641adf2"),
>>>     entity_types=[ArtifactTypes.FileSample, ArtifactTypes.Archive],
>>> )

Observable entities#

Use this section of API to register entities and retrieve aggregates about entities.

class cybsi.api.observable.ObservableAPI(connector)[source]#

Observable API.

property entities#

Entities API.

property entity_views#

Entity views API.

property relationships#

Relationships API.

property annotations#

Annotations API.

class cybsi.api.observable.ObservableAsyncAPI(connector)[source]#

Observable async API.

property entities#

Entities API handle.

class cybsi.api.observable.EntitiesAPI(connector)[source]#

Entities API.

register(entity)[source]#

Register an entity.

Note

Calls PUT /observable/entities.

Parameters:

entity (EntityForm) – Entity registration form.

Return type:

RefView

Returns:

Reference to a registered entity.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
Usage:
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import EntityForm, EntityTypes, EntityKeyTypes
>>> client: CybsiClient
>>> entity_form = EntityForm(
>>>     EntityTypes.File,
>>>     [(EntityKeyTypes.MD5, "3c4729715ef0d6bafd3d9c719e152099")],
>>> )
>>> # if you need to add extra key to entity form keys
>>> entity_form.add_key(
>>>     EntityKeyTypes.SHA1,
>>>     "0462cb99ddd46c142aa46244cb8c2d35bfe226f5",
>>> )
>>> ref = client.observable.entities.register(entity_form)
>>> # It's a good idea to use entity uuid in observation forms.
>>> # But here we simply print returned ref.
>>> print(ref)
view(entity_uuid, *, sections=None, forecast_at=None, with_valuable_facts=None)[source]#

Get an entity view.

Note

Calls GET /observable/entities/{entity_uuid}.

Parameters:
Return type:

EntityAggregateView

Returns:

Aggregated view of the entity.

Raises:

NotFoundError – Entity not found.

Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import (
>>>     EntityAggregateSections,
>>>     EntityTypes,
>>>     EntityKeyTypes
>>> )
>>> client: CybsiClient
>>> filter_sections = [
>>>     EntityAggregateSections.AssociatedAttributes,
>>>     EntityAggregateSections.NaturalAttributes,
>>> ]
>>> aggregate = client.observable.entities.view(
>>>    UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>    sections=filter_sections,
>>>    with_valuable_facts = True
>>> )
>>> # Do something with an aggregate
>>> if aggregate.sections.associated_attributes is not None:
>>>     for attr in aggregate.sections.associated_attributes.data:
>>>         print(attr.attribute_name)
aggregate(*, entity_uuids=None, dict_item_uuid=None, entity_type=None, key_type=None, key=None, suggest=None, sections=None, forecast_at=None, cursor=None, limit=None)[source]#

Get list of aggregated entities.

Changed in version 2.8: Added new parameters: ent_type, key_type, key. Parameter entity_uuids changed to Optional.

Changed in version 2.11: Added new parameter dict_item_uuid.

Changed in version 2.13: Added new parameter suggest.

Note

Calls GET /observable/entities.

To get entity aggregate, only one of [key, entity_uuids] parameters should be specified else Cybsi API will return error.

Parameters:

  • entity_uuids (Optional[Iterable[UUID]]) – Entity uuids. Excludes parameters: dict_item_uuid, entity_type, key_type, key, suggest.

  • dict_item_uuid (Optional[UUID]) – Dictionary item which is attributed to the entity. Excludes parameters: entity_uuids, entity_type, key_type, key, suggest.

  • entity_type (Optional[EntityTypes]) – Entity type. Excludes parameter entity_uuids, dict_item_uuid and requires parameter key. The parameter is not required if the entity_type can be uniquely determined by key_type.

  • key_type (Optional[EntityKeyTypes]) – Entity natural key type. Excludes parameter entity_uuids, dict_item_uuid, suggest and requires parameter key. The parameter is not required if only one key_type is used for the specified entity_type.

  • key (Optional[str]) – Entity natural key value. Excludes parameter suggest and required if entity_type or key_type parameter is specified. It is possible to pass a key value in a non-canonical representation.

  • suggest (Optional[str]) – Case-insensitive prefix of natural key or value of identity.Names attribute. Excludes parameter key and can be used with entity_type parameter. suggest length must greater than or equals to 2.

  • sections (Optional[Iterable[EntityAggregateSections]]) – Sections to be aggregated.

  • forecast_at (Optional[datetime]) – Point of time to aggregate sections at.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[EntityAggregateView]

Returns:

Page with aggregated entities views and next page cursor.

Note

Semantic error codes specific for this method:
Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>> from cybsi.api.observable import (
>>>     EntityAggregateSections,
>>>     EntityTypes,
>>>     EntityKeyTypes
>>> )
>>> client: CybsiClient
>>> entities = [
>>>     UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>     UUID("85fca85e-0036-488d-9dcf-35970d182afc"),
>>> ]
>>> filter_sections = [EntityAggregateSections.AssociatedAttributes]
>>> # You can aggregate entities by entity_uuids. Be aware that
>>> # optional parameters such as entity_type, key_type or key are excluded.
>>> # Cybsi API will return an error if you specify
>>> # one of these with entity_uuids.
>>> aggregates = client.observable.entities.aggregate(
>>>     entity_uuids=entities,
>>>     sections=filter_sections
>>> )
>>> for item in chain_pages(aggregates):
>>>     # Do something with an aggregate
>>>     pass
>>>
>>> # Also you can aggregate entities by natural key, but for this
>>> # you need to specified one of parameters entity_type or key_type.
>>> # Keep in mind that Cybsi API will return error if you provide
>>> # entity_uuids with natural key.
>>> aggregates = client.observable.entities.aggregate(
>>>     entity_type=EntityTypes.URL,
>>>     key_type=EntityKeyTypes.String,
>>>     key="http://young.biz/wp-content/index/",
>>> )
canonize_key(entity_type, key_type, value)[source]#

Get a canonized entity key.

Note

Calls GET /observable/entity-canonical-key.

Parameters:
Return type:

EntityKeyView

Returns:

Canonized key view.

Note

Semantic error codes specific for this method:
Usage:
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import EntityTypes, EntityKeyTypes
>>> client: CybsiClient
>>> canonized_key = client.observable.entities.canonize_key(
>>>     EntityTypes.DomainName, EntityKeyTypes.String, "xn--80ATjc.XN--P1AI"
>>> )
>>> # Do something with the canonized key
>>> print(canonized_key)
>>> # {
>>> #   "type": "String",
>>> #   "value": "окна.рф"
>>> # }
add_natural_keys(entity_uuid, keys)[source]#

Add entity nalural keys.

Note

Calls PUT /observable/entities/{entity_uuid}/keys.

Parameters:
Raises:

SemanticError – Form contains logic errors.

Return type:

None

Note

Semantic error codes specific for this method:
Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import EntityKeyTypes
>>> client: CybsiClient
>>> entity_keys = [
>>>     (EntityKeyTypes.MD5, "3c4729715ef0d6bafd3d9c719e152099"),
>>>     (EntityKeyTypes.SHA1, "0462cb99ddd46c142aa46244cb8c2d35bfe226f5")
>>> ],
>>> client.observable.entities.add_natural_keys(
>>>     entity_uuid=uuid.UUID("d90f5ea5-0f33-44a4-b063-6bf90e654a81"),
>>>     form=entity_keys,
>>> )
forecast_attribute_values(entity_uuid, attr_name, forecast_at=None)[source]#

Get a forecast of entity attribute value.

See also

See Attributes of observable entities for complete information about available attributes.

Note

Calls GET /observable/entities/{entity_uuid}/attributes/{attr_name}.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • attr_name (AttributeNames) – Attribute name. Converts to kebab-case on URL-path.

  • forecast_at (Optional[datetime]) – Point of time to forecast at. If not specified, forecast is built on current time.

Return type:

EntityAttributeForecastView

Returns:

Attribute forecast view.

Raises:

Note

Semantic error codes specific for this method:
Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import EntityAttributeForecastView
>>> from cybsi.api.observable import AttributeNames
>>> client: CybsiClient
>>> attr_forecast = client.observable.entities.forecast_attribute_values(
>>>     entity_uuid=UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>     attr_name=AttributeNames.IsIoC,
>>> )
>>> # Do something with the forecast
>>> print(attr_forecast)

Get a list of link forecasts of entity.

See also

See Relationships of observable entities for complete information about available relationships.

Note

Calls GET /observable/entities/{entity_uuid}/links.

Parameters:
Return type:

Page[EntityLinksForecastView]

Returns:

Page with links forecast view and next page cursor.

Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>> from cybsi.api.observable import (
>>>     EntityTypes,
>>>     LinkDirection,
>>>     RelationshipKinds,
>>> )
>>> from cybsi.api.observable import EntityLinksForecastView
>>> client: CybsiClient
>>> links_forecast = client.observable.entities.forecast_links(
>>>     entity_uuid=UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>     related_entity_types=[EntityTypes.IPAddress, EntityTypes.File],
>>>     direction=[LinkDirection.Forward],
>>>     kind=[RelationshipKinds.ResolvesTo, RelationshipKinds.Uses],
>>>     confidence_threshold=0.5
>>> )
>>> # Do something with the forecast
>>> print(links_forecast)

Get statictics of forecasted links for entity considering all facts about entity.

Note

Calls GET /observable/entities/{entity_uuid}/link-type-statistic.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • forecast_at (Optional[datetime]) – Date of forecast. If not specified, forecast is built on current time.

Return type:

List[EntityLinkStatisticView]

Returns:

List of link forecasts. Links are grouped by direction, relation kind,

and entity type. Groups are ordered by direction, relation kind, and entity type.

Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import EntityLinkStatisticView
>>> client: CybsiClient
>>> link_forecast = client.observable.entities.forecast_links_statistic(
>>>     entity_uuid=UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a")
>>> )
>>> # Do something with the forecast
>>> print(link_forecast)
add_labels(entity_uuid, labels)[source]#

Add entity labels.

Deprecated since version 2.14: Labels are attribute of entity. This method will be deleted soon. To register labels use Generic-observation register().

Note

Calls PUT /observable/entities/{entityUUID}/labels.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • labels (Iterable[str]) – List of labels. Label length must be in range [2, 50]. Labels are converted to lowercase before saving.

Return type:

None

delete_labels(entity_uuid, labels)[source]#

Delete entity labels.

Deprecated since version 2.14: Labels are attribute of entity and can’t be deleted. This method will be deleted soon. Method always raises MethodNotAllowedError.

Note

Calls DELETE /observable/entities/{entityUUID}/labels.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • labels (Iterable[str]) – List of labels. Labels are case-insensitive when compared.

Return type:

None

class cybsi.api.observable.EntitiesAsyncAPI(connector)[source]#

Asynchronous entities API.

async register(entity)[source]#

Register an entity.

Note

Calls PUT /observable/entities.

Parameters:

entity (EntityForm) – Entity registration form.

Return type:

RefView

Returns:

Reference to a registered entity.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
Usage:
>>> import asyncio
>>> from cybsi.api import CybsiAsyncClient
>>> from cybsi.api.observable import EntityForm, EntityTypes, EntityKeyTypes
>>> async def register_entities():
>>>     entities = [
>>>         EntityForm(
>>>             EntityTypes.File,
>>>             [(EntityKeyTypes.MD5, "3c4729715ef0d6bafd3d9c719e152099")]
>>>         ),
>>>         EntityForm(
>>>             EntityTypes.IPAddress,
>>>             [(EntityKeyTypes.String, "192.168.0.1")]
>>>         ),
>>>         EntityForm(
>>>             EntityTypes.DomainName,
>>>             [(EntityKeyTypes.String, "google.com")]
>>>         ),
>>>     ]
>>>     # concurrently register a batch of entities
>>>     async with CybsiAsyncClient as client:
>>>         registrations = [
>>>             client.observable.entities.register(e) for e in entities
>>>         ]
>>>         results = await asyncio.gather(*registrations)
>>>         uuids = ", ".join(str(u.uuid) for u in results)
>>>         print(f"Registered entities: {uuids}")
>>> asyncio.run(register_entities())
async view(entity_uuid, *, sections=None, forecast_at=None, with_valuable_facts=None)[source]#

Get an entity view.

Note

Calls GET /observable/entities/{entity_uuid}.

Parameters:
Return type:

EntityAggregateView

Returns:

Aggregated view of the entity.

Raises:

NotFoundError – Entity not found.

async aggregate(*, entity_uuids=None, dict_item_uuid=None, entity_type=None, key_type=None, key=None, suggest=None, sections=None, forecast_at=None, cursor=None, limit=None)[source]#

Get list of aggregated entities.

Changed in version 2.11: Added new parameter dict_item_uuid.

Changed in version 2.13: Added new parameter suggest.

Note

Calls GET /observable/entities.

To get entity aggregate, only one of [key, entity_uuids] parameters should be specified else Cybsi API will return error.

Parameters:

  • entity_uuids (Optional[Iterable[UUID]]) – Entity uuids. Excludes parameters: dict_item_uuid, entity_type, key_type, key, suggest.

  • dict_item_uuid (Optional[UUID]) – Dictionary item which is attributed to the entity. Excludes parameters: entity_uuids, entity_type, key_type, key, suggest.

  • entity_type (Optional[EntityTypes]) – Entity type. Excludes parameter entity_uuids, dict_item_uuid and requires parameter key. The parameter is not required if the entity_type can be uniquely determined by key_type.

  • key_type (Optional[EntityKeyTypes]) – Entity natural key type. Excludes parameter entity_uuids, dict_item_uuid, suggest and requires parameter key. The parameter is not required if only one key_type is used for the specified entity_type.

  • key (Optional[str]) – Entity natural key value. Excludes parameter suggest and required if entity_type or key_type parameter is specified. It is possible to pass a key value in a non-canonical representation.

  • suggest (Optional[str]) – Case-insensitive prefix of natural key or value of identity.Names attribute. Excludes parameter key and can be used with entity_type parameter. suggest length must greater than or equals to 2.

  • sections (Optional[Iterable[EntityAggregateSections]]) – Sections to be aggregated.

  • forecast_at (Optional[datetime]) – Point of time to aggregate sections at.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[EntityAggregateView]

Returns:

Page with aggregated entities views and next page cursor.

Note

Semantic error codes specific for this method:
async canonize_key(entity_type, key_type, value)[source]#

Get a canonized entity key.

Note

Calls GET /observable/entity-canonical-key.

Parameters:
Return type:

EntityKeyView

Returns:

Canonized key view.

Note

Semantic error codes specific for this method:
async add_natural_keys(entity_uuid, keys)[source]#

Add entity nalural keys.

Note

Calls PUT /observable/entities/{entity_uuid}/keys.

Parameters:
Raises:

SemanticError – Form contains logic errors.

Return type:

None

Note

Semantic error codes specific for this method:
async forecast_attribute_values(entity_uuid, attr_name, forecast_at=None)[source]#

Get a forecast of entity attribute value.

See also

See Attributes of observable entities for complete information about available attributes.

Note

Calls GET /observable/entities/{entity_uuid}/attributes/{attr_name}.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • attr_name (AttributeNames) – Attribute name. Converts to kebab-case on URL-path.

  • forecast_at (Optional[datetime]) – Point of time to forecast at. If not specified, forecast is built on current time.

Return type:

EntityAttributeForecastView

Returns:

Attribute forecast view.

Raises:

Note

Semantic error codes specific for this method:

Get a list of link forecasts of entity.

See also

See Relationships of observable entities for complete information about available relationships.

Note

Calls GET /observable/entities/{entity_uuid}/links.

Parameters:
Return type:

AsyncPage[EntityLinksForecastView]

Returns:

Page with links forecast view and next page cursor.

Get statictics of forecasted links for entity considering all facts about entity.

Note

Calls GET /observable/entities/{entity_uuid}/link-type-statistic.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • forecast_at (Optional[datetime]) – Date of forecast. If not specified, forecast is built on current time.

Return type:

List[EntityLinkStatisticView]

Returns:

List of link forecasts. Links are grouped by direction, relation kind,

and entity type. Groups are ordered by direction, relation kind, and entity type.

add_labels(entity_uuid, labels)[source]#

Add entity labels.

Deprecated since version 2.14: Labels are attribute of entity. This method will be deleted soon. To register labels use Generic-observation register().

Note

Calls PUT /observable/entities/{entityUUID}/labels.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • labels (Iterable[str]) – List of labels. Label length must be in range [2, 50]. Labels are converted to lowercase before saving.

Return type:

None

delete_labels(entity_uuid, labels)[source]#

Delete entity labels.

Deprecated since version 2.14: Labels are attribute of entity and can’t be deleted. This method will be deleted soon. Method always raises MethodNotAllowedError.

Note

Calls DELETE /observable/entities/{entityUUID}/labels.

Parameters:

  • entity_uuid (UUID) – Entity UUID.

  • labels (Iterable[str]) – List of labels. Labels are case-insensitive when compared.

Return type:

None

class cybsi.api.observable.AbstractEntityView(data=None)[source]#

This is the class you need to extend to implement a custom entity view.

abstract classmethod _view_uuid()[source]#

UUID of the view in API. Usually well-known.

Return type:

UUID

New in version 2.9.

class cybsi.api.observable.EntityViewsAPI(connector)[source]#

Entity views API.

Entity views allow to redefine API response format. In other words, some API methods returning basic entity view (EntityView) can return a completely different structure.

The basic entity view contains entity keys and type, but custom views can contain much more information about entity. The example of a method utilizing custom views is entities().

Extend AbstractEntityView to implement a custom entity view.

New in version 2.9.

filter(*, cursor=None, limit=None)[source]#

Filter views of observable entities.

New in version 2.9.

Note

Calls GET /entity-views.

Parameters:
Return type:

Page[EntityViewView]

Returns: List of views.

class cybsi.api.observable.EntityViewView(data=None)[source]#

View of the entity view.

New in version 2.9.

property uuid#

Entity view UUID.

property name#

Entity view name.

class cybsi.api.observable.EntityForm(ent_type, ent_keys=[])[source]#

Entity form. Use to register or update an entity.

Parameters:
add_key(key_type, value)[source]#

Add natural key to the list of entity keys.

Parameters:

  • key_type (EntityKeyTypes) – Key type. Valid values depend on entity type.

  • value (str) – Key value.

Return type:

EntityForm

Returns:

Updated entity form.

class cybsi.api.observable.EntityKeyView(data=None)[source]#

Entity key view.

property type#

Entity key type.

property value#

Entity key value. Type depends on key type.

class cybsi.api.observable.EntityView(data=None)[source]#

Default and complete entity view. Includes entity types and natural keys.

New in version 2.9.

property uuid#

Entity UUID.

property url#

URL of the entity in API. Property is presented if Config embed_object_url is True.

property type#

Entity type.

property keys#

Entity natural keys.

class cybsi.api.observable.EntityAggregateView(data=None)[source]#

Entity aggregated view.

property sections#

Entity aggregated sections.

property first_seen#

Date and time when entity was first mentioned in the observations

property last_seen#

Date and time when entity was last mentioned in the observations

property keys#

Entity natural keys.

property type#

Entity type.

property url#

URL of the entity in API. Property is presented if Config embed_object_url is True.

property uuid#

Entity UUID.

class cybsi.api.observable.EntityAttributeForecastView(data, attribute_name)[source]#

Entity attribute forecast view.

property has_conflicts#

Entity has conflicting facts about attribute.

property values#

Attribute values forecast in descending order of confidence.

class cybsi.api.observable.AttributeForecastView(data, attribute_name)[source]#

Single attribute value forecast.

property value#

Return value type depends on attribute.

Note

Return RefView type is used to get the value of a dictionary item attribute. You can resolve the ref using view_item().

property confidence#

Confidence of forecast.

property valuable_facts#

List of forecast valuable facts in descending order of confidence.

class cybsi.api.observable.SectionsView(data)[source]#

Sections list view.

property associated_attributes#

Associated with the entity attributes.

Raises:

KeyError – Section is absent in the SectionsView.

property natural_attributes#

Natural attributes of the entity.

Raises:

KeyError – Section is absent in the SectionsView.

property threat#

Entity threat status.

Raises:

KeyError – Section is absent in the SectionsView.

property geo_ip#

GeoIP information.

Raises:

KeyError – Section is absent in the SectionsView.

property labels#

Labels of the entity.

Raises:

KeyError – Section is absent in the SectionsView.

class cybsi.api.observable.SectionView(data, data_view)[source]#

Common section view.

property name#

Section name.

property data_raw#

Section raw data.

property data#

Section data.

class cybsi.api.observable.AttributesSectionData(data=None)[source]#

View for attributes section data.

property attribute_name#

Attribute name.

property has_conflicts#

Attribute value has conflicts.

property values#

Attribute values.

class cybsi.api.observable.AttributeAggregatedValue(data, attribute_name)[source]#

View for attribute value aggregated data.

property value#

Attribute value. Returned value type depends on attribute.

Usage:
>>> from typing import cast
>>> from cybsi.api.observable import AttributeValuableFactView
>>> from cybsi.api.dictionary import DictionaryItemCommonView
>>>
>>> view = AttributesSectionData()
>>> if view.attribute_name == AttributeNames.MalwareFamilies:
>>>     for v in view.values:
>>>         value = cast(DictionaryItemCommonView, v.value)
>>>         print(value)
property confidence#

Confidence of the value. Value is in range (0; 1].

property valuable_facts#

Facts influenced on value and its confidence. Can return None if valuable facts list is not set.

Note

This list is not set in common aggregate methods results.

class cybsi.api.observable.ValuableFactView(data=None)[source]#

Facts influenced on value and its confidence.

property data_source#

Data source of the fact.

property share_level#

Share level of the fact.

property seen_at#

Date and time when facts were seen.

property confidence#

Data source confidence in the fact. Value is in range (0; 1].

property final_confidence#

Cybsi final confidence in the fact. Value is in range (0; 1].

class cybsi.api.observable.AttributeValuableFactView(data, attribute_name)[source]#

Valuable fact of attribute forecast view.

property value#

Facts attribute value. Returned value type depends on attribute.

Usage:
>>> from typing import cast
>>> from cybsi.api.observable import AttributeValuableFactView
>>> from cybsi.api.dictionary import DictionaryItemCommonView
>>>
>>> view = AttributesSectionData()
>>> if view.attribute_name == AttributeNames.MalwareFamilies:
>>>     for v in view.values:
>>>         value = cast(DictionaryItemCommonView, v.value)
>>>         print(value)
property confidence#

Data source confidence in the fact. Value is in range (0; 1].

property data_source#

Data source of the fact.

property final_confidence#

Cybsi final confidence in the fact. Value is in range (0; 1].

property seen_at#

Date and time when facts were seen.

property share_level#

Share level of the fact.

class cybsi.api.observable.ThreatSectionData(data=None)[source]#

View for threat section data.

property status#

Threat status.

class cybsi.api.observable.GeoIPSectionData(data=None)[source]#

View for GeoIP section data.

property asn#

Autonomous system number.

property country_code#

Country cody in ISO.

property country#

Country name.

class cybsi.api.observable.LabelsSectionData(data=None)[source]#

View for labels section data.

property labels#

Labels.

class cybsi.api.observable.EntityLinksForecastView(data=None)[source]#

Entity links forecast view.

Link forecast view.

property confidence#

Confidence of forecast.

class cybsi.api.observable.LinkForecastView(data=None)[source]#

Link forecast view.

property url#

URL of relationship forecast detailed information.

property direction#

Link direction.

property relation_kind#

Relationship kind.

property related_entity#

Related entity view.

class cybsi.api.observable.EntityLinkStatisticView(data=None)[source]#

Link statistics view.

Link type view.

Link statistic.

class cybsi.api.observable.LinkTypeView(data=None)[source]#

Link view.

property url#

URL of link detailed information.

property direction#

Link direction.

property relation_kind#

Relationship kind.

property related_entities_type#

Related entities types.

class cybsi.api.observable.LinkStatisticView(data=None)[source]#

Link statistic view.

property total#

Total number of forecasted links of this type.

property confidence_distribution#

Distribution of number of links by confidence.

class cybsi.api.observable.LinkConfidenceDistributionView(data=None)[source]#

Distribution of number of links by confidence with step of 0.1 in descending order.

property confidence_range#

List of confidence in range format (from; to].

property count#

Count of links whose forecast falls within specified range.

class cybsi.api.observable.RelationshipsAPI(connector)[source]#

Relationships API.

forecast(*, source_entity_uuid, target_entity_uuid, kind, forecast_at=None, valuable_facts=None)[source]#

Get forecast of relationship between two entities.

See also

See Relationships of observable entities for complete information about available relationships.

Note

Calls GET /observable/relationships/{sourceEntityUUID}/{relationKind}/{targetEntityUUID}. # noqa: E501

Parameters:

  • source_entity_uuid (UUID) – Source entity UUID.

  • kind (RelationshipKinds) – Kind of relationship. Converts to kebab-case on URL-path.

  • target_entity_uuid (UUID) – Target entity UUID.

  • forecast_at (Optional[datetime]) – Date of forecast. If not specified, forecast is built on current time.

  • valuable_facts (Optional[bool]) – Attach list of valuable facts to forecast.

Return type:

RelationshipsForecastView

Returns:

Relationship forecast view.

Usage:
>>> from uuid import UUID
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.observable import RelationshipKinds
>>> client: CybsiClient
>>> forecasts = client.observable.relationships.forecast(
>>>     source_entity_uuid = UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>     target_entity_uuid = UUID("3a53cc35-f632-434c-bd4b-1ed8c014003a"),
>>>     kind = RelationshipKinds.ResolvesTo,
>>> )
>>> # Do something with the forecast
>>> print(forecasts)
class cybsi.api.observable.RelationshipsForecastView(data=None)[source]#

Relationship forecast view.

property relationship#

Relationship view.

property confidence#

Relationship forecast confidence. 0 if there’s no valuable facts about the relationship.

property valuable_facts#

List of forecast valuable facts in descending order of confidence.

class cybsi.api.observable.RelationshipView(data=None)[source]#

Relationship fact view.

property source#

Relationship’s source entity.

Warning

Ref uuid may be zero uuid, if source entity keys were invalid during registration.

property kind#

Kind of the relationship.

property target#

Target entity.

Warning

Ref uuid may be zero uuid, if source entity keys were invalid during registration.

property confidence#

Relationship fact confidence.

class cybsi.api.observable.AnnotationsAPI(connector)[source]#

Annotations API

filter(prefix, *, cursor=None, limit=None)[source]#

Filter labels of observable entities.

Note

Calls GET /observable/annotation/labels.

Parameters:

  • prefix (str) – Label prefix. Prefix length must be in range [2, 50].

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[str]

Returns: List of labels.

Labels are sorted in a stable best match order.

enum cybsi.api.observable.ThreatCategory(value)[source]#

Threat categories.

Valid values are as follows:

Clean = <ThreatCategory.Clean: 'Clean'>#
Riskware = <ThreatCategory.Riskware: 'Riskware'>#
Adware = <ThreatCategory.Adware: 'Adware'>#
Malware = <ThreatCategory.Malware: 'Malware'>#
enum cybsi.api.observable.RelatedThreatCategory(value)[source]#

Related threat categories.

Valid values are as follows:

Riskware = <RelatedThreatCategory.Riskware: 'Riskware'>#
Adware = <RelatedThreatCategory.Adware: 'Adware'>#
Malware = <RelatedThreatCategory.Malware: 'Malware'>#
enum cybsi.api.observable.PotentialDamage(value)[source]#

Potential damage.

Valid values are as follows:

Low = <PotentialDamage.Low: 'Low'>#
Medium = <PotentialDamage.Medium: 'Medium'>#
High = <PotentialDamage.High: 'High'>#
enum cybsi.api.observable.RegionalInternetRegistry(value)[source]#

Regional internet registrars.

Valid values are as follows:

RIPE = <RegionalInternetRegistry.RIPE: 'RIPE'>#
APNIC = <RegionalInternetRegistry.APNIC: 'APNIC'>#
ARIN = <RegionalInternetRegistry.ARIN: 'ARIN'>#
AFRINIC = <RegionalInternetRegistry.AFRINIC: 'AFRINIC'>#
LACNIC = <RegionalInternetRegistry.LACNIC: 'LACNIC'>#
enum cybsi.api.observable.enums.ShareLevels(value)[source]#

Bases: CybsiAPIEnum

Information share level, according to Traffic Light Protocol.

Valid values are as follows:

White = <ShareLevels.White: 'White'>#

Disclosure is not limited.

Green = <ShareLevels.Green: 'Green'>#

Limited disclosure, restricted to the community.

Amber = <ShareLevels.Amber: 'Amber'>#

Limited disclosure, restricted to participants’ organizations.

Red = <ShareLevels.Red: 'Red'>#

Not for disclosure, restricted to participants only.

enum cybsi.api.observable.enums.EntityTypes(value)[source]#

Bases: CybsiAPIEnum

Entity types.

Valid values are as follows:

IPAddress = <EntityTypes.IPAddress: 'IPAddress'>#

IPv4 or IPv6 address.

DomainName = <EntityTypes.DomainName: 'DomainName'>#

Domain name.

File = <EntityTypes.File: 'File'>#

File.

EmailAddress = <EntityTypes.EmailAddress: 'EmailAddress'>#

Email address.

PhoneNumber = <EntityTypes.PhoneNumber: 'PhoneNumber'>#

Phone number.

Identity = <EntityTypes.Identity: 'Identity'>#

Identity.

URL = <EntityTypes.URL: 'URL'>#

URL.

enum cybsi.api.observable.enums.EntityKeyTypes(value)[source]#

Bases: CybsiAPIEnum

Natural entity key types.

Valid values are as follows:

String = <EntityKeyTypes.String: 'String'>#

String identifying entity.

MD5 = <EntityKeyTypes.MD5: 'MD5Hash'>#

File MD5 hash.

SHA1 = <EntityKeyTypes.SHA1: 'SHA1Hash'>#

File SHA1 hash.

SHA256 = <EntityKeyTypes.SHA256: 'SHA256Hash'>#

File SHA256 hash.

IANAID = <EntityKeyTypes.IANAID: 'IANAID'>#

Identity identifier in IANA registry.

NICHandle = <EntityKeyTypes.NICHandle: 'NICHandle'>#

Identity identifier in NIC database.

enum cybsi.api.observable.enums.AttributeNames(value)[source]#

Bases: CybsiAPIEnum

Entity attribute names.

See also

See Attributes of observable entities for complete information about available attributes.

Valid values are as follows:

Class = <AttributeNames.Class: 'Class'>#

Identity class. Attribute value type is enum, see IdentityClass. Attribute belongs to Identity entity type.

RegistrationCountry = <AttributeNames.RegistrationCountry: 'RegistrationCountry'>#

New in version 2.11.

Registration country. Attribute value type is DictItemAttributeValue. Attribute belongs to IPAddress entity type.

DisplayNames = <AttributeNames.DisplayNames: 'DisplayNames'>#

Email address display names. Attribute value type is str. Attribute belongs to EmailAddress entity type.

IsIoC = <AttributeNames.IsIoC: 'IsIoC'>#

The entity is indicator of compromise. Attribute value type is bool. Attribute belongs to DomainName, IPAddress, URL, EmailAddress, PhoneNumber, File entity type.

IsTrusted = <AttributeNames.IsTrusted: 'IsTrusted'>#

The entity is trusted. Attribute value type is bool. Attribute belongs to DomainName, IPAddress, URL, EmailAddress, File entity type.

Names = <AttributeNames.Names: 'Names'>#

Names of the entity. Attribute value type is str. Attribute belongs to Identity, File entity type.

NodeRoles = <AttributeNames.NodeRoles: 'NodeRoles'>#

The role of the node in a network. Attribute value type is enum, see NodeRole. Attribute belongs to DomainName, IPAddress entity type.

Sectors = <AttributeNames.Sectors: 'Sectors'>#

Changed in version 2.10: Change attribute value type from enums to dictionary item.

Identity industry sector. Attribute value type is DictItemAttributeValue. Attribute belongs to Identity entity type.

Size = <AttributeNames.Size: 'Size'>#

Entity size. Attribute value type is int. Attribute belongs to File entity type.

IsDGA = <AttributeNames.IsDGA: 'IsDGA'>#

The domain was generated by algorithm. Attribute value type is bool. Attribute belongs to DomainName entity type.

MalwareClasses = <AttributeNames.MalwareClasses: 'MalwareClasses'>#

New in version 2.9.

The file belongs to malware class. Attribute value type is DictItemAttributeValue. Attribute belongs to File entity type.

MalwareFamilies = <AttributeNames.MalwareFamilies: 'MalwareFamilies'>#

New in version 2.9.

The file belongs to a malware family. Attribute value type is DictItemAttributeValue. Attribute belongs to File entity type.

RelatedMalwareFamilies = <AttributeNames.RelatedMalwareFamilies: 'RelatedMalwareFamilies'>#

New in version 2.9.

The entity belongs to related malware family. Attribute value type is DictItemAttributeValue. Attribute belongs to DomainName, IPAddress, URL, EmailAddress entity type.

IsDelegated = <AttributeNames.IsDelegated: 'IsDelegated'>#

New in version 2.9.

Domain name is delegated if DNS servers are specified. Attribute value type is bool. Attribute belongs to DomainName entity type.

Statuses = <AttributeNames.Statuses: 'Statuses'>#

New in version 2.9.

Domain name or IP address status obtained from Whois. Attribute value type is DictItemAttributeValue. Attribute belongs to DomainName, IPAddress entity type.

ASN = <AttributeNames.ASN: 'ASN'>#

New in version 2.9.

Autonomous system number. Attribute value type is int. Attribute belongs to IPAddress entity type.

RegionalInternetRegistry = <AttributeNames.RegionalInternetRegistry: 'RegionalInternetRegistry'>#

New in version 2.9.

IP address belongs to one of the regional internet registrars. Attribute value type is RegionalInternetRegistry. Attribute belongs to IPAddress entity type.

ThreatCategory = <AttributeNames.ThreatCategory: 'ThreatCategory'>#

New in version 2.9.

The entity threat category. Attribute value type is ThreatCategory. Attribute belongs to File entity type.

RelatedThreatCategory = <AttributeNames.RelatedThreatCategory: 'RelatedThreatCategory'>#

New in version 2.9.

The threat category with which the entity has a relationship. Attribute value type is RelatedThreatCategory. Attribute belongs to DomainName, IPAddress, URL, EmailAddress entity types.

MalwareNames = <AttributeNames.MalwareNames: 'MalwareNames'>#

New in version 2.9.

The entity malware name. Attribute value type is str. Attribute belongs to File entity type.

Campaigns = <AttributeNames.Campaigns: 'Campaigns'>#

New in version 2.10.

The entity is used in a malicious campaign. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

ThreatActors = <AttributeNames.ThreatActors: 'ThreatActors'>#

New in version 2.10.

The entity is used by threat actor. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

AffectedCountries = <AttributeNames.AffectedCountries: 'AffectedCountries'>#

New in version 2.10.

The entity can be used most often in countries. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

ExploitedVulnerabilities = <AttributeNames.ExploitedVulnerabilities: 'ExploitedVulnerabilities'>#

New in version 2.10.

The entity exploits vulnerabilities. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

TargetedSectors = <AttributeNames.TargetedSectors: 'TargetedSectors'>#

New in version 2.10.

The entity targets sectors of activity. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

PotentialDamage = <AttributeNames.PotentialDamage: 'PotentialDamage'>#

New in version 2.11.

The amount of potential damage from the entity. Attribute value type is PotentialDamage. Attribute belongs to File, DomainName, IPAddress, URL entity type.

Platforms = <AttributeNames.Platforms: 'Platforms'>#

New in version 2.12.

The file operates on platforms. Attribute value type is DictItemAttributeValue. Attribute belongs to File entity type.

Tactics = <AttributeNames.Tactics: 'Tactics'>#

New in version 2.12.

The entity uses tactics. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

Techniques = <AttributeNames.Techniques: 'Techniques'>#

New in version 2.12.

The entity uses techniques. Attribute value type is DictItemAttributeValue. Attribute belongs to File, DomainName, IPAddress, EmailAddress, URL entity type.

Labels = <AttributeNames.Labels: 'Labels'>#

New in version 2.14.

Labels are assigned to entities. Attribute value type is DictItemAttributeValue. Attribute belongs to DomainName, URL, IPAddress, File, Identity, PhoneNumber, EmailAddress entity type.

enum cybsi.api.observable.enums.NodeRole(value)[source]#

Bases: CybsiAPIEnum

Node roles.

Valid values are as follows:

CnC = <NodeRole.CnC: 'CnC'>#

CnC node.

TorNode = <NodeRole.TorNode: 'TorNode'>#

Tor node of any type.

TorExitNode = <NodeRole.TorExitNode: 'TorExitNode'>#

Tor exit node.

Proxy = <NodeRole.Proxy: 'Proxy'>#

Proxy server.

NameServer = <NodeRole.NameServer: 'NameServer'>#

Name server.

MailExchanger = <NodeRole.MailExchanger: 'MailExchanger'>#

Mail server.

Phishing = <NodeRole.Phishing: 'Phishing'>#

Phishing server.

DynDNS = <NodeRole.DynDNS: 'DynDNS'>#

Belongs to the DynDNS infrastructure

Cloud = <NodeRole.Cloud: 'Cloud'>#

Belongs to a cloud infrastructure

VPN = <NodeRole.VPN: 'VPN'>#

VPN server

STUN = <NodeRole.STUN: 'STUN'>#

STUN server

Sinkhole = <NodeRole.Sinkhole: 'Sinkhole'>#

Sinkhole nodes

PayloadDelivery = <NodeRole.PayloadDelivery: 'PayloadDelivery'>#

Serves malicious payloads

ExfiltrationStore = <NodeRole.ExfiltrationStore: 'ExfiltrationStore'>#

Used for data exfiltration

CDN = <NodeRole.CDN: 'CDN'>#

Belongs to a CDN infrastructure

BitTorrentTracker = <NodeRole.BitTorrentTracker: 'BitTorrentTracker'>#

BitTorrent tracker

PublicDNS = <NodeRole.PublicDNS: 'PublicDNS'>#

Public DNS

FreeEmail = <NodeRole.FreeEmail: 'FreeEmail'>#

Free email servers

Cryptomining = <NodeRole.Cryptomining: 'Cryptomining'>#

Mining pools

CrlOcsp = <NodeRole.CrlOcsp: 'CrlOcsp'>#

OCSP servers

Parking = <NodeRole.Parking: 'Parking'>#

Unregistered domains parking

Service = <NodeRole.Service: 'Service'>#

Belongs to web service (forums, file hosting, etc)

Scanner = <NodeRole.Scanner: 'Scanner'>#

IPs are detected as a scanners

enum cybsi.api.observable.enums.IdentityClass(value)[source]#

Bases: CybsiAPIEnum

Identity classes.

Valid values are as follows:

Individual = <IdentityClass.Individual: 'Individual'>#

A single person.

Group = <IdentityClass.Group: 'Group'>#

An informal collection of people, without formal governance.

Organization = <IdentityClass.Organization: 'Organization'>#

A formal organization of people, with governance.

Class = <IdentityClass.Class: 'Class'>#

A class of entities, such as all hospitals, all Europeans etc.

enum cybsi.api.observable.enums.RelationshipKinds(value)[source]#

Bases: CybsiAPIEnum

Kind of a relationship between entities.

See also

See Relationships of observable entities for complete information about available relationships.

Valid values are as follows:

Has = <RelationshipKinds.Has: 'Has'>#
Contains = <RelationshipKinds.Contains: 'Contains'>#
BelongsTo = <RelationshipKinds.BelongsTo: 'BelongsTo'>#

Deprecated.

ConnectsTo = <RelationshipKinds.ConnectsTo: 'ConnectsTo'>#
Drops = <RelationshipKinds.Drops: 'Drops'>#
Uses = <RelationshipKinds.Uses: 'Uses'>#
Owns = <RelationshipKinds.Owns: 'Owns'>#
Supports = <RelationshipKinds.Supports: 'Supports'>#
ResolvesTo = <RelationshipKinds.ResolvesTo: 'ResolvesTo'>#
VariantOf = <RelationshipKinds.VariantOf: 'VariantOf'>#

Deprecated.

Hosts = <RelationshipKinds.Hosts: 'Hosts'>#
Serves = <RelationshipKinds.Serves: 'Serves'>#
Locates = <RelationshipKinds.Locates: 'Locates'>#
enum cybsi.api.observable.enums.EntityAggregateSections(value)[source]#

Bases: CybsiAPIEnum

Entity aggregation section.

Valid values are as follows:

AssociatedAttributes = <EntityAggregateSections.AssociatedAttributes: 'AssociatedAttributes'>#
NaturalAttributes = <EntityAggregateSections.NaturalAttributes: 'NaturalAttributes'>#
Threat = <EntityAggregateSections.Threat: 'Threat'>#
GeoIP = <EntityAggregateSections.GeoIP: 'GeoIP'>#
Labels = <EntityAggregateSections.Labels: 'Labels'>#
enum cybsi.api.observable.enums.ThreatStatus(value)[source]#

Bases: CybsiAPIEnum

Threat status.

Valid values are as follows:

Unknown = <ThreatStatus.Unknown: 'Unknown'>#
Malicious = <ThreatStatus.Malicious: 'Malicious'>#
NonMalicious = <ThreatStatus.NonMalicious: 'NonMalicious'>#
enum cybsi.api.observable.enums.LinkDirection(value)[source]#

Bases: CybsiAPIEnum

Direction of links.

Valid values are as follows:

Forward = <LinkDirection.Forward: 'Forward'>#
Reverse = <LinkDirection.Reverse: 'Reverse'>#
enum cybsi.api.observable.enums.RegionalInternetRegistry(value)[source]#

Bases: CybsiAPIEnum

Regional internet registrars.

Valid values are as follows:

RIPE = <RegionalInternetRegistry.RIPE: 'RIPE'>#
APNIC = <RegionalInternetRegistry.APNIC: 'APNIC'>#
ARIN = <RegionalInternetRegistry.ARIN: 'ARIN'>#
AFRINIC = <RegionalInternetRegistry.AFRINIC: 'AFRINIC'>#
LACNIC = <RegionalInternetRegistry.LACNIC: 'LACNIC'>#
enum cybsi.api.observable.enums.ThreatCategory(value)[source]#

Bases: CybsiAPIEnum

Threat categories.

Valid values are as follows:

Clean = <ThreatCategory.Clean: 'Clean'>#
Riskware = <ThreatCategory.Riskware: 'Riskware'>#
Adware = <ThreatCategory.Adware: 'Adware'>#
Malware = <ThreatCategory.Malware: 'Malware'>#
enum cybsi.api.observable.enums.RelatedThreatCategory(value)[source]#

Bases: CybsiAPIEnum

Related threat categories.

Valid values are as follows:

Riskware = <RelatedThreatCategory.Riskware: 'Riskware'>#
Adware = <RelatedThreatCategory.Adware: 'Adware'>#
Malware = <RelatedThreatCategory.Malware: 'Malware'>#
enum cybsi.api.observable.enums.PotentialDamage(value)[source]#

Bases: CybsiAPIEnum

Potential damage.

Valid values are as follows:

Low = <PotentialDamage.Low: 'Low'>#
Medium = <PotentialDamage.Medium: 'Medium'>#
High = <PotentialDamage.High: 'High'>#

Observations#

Use this section of API to register/retrieve observation of types known to Cybsi.

Each type of observation is handled by their own subsection of API.

class cybsi.api.observation.api.ObservationsAPI(connector)[source]#

Observations API.

property archives#

Get archive observations route.

property dns_lookups#

Get DNS Lookup observations route.

property generics#

Get generic observations route.

property network_sessions#

Get network session observations route.

property threats#

Get threat observations route.

property whois_lookups#

Get Whois lookup observations route.

search(*, types=None, data_source_uuids=None, reporter_uuids=None, max_share_level=None, seen_before=None, seen_after=None, registered_before=None, registered_after=None, report_uuid=None, entity_uuid=None, cursor=None, limit=None)[source]#

Get observation search results page.

The result elements are sorted in descending order of observation time.

Note

Calls GET /enrichment/observations

Parameters:

  • types (Optional[Iterable[ObservationTypes]]) – List of observation types. Search for observations of only the specified types.

  • entity_uuid (Optional[UUID]) – Entity identifier. Search for observations mentioning the entity.

  • report_uuid (Optional[UUID]) – Report identifier. Search for observations of the report.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Search for observations by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Search for observations by reporter data source identifiers.

  • max_share_level (Optional[ShareLevels]) – Max share level. Search for observations up to the max access level.

  • seen_before (Optional[datetime]) – Search for observations seen before the time.

  • seen_after (Optional[datetime]) – Search for observations seen after the time.

  • registered_before (Optional[datetime]) – Search for observations registered before the time.

  • registered_after (Optional[datetime]) – Search for observations registered after the time.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[ObservationHeaderView]

Returns:

Search results page and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get observation header.

Note

Calls GET /enrichment/observations/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

ObservationHeaderView

Returns:

Header of the observation.

Raises:

NotFoundError – Observation not found.

class cybsi.api.observation.api.ObservationsAsyncAPI(connector)[source]#

Observations asynchronous API.

property generics#

Get generic observations route.

Archive#

class cybsi.api.observation.archive.ArchiveObservationsAPI(connector)[source]#

Archive observation API.

filter(*, entity_uuid=None, artifact_uuid=None, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered observations.

Page’s items are sorted in descending order of observation time.

Note

Calls GET /enrichment/observations/archives

Parameters:

  • artifact_uuid (Optional[UUID]) – Artifact identifier. Filter archive by specified artifact.

  • entity_uuid (Optional[UUID]) – Entity identifier. Filter archive by specified file entity.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter observation by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter observation by reporter data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[ArchiveObservationView]

Returns:

Page of observation list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the Archive view.

Note

Calls GET /enrichment/observations/archives/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

ArchiveObservationView

Returns:

View of the observation.

Raises:

NotFoundError – observation not found.

class cybsi.api.observation.archive.ArchiveObservationView(data=None)[source]#

Archive observation view, as retrieved by ArchiveObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.archive.ArchiveObservationContentView(data=None)[source]#

Archive content.

Todo

Implement properties.

DNS Lookup#

class cybsi.api.observation.dns_lookup.DNSLookupObservationsAPI(connector)[source]#

DNS Lookup API.

filter(*, entity_uuid=None, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered DNS lookups.

Page’s items are sorted in descending order of lookup time.

Note

Calls GET /enrichment/observations/dns-lookups

Parameters:

  • entity_uuid (Optional[UUID]) – Entity identifier. Filter lookups of specified DomainName/IPAddress entity.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter lookups by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter lookups by reporter data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[DNSLookupObservationView]

Returns:

Page of DNS lookups list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the DNS lookup view.

Note

Calls GET /enrichment/observations/dns-lookups/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

DNSLookupObservationView

Returns:

View of the observation.

Raises:

NotFoundError – DNS Lookup not found.

class cybsi.api.observation.dns_lookup.DNSLookupObservationView(data=None)[source]#

DNS Lookup view, as retrieved by DNSLookupObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.dns_lookup.DNSLookupObservationContentView(data=None)[source]#

DNS lookup content.

Todo

Implement properties.

Generic#

Generic observation is the main form of observation. In essence, it’s a container of arbitrary facts Cybsi domain model supports.

See also

See Register a generic observation for a complete examples of generic observation API usage.

class cybsi.api.observation.generic.GenericObservationsAPI(connector)[source]#

Generic observation API.

register(observation)[source]#

Register a generic observation.

The observation is always registered unless it contains logic errors. Entity key value validation errors are ignored.

Note

Calls POST /enrichment/observations/generics.

Parameters:

observation (GenericObservationForm) – Filled generic observation form.

Return type:

RefView

Returns:

Reference to a newly registered observation.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
filter(*, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered generic observation list.

Page’s items are sorted in descending order of observation time.

Note

Calls GET /enrichment/observations/generics

Parameters:

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter observations by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter observations by reporter data source identifiers.

Return type:

Page[GenericObservationView]

Returns:

Page of generic observations list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the generic observation view.

Note

Calls GET /enrichment/observations/generics/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

GenericObservationView

Returns:

View of the observation.

Raises:

NotFoundError – Generic observation not found.

class cybsi.api.observation.generic.GenericObservationsAsyncAPI(connector)[source]#

Generic observation asynchronous API.

async register(observation)[source]#

Register a generic observation.

Async analog of GenericObservationsAPI.register().

Return type:

RefView

async filter(*, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered generic observation list.

Async analog of GenericObservationsAPI.filter().

Return type:

AsyncPage[GenericObservationView]

async view(observation_uuid)[source]#

Get the generic observation view.

Async analog of GenericObservationsAPI.view().

Return type:

GenericObservationView

class cybsi.api.observation.generic.GenericObservationForm(share_level, seen_at)[source]#

Generic observation form.

This is the form you need to fill to register observation. To fill the form, call add_attribute_fact() and add_entity_relationship() for each fact and relationship you observe.

Parameters:

  • share_level (ShareLevels) – Share level of the observation.

  • seen_at (datetime) – Date and time when facts were seen.

Usage:
>>> from datetime import datetime, timezone
>>> from cybsi.api.dictionary import DictItemAttributeValue
>>> from cybsi.api.observable import (
>>>     AttributeNames, EntityForm,
>>>     EntityKeyTypes, EntityTypes,
>>>     ShareLevels, RelationshipKinds,
>>> )
>>> from cybsi.api.observation import GenericObservationForm
>>> domain = EntityForm(EntityTypes.DomainName)
>>> domain.add_key(EntityKeyTypes.String, "test.com")
>>> ip_address = EntityForm(EntityTypes.IPAddress)
>>> ip_address.add_key(EntityKeyTypes.String, "8.8.8.8")
>>> observation = GenericObservationForm(
>>>    share_level=ShareLevels.Green,
>>>    seen_at=datetime.now(timezone.utc)
>>> ).add_attribute_fact(
>>>     entity=domain,
>>>     attribute_name=AttributeNames.IsIoC,
>>>     value=True,
>>>     confidence=0.9
>>> ).add_attribute_fact(
>>>     entity=domain,
>>>     attribute_name=AttributeNames.RelatedMalwareFamilies,
>>>     value=DictItemAttributeValue(key="Aware"),
>>>     confidence=0.9
>>> ).add_entity_relationship(
>>>     source=domain,
>>>     kind=RelationshipKinds.ResolvesTo,
>>>     target=ip_address,
>>>     confidence=0.5,
>>>)
set_data_source(source_uuid)[source]#

Set observation data source.

add_attribute_fact(entity, attribute_name, value, *, confidence=None)[source]#

Add attribute value fact to the observation.

See also

See Attributes of observable entities and AttributeNames for complete information about available attributes.

Parameters:
Return type:

GenericObservationForm

Returns:

Updated observation form.

add_entity_relationship(*, source, kind, target, confidence=None)[source]#

Add entity relationship to observation.

See also

See Relationships of observable entities for complete information about available relationships.

Parameters:

  • source (Union[UUID, EntityForm]) – Filled form of source entity in the relationship or passed uuid of source entity. Entity with passed UUID must be registered in system.

  • kind (RelationshipKinds) – Kind of relationship.

  • target (Union[UUID, EntityForm]) – Filled form of target entity in the relationship or passed uuid of target entity. Entity with passed UUID must be registered in system.

  • confidence (Optional[float]) – Relationship confidence. Confidence must be in range (0;1]. Empty value means default value (1)

Return type:

GenericObservationForm

Returns:

Updated observation form.

class cybsi.api.observation.generic.GenericObservationView(data=None)[source]#

Generic observation view, as retrieved by GenericObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.generic.GenericObservationContentView(data=None)[source]#

Generic observation content.

property entity_relationships#

Entity relationships.

property entity_attribute_values#

Entity attribute values.

class cybsi.api.observation.generic.AttributeValueFactView(data=None)[source]#

Attribute value fact view.

property entity#

Entity of the fact.

Warning

Ref uuid may be zero uuid, if entity keys were invalid during registration.

property attribute_name#

Attribute name.

property value#

Value of the attribute. Return type depends on attribute name and entity type.

Usage:
>>> from typing import cast
>>> from cybsi.api.observation import GenericObservationContentView
>>> from cybsi.api.dictionary import DictionaryItemCommonView
>>>
>>> view = GenericObservationContentView()
>>> for v in view.entity_attribute_values:
>>>     if v.attribute_name == AttributeNames.MalwareFamilies:
>>>         value = cast(DictionaryItemCommonView, v.value)
>>>         print(value)
property confidence#

Fact confidence.

Network Session#

class cybsi.api.observation.network_session.NetworkSessionObservationsAPI(connector)[source]#

Network Session API.

filter(*, entity_uuid=None, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered observations.

Page’s items are sorted in descending order of observation time.

Note

Calls GET /enrichment/observations/network-sessions

Parameters:

  • entity_uuid (Optional[UUID]) – Entity identifier. Filter observations of specified file entity.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter observations by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter observation by reporter data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[NetworkSessionObservationView]

Returns:

Page of observation list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the NetworkSession view.

Note

Calls GET /enrichment/observations/network-sessions/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

NetworkSessionObservationView

Returns:

View of the observation.

Raises:

NotFoundError – observation not found.

class cybsi.api.observation.network_session.NetworkSessionObservationView(data=None)[source]#

NetworkSession observation view, as retrieved by NetworkSessionObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.network_session.NetworkSessionObservationContentView(data=None)[source]#

NetworkSession content.

Todo

Implement properties.

Threat#

class cybsi.api.observation.threat.ThreatObservationsAPI(connector)[source]#

Threat observation API.

filter(*, entity_uuid=None, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered observations.

Page’s items are sorted in descending order of observation time.

Note

Calls GET /enrichment/observations/threats

Parameters:

  • entity_uuid (Optional[UUID]) – Entity identifier. Filter threats of specified file entity.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter observation by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter observation by reporter data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[ThreatObservationView]

Returns:

Page of observation list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the Threat observation view.

Note

Calls GET /enrichment/observations/threats/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

ThreatObservationView

Returns:

View of the observation.

Raises:

NotFoundError – observation not found.

class cybsi.api.observation.threat.ThreatObservationView(data=None)[source]#

Threat observation view, as retrieved by ThreatObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.threat.ThreatObservationContentView(data=None)[source]#

Threat observation content.

Todo

Implement properties.

WHOIS Lookup#

class cybsi.api.observation.whois_lookup.WhoisLookupObservationsAPI(connector)[source]#

Whois Lookup API.

filter(*, entity_uuid=None, data_source_uuids=None, reporter_uuids=None, cursor=None, limit=None)[source]#

Get page of filtered whois lookups.

Page’s items are sorted in descending order of lookup time.

Note

Calls GET /enrichment/observations/whois-lookups

Parameters:

  • entity_uuid (Optional[UUID]) – Entity identifier. Filter lookups of specified DomainName/IPAddress entity.

  • data_source_uuids (Optional[Iterable[UUID]]) – List of data source identifiers. Filter lookups by original data source identifiers.

  • reporter_uuids (Optional[Iterable[UUID]]) – List of reporter identifiers. Filter lookups by reporter data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[WhoisLookupObservationView]

Returns:

Page of Whois lookups list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
view(observation_uuid)[source]#

Get the Whois lookup view.

Note

Calls GET /enrichment/observations/whois-lookups/{observation_uuid}.

Parameters:

observation_uuid (UUID) – Observation uuid.

Return type:

WhoisLookupObservationView

Returns:

View of the observation.

Raises:

NotFoundError – Whois Lookup not found.

class cybsi.api.observation.whois_lookup.WhoisLookupObservationView(data=None)[source]#

Whois Lookup view, as retrieved by WhoisLookupObservationsAPI.view().

property content#

Content.

property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.whois_lookup.WhoisLookupObservationContentView(data=None)[source]#

Whois lookup content.

Todo

Implement properties.

Common#

class cybsi.api.observation.view.ObservationCommonView(data=None)[source]#

Observation short view.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.observation.view.ObservationHeaderView(data=None)[source]#

Observation header view.

property reporter#

Source reporting the observation.

property data_source#

Observation data source.

property share_level#

Share level.

property seen_at#

Date and time when observation was seen.

property registered_at#

Date and time when observation was registered.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

enum cybsi.api.observation.enums.ObservationTypes(value)[source]#

Bases: CybsiAPIEnum

Observation types.

Valid values are as follows:

DNSLookup = <ObservationTypes.DNSLookup: 'DNSLookup'>#

DNS lookup results.

WhoisLookup = <ObservationTypes.WhoisLookup: 'WhoisLookup'>#

Whois lookup results.

NetworkSession = <ObservationTypes.NetworkSession: 'NetworkSession'>#

Network activity information.

Threat = <ObservationTypes.Threat: 'Threat'>#

Threat information.

Generic = <ObservationTypes.Generic: 'Generic'>#

Fact set of attributes and relationships.

Data sources#

enum cybsi.api.data_source.enums.DataSourceListOrder(value)[source]#

Bases: CybsiAPIEnum

Sorting field of data sources.

Valid values are as follows:

FullName = <DataSourceListOrder.FullName: 'FullName'>#

Sort by FullName means sort by LongName of type + LongName of datasource.

enum cybsi.api.data_source.enums.DataSourceTypeListOrder(value)[source]#

Bases: CybsiAPIEnum

Sorting field of data source types.

Valid values are as follows:

ShortName = <DataSourceTypeListOrder.ShortName: 'ShortName'>#

Sort by ShortName field.

LongName = <DataSourceTypeListOrder.LongName: 'LongName'>#

Sort by LongName field.

Types#

class cybsi.api.data_source.api_types.DataSourceTypesAPI(connector)[source]#

API to operate data source types.

register(form)[source]#

Register a data source type.

Note

Calls POST /data-source-types.

Parameters:

form (DataSourceTypeForm) – Filled data source type form.

Raises:

ConflictError – DataSourceType already exist.

Return type:

RefView

view(type_uuid)[source]#

Get the data source type view.

Note

Calls GET /data-source-types/{type_uuid}.

Parameters:

type_uuid (UUID) – Data source UUID.

Return type:

DataSourceTypeView

Returns:

View of the data source type.

Raises:

NotFoundError – Data source type not found.

edit(type_uuid, tag, *, long_name=None, manual_confidence=None)[source]#

Edit the data source type.

Note

Calls PATCH /data-source-types/{type_uuid}.

Parameters:

  • type_uuid (UUID) – Data source type UUID.

  • tag (Tag) – DataSourceTypeView.tag value. Use view() to retrieve it.

  • long_name (Optional[str]) – Human-readable data source type name. Non-empty if not None.

  • manual_confidence (Union[float, None, NullType]) – Confidence for datasource type. Overrides default confidence of the data source type. Valid values are in [0, 1]. Null means that Cybsi can use default confidence. None means that confidence is left unchanged.

Raises:
Return type:

None

filter(*, order_by=None, cursor=None, limit=None)[source]#

Get a filtered list of data source type.

Changed in version 2.8: Added new parameters: order_by.

Note

Calls GET /data-source-types.

Parameters:

  • order_by (Optional[DataSourceTypeListOrder]) –

    Data source type list sort key. Default value is “ShortName”. The sort is performed in case-insensitive manner in lexicographic order.

    If order_by is not None then it is necessary to pass the parameter to each next request along with a non-empty cursor. Otherwise, the sort will be reset to the “default” sort which may lead to inconsistency in the data selection.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[DataSourceTypeCommonView]

Returns:

Page with data source type common views and next page cursor.

Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>> from cybsi.api.data_source import DataSourceTypeListOrder
>>>
>>> client: CybsiClient
>>> # filter data sources by specified sort
>>> started_page = client.data_source_types.filter(
>>>     order_by=DataSourceTypeListOrder.LongName,
>>> )
>>> for item in chain_pages(started_page):
>>>     # do something with data source type
>>>     print(item)
>>> pass
class cybsi.api.data_source.api_types.DataSourceTypesAsyncAPI(connector)[source]#

API to operate data source types.

async register(form)[source]#

Register a data source type.

Note

Calls POST /data-source-types.

Parameters:

form (DataSourceTypeForm) – Filled data source type form.

Raises:

ConflictError – DataSourceType already exist.

Return type:

RefView

async view(type_uuid)[source]#

Get the data source type view.

Note

Calls GET /data-source-types/{type_uuid}.

Parameters:

type_uuid (UUID) – Data source UUID.

Return type:

DataSourceTypeView

Returns:

View of the data source type.

Raises:

NotFoundError – Data source type not found.

async edit(type_uuid, tag, *, long_name=None, manual_confidence=None)[source]#

Edit the data source type.

Note

Calls PATCH /data-source-types/{type_uuid}.

Parameters:

  • type_uuid (UUID) – Data source type UUID.

  • tag (Tag) – DataSourceTypeView.tag value. Use view() to retrieve it.

  • long_name (Optional[str]) – Human-readable data source type name. Non-empty if not None.

  • manual_confidence (Union[float, None, NullType]) – Confidence for datasource type. Overrides default confidence of the data source type. Valid values are in [0, 1]. Null means that Cybsi can use default confidence. None means that confidence is left unchanged.

Raises:
Return type:

None

async filter(*, order_by=None, cursor=None, limit=None)[source]#

Get a filtered list of data source type.

Note

Calls GET /data-source-types.

Parameters:

  • order_by (Optional[DataSourceTypeListOrder]) –

    Data source type list sort key. Default value is “ShortName”. The sort is performed in case-insensitive manner in lexicographic order.

    If order_by is not None then it is necessary to pass the parameter to each next request along with a non-empty cursor. Otherwise, the sort will be reset to the “default” sort which may lead to inconsistency in the data selection.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[DataSourceTypeCommonView]

Returns:

Page with data source type common views and next page cursor.

class cybsi.api.data_source.api_types.DataSourceTypeForm(*, short_name, long_name, manual_confidence=None)[source]#

Data source type form.

This is the form you need to fill to register data source type.

Parameters:

  • short_name (str) – Data source type identifier. Must be unique across all data source types. Non-empty. Short name should consist of characters without spaces ([a-zA-Z0-9_-]) and have length in the range [1, 250].

  • long_name (str) – Human-readable data source type name. Non-empty. Long name length must be in the range [1, 250].

  • manual_confidence (Optional[float]) – Confidence for datasource type. Overrides default confidence of the data source type. Valid values are in [0, 1].

Returns:

Datasource Type register form.

class cybsi.api.data_source.api_types.DataSourceTypeView(resp)[source]#

View of data source type.

property short_name#

Data source type identifier. Unique across all data source types.

property long_name#

Human-readable data source type name.

property confidence#

Confidence.

property manual_confidence#

Manually set confidence for datasource type. Overrides confidence of the data source type.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.data_source.api_types.DataSourceTypeCommonView(data=None)[source]#

Data source type short view

property long_name#

Human-readable data source type name.

property confidence#

Confidence of data source type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

Instances#

class cybsi.api.data_source.api.DataSourcesAPI(connector)[source]#

API to operate data source.

view(datasource_uuid)[source]#

Get the data source view.

Note

Calls GET /data-sources/{datasource_uuid}.

Parameters:

datasource_uuid (UUID) – Data source UUID.

Return type:

DataSourceView

Returns:

View of the data source.

Raises:

NotFoundError – Data source not found.

Get links view of the data source.

New in version 2.7.

Note

Calls GET /data-sources/{datasource_uuid}/links.

Parameters:

datasource_uuid (UUID) – Data source UUID.

Return type:

DataSourceLinksView

Returns:

Links view of the data source.

Raises:

NotFoundError – Data source not found.

me()[source]#

Get data source associated with current client. :rtype: DataSourceView

Note

Calls GET /data-sources/me.

register(form)[source]#

Register a data source.

Note

Calls POST /data-sources.

Parameters:

form (DataSourceForm) – Filled data source form.

Raises:
Return type:

RefView

Note

Semantic error codes:
edit(type_uuid, tag, *, long_name=None, manual_confidence=None)[source]#

Edit the data source.

Note

Calls PATCH /data-sources/{source_uuid}.

Parameters:

  • type_uuid (UUID) – Data source type uuid.

  • tag (Tag) – DataSourceView.tag value. Use view() to retrieve it.

  • long_name (Optional[str]) – Human-readable data source name. Non-empty if not None.

  • manual_confidence (Union[float, None, NullType]) – Confidence for data source. Overrides confidence of the data source inherited from data source type. Valid values are in [0, 1]. Null means that Cybsi can use confidence provided by data source type. None means that confidence is left unchanged.

Raises:
Return type:

None

filter(*, query=None, type_uuids=None, order_by=None, cursor=None, limit=None)[source]#

Get a filtered list of data sources.

Changed in version 2.8: Added new parameters: query, type_uuids, order_by. Added semantic error DataSourceNotFound

Changed in version 2.13: Increased maxumum length of query parameter.

Note

Calls GET /data-sources.

Parameters:

  • query (Optional[str]) – Filter of data sources by specified substring (case-insensitive). Substring length must be in range [1, 250]. Filtering is performed by specified substring in data source names or its type names.

  • type_uuids (Optional[Iterable[UUID]]) – List of data source type UUIDs.

  • order_by (Optional[DataSourceListOrder]) –

    Data source list sort key. If order_by is None then the order is not specified. But results are stable sorted when paging.

    For “FullName” key, sorting is performed in case-insensitive manner in lexicographic order.

    If order_by is not None then it is necessary to pass the parameter to each next request along with a non-empty cursor. Otherwise, the sort will be reset to the “default” sort, which may lead to inconsistency in the data selection.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[DataSourceCommonView]

Returns:

Page with data source common views and next page cursor.

Raises:

SemanticError –

Note

Semantic error codes:
Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>> from cybsi.api.data_source import DataSourceListOrder
>>>
>>> client: CybsiClient
>>> # filter data sources by specified type uuid and sort
>>> started_page = client.data_sources.filter(
>>>     type_uuids=[uuid.UUID("89200bef-2f50-4d4f-8b38-843d5ab9dfa9")],
>>>     order_by=DataSourceListOrder.FullName,
>>> )
>>> for item in chain_pages(started_page):
>>>     # do something with data source
>>>     print(item)
>>> pass
class cybsi.api.data_source.api.DataSourcesAsyncAPI(connector)[source]#

Asynchronous API to operate data source.

async view(datasource_uuid)[source]#

Get the data source view.

Note

Calls GET /data-sources/{datasource_uuid}.

Parameters:

datasource_uuid (UUID) – Data source UUID.

Return type:

DataSourceView

Returns:

View of the data source.

Raises:

NotFoundError – Data source not found.

Get links view of the data source.

New in version 2.7.

Note

Calls GET /data-sources/{datasource_uuid}/links.

Parameters:

datasource_uuid (UUID) – Data source UUID.

Return type:

DataSourceLinksView

Returns:

Links view of the data source.

Raises:

NotFoundError – Data source not found.

async me()[source]#

Get data source associated with current client. :rtype: DataSourceView

Note

Calls GET /data-sources/me.

async register(form)[source]#

Register a data source.

Note

Calls POST /data-sources.

Parameters:

form (DataSourceForm) – Filled data source form.

Raises:
Return type:

RefView

Note

Semantic error codes:
async edit(type_uuid, tag, *, long_name=None, manual_confidence=None)[source]#

Edit the data source.

Note

Calls PATCH /data-sources/{source_uuid}.

Parameters:

  • type_uuid (UUID) – Data source type uuid.

  • tag (Tag) – DataSourceView.tag value. Use view() to retrieve it.

  • long_name (Optional[str]) – Human-readable data source name. Non-empty if not None.

  • manual_confidence (Union[float, None, NullType]) – Confidence for data source. Overrides confidence of the data source inherited from data source type. Valid values are in [0, 1]. Null means that Cybsi can use confidence provided by data source type. None means that confidence is left unchanged.

Raises:
Return type:

None

async filter(*, query=None, type_uuids=None, order_by=None, cursor=None, limit=None)[source]#

Get a filtered list of data sources.

Changed in version 2.13: Increased maxumum length of query parameter.

Note

Calls GET /data-sources.

Parameters:

  • query (Optional[str]) – Filter of data sources by specified substring (case-insensitive). Substring length must be in range [1, 250]. Filtering is performed by specified substring in data source names or its type names.

  • type_uuids (Optional[Iterable[UUID]]) – List of data source type UUIDs.

  • order_by (Optional[DataSourceListOrder]) –

    Data source list sort key. If order_by is None then the order is not specified. But results are stable sorted when paging.

    For “FullName” key, sorting is performed in case-insensitive manner in lexicographic order.

    If order_by is not None then it is necessary to pass the parameter to each next request along with a non-empty cursor. Otherwise, the sort will be reset to the “default” sort, which may lead to inconsistency in the data selection.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[DataSourceCommonView]

Returns:

Page with data source common views and next page cursor.

Raises:

SemanticError –

Note

Semantic error codes:
class cybsi.api.data_source.api.DataSourceForm(type_uuid, *, name, long_name, manual_confidence=None)[source]#

Data source form.

This is the form you need to fill to register data source.

Parameters:

  • type_uuid (UUID) – Data source type UUID.

  • name (str) – Data source identifier. Must be unique name for data source type. Name should consist of characters without spaces ([a-zA-Z0-9_-]) and have length in the range [1, 250].

  • long_name (str) – Human-readable data source name. Long name length must be in the range [1, 250].

  • manual_confidence (Optional[float]) – Confidence of the data source. Overrides confidence of the data source inherited from data source type. Valid values are in [0, 1].

Returns:

Data source register form.

class cybsi.api.data_source.api.DataSourceView(resp)[source]#

View of data source.

property type#

Data source type.

property name#

Data source identifier. Must be unique name for data source type.

property long_name#

Human-readable data source name.

property confidence#

Confidence of data source.

property manual_confidence#

Manually set confidence of the data source. Overrides confidence of the data source type.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.data_source.api.DataSourceCommonView(data=None)[source]#

Data source short view.

property long_name#

Human-readable data source name.

property unique_name#

The unique identifier contains of the type ShortName and the source Name (ShortName/Name).

property confidence#

Confidence of data source.

property type#

Data source type short view.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.data_source.api.DataSourceLinksView(data=None)[source]#

Data source links view

property analyzer#

Reference to analyzer.

Use view() to retrieve analyzer view.

property external_db#

Reference to external database.

Use view() to retrieve external db view.

property user#

Reference to user.

Deprecated since version 2.8.

Use view() to retrieve user view.

property users#

References to users.

Use view() to retrieve user view.

Search#

Use this section of API to register, retrieve or validate search queries.

class cybsi.api.search.SearchAPI(connector)[source]#

Search API.

property stored_queries#

Get stored queries route.

property entities#

Get search entities route.

class cybsi.api.search.SearchEntitiesAPI(connector)[source]#

Search entities API.

Starts entities search.

Note

Calls POST /search/entities.

Parameters:

  • query_text (str) – CybsiLang query text. Query must not be empty.

  • share_level (Optional[ShareLevels]) – Facts share level. Use facts appropriate to share_level. None means current user access level.

Return type:

Cursor

Returns:

Cursor of the first page of the search. The cursor can be used to call next_search_page().

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
next_search_page(cursor, *, limit=None, entity_view=<class 'cybsi.api.observable.entity.EntityView'>)[source]#

Get next search page result.

Note

Calls GET /search/entities.

Parameters:
Raises:

SemanticError – Request contains logic errors.

Return type:

Page[TypeVar(EntityViewT, bound= AbstractEntityView)]

Note

Semantic error codes specific for this method:
class cybsi.api.search.SearchEntitiesAsyncAPI(connector)[source]#

Search entities API.

Starts entities search.

Note

Calls POST /search/entities.

Parameters:

  • query_text (str) – CybsiLang query text. Query must not be empty.

  • share_level (Optional[ShareLevels]) – Facts share level. Use facts appropriate to share_level. None means current user access level.

Return type:

Cursor

Returns:

Cursor of the first page of the search. The cursor can be used to call next_search_page().

Raises:

NotFoundError – Stored query not found.

async next_search_page(cursor, *, limit=None, entity_view=<class 'cybsi.api.observable.entity.EntityView'>)[source]#

Get next search page result.

Note

Calls GET /search/entities.

Parameters:
Raises:
Return type:

AsyncPage[TypeVar(EntityViewT, bound= AbstractEntityView)]

Note

Semantic error codes specific for this method:
class cybsi.api.search.CybsiLangErrorView(data=None)[source]#

View of a search query validation errors.

classmethod from_semantic_error(exc)[source]#

Extract CybsiLang error from semantic error.

Parameters:

exc (SemanticError) – SemanticError exception.

Return type:

CybsiLangErrorView

Note

Only InvalidQueryText can be unwrapped

property code#

Code. See CybsiLangErrorCodes for all available error codes

property message#

Message.

property details_raw#

Details.

property position#

Position of the error start.

property until_position#

Position of the error end.

Points to a symbol next to the last symbol of the error.

class cybsi.api.search.ErrorPosition(data=None)[source]#

Error position.

property line#

Line. Starts from 1.

property column#

Column. Relative position from start of line. Starts from 1.

property offset#

Offset. Absolute position from start of query text. Starts from 0.

class cybsi.api.search.StoredQueriesAPI(connector)[source]#

Stored queries API.

register(stored_query)[source]#

Register a stored query.

Note

Calls POST /search/stored-queries.

Parameters:

stored_query (StoredQueryForm) – Stored query registration form.

Return type:

RefView

Returns:

Reference to a registered stored query.

Raises:

Note

Semantic error codes specific for this method:
view(query_uuid)[source]#

Get a stored query view.

Note

Calls GET /search/stored-queries/{query_uuid}.

Parameters:

query_uuid (UUID) – Stored query uuid.

Return type:

StoredQueryView

Returns:

View of the stored query.

Raises:

NotFoundError – Stored query not found.

validate(text, compatibility)[source]#

Validates search query.

Note

Calls PUT /search/query.

Parameters:

  • text (str) – Text of the query.

  • compatibility (QueryCompatibility) – Compatibility scope for query text.

Return type:

StoredQueryValidationView

Returns:

View of the validation results.

edit(query_uuid, tag, *, name=None, text=None)[source]#

Edit the stored query.

Note

Calls PATCH /search/stored-queries/{query_uuid}.

Parameters:
Raises:
Return type:

None

Note

Semantic error codes specific for this method:
delete(query_uuid)[source]#

Delete stored query.

New in version 2.13.

Note

Calls DELETE /search/stored-queries/{query_uuid}.

Parameters:

query_uuid (UUID) – Stored query uuid.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:
filter(*, user_uuid=None, query_name=None, is_replist_compatible=None, cursor=None, limit=None)[source]#

Get page of filtered stored queries list.

Note

Calls GET /search/stored-queries

Parameters:

  • user_uuid (Optional[UUID]) – User’s identifier. Filter stored queries by author’s id.

  • query_name (Optional[str]) – Filter stored queries by specified substring (case-insensitive). Substring length must be in range [1, 250].

  • is_replist_compatible (Optional[bool]) – Filter stored queries by replist compatibility flag.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[StoredQueryFilterView]

Returns:

Page of filtered stored queries list and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
class cybsi.api.search.StoredQueryCommonView(data=None)[source]#

Stored query short view, as retrieved by view().

property name#

Query name.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.search.StoredQueryFilterView(data=None)[source]#

Filter view of a stored query, as retrieved by StoredQueriesAPI.filter().

property text#

Query text.

property author#

User, author of the query.

property is_replist_compatible#

Replist compatibility flag.

property name#

Query name.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.search.StoredQueryForm(name, text)[source]#

Stored query form.

This is the form you need to fill to register stored query.

Parameters:

  • name (str) – Name of the stored query, non-empty.

  • text (str) – Text of the stored query, non-empty.

class cybsi.api.search.StoredQueryValidationView(data=None)[source]#

View of a search query validation, as retrieved by StoredQueriesAPI.validate().

property errors#

Errors.

property warnings#

Warnings.

class cybsi.api.search.StoredQueryView(resp)[source]#

View of a stored query, as retrieved by StoredQueriesAPI.view().

property author#

User, author of the query.

property is_replist_compatible#

Replist compatibility flag.

property name#

Query name.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property text#

Query text.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

enum cybsi.api.search.enums.QueryCompatibility(value)[source]#

Bases: CybsiAPIEnum

Stored query compatibility.

Valid values are as follows:

Replist = <QueryCompatibility.Replist: 'Replist'>#

Replists.

Search = <QueryCompatibility.Search: 'Search'>#

Search.

enum cybsi.api.search.error.CybsiLangErrorCodes(value)[source]#

Bases: CybsiAPIEnum

Stored query error code.

Valid values are as follows:

CommentNotTerminated = <CybsiLangErrorCodes.CommentNotTerminated: 'CommentNotTerminated'>#

Syntax error: comment not terminated

IdentifierNotTerminated = <CybsiLangErrorCodes.IdentifierNotTerminated: 'IdentifierNotTerminated'>#

Syntax error: identifier not terminated

InvalidCharacter = <CybsiLangErrorCodes.InvalidCharacter: 'InvalidCharacter'>#

Symbol error: invalid character

InvalidEscapeSequence = <CybsiLangErrorCodes.InvalidEscapeSequence: 'InvalidEscapeSequence'>#

Symbol error: invalid escape sequence

InvalidIdentifier = <CybsiLangErrorCodes.InvalidIdentifier: 'InvalidIdentifier'>#

Syntax error: invalid identifier

InvalidNumber = <CybsiLangErrorCodes.InvalidNumber: 'InvalidNumber'>#

Syntax error: invalid number

StringNotTerminated = <CybsiLangErrorCodes.StringNotTerminated: 'StringNotTerminated'>#

Syntax error: string not terminated

UnexpectedToken = <CybsiLangErrorCodes.UnexpectedToken: 'UnexpectedToken'>#

Syntax error: unexpected token

AmbiguousIdentifierType = <CybsiLangErrorCodes.AmbiguousIdentifierType: 'AmbiguousIdentifierType'>#

Semantic error: the identifier has multiple possible types

AttributeNotFound = <CybsiLangErrorCodes.AttributeNotFound: 'AttributeNotFound'>#

Semantic error: attribute not found

DatasourceNotFound = <CybsiLangErrorCodes.DatasourceNotFound: 'DatasourceNotFound'>#

Semantic error: datasource not found

DatasourceTypeNotFound = <CybsiLangErrorCodes.DatasourceTypeNotFound: 'DatasourceTypeNotFound'>#

Semantic error: datasource type not found

DuplicatedSpecifier = <CybsiLangErrorCodes.DuplicatedSpecifier: 'DuplicatedSpecifier'>#

Semantic error: duplicated specifier

EmptyEntityBody = <CybsiLangErrorCodes.EmptyEntityBody: 'EmptyEntityBody'>#

Semantic error: entity has empty body

EmptyExpressionResult = <CybsiLangErrorCodes.EmptyExpressionResult: 'EmptyExpressionResult'>#

Semantic error: expression produces empty result

EntityTypeNotFound = <CybsiLangErrorCodes.EntityTypeNotFound: 'EntityTypeNotFound'>#

Semantic error: entity type not found

NoValidRelations = <CybsiLangErrorCodes.NoValidRelations: 'NoValidRelations'>#

Semantic error: allowed relations for such source and target not found

InvalidOperation = <CybsiLangErrorCodes.InvalidOperation: 'InvalidOperation'>#

Semantic error: operation is invalid for provided types

InvalidValue = <CybsiLangErrorCodes.InvalidValue: 'InvalidValue'>#

Semantic error: value is invalid

InvalidValueType = <CybsiLangErrorCodes.InvalidValueType: 'InvalidValueType'>#

Semantic error: value type is invalid

RelationKindNotFound = <CybsiLangErrorCodes.RelationKindNotFound: 'RelationKindNotFound'>#

Semantic error: relation kind not found

UnsupportedAttribute = <CybsiLangErrorCodes.UnsupportedAttribute: 'UnsupportedAttribute'>#

Semantic error: attribute is not supported

UnsupportedExpression = <CybsiLangErrorCodes.UnsupportedExpression: 'UnsupportedExpression'>#

The expression is allowed by grammar but not supported yet.

InvalidReplistSpecifier = <CybsiLangErrorCodes.InvalidReplistSpecifier: 'InvalidReplistSpecifier'>#

Invalid specifier for replist

Reputation lists#

Use this section of API to register and view reputation lists.

The API also allows retrieving reputation list content, both as a snapshot and a stream of changes.

class cybsi.api.replist.ReplistsAPI(connector)[source]#

Reputation list API.

register(replist)[source]#

Register reputation list.

Note

Calls POST /replists.

Parameters:

replist (ReplistForm) – Filled replist form.

Return type:

RefView

Returns:

Reference to the registered replist.

Raises:

Note

Semantic error codes specific for this method:
view(replist_uuid)[source]#

Get reputation list full view.

Note

Calls GET /replists/{replist_uuid}.

Parameters:

replist_uuid (UUID) – Replist uuid.

Return type:

ReplistView

Returns:

Full view of the replist with ETag string value.

Raises:

NotFoundError – Replist not found.

edit(replist_uuid, tag, *, is_enabled=None, query_uuid=None, share_level=None)[source]#

Edit the reputation list.

Note

Calls PATCH /replists/{replist_uuid}.

Parameters:
Raises:
Return type:

None

Note

Semantic error codes specific for this method:
filter(*, query_uuids=None, cursor=None, limit=None)[source]#

Get replist filtration list.

Note

Calls GET /replists

Parameters:
Return type:

Page[ReplistCommonView]

Returns:

Page with entities and cursor allowing to get next batch of changes.

Raises:

SemanticError – Request contains logic errors.

Note

Semantic error codes specific for this method:
entities(replist_uuid, *, entity_view=<class 'cybsi.api.observable.entity.EntityView'>, cursor=None, limit=None)[source]#

Get replist entities.

Note

Calls GET /replist/{replist_uuid}/entities

Parameters:
Return type:

Tuple[Page[TypeVar(EntityViewT, bound= AbstractEntityView)], Cursor]

Returns:

Page with entity views and cursor. The cursor can be used to call changes().

Raises:

Note

Semantic error codes specific for this method:

Changed in version 2.9: Add entity view support. See views for details.

changes(replist_uuid, *, cursor, entity_view=<class 'cybsi.api.observable.entity.EntityView'>, limit=None)[source]#

Get replist changes

Note

Calls GET /replist/{replist_uuid}/changes

Parameters:

  • replist_uuid (UUID) – Replist uuid.

  • entity_view (Type[TypeVar(EntityViewT, bound= AbstractEntityView)]) – Entity view to use. Default is EntityView - - only natural keys. You can specify one of builtin views in views.

  • cursor (Cursor) – Page cursor. On the first request you should pass the cursor value obtained when requesting replist entities entities(). Subsequent calls should use cursor property of the page returned by changes().

  • limit (Optional[int]) – Page limit.

Return type:

Page[EntitySetChangeView[TypeVar(EntityViewT, bound= AbstractEntityView)]]

Returns:

Page with changes.

Warning

Cursor behaviour differs from other API methods.

Do not save returned page cursor if it is None. None means that all changes for this moment are received. More changes can arrive later. Pass your previous non-none cursor value in loop, until non-none cursor is returned.

Please wait some time if method returns a page with None cursor.

Raises:

Note

Semantic error codes specific for this method:

Changed in version 2.9: Add entity view support. See views for details.

statistic(replist_uuid)[source]#

Get replist statistic.

Note

Calls GET /replists/{replist_uuid}/statistic.

Parameters:

replist_uuid (UUID) – Replist uuid.

Return type:

ReplistStatisticView

Returns:

Replist statistic view.

Raises:

NotFoundError – Replist not found.

class cybsi.api.replist.ReplistsAsyncAPI(connector)[source]#

Replists asynchronous API.

async entities(replist_uuid, *, entity_view=<class 'cybsi.api.observable.entity.EntityView'>, cursor=None, limit=None)[source]#

Get replist entities.

Note

Calls GET /replist/{replist_uuid}/entities

Parameters:
Return type:

Tuple[AsyncPage[TypeVar(EntityViewT, bound= AbstractEntityView)], Cursor]

Returns:

Page with entity views and cursor. The cursor can be used to call changes().

Raises:

NotFoundError – Replist not found.

Changed in version 2.9: Add entity view support. See views for details.

async changes(replist_uuid, *, cursor, entity_view=<class 'cybsi.api.observable.entity.EntityView'>, limit=None)[source]#

Get replist changes

Note

Calls GET /replist/{replist_uuid}/changes

Parameters:

  • replist_uuid (UUID) – Replist uuid.

  • entity_view (Type[TypeVar(EntityViewT, bound= AbstractEntityView)]) – Entity view to use. Default is EntityView - - only natural keys. You can specify one of builtin views in views.

  • cursor (Cursor) – Page cursor. On the first request you should pass the cursor value obtained when requesting replist entities entities(). Subsequent calls should use cursor property of the page returned by changes().

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[EntitySetChangeView[TypeVar(EntityViewT, bound= AbstractEntityView)]]

Returns:

Page with changes.

Warning

Cursor behaviour differs from other API methods.

Do not save returned page cursor if it is None. None means that all changes for this moment are received. More changes can arrive later. Pass your previous non-none cursor value in loop, until non-none cursor is returned.

Please wait some time if method returns a page with None cursor.

Raises:

Note

Semantic error codes specific for this method:

Changed in version 2.9: Add entity view support. See views for details.

async statistic(replist_uuid)[source]#

Get replist statistic.

Note

Calls GET /replists/{replist_uuid}/statistic.

Parameters:

replist_uuid (UUID) – Replist uuid.

Return type:

ReplistStatisticView

Returns:

Replist statistic view.

Raises:

NotFoundError – Replist not found.

class cybsi.api.replist.ReplistForm(query_uuid, share_level, *, is_enabled=None)[source]#

Reputation list form.

Parameters:

  • query_uuid (UUID) – Search query UUID attached to replist.

  • share_level (ShareLevels) – Replist share level.

  • is_enabled (Optional[bool]) – Replist status toggle.

class cybsi.api.replist.ReplistCommonView(data=None)[source]#

Reputation list short view.

property query#

Search query attached to replist (without raw query text).

property author#

Replist author.

property share_level#

Replist share level.

property is_enabled#

Replist enabled status.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.replist.ReplistView(resp)[source]#

Reputation list full view.

property updated_at#

Replist last updated time.

None if it was never updated.

property status#

Replist current status.

property author#

Replist author.

property is_enabled#

Replist enabled status.

property query#

Search query attached to replist (without raw query text).

property share_level#

Replist share level.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.replist.EntitySetChangeView(entity_view, data=None)[source]#

Replist change.

property operation#

Get change operation.

property entity#

Get entity view.

class cybsi.api.replist.ReplistStatisticView(data=None)[source]#

Replist statistic view.

property entity_count#

Total number of entities in the replist.

property entity_type_distribution#

Distribution of entities number by their types.

class cybsi.api.replist.EntityTypeDistributionView(data=None)[source]#

Entity type distribution.

property entity_type#

Entity type.

property count#

Number of entities.

enum cybsi.api.replist.enums.EntitySetOperations(value)[source]#

Bases: CybsiAPIEnum

Type of operation applied to an entity in reputation list.

Valid values are as follows:

Add = <EntitySetOperations.Add: 'Add'>#

An entity was added.

Remove = <EntitySetOperations.Remove: 'Remove'>#

An entity was removed.

enum cybsi.api.replist.enums.ReplistStatus(value)[source]#

Bases: CybsiAPIEnum

Current status of reputation list.

Valid values are as follows:

Initializing = <ReplistStatus.Initializing: 'Initializing'>#

Replist is in building process.

Active = <ReplistStatus.Active: 'Active'>#

Replist is enabled.

Inactive = <ReplistStatus.Inactive: 'Inactive'>#

Replist is disabled.

Reports#

Use this section of API to register and retrieve reports.

class cybsi.api.report.ReportsAPI(connector)[source]#

Report API.

register(report)[source]#

Register report.

Note

Calls POST /enrichment/reports.

Parameters:

report (ReportForm) – Filled report form.

Return type:

RefView

Returns:

Reference to the registered report.

Raises:

  • SemanticError – Form contains logic errors.

  • ConflictError – A report with such external_id and data source is already registered.

Note

Semantic error codes specific for this method:
view(report_uuid)[source]#

Get report view.

Note

Calls GET /enrichment/reports/{report_uuid}.

Parameters:

report_uuid (UUID) – Report uuid.

Return type:

ReportView

Returns:

View of the report.

Raises:

NotFoundError – Report not found.

filter(*, file_uuid=None, reporter_uuids=None, data_source_uuids=None, entity_uuids=None, labels=None, analyzed_artifact_uuid=None, title=None, created_before=None, created_after=None, updated_before=None, updated_after=None, external_id=None, cursor=None, limit=None, reverse_order=False)[source]#

Get report header filtration list that matches the specified criteria.

Reports are returned in reverse order of registration time.

Note

Calls GET /enrichment/reports.

Parameters:

  • file_uuid (Optional[UUID]) – File identifier. Filter reports by the artifact of the observed file with the specified identifier.

  • reporter_uuids (Optional[Iterable[UUID]]) – Reporter identifiers. Filter reports by reporter data source identifiers.

  • data_source_uuids (Optional[Iterable[UUID]]) – Data source identifiers. Filter reports by original data source identifiers.

  • entity_uuids (Optional[Iterable[UUID]]) – entity identifiers. Filter reports by at least one of the specified entity.

  • labels (Optional[Iterable[str]]) – Filter reports by any of the specified labels. Label case is ignored.

  • analyzed_artifact_uuid (Optional[UUID]) – Analyzed artifact identifier. Filter reports based on analysis of the specified artifact.

  • title (Optional[str]) – Filter reports by specified title. Title case is ignored. Allows special symbols ‘%’ and ‘_’. The ‘%’ symbol replaces any number of title symbols. The ‘_’ symbol replaces only one title symbol. To search for ‘%’ and ‘_’ symbols in the usual sense, you need to prepend them with ‘’.

  • created_before (Optional[datetime]) – Filter reports created before the timestamp (inclusive).

  • created_after (Optional[datetime]) – Filter reports created after the timestamp (inclusive).

  • updated_before (Optional[datetime]) – Filter reports updated before the timestamp (inclusive).

  • updated_after (Optional[datetime]) – Filter reports updated after the timestamp (inclusive).

  • external_id (Optional[str]) – Filter reports by their external id. Min length is 1.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

  • reverse_order (bool) – Result list order, default false

Return type:

Page[ReportHeaderView]

Returns:

Page of reports list and next page cursor.

Raises:

SemanticError – Query arguments contain semantic errors.

Note

Semantic error codes specific for this method:
filter_similar_reports(report_uuid, *, reporter_uuid=None, data_source_uuid=None, cursor=None, limit=None)[source]#

Get similar reports filtration list in descending order of similarity.

Note

Calls GET /enrichment/reports/{report_uuid}/similar-reports.

Parameters:

  • report_uuid (UUID) – Report identifier.

  • reporter_uuid (Optional[UUID]) – Reporter identifier. Filter similar reports the reporter data source identifiers.

  • data_source_uuid (Optional[UUID]) – Data source identifier. Filter similar reports the original data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[SimilarReportView]

Returns:

Page of similar reports list and next page cursor.

explain_report_similarity(report_uuid, similar_report_uuid)[source]#

Get information about the similarity of reports.

Note

Report A is similar to report B, but not the same as report B is similar report A.

Note

Calls GET /enrichment/reports/{report_uuid}/similar-reports/{similar_report_uuid}. # noqa: E501

Parameters:

  • report_uuid (UUID) – Report identifier.

  • similar_report_uuid (UUID) – Report identifier for comparison

Return type:

SimilarReportView

Returns:

View of the report.

search_labels(prefix, *, cursor=None, limit=None)[source]#

Get report label filtration list.

Note

Calls GET /enrichment/report-labels.

Parameters:

  • prefix (str) – Label prefix. Prefix length must be in range [2;50].

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[str]

Returns:

Page of reports label list and next page cursor.

attach_observations(report_uuid, observation_uuids)[source]#

Attach observations to existing report.

Note

Calls POST /enrichment/reports/{report_uuid}/observations.

Parameters:

  • report_uuid (UUID) – Report UUID.

  • observation_uuids (Iterable[UUID]) – Observation UUIDs.

Return type:

RefView

Returns:

Reference to the report.

Raises:

Note

Semantic error codes specific for this method:
filter_observations(report_uuid, *, cursor=None, limit=None)[source]#

Filter observations in the report. Observations having share level above user’s access level are filtered out.

Note

Calls GET /enrichment/reports/{report_uuid}/observations.

Parameters:
Return type:

Page[ObservationView]

Returns:

Page of report observations list and next page cursor.

The list of observations is ordered as in the report.

Raises:

NotFoundError – Report not found.

attach_artifacts(report_uuid, artifact_uuids)[source]#

Attach artifacts to existing report.

Note

Calls POST /enrichment/reports/{report_uuid}/artifacts.

Parameters:

  • report_uuid (UUID) – Report UUID.

  • artifact_uuids (Iterable[UUID]) – Artifact UUIDs.

Return type:

RefView

Returns:

Reference to the report.

Raises:

Note

Semantic error codes specific for this method:
filter_artifacts(report_uuid, *, cursor=None, limit=None)[source]#

Filter artifacts in the report. Artifacts having share level above user’s access level are filtered out.

Note

Calls GET /enrichment/reports/{report_uuid}/artifacts.

Parameters:
Return type:

Page[ArtifactCommonView]

Returns:

Page of report artifacts list and next page cursor.

The list of artifacts is ordered as in the report.

Raises:

NotFoundError – Report not found.

class cybsi.api.report.ReportsAsyncAPI(connector)[source]#

Report asynchronous API.

async register(report)[source]#

Register report.

Note

Calls POST /enrichment/reports.

Parameters:

report (ReportForm) – Filled report form.

Return type:

RefView

Returns:

Reference to the registered report.

Raises:

  • SemanticError – Form contains logic errors.

  • ConflictError – A report with such external_id and data source is already registered.

Note

Semantic error codes specific for this method:
async view(report_uuid)[source]#

Get report view.

Note

Calls GET /enrichment/reports/{report_uuid}.

Parameters:

report_uuid (UUID) – Report uuid.

Return type:

ReportView

Returns:

View of the report.

Raises:

NotFoundError – Report not found.

async filter(*, file_uuid=None, reporter_uuids=None, data_source_uuids=None, entity_uuids=None, labels=None, analyzed_artifact_uuid=None, title=None, created_before=None, created_after=None, updated_before=None, updated_after=None, external_id=None, cursor=None, limit=None, reverse_order=False)[source]#

Get report header filtration list that matches the specified criteria.

Reports are returned in reverse order of registration time.

Note

Calls GET /enrichment/reports.

Parameters:

  • file_uuid (Optional[UUID]) – File identifier. Filter reports by the artifact of the observed file with the specified identifier.

  • reporter_uuids (Optional[Iterable[UUID]]) – Reporter identifiers. Filter reports by reporter data source identifiers.

  • data_source_uuids (Optional[Iterable[UUID]]) – Data source identifiers. Filter reports by original data source identifiers.

  • entity_uuids (Optional[Iterable[UUID]]) – entity identifiers. Filter reports by at least one of the specified entity.

  • labels (Optional[Iterable[str]]) – Filter reports by any of the specified labels. Label case is ignored.

  • analyzed_artifact_uuid (Optional[UUID]) – Analyzed artifact identifier. Filter reports based on analysis of the specified artifact.

  • title (Optional[str]) – Filter reports by specified title. Title case is ignored. Allows special symbols ‘%’ and ‘_’. The ‘%’ symbol replaces any number of title symbols. The ‘_’ symbol replaces only one title symbol. To search for ‘%’ and ‘_’ symbols in the usual sense, you need to prepend them with ‘’.

  • created_before (Optional[datetime]) – Filter reports created before the timestamp (inclusive).

  • created_after (Optional[datetime]) – Filter reports created after the timestamp (inclusive).

  • updated_before (Optional[datetime]) – Filter reports updated before the timestamp (inclusive).

  • updated_after (Optional[datetime]) – Filter reports updated after the timestamp (inclusive).

  • external_id (Optional[str]) – Filter reports by their external id. Min length is 1.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

  • reverse_order (bool) – Result list order, default false

Return type:

AsyncPage[ReportHeaderView]

Returns:

Page of reports list and next page cursor.

Raises:

SemanticError – Query arguments contain semantic errors.

Note

Semantic error codes specific for this method:
async filter_similar_reports(report_uuid, *, reporter_uuid=None, data_source_uuid=None, cursor=None, limit=None)[source]#

Get similar reports filtration list in descending order of similarity.

Note

Calls GET /enrichment/reports/{report_uuid}/similar-reports.

Parameters:

  • report_uuid (UUID) – Report identifier.

  • reporter_uuid (Optional[UUID]) – Reporter identifier. Filter similar reports the reporter data source identifiers.

  • data_source_uuid (Optional[UUID]) – Data source identifier. Filter similar reports the original data source identifiers.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[SimilarReportView]

Returns:

Page of similar reports list and next page cursor.

async explain_report_similarity(report_uuid, similar_report_uuid)[source]#

Get information about the similarity of reports.

Note

Report A is similar to report B, but not the same as report B is similar report A.

Note

Calls GET /enrichment/reports/{report_uuid}/similar-reports/{similar_report_uuid}. # noqa: E501

Parameters:

  • report_uuid (UUID) – Report identifier.

  • similar_report_uuid (UUID) – Report identifier for comparison

Return type:

SimilarReportView

Returns:

View of the report.

async search_labels(prefix, *, cursor=None, limit=None)[source]#

Get report label filtration list.

Note

Calls GET /enrichment/report-labels.

Parameters:

  • prefix (str) – Label prefix. Prefix length must be in range [2;50].

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[str]

Returns:

Page of reports label list and next page cursor.

async attach_observations(report_uuid, observation_uuids)[source]#

Attach observations to existing report.

Note

Calls POST /enrichment/reports/{report_uuid}/observations.

Parameters:

  • report_uuid (UUID) – Report UUID.

  • observation_uuids (Iterable[UUID]) – Observation UUIDs.

Return type:

RefView

Returns:

Reference to the report.

Raises:

Note

Semantic error codes specific for this method:
async filter_observations(report_uuid, *, cursor=None, limit=None)[source]#

Filter observations in the report. Observations having share level above user’s access level are filtered out.

Note

Calls GET /enrichment/reports/{report_uuid}/observations.

Parameters:
Return type:

AsyncPage[ObservationView]

Returns:

Page of report observations list and next page cursor.

The list of observations is ordered as in the report.

Raises:

NotFoundError – Report not found.

async attach_artifacts(report_uuid, artifact_uuids)[source]#

Attach artifacts to existing report.

Note

Calls POST /enrichment/reports/{report_uuid}/artifacts.

Parameters:

  • report_uuid (UUID) – Report UUID.

  • artifact_uuids (Iterable[UUID]) – Artifact UUIDs.

Return type:

RefView

Returns:

Reference to the report.

Raises:

Note

Semantic error codes specific for this method:
async filter_artifacts(report_uuid, *, cursor=None, limit=None)[source]#

Filter artifacts in the report. Artifacts having share level above user’s access level are filtered out.

Note

Calls GET /enrichment/reports/{report_uuid}/artifacts.

Parameters:
Return type:

AsyncPage[ArtifactCommonView]

Returns:

Page of report artifacts list and next page cursor.

The list of artifacts is ordered as in the report.

Raises:

NotFoundError – Report not found.

class cybsi.api.report.ReportForm(share_level, *, title=None, description=None, external_id=None, created_at=None, published_at=None, external_refs=None, labels=None, data_source=None, observation_uuids=None, artifact_uuids=None, analyzed_artifact_uuid=None)[source]#

Report form.

Parameters:
add_observation(observation_uuid)[source]#

Add observation to report. :type observation_uuid: UUID :param observation_uuid: UUID of associated observation.

Return type:

ReportForm

Returns:

Updated report form.

add_artifact(artifact_uuid)[source]#

Add artifact to report. :type artifact_uuid: UUID :param artifact_uuid: UUID of associated artifact.

Return type:

ReportForm

Returns:

Updated report form.

class cybsi.api.report.ReportView(data=None)[source]#

Report view.

property artifacts#

Artifacts attached to report.

property observations#

Observations attached to report.

property analyzed_artifact_uuid#

Analyzed artifact UUID.

property created_at#

Report created time.

property data_source#

Original data source of report.

property description#

Report description.

property external_id#

Unique external ID for current data source.

property external_refs#

List of external references associated with report.

property labels#

List of report labels.

property published_at#

Report publication time.

property registered_at#

Report registered time.

property reporter#

Data source that reported to system.

property share_level#

Report share level.

property title#

Report title.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.report.ArtifactShortView(data=None)[source]#

Artifact short view.

property type#

Artifact type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.report.ReportHeaderView(data=None)[source]#

Report header view.

property share_level#

Report share level.

property title#

Report title.

property description#

Report description.

property external_id#

Unique external ID for current data source.

property created_at#

Report created time.

property published_at#

Report publication time.

property registered_at#

Report registered time.

property external_refs#

List of external references associated with report.

property labels#

List of report labels.

property data_source#

Original data source of report.

property reporter#

Data source that reported to system.

property analyzed_artifact_uuid#

Analyzed artifact UUID.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.report.SimilarReportView(data=None)[source]#

Similar report view.

property report#

Report header view.

property correlation#

Report correlation view.

class cybsi.api.report.SimilarReportCorrelationView(data=None)[source]#

Similar report correlation view.

property similarity#

Similarity degree of reports in the range [0;1] The larger the value, the greater the degree of coincidence.

property matched_entities#

List of matched entities.

class cybsi.api.report.MatchedEntitiesView(data=None)[source]#

Matched entity view.

property entity#

Entity.

property weight#

Weight value of entity in range [0;1].

class cybsi.api.report.ObservationView(data=None)[source]#

Observation view.

property content#

Observation content.

Depends on observation type.

Using:
>>> from typing import cast
>>> from cybsi.api.observation import ObservationTypes
>>> from cybsi.api.report import ObservationView
>>> view = ObservationView()
>>> if view.type == ObservationTypes.Generic:
>>>     # do something with generic content
>>>     print(view.content.generic)
property data_source#

Observation data source.

property registered_at#

Date and time when observation was registered.

property reporter#

Source reporting the observation.

property seen_at#

Date and time when observation was seen.

property share_level#

Share level.

property type#

Observation type.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.report.ObservationContentView(obs_type, content)[source]#

Observation content view.

property dns_lookup#

Content of dns lookup observation.

Raises:

KeyError – Content is absent in the ObservationContentView.

property generic#

Content of generic observation.

Raises:

KeyError – Content is absent in the ObservationContentView.

property network_session#

Content of network session observation.

Raises:

KeyError – Content is absent in the ObservationContentView.

property threat#

Content of threat observation.

Raises:

KeyError – Content is absent in the ObservationContentView.

property whois_lookup#

Content of whois lookup observation.

Raises:

KeyError – Content is absent in the ObservationContentView.

Users#

Use this section of API to operate users.

class cybsi.api.user.UsersAPI(connector)[source]#

Users API.

register(form)[source]#

Register user.

Note

Calls POST /users.

Parameters:

form (UserForm) – Filled user form.

Return type:

RefView

Returns:

Reference to the registered user.

Raises:

Note

Semantic error codes specific for this method:
view(user_uuid)[source]#

Get the user view.

Note

Calls GET /users/{user_uuid}.

Parameters:

user_uuid (UUID) – User UUID.

Return type:

UserView

Returns:

Full view of the user with ETag string value.

Raises:

NotFoundError – User not found.

me()[source]#

Get user associated with current client.

Note

Calls GET /users/me.

Return type:

CurrentUserView

Returns:

View of current user.

filter(*, user_uuids=None, data_source_uuid=None, query=None, providers=None, is_disabled=None, cursor=None, limit=None)[source]#

Filter users.

Changed in version 2.8: Added new parameters: data_source_uuid, query, providers, is_disabled. Added semantic error: UserNotFound.

Note

Calls GET /users.

Parameters:

  • user_uuids (Optional[Iterable[UUID]]) – User identifiers. Filter users by specified user UUIDs.

  • data_source_uuid (Optional[UUID]) – Data source identifier. Filter users by associated data source UUID.

  • query (Optional[str]) – Filter users by substring. Filter users whoes login, name or email starts with query.

  • providers (Optional[Iterable[str]]) – Provider identifiers. Filter user by authentication provider ids.

  • is_disabled (Optional[bool]) – Disabled user flag. If true filter disabled users.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[UserCommonView]

Returns:

Page with user common views and next page cursor.

Raises:

SemanticError – query arguments contain errors.

Note

Semantic error codes specific for this method:
Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>>
>>> client: CybsiClient
>>> # filter users by specified data source uuid
>>> started_page = client.users.filter(
>>>     data_source_uuid=uuid.UUID("007c3927-1ef6-474a-b89b-d6feb3c73871"),
>>> )
>>> for item in chain_pages(started_page):
>>>     # do something with users
>>>     print(item)
>>> pass
edit(user_uuid, tag, *, full_name=None, email=None, data_source_uuid=None, access_level=None, roles=None, password=None, is_disabled=None)[source]#

Edit user.

Note

Calls PATCH /users/{user_uuid}.

Parameters:
Raises:

Note

Semantic error codes specific for this method:
edit_me(tag, *, full_name=None, email=None)[source]#

Edit API-Client user.

Note

Calls PATCH /users/me. Doesn’t require any permissions.

Parameters:
Raises:

Note

Semantic error codes specific for this method:

New in version 2.8.

change_my_password(*, old_password, new_password)[source]#

Change password of current client.

Note

The password can be changed only if the password was set initially. Password login is not available for users without a password.

To confirm authorization and exclude situations when the password is changed using the API key, you must specify the valid current user password in the request.

Note

Calls PUT /users/me/password.

Parameters:

  • old_password (str) – Old user password. Password length must be in range [4, 50].

  • new_password (str) – New user password. Password length must be in range [4, 50].

Raises:

Note

Semantic error codes specific for this method:
class cybsi.api.user.UserForm(login, access_level, roles, *, password=None, full_name=None, email=None, data_source_uuid=None)[source]#

User form.

This is the form you need to fill to register user.

Parameters:

  • login (str) – User login. Login should consist of characters without spaces ([a-zA-Z0-9_-]) and have length in the range [1, 250].

  • access_level (ShareLevels) – User access level.

  • roles (Iterable[RoleName]) – List of user role names.

  • password (Optional[str]) – User password. Password length must be in range [4, 50]. if password is None then the user will not be able to enter the system by password.

  • full_name (Optional[str]) – User full name. Name must be less than or equal to 250 characters.

  • email (Optional[str]) – User email. Email length must be in range [3, 254].

  • data_source_uuid (Optional[UUID]) – Associated data source UUID. If data_source_uuid is None then data source will be created and assigned when the user first tries to register TI data.

Usage:
>>> from cybsi.api.observable import ShareLevels
>>> from cybsi.api.user import UserForm
>>>
>>> userForm = UserForm(
>>>     login="user_test",
>>>     access_level=ShareLevels.Green,
>>>     roles=[RoleName.SystemAdministrator],
>>>     password="string",
>>>     full_name="Test Tester",
>>>     email="test@pt.com",
>>> )
>>> pass
class cybsi.api.user.UserView(resp)[source]#

User full view.

property access_level#

User access level.

property roles#

List of user role.

property permissions#

List of permissions derived from user roles.

property data_source#

Associated data source.

property auth_provider_id#

Authentication provider ID.

property email#

User email.

property full_name#

User full name.

property is_disabled#

Disabled user flag.

property login#

User login.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.user.UserCommonView(data=None)[source]#

User common view.

property login#

User login.

property full_name#

User full name.

property email#

User email.

property is_disabled#

Disabled user flag.

property auth_provider_id#

Authentication provider ID.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.user.RoleCommonView(data=None)[source]#

Role common view.

property uuid#

Role UUID.

property name#

Role name.

class cybsi.api.user.CurrentUserView(data=None)[source]#

Current user view.

property access_level#

User access level.

property auth_provider_id#

Authentication provider ID.

property email#

User email.

property full_name#

User full name.

property is_disabled#

Disabled user flag.

property login#

User login.

property permissions#

List of permissions derived from user roles.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

property data_source#

Associated data source.

enum cybsi.api.user.enums.RoleName(value)[source]#

Bases: CybsiAPIEnum

Role name.

Role means a list of permissions. Each permission is Resource:Action pair. See ResourceName.

Valid values are as follows:

SystemAdministrator = <RoleName.SystemAdministrator: 'SystemAdministrator'>#

New in version 2.12.

Changed in version 2.14: Add new privilege ‘Log:r’.

System administrator’s role permissions: [DataSources:r,Users:rw,APIKeys:rw,License:w,Log:r]

DataEngineer = <RoleName.DataEngineer: 'DataEngineer'>#

New in version 2.12.

Data engineer’s role permissions: [StoredQuery:rw,Observable:r,EntityView:r,Artifacts:r, ArtifactsContent:r,ReputationLists:rw,ReputationListsContent:r, EnrichmentConfig:rw,DataSources:rw,Users:rw,APIKeys:rw, Dictionaries:rw]

SOCAnalyst = <RoleName.SOCAnalyst: 'SOCAnalyst'>#

New in version 2.12.

Changed in version 2.14: Removed RawReports:r privilege

SOC analyst’s role permissions: [StoredQuery:rw,Observable:rw,EntityView:r,Artifacts:rw, ArtifactsContent:r,Reports:rw,Observations:rw,EnrichmentTasks:rw, ReputationLists:rw,ReputationListsContent:r,EnrichmentConfig:r, DataSources:r,Users:r,Dictionaries:rw]

CTIAnalyst = <RoleName.CTIAnalyst: 'CTIAnalyst'>#

New in version 2.12.

Changed in version 2.14: Removed RawReports:r privilege

CTI analyst’s role permissions: [StoredQuery:r,Observable:rw,EntityView:r,Artifacts:rw, ArtifactsContent:r,Reports:rw,Observations:rw,EnrichmentTasks:rw, ReputationLists:r,ReputationListsContent:r,EnrichmentConfig:r, DataSources:r,Users:r,Dictionaries:rw]

CyberSecuritySpecialist = <RoleName.CyberSecuritySpecialist: 'CyberSecuritySpecialist'>#

New in version 2.12.

Changed in version 2.14: Removed RawReports:r privilege

Cyber security specialist’s role permissions: [StoredQuery:r,Observable:r,EntityView:r,Artifacts:r, Reports:r,Observations:r,EnrichmentTasks:rw, ReputationLists:r,ReputationListsContent:r, EnrichmentConfig:r,DataSources:r,Users:r,Dictionaries:rw]

Guest = <RoleName.Guest: 'Guest'>#

New in version 2.12.

Changed in version 2.14: Removed RawReports:r privilege

Guest’s role permissions: [Observable:r,Artifacts:r,Reports:r,Observations:r, EnrichmentTasks:r,EnrichmentConfig:r,DataSources:r, Dictionaries:r]

enum cybsi.api.user.enums.ResourceName(value)[source]#

Bases: CybsiAPIEnum

Resource name.

Permission can be with read/write action for almost all resources. Exclusion resources: ArtifactsContent, Search, ReputationListsContent, Log.

Valid values are as follows:

Artifacts = <ResourceName.Artifacts: 'Artifacts'>#

Samples.

ArtifactsContent = <ResourceName.ArtifactsContent: 'ArtifactsContent'>#

Sample contents. Permission can be only with reading action.

DataSources = <ResourceName.DataSources: 'DataSources'>#

Data sources.

Dictionaries = <ResourceName.Dictionaries: 'Dictionaries'>#

New in version 2.11.2.

Dictionaries

EnrichmentConfig = <ResourceName.EnrichmentConfig: 'EnrichmentConfig'>#

Enrichment configs.

EnrichmentTasks = <ResourceName.EnrichmentTasks: 'EnrichmentTasks'>#

Enrichment tasks.

Observable = <ResourceName.Observable: 'Observable'>#

Observable entities.

Observations = <ResourceName.Observations: 'Observations'>#

Observations.

Reports = <ResourceName.Reports: 'Reports'>#

Reports.

Search = <ResourceName.Search: 'Search'>#

Search. Permission can be only with reading action.

Users = <ResourceName.Users: 'Users'>#

Users.

APIKeys = <ResourceName.APIKeys: 'APIKeys'>#

Access keys.

ReputationLists = <ResourceName.ReputationLists: 'ReputationLists'>#

Reputation lists.

ReputationListsContent = <ResourceName.ReputationListsContent: 'ReputationListsContent'>#

Reputation list contents. Permission can be only with reading action.

StoredQuery = <ResourceName.StoredQuery: 'StoredQuery'>#

Stored queries.

License = <ResourceName.License: 'License'>#

New in version 2.12.

Licenses.

Log = <ResourceName.Log: 'Log'>#

New in version 2.14.

User access log.

ThreatLandscapes = <ResourceName.ThreatLandscapes: 'ThreatLandscapes'>#

New in version 2.14.

Threat landscapes.

CustomLists = <ResourceName.CustomLists: 'CustomLists'>#

New in version 2.14.

Custom lists.

Dictionaries#

Use this section of API to operate dictionaries and their items. Dictionary is an open set of string values. Dictionary items are used as attribute values. For example, dictionary “MalwareFamilies” contains names of malware families known by system. Use cybsi.api.observation.generic.GenericObservationForm.add_attribute_fact() or register_item() to add items to a dictionary.

class cybsi.api.dictionary.DictionariesAPI(connector)[source]#

API to operate dictionaries.

New in version 2.9.

view(dictionary_uuid)[source]#

Get the dictionary view.

New in version 2.9.

Note

Calls GET /dictionaries/{dictionary_uuid}.

Parameters:

dictionary_uuid (UUID) – Dictionary UUID.

Return type:

DictionaryView

Returns:

View of the dictionary.

Raises:

NotFoundError – Dictionary not found.

filter(*, cursor=None, limit=None)[source]#

Get a filtered list of dictionaries.

Results are sorted in alphabetical order by dictionary name.

New in version 2.9.

Note

Calls GET /dictionaries.

Parameters:
Return type:

Page[DictionaryCommonView]

Returns:

Page with dictionary views and next page cursor.

Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>>
>>> client: CybsiClient
>>>
>>> started_page = client.dictionaries.filter()
>>> for item in chain_pages(started_page):
>>>     # do something with dictionaries
>>>     print(item)
>>> pass
register_item(item)[source]#

Register item for the dictionary.

New in version 2.9.

Changed in version 2.10: Added semantic error DictionaryClosed

Changed in version 2.11: Move dictionary_uuid parameter into DictionaryItemForm

Note

Calls POST /dictionary-items.

Parameters:

item (DictionaryItemForm) – Filled dictionary item form.

Return type:

RefView

Returns:

Reference to a newly added dictionary item.

Raises:

Note

Semantic error codes specific for this method:
view_item(item_uuid)[source]#

Get the dictionary item view.

New in version 2.9.

Note

Calls GET /dictionary-items/{item_uuid}.

Parameters:

item_uuid (UUID) – Dictionary item UUID.

Return type:

DictionaryItemView

Returns:

View of the dictionary item with tag.

Raises:

NotFoundError – Dictionary item not found.

edit_item(item_uuid, tag, *, description=None)[source]#

Edit the dictionary item.

New in version 2.9.

Changed in version 2.10: Added semantic error DictionaryClosed

Note

Calls PATCH /dictionary-items/{item_uuid}.

Parameters:
Raises:
Return type:

None

Note

Semantic error codes specific for this method:
filter_items(dictionary_uuid, *, prefix=None, cursor=None, limit=None)[source]#

Get a filtered list of dictionary items.

Results are sorted in alphabetical order by dictionary item name.

New in version 2.9.

Note

Calls GET /dictionaries/{dictionaryUUID}/items.

Parameters:

  • dictionary_uuid (UUID) – Open dictionary UUID.

  • prefix (Optional[str]) – Dictionary item name prefix (case-insensitive). Prefix length must be in range [1;30].

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[DictionaryItemCommonView]

Returns:

Page with dictionary items common views and next page cursor.

Usage:
>>> import uuid
>>> from cybsi.api import CybsiClient
>>> from cybsi.api.pagination import chain_pages
>>>
>>> client: CybsiClient
>>>
>>> started_page = client.dictionaries.filter_items(
>>>     dictionary_uuid=uuid.UUID("89200bef-2f50-4d4f-8b38-843d5ab9dfa9"),
>>> )
>>> for item in chain_pages(started_page):
>>>     # do something with dictionary items
>>>     print(item)
>>> pass
add_item_synonym(*, item_uuid, synonym_uuid)[source]#

Add dictionary item to synonym group.

New in version 2.9.

Changed in version 2.10: Added semantic error DictionaryClosed

Note

Calls PUT /dictionary-items/{item_uuid}/synonyms.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • synonym_uuid (UUID) – Synonym item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:
remove_item_synonym(item_uuid)[source]#

Remove dictionary item from synonym group.

New in version 2.9.

Changed in version 2.10: Added semantic error DictionaryClosed

Note

Calls DELETE /dictionary-items/{item_uuid}/synonyms.

Parameters:

item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Add related item for dictionary item.

New in version 2.11.

Note

Calls PUT /dictionary-items/{item_uuid}/related-items.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • related_uuid (UUID) – Related dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Remove related item for dictionary item.

New in version 2.11.

Note

Calls DELETE /dictionary-items/{item_uuid}/related-items/{related_uuid}.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • related_uuid (UUID) – Related dictionary item UUID.

Raises:

NotFoundError – Dictionary item not found.

Return type:

None

class cybsi.api.dictionary.DictionariesAsyncAPI(connector)[source]#

Async API to operate dictionaries.

New in version 2.13.1.

async view(dictionary_uuid)[source]#

Get the dictionary view.

New in version 2.13.1.

Note

Calls GET /dictionaries/{dictionary_uuid}.

Parameters:

dictionary_uuid (UUID) – Dictionary UUID.

Return type:

DictionaryView

Returns:

View of the dictionary.

Raises:

NotFoundError – Dictionary not found.

async filter(*, cursor=None, limit=None)[source]#

Get a filtered list of dictionaries.

Results are sorted in alphabetical order by dictionary name.

New in version 2.13.1.

Note

Calls GET /dictionaries.

Parameters:
Return type:

AsyncPage[DictionaryCommonView]

Returns:

Page with dictionary views and next page cursor.

Usage:
>>> import uuid
>>> from cybsi.api import CybsiAsyncClient
>>> from cybsi.api.pagination import chain_pages_async
>>>
>>> async def example():
>>>     client: CybsiAsyncClient
>>>
>>>     started_page = await client.dictionaries.filter()
>>>     async for item in chain_pages_async(started_page):
>>>         # do something with dictionaries
>>>         print(item)
>>>     pass
async register_item(item)[source]#

Register item for the dictionary.

New in version 2.13.1.

Note

Calls POST /dictionary-items.

Parameters:

item (DictionaryItemForm) – Filled dictionary item form.

Return type:

RefView

Returns:

Reference to a newly added dictionary item.

Raises:

Note

Semantic error codes specific for this method:
async view_item(item_uuid)[source]#

Get the dictionary item view.

New in version 2.13.1.

Note

Calls GET /dictionary-items/{item_uuid}.

Parameters:

item_uuid (UUID) – Dictionary item UUID.

Return type:

DictionaryItemView

Returns:

View of the dictionary item with tag.

Raises:

NotFoundError – Dictionary item not found.

async edit_item(item_uuid, tag, *, description=None)[source]#

Edit the dictionary item. .. versionadded:: 2.13.1 .. note:: Calls PATCH /dictionary-items/{item_uuid}.

Parameters:
Raises:
Return type:

None

Note

Semantic error codes specific for this method:
async filter_items(dictionary_uuid, *, prefix=None, cursor=None, limit=None)[source]#

Get a filtered list of dictionary items.

Results are sorted in alphabetical order by dictionary item name.

New in version 2.13.1.

Note

Calls GET /dictionaries/{dictionaryUUID}/items.

Parameters:

  • dictionary_uuid (UUID) – Open dictionary UUID.

  • prefix (Optional[str]) – Dictionary item name prefix (case-insensitive). Prefix length must be in range [1;30].

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[DictionaryItemCommonView]

Returns:

Page with dictionary items common views and next page cursor.

Usage:
>>> import uuid
>>> from cybsi.api import CybsiAsyncClient
>>> from cybsi.api.pagination import chain_pages_async
>>>
>>> async def example():
>>>     client: CybsiAsyncClient
>>>
>>>     started_page = await client.dictionaries.filter_items(
>>>         dictionary_uuid=uuid.UUID(
>>>             "89200bef-2f50-4d4f-8b38-843d5ab9dfa9"
>>>         ),
>>>     )
>>>     async for item in chain_pages_async(started_page):
>>>         # do something with dictionary items
>>>         print(item)
>>> pass
async add_item_synonym(*, item_uuid, synonym_uuid)[source]#

Add dictionary item to synonym group.

New in version 2.13.1.

Note

Calls PUT /dictionary-items/{item_uuid}/synonyms.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • synonym_uuid (UUID) – Synonym item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:
async remove_item_synonym(item_uuid)[source]#

Remove dictionary item from synonym group.

New in version 2.13.1.

Note

Calls DELETE /dictionary-items/{item_uuid}/synonyms.

Parameters:

item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Add related item for dictionary item.

New in version 2.13.1.

Note

Calls PUT /dictionary-items/{item_uuid}/related-items.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • related_uuid (UUID) – Related dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Remove related item for dictionary item.

New in version 2.13.1.

Note

Calls DELETE /dictionary-items/{item_uuid}/related-items/{related_uuid}.

Parameters:

  • item_uuid (UUID) – Dictionary item UUID.

  • related_uuid (UUID) – Related dictionary item UUID.

Raises:

NotFoundError – Dictionary item not found.

Return type:

None

class cybsi.api.dictionary.DictionaryItemForm(*, dictionary_uuid, key)[source]#

Dictionary item form. Use to add dictionary item.

Parameters:

  • dictionary_uuid (UUID) – Dictionary identifier.

  • key (str) – Dictionary item key. The key should consist of characters according to the pattern [a-zA-Z0-9_ :.@-] and have length in the range [1;50]. First and last char of key can’t be space-symbol User-specified key case is preserved.

class cybsi.api.dictionary.DictionaryView(data=None)[source]#

Dictionary detailed view.

property is_closed#

Closed dictionary flag.

property name#

Dictionary name.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.dictionary.DictionaryCommonView(data=None)[source]#

Dictionary common view.

property name#

Dictionary name.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.dictionary.DictionaryItemView(resp)[source]#

Dictionary item detailed view.

property dictionary#

Reference to dictionary.

property description#

Dictionary item description.

property synonyms#

List of refs to dictionary item that are synonyms.

property key#

Dictionary item key.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.dictionary.DictionaryItemCommonView(data=None)[source]#

Dictionary item common view.

property key#

Dictionary item key.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.dictionary.DictItemAttributeValue(*, key)[source]#

Dictionary item. Used as attribute value to create a general observation. See add_attribute_fact()

Parameters:

key (str) – Dictionary item key. The key should have length in the range [1;50]. First and last char of key can’t be space-symbol User-specified key case is preserved.

Licenses#

Use this section of API to operate licenses.

enum cybsi.api.license.Status(value)[source]#

License status.

Valid values are as follows:

Valid = <Status.Valid: 'Valid'>#

Valid current license. Excludes all other statuses.

Expired = <Status.Expired: 'Expired'>#

The license has expired.

Inactive = <Status.Inactive: 'Inactive'>#

Removed or deactivated.

class cybsi.api.license.LicensesAPI(connector)[source]#

API to operate licenses.

New in version 2.10.

upload(data)[source]#

Upload license.

New in version 2.10.

Note

Calls PUT /license.

Parameters:

data (Any) – File-like object. Data must be present as a license-access-token.key file or as zip-archive with nested license-access-token.key. If you have key in bytes, wrap them in BytesIO.

Raises:

SemanticError – Form contains logic errors.

Note

Semantic error codes specific for this method:
info()[source]#

Get the license information.

New in version 2.10.

Note

Calls GET /license/info.

Return type:

LicenseInfoView

Returns:

View of the license info.

Raises:

NotFoundError – License not found.

class cybsi.api.license.LicenseInfoView(data=None)[source]#

License information view.

property no#

License serial number.

property expires_at#

License expiration time.

property updated_at#

Time of the last license update from the update server. None if license wasn’t updated yet.

property status#

License status (flag set).

AccessLogs#

Use this section of API to operate user access logs.

class cybsi.api.ual.AccessLogsAPI(connector)[source]#

User access logs API.

filter_entries(*, user_uuid=None, operation=None, object_type=None, object_domain=None, since=None, till=None, cursor=None, limit=None)[source]#

Get list of user access log entry.

Note

Calls GET /access-log/entries.

Parameters:
Return type:

Page[EntryView]

Returns:

Page with entries and next page cursor.

Raises:

Note

Semantic error codes specific for this method: * UserNotFound

class cybsi.api.ual.EntryView(data=None)[source]#

Access user log entry view.

property remote_addr#

User ip-address. Format ipv4.

property begin_at#

Start time of action.

property end_at#

End time of action. None if it wasn’t end yet

property user_uuid#

User UUID.

property object_type#

Object domain.

property object_domain#

Object domain.

property operation#

Operation.

property object_uuid#

Object UUID.

property result#

Action result.

property details#

Action details.

enum cybsi.api.ual.Result(value)[source]#

Action result.

Valid values are as follows:

Unknown = <Result.Unknown: 'Unknown'>#

Unknown.

Success = <Result.Success: 'Success'>#

Success.

Failure = <Result.Failure: 'Failure'>#

Failure.

enum cybsi.api.ual.Operation(value)[source]#

Operation.

Valid values are as follows:

Create = <Operation.Create: 'Create'>#

Create

Register = <Operation.Register: 'Register'>#

Register

Run = <Operation.Run: 'Run'>#

Run

Read = <Operation.Read: 'Read'>#

Read

Modify = <Operation.Modify: 'Modify'>#

Modify

Delete = <Operation.Delete: 'Delete'>#

Delete

Login = <Operation.Login: 'Login'>#

Login

Logout = <Operation.Logout: 'Logout'>#

Logout

Import = <Operation.Import: 'Import'>#

Import

UpdatePasswd = <Operation.UpdatePasswd: 'UpdatePasswd'>#

UpdatePasswd

enum cybsi.api.ual.ObjectType(value)[source]#

Object type.

Valid values are as follows:

User = <ObjectType.User: 'User'>#

User

ApiKey = <ObjectType.ApiKey: 'ApiKey'>#

ApiKey

Entity = <ObjectType.Entity: 'Entity'>#

Entity

Artifact = <ObjectType.Artifact: 'Artifact'>#

Artifact

EnrichmentRule = <ObjectType.EnrichmentRule: 'EnrichmentRule'>#

EnrichmentRule

Analyzer = <ObjectType.Analyzer: 'Analyzer'>#

Analyzer

ExternalDB = <ObjectType.ExternalDB: 'ExternalDB'>#

ExternalDB

Task = <ObjectType.Task: 'Task'>#

Task

StoredQuery = <ObjectType.StoredQuery: 'StoredQuery'>#

StoredQuery

Report = <ObjectType.Report: 'Report'>#

Report

Observation = <ObjectType.Observation: 'Observation'>#

Observation

DataSourceType = <ObjectType.DataSourceType: 'DataSourceType'>#

DataSourceType

DataSource = <ObjectType.DataSource: 'DataSource'>#

DataSource

Replist = <ObjectType.Replist: 'Replist'>#

Replist

Dictionary = <ObjectType.Dictionary: 'Dictionary'>#

Dictionary

DictionaryItem = <ObjectType.DictionaryItem: 'DictionaryItem'>#

DictionaryItem

DictionaryRelatedItems = <ObjectType.DictionaryRelatedItems: 'DictionaryRelatedItems'>#

DictionaryRelatedItems

EntityView = <ObjectType.EntityView: 'EntityView'>#

EntityView

License = <ObjectType.License: 'License'>#

License

enum cybsi.api.ual.ObjectDomain(value)[source]#

Object domain.

Valid values are as follows:

Auth = <ObjectDomain.Auth: 'Auth'>#

Auth

Users = <ObjectDomain.Users: 'Users'>#

Users

ApiKeys = <ObjectDomain.ApiKeys: 'ApiKeys'>#

ApiKeys

Entities = <ObjectDomain.Entities: 'Entities'>#

Entities

Artifacts = <ObjectDomain.Artifacts: 'Artifacts'>#

Artifacts

Enrichment = <ObjectDomain.Enrichment: 'Enrichment'>#

Enrichment

Tasks = <ObjectDomain.Tasks: 'Tasks'>#

Tasks

StoredQueries = <ObjectDomain.StoredQueries: 'StoredQueries'>#

StoredQueries

Reports = <ObjectDomain.Reports: 'Reports'>#

Reports

Observations = <ObjectDomain.Observations: 'Observations'>#

Observations

DataSources = <ObjectDomain.DataSources: 'DataSources'>#

DataSources

Replists = <ObjectDomain.Replists: 'Replists'>#

Replists

Dictionaries = <ObjectDomain.Dictionaries: 'Dictionaries'>#

Dictionaries

EntityViews = <ObjectDomain.EntityViews: 'EntityViews'>#

EntityViews

License = <ObjectDomain.License: 'License'>#

License

Custom lists#

Use this section of API to operate custom lists and their items

class cybsi.api.custom_list.CustomListsAPI(connector)[source]#

API to operate custom lists.

New in version 2.14.0.

filter(*, prefix=None, cursor=None, limit=None)[source]#

Get custom lists.

New in version 2.14.0.

Note

Calls GET /custom-lists.

Parameters:
Return type:

Page[CustomListCommonView]

Returns:

Page with custom lists and next page cursor.

Raises:

InvalidRequestError – Provided arguments have invalid values.

register(custom_list)[source]#

Register a custom list.

New in version 2.14.0.

Note

Calls POST /custom-lists.

Parameters:

custom_list (CustomListForm) – Filled custom list form.

Return type:

RefView

Returns:

Reference to the registered custom list.

Raises:

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryNotFound

view(custom_list_uuid)[source]#

Get view of a custom list.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}.

Parameters:

custom_list_uuid (UUID) – Custom list UUID.

Return type:

CustomListView

Returns:

Custom list view.

Raises:
edit(custom_list_uuid, tag, name)[source]#

Edit the custom list.

New in version 2.14.0.

Note

Calls PATCH /custom-lists/{list_uuid}.

Parameters:
Raises:
Return type:

None

filter_items(custom_list_uuid, *, cursor=None, limit=None)[source]#

Get custom list items.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}/items.

Parameters:
Return type:

Page[RefView]

Returns:

Page with custom list items and next page cursor.

Raises:
add_item(custom_list_uuid, dictionary_item_uuid)[source]#

Add item to custom list.

New in version 2.14.0.

Note

Calls POST /custom-lists/{custom_list_uuid}/items.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID.

  • dictionary_item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryItemNotFound * cybsi.api.error.SemanticErrorCodes.DictionaryMismatch

delete_item(custom_list_uuid, dictionary_item_uuid)[source]#

Delete item from custom list.

New in version 2.14.0.

Note

Calls DELETE /custom-lists/{custom_list_uuid}/items/{item_uuid}.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID

  • dictionary_item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Get dictionary items that are related to custom list.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}/related-items.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID

  • dictionary_uuid (UUID) – Dictionary UUID.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

Page[RefView]

Returns:

Page with related items and next page cursor.

Raises:

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryNotFound

class cybsi.api.custom_list.CustomListsAsyncAPI(connector)[source]#

Async API to operate custom lists.

New in version 2.14.0.

async filter(*, prefix=None, cursor=None, limit=None)[source]#

Get custom lists.

New in version 2.14.0.

Note

Calls GET /custom-lists.

Parameters:
Return type:

AsyncPage[CustomListCommonView]

Returns:

Page with custom lists and next page cursor.

Raises:
async register(custom_list)[source]#

Register a custom list.

New in version 2.14.0.

Note

Calls POST /custom-lists.

Parameters:

custom_list (CustomListForm) – Filled custom list form.

Return type:

RefView

Returns:

Reference to the registered custom list.

Raises:

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryNotFound

async view(custom_list_uuid)[source]#

Get view of the custom list.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}.

Parameters:

custom_list_uuid (UUID) – Custom list UUID.

Return type:

CustomListView

Returns:

View of the custom list.

Raises:
async edit(custom_list_uuid, tag, name)[source]#

Edit the custom list.

New in version 2.14.0.

Note

Calls PATCH /custom-lists/{custom_list_uuid}.

Parameters:
Raises:
Return type:

None

async filter_items(custom_list_uuid, *, cursor=None, limit=None)[source]#

Get custom list items.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}/items.

Parameters:
Return type:

AsyncPage[RefView]

Returns:

Page with custom list items and next page cursor.

Raises:
async add_item(custom_list_uuid, dictionary_item_uuid)[source]#

Add item to custom list.

New in version 2.14.0.

Note

Calls POST /custom-lists/{custom_list_uuid}/items.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID.

  • dictionary_item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryItemNotFound * cybsi.api.error.SemanticErrorCodes.DictionaryMismatch

async delete_item(custom_list_uuid, dictionary_item_uuid)[source]#

Delete item from custom list.

New in version 2.14.0.

Note

Calls DELETE /custom-lists/{custom_list_uuid}/items/{item_uuid}.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID.

  • dictionary_item_uuid (UUID) – Dictionary item UUID.

Raises:
Return type:

None

Get dictionary items that are related to custom list.

New in version 2.14.0.

Note

Calls GET /custom-lists/{custom_list_uuid}/related-items.

Parameters:

  • custom_list_uuid (UUID) – Custom list UUID.

  • dictionary_uuid (UUID) – Dictionary UUID.

  • cursor (Optional[Cursor]) – Page cursor.

  • limit (Optional[int]) – Page limit.

Return type:

AsyncPage[RefView]

Returns:

Page with related items and next page cursor.

Raises:

Note

Semantic error codes specific for this method: * cybsi.api.error.SemanticErrorCodes.DictionaryNotFound

class cybsi.api.custom_list.CustomListCommonView(data=None)[source]#

Custom list short view.

property id#

String id of custom list.

property name#

String name of custom list.

property dictionary#

Dictionary ref for custom list.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.custom_list.CustomListForm(custom_list_id, name, dictionary_uuid)[source]#

Custom list form.

Parameters:

  • custom_list_id (str) – String id of custom list.

  • name (str) – String name of custom list.

  • dictionary_uuid (UUID) – UUID of dictionary attached to custom list.

class cybsi.api.custom_list.CustomListView(resp)[source]#

Custom list full view.

property dictionary#

Dictionary ref for custom list.

property id#

String id of custom list.

property name#

String name of custom list.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

Threat landscapes#

Use this section to operate threat landscape API

class cybsi.api.threat_landscape.ThreatLandscapesAPI(connector)[source]#

API to operate threat landscapes.

New in version 2.14.0.

filter(*, cursor=None, limit=None)[source]#

Get a list of threat landscapes.

New in version 2.14.0.

Note

Calls GET /threat-landscapes.

Parameters:
Raises:

InvalidRequestError – Provided value are invalid (see args value requirements).

Return type:

Page[ThreatLandscapeCommonView]

register(landscape)[source]#

Register a threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes.

Parameters:

landscape (ThreatLandscapeForm) – Threat landscape form.

Raises:

InvalidRequestError – Provided value are invalid (see args value requirements).

Return type:

RefView

view(landscape_uuid)[source]#

Get a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscape_uuid}.

Parameters:

landscape_uuid (UUID) – Landscape UUID.

Return type:

ThreatLandscapeView

Returns:

View of threat landscape.

Raises:
edit(landscape_uuid, tag, name)[source]#

Edit a threat landscape.

New in version 2.14.0.

Note

Calls PATCH /threat-landscapes/{landscape_uuid}.

Parameters:
Raises:
Return type:

None

delete(landscape_uuid)[source]#

Delete a threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscape_uuid}.

Parameters:

landscape_uuid (UUID) – Threat landscape UUID.

Raises:
Return type:

None

filter_custom_lists(landscape_uuid, *, cursor=None, limit=None)[source]#

Get a list of all custom lists related to a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:
Raises:
Return type:

Page[ThreatLandscapesCustomListView]

add_custom_list(landscape_uuid, custom_list_uuid)[source]#

Add custom list to a threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:
delete_custom_list(landscape_uuid, custom_list_uuid)[source]#

Delete custom list to a threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Add related dictionary to custom list of threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes/{landscapeUUID}/custom-lists/{customListUUID}/related-dictionaries. # noqa: E501

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • dictionary_uuid (UUID) – Dictionary UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Add related dictionary to custom list of threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscapeUUID}/custom-lists/{customListUUID}/related-dictionaries/{dictionary_uuid}/related-dictionaries/{dictionary_uuid}. # noqa: E501

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • dictionary_uuid (UUID) – Dictionary UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

build_query(landscape_uuid, *, data_source_uuid=None)[source]#

Build a query for a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscapeUUID}/query.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • data_source_uuid (Optional[UUID]) – Data source UUID.

Raises:
Return type:

str

Note

Semantic error codes specific for this method: * DataSourceNotFound * EmptyLandscapeQuery

class cybsi.api.threat_landscape.ThreatLandscapesAsyncAPI(connector)[source]#

Async API to operate threat landscapes.

New in version 2.14.0.

async filter(*, cursor=None, limit=None)[source]#

Get a list of all threat landscapes.

New in version 2.14.0.

Note

Calls GET /threat-landscapes.

Parameters:
Raises:

InvalidRequestError – Provided value are invalid (see args value requirements).

Return type:

AsyncPage[ThreatLandscapeCommonView]

async register(landscape)[source]#

Register a threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes.

Parameters:

landscape (ThreatLandscapeForm) – Threat landscape form.

Raises:

InvalidRequestError – Provided value are invalid (see args value requirements).

Return type:

RefView

async view(landscape_uuid)[source]#

Get a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscape_uuid}.

Parameters:

landscape_uuid (UUID) – Landscape UUID.

Return type:

ThreatLandscapeView

Returns:

View of threat landscape.

Raises:
async edit(landscape_uuid, tag, name)[source]#

Edit a threat landscape.

New in version 2.14.0.

Note

Calls PATCH /threat-landscapes/{landscape_uuid}.

Parameters:
Raises:
Return type:

None

async delete(landscape_uuid)[source]#

Delete a threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscape_uuid}.

Parameters:

landscape_uuid (UUID) – Threat landscape UUID.

Raises:
Return type:

None

async filter_custom_lists(landscape_uuid, *, cursor=None, limit=None)[source]#

Get a list of all custom lists related to a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:
Raises:
Return type:

AsyncPage[ThreatLandscapesCustomListView]

async add_custom_list(landscape_uuid, custom_list_uuid)[source]#

Add custom list to a threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:
async delete_custom_list(landscape_uuid, custom_list_uuid)[source]#

Delete custom list to a threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscape_uuid}/custom-lists.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Add related dictionary to custom list of threat landscape.

New in version 2.14.0.

Note

Calls POST /threat-landscapes/{landscapeUUID}/custom-lists/{customListUUID}/related-dictionaries. # noqa: E501

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • dictionary_uuid (UUID) – Dictionary UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

Note

Semantic error codes specific for this method:

Add related dictionary to custom list of threat landscape.

New in version 2.14.0.

Note

Calls DELETE /threat-landscapes/{landscapeUUID}/custom-lists/{customListUUID}/related-dictionaries/{dictionary_uuid}/related-dictionaries/{dictionary_uuid}. # noqa: E501

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • dictionary_uuid (UUID) – Dictionary UUID.

  • custom_list_uuid (UUID) – Custom list UUID.

Raises:
Return type:

None

async build_query(landscape_uuid, *, data_source_uuid=None)[source]#

Build a query for a threat landscape.

New in version 2.14.0.

Note

Calls GET /threat-landscapes/{landscapeUUID}/query.

Parameters:

  • landscape_uuid (UUID) – Landscape UUID.

  • data_source_uuid (Optional[UUID]) – Data source UUID.

Raises:
Return type:

str

Note

Semantic error codes specific for this method: * DataSourceNotFound. * EmptyLandscapeQuery.

class cybsi.api.threat_landscape.ThreatLandscapeCommonView(data=None)[source]#

Threat landscape common view.

property name#

Threat landscape name.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.threat_landscape.ThreatLandscapeView(resp)[source]#

Threat landscape view.

property name#

Threat landscape name.

property tag#

Resource tag.

Protects against concurrent object changes. Alternatively, can be used for caching.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

class cybsi.api.threat_landscape.ThreatLandscapeForm(name)[source]#

Threat landscape form. Use to add threat landscapes.

Parameters:

name (str) – Threat landscape name.

class cybsi.api.threat_landscape.ThreatLandscapesCustomListView(data=None)[source]#

Threat landscape’s custom list view.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

property uuid#

Resource UUID.

Common views and data types#

cybsi.api.Null#

alias of <cybsi.api.api.NullType object>

cybsi.api.Nullable#

alias of Union[T, None, NullType]

class cybsi.api.NullType[source]#

Depicts explicit null values in API.

The only instance of this type is Null.

class cybsi.api.Tag[source]#

Identifier of a specific version of a resource.

Prevents mid-air-collisions. Required for edit() functions on Threat Analyzer API resources.

class cybsi.api.RefView(data=None)[source]#

Reference to a resource.

Many API methods operate such references. Most commonly, methods return a reference on a resource registration.

property uuid#

Resource UUID.

property url#

URL of the resource in API. Can be used to retrieve complete view of the resource. Property is presented if Config embed_object_url is True.

class cybsi.api.CybsiAPIEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

CybsiAPIEnum is a base class for all Cybsi API enumerations.

classmethod from_string(cls, value, ignore_case=False)[source]#

Convert a string value to enumeration value.

Parameters:

  • value (str) – value to convert.

  • ignore_case – ignore enumeration values case.

Returns:

Enumeration value.

Pagination#

Pagination API.

See also

See Pagination for complete examples of pagination usage.

class cybsi.api.pagination.Cursor[source]#

Page cursor value.

If None cursor value is passed to SDK (as a parameter to filter-like functions), SDK retrieves the first page.

Typically, SDK does not return cursors as function return values. SDK returns Page or AsyncPage, and cursor is a property of the page.

None cursor value of a page means last page.

class cybsi.api.pagination.Page(api_call, resp, view)[source]#
Page returned by Cybsi API.

Should not be constructed manually, use filter-like methods provided by SDK.

Parameters:

  • api_call (Callable[..., Response]) – Callable object for getting next page

  • resp (Response) – Response which represents a start page

  • view (Callable[..., TypeVar(T)]) – View class for page elements

next_page()[source]#

Get next page. If there is no link to the next page it return None.

Return type:

Optional[Page[TypeVar(T)]]

property cursor#

Page cursor. The current position in the collection.

None means the page is last one.

data()#

Get page data as a list of items.

Return type:

List[TypeVar(T)]

Next page link.

class cybsi.api.pagination.AsyncPage(api_call, resp, view)[source]#
Page returned by Cybsi API.

Should not be constructed manually, use filter-like methods provided by SDK.

Parameters:

  • api_call (Callable[..., Coroutine]) – Callable object for getting next page

  • resp (Response) – Response which represents a start page

  • view (Callable[..., TypeVar(T)]) – View class for page elements

async next_page()[source]#

Get next page. If there is no link to the next page it return None.

Return type:

Optional[AsyncPage[TypeVar(T)]]

property cursor#

Page cursor. The current position in the collection.

None means the page is last one.

data()#

Get page data as a list of items.

Return type:

List[TypeVar(T)]

Next page link.

cybsi.api.pagination.chain_pages(start_page)[source]#

Get chain of collection objects.

Return type:

Iterator[TypeVar(T)]

async cybsi.api.pagination.chain_pages_async(start_page)[source]#

Get chain of collection objects asynchronously.

Return type:

AsyncIterator[TypeVar(T)]

Exceptions#

This section documents exceptions SDK can raise.

Those are exceptions SDK client can expect if SDK is used in correct way. If your Python code didn’t respect the expected model, there’s no guarantees. For example, if function argument types are ignored, SDK can raise exceptions not listed here.

Each exception type is annotated if it makes sense to retry.

Some exceptions have code property. It allows to determine the concrete error.

exception cybsi.api.error.CybsiError(message, ex=None)[source]#

Bases: Exception

Base exception used by SDK. Sometimes can be retried.

If it’s not of one of subclasses (see below), means unexpected error.

CybsiError covers those cases:

  • Unexpected API response status code. See APIError for specific errors.

  • Unexpected API response content.

  • Connection error.

exception cybsi.api.error.APIError(status, content, header=None, suffix=None)[source]#

Bases: CybsiError

Base exception for HTTP 4xx API responses.

exception cybsi.api.error.InvalidRequestError(content)[source]#

Bases: APIError

Invalid request error. Retry will never work.

Ideally, should not be raised by SDK. If it’s raised, it means one of two things:

  • SDK was used incorrectly. For example, values of invalid type were passed to SDK functions.

  • There’s a bug in request serialization in SDK. Please report the bug.

exception cybsi.api.error.UnauthorizedError(content)[source]#

Bases: APIError

Client lacks valid authentication credentials. Retry will never work.

exception cybsi.api.error.ForbiddenError(content)[source]#

Bases: APIError

Operation was forbidden. Retry will not work unless system is reconfigured.

property code#

Error code.

exception cybsi.api.error.NotFoundError(content)[source]#

Bases: APIError

Requested resource not found. Retry will never work.

exception cybsi.api.error.MethodNotAllowedError(content)[source]#

Bases: APIError

Method not allowed by server. Retry will never work

exception cybsi.api.error.ConflictError(content)[source]#

Bases: APIError

Resource already exists. Retry will never work.

exception cybsi.api.error.ResourceModifiedError(content)[source]#

Bases: APIError

Resource was modified since last read. Retry is a must.

Read the updated resource from API, and apply your modifications again.

exception cybsi.api.error.SemanticError(content)[source]#

Bases: APIError

Semantic error. Retry will not work (almost always).

Request syntax was valid, but system business rules forbid the request.

For example, we’re trying to unpack an artifact, but the artifact is not an archive.

property code#

Error code.

enum cybsi.api.error.ForbiddenErrorCodes(value)[source]#

Bases: CybsiAPIEnum

Possible error codes of ForbiddenError.

Valid values are as follows:

InvalidCredentials = <ForbiddenErrorCodes.InvalidCredentials: 'InvalidCredentials'>#

User provided invalid credentials.

InsufficientAccessLevel = <ForbiddenErrorCodes.InsufficientAccessLevel: 'InsufficientAccessLevel'>#

User authenticated but has insufficient access level to access the resource.

MissingPermissions = <ForbiddenErrorCodes.MissingPermissions: 'MissingPermissions'>#

User authenticated but not authorized to perform operation.

NotOwner = <ForbiddenErrorCodes.NotOwner: 'NotOwner'>#

Only owner can edit the resource.

Forbidden = <ForbiddenErrorCodes.Forbidden: 'Forbidden'>#

Other cases.

enum cybsi.api.error.SemanticErrorCodes(value)[source]#

Bases: CybsiAPIEnum

Common semantic error codes.

Valid values are as follows:

ArtifactNotFound = <SemanticErrorCodes.ArtifactNotFound: 'ArtifactNotFound'>#

Artifact not found.

BrokenKeySet = <SemanticErrorCodes.BrokenKeySet: 'BrokenKeySet'>#

Key set identifies multiple entities.

CorruptedLicense = <SemanticErrorCodes.CorruptedLicense: 'CorruptedLicense'>#

Invalid signature or license data corrupted

CursorOutOfRange = <SemanticErrorCodes.CursorOutOfRange: 'CursorOutOfRange'>#

Cursor points outside of event list.

DataSourceNotFound = <SemanticErrorCodes.DataSourceNotFound: 'DataSourceNotFound'>#

Data source not found.

DataSourceTypeNotFound = <SemanticErrorCodes.DataSourceTypeNotFound: 'DataSourceTypeNotFound'>#

Data source type not found.

DictionaryClosed = <SemanticErrorCodes.DictionaryClosed: 'DictionaryClosed'>#

Dictionary is closed for modification.

DictionaryNotFound = <SemanticErrorCodes.DictionaryNotFound: 'DictionaryNotFound'>#

Dictionary not found.

DictionaryItemNotFound = <SemanticErrorCodes.DictionaryItemNotFound: 'DictionaryItemNotFound'>#

Dictionary item not found.

DuplicatedEntityAttribute = <SemanticErrorCodes.DuplicatedEntityAttribute: 'DuplicatedEntityAttribute'>#

Entity attribute was specified several times and attribute is not an array.

EnrichmentNotAllowed = <SemanticErrorCodes.EnrichmentNotAllowed: 'EnrichmentNotAllowed'>#

Enrichment using provided parameters is not possible.

EntityNotFound = <SemanticErrorCodes.EntityNotFound: 'EntityNotFound'>#

Entity not found.

EntityViewNotFound = <SemanticErrorCodes.EntityViewNotFound: 'EntityViewNotFound'>#

Entity view not found.

ExpiredLicense = <SemanticErrorCodes.ExpiredLicense: 'ExpiredLicense'>#

Expired license

FileNotFound = <SemanticErrorCodes.FileNotFound: 'FileNotFound'>#

File entity not found.

LicenseFileMissing = <SemanticErrorCodes.LicenseFileMissing: 'LicenseFileMissing'>#

License file is missing or corrupted

ImmutableValue = <SemanticErrorCodes.ImmutableValue: 'ImmutableValue'>#

Resource attribute edits are blocked.

InvalidAttribute = <SemanticErrorCodes.InvalidAttribute: 'InvalidAttribute'>#

Invalid attribute for such entity.

InvalidAttributeValue = <SemanticErrorCodes.InvalidAttributeValue: 'InvalidAttributeValue'>#

Invalid attribute value.

InvalidDictionary = <SemanticErrorCodes.InvalidDictionary: 'InvalidDictionary'>#

The specified dictionary item and the synonym refer to different directories.

InvalidErrorCode = <SemanticErrorCodes.InvalidErrorCode: 'InvalidErrorCode'>#

Invalid task error code reported by enricher.

InvalidKey = <SemanticErrorCodes.InvalidKey: 'InvalidKey'>#

Invalid key value for such entity or entity key type.

InvalidKeySet = <SemanticErrorCodes.InvalidKeySet: 'InvalidKeySet'>#

Entity has invalid set of keys (invalid key type for such entity, invalid number of keys, and so on).

InvalidQueryText = <SemanticErrorCodes.InvalidQueryText: 'InvalidQueryText'>#

Query text is invalid CybsiLang expression.

InvalidRelationship = <SemanticErrorCodes.InvalidRelationship: 'InvalidRelationship'>#

Relationship is invalid.

InvalidRule = <SemanticErrorCodes.InvalidRule: 'InvalidRule'>#

Enrichment configuration rule is invalid.

InvalidShareLevel = <SemanticErrorCodes.InvalidShareLevel: 'InvalidShareLevel'>#

Specified share level is above API client share level.

InvalidTaskResult = <SemanticErrorCodes.InvalidTaskResult: 'InvalidTaskResult'>#

Invalid task result was reported by enricher.

InvalidTaskStatus = <SemanticErrorCodes.InvalidTaskStatus: 'InvalidTaskStatus'>#

Could not accept enrichment result, task status is not Executing.

InvalidSynonym = <SemanticErrorCodes.InvalidSynonym: 'InvalidSynonym'>#

The specified element is an invalid synonym (for example, the element and the synonym have the same key).

InvalidTime = <SemanticErrorCodes.InvalidTime: 'InvalidTime'>#

Timestamp is invalid (for example, it’s in the future)

KeyConflict = <SemanticErrorCodes.KeyConflict: 'KeyConflict'>#

Provided entity key conflicts with key already registered in the system.

MisconfiguredDataSource = <SemanticErrorCodes.MisconfiguredDataSource: 'MisconfiguredDataSource'>#

Enrichment rule is invalid for such data source.

NonLocalUser = <SemanticErrorCodes.NonLocalUser: 'NonLocalUser'>#

Impossible to change user attribute because this attribute is managed by external provider.

NotOwner = <SemanticErrorCodes.NotOwner: 'NotOwner'>#

Only owner can edit the resource.

ObservationNotFound = <SemanticErrorCodes.ObservationNotFound: 'ObservationNotFound'>#

Observation not found.

PasswordAuthDisabled = <SemanticErrorCodes.PasswordAuthDisabled: 'PasswordAuthDisabled'>#

Impossible to change the password because password auth for such user is disabled.

PermissionsExceeded = <SemanticErrorCodes.PermissionsExceeded: 'PermissionsExceeded'>#

Provided set of permissions exceeds user permissions.

ReportNotFound = <SemanticErrorCodes.ReportNotFound: 'ReportNotFound'>#

Report not found.

StoredQueryNotFound = <SemanticErrorCodes.StoredQueryNotFound: 'StoredQueryNotFound'>#

Stored query not found.

SynonymGroupConflict = <SemanticErrorCodes.SynonymGroupConflict: 'SynonymGroupConflict'>#

The specified item and synonym belong to different synonym groups.

ItemAlreadyInSynonymGroup = <SemanticErrorCodes.ItemAlreadyInSynonymGroup: 'ItemAlreadyInSynonymGroup'>#

The specified synonym is already in a synonym group.

TaskNotFound = <SemanticErrorCodes.TaskNotFound: 'TaskNotFound'>#

Enrichment task not found.

UnallowedObservationType = <SemanticErrorCodes.UnallowedObservationType: 'UnallowedObservationType'>#

Observation of such type cannot be attached to report.

UnsupportedProduct = <SemanticErrorCodes.UnsupportedProduct: 'UnsupportedProduct'>#

Unsupported product

UserDisabled = <SemanticErrorCodes.UserDisabled: 'UserDisabled'>#

User disabled.

UserNotFound = <SemanticErrorCodes.UserNotFound: 'UserNotFound'>#

User not found.

WrongEntityAttribute = <SemanticErrorCodes.WrongEntityAttribute: 'WrongEntityAttribute'>#

The attribute is not registered for provided entity.

InvalidStoredQuery = <SemanticErrorCodes.InvalidStoredQuery: 'InvalidStoredQuery'>#

Query is not compatible with replist.

StoredQueryIsLocked = <SemanticErrorCodes.StoredQueryIsLocked: 'StoredQueryIsLocked'>#

Stored query is in use. Probably used in replist.

CustomListNotFound = <SemanticErrorCodes.CustomListNotFound: 'CustomListNotFound'>#

Custom List Not Found

DictionaryMismatch = <SemanticErrorCodes.DictionaryMismatch: 'DictionaryMismatch'>#

Item related to dictionary that not related to custom list

EmptyLandscapeQuery = <SemanticErrorCodes.EmptyLandscapeQuery: 'EmptyLandscapeQuery'>#

Landscape does not contain any custom list

Converters#

A set of utility functions allowing to convert a string to a valid value of a chosen type.

cybsi.utils.converters.convert_entity_key(k_type, val)[source]#

Convert value to entity key type.

Parameters:

  • k_type (EntityKeyTypes) – Type of entity key.

  • val (Any) – Value to convert. Usually string, but value of desired type is accepted too.

Return type:

Any

Returns:

Valid value of entity key, return type depends on entity key type.

cybsi.utils.converters.convert_attribute_value(attribute_name, val)[source]#

Convert value to attribute value type.

Parameters:

  • attribute_name (AttributeNames) – attribute name.

  • val (Any) – value to convert. Usually string, but value of desired type is accepted too.

Return type:

Any

Returns:

Valid value of attribute, return type depends on attribute.

Entity views#

class cybsi.utils.views.BasicEntityView(data=None)[source]#

Builtin basic entity view. Includes only entity type and natual keys.

New in version 2.9.

property uuid#

Entity UUID.

property type#

Entity type.

property keys#

Entity natural keys.

class cybsi.utils.views.PTMSEntityView(data=None)[source]#

Entity view tailored for consumption by PT Multiscanner.

New in version 2.9.

property entity#

Basic entity view.

property malware_classes#

Malware classes. Expected, but not required for File entity type. None for other entity types.

property malware_family#

Malware family value having the highest confidence. Expected, but not required for File entity type. None for other entity types.

property related_malware_family#

Related malware family value having the highest confidence. Expected, but not required for DomainName, URL, IPAddress, EmailAddress entity types. None for other entity types.

class cybsi.utils.views.CybsiEntityView(data=None)[source]#

Entity view tailored for consumption by Cybsi-Cybsi relay.

New in version 2.10.

property entity#

Basic entity view.

property attribute_values#

Natural and associated attributes forecast of the entity.

Natural attributes only from the list:

For File entity type: Size, Names, MalwareNames.

class cybsi.utils.views.AttributeValuesView(data=None)[source]#

Attribute value view.

property name#

Attribute name.

property values#

Attribute values.

Method returns list of forecasted attribute values and their confidence.

class cybsi.utils.views.ValuesView(data=None)[source]#

Values view

property value#

Forecast attribute value.

Return type depends on attribute name.

Use convert_attribute_value()

to get attribute value form to create a general observation.

property confidence#

Attribute confidence.

API Changes#

Breaking API changes are documented here.

Version 2.13 - Removed image_id from cybsi.api.enrichment.tasks.ArtifactAnalysisParamsForm

Version 2.14 - Removed RawReports resource from cybsi.api.user.enums.ResourceName and RawReports:r privilege from cybsi.api.user.enums.RoleName

Licensing#

TBD