Workbench API Reference¶

class pyexclient.workbench.ActivityMetrics(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io activity_metric records

Resource type name is activity_metrics.

Example JSON record:

{           'activity': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'data': {},
    'ended_at': '2019-01-15T15:35:00-05:00',
    'referring_url': 'https://company.com/',
    'started_at': '2019-01-15T15:35:00-05:00',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'url': 'https://company.com/'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Referring url Allows: “”, null referring_url string Y N

Activity Allows: “”, null activity string Y N

Date/Time of when the activity concluded ended_at string Y N

Additional data about the activity Allows: null: no-sort data object Y N

Last Updated timestamp: readonly updated_at string Y N

Url Allows: “”, null url string Y N

Date/Time of when the activity started started_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigation Investigations N Y

Security devices security_device SecurityDevices N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alerts expel_alert ExpelAlerts N Y

class pyexclient.workbench.Actors(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io actor records

Resource type name is actors.

Example JSON record:

{'actor_type': 'system', 'created_at': '2019-01-15T15:35:00-05:00', 'display_name': 'string', 'is_expel': True, 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Actor type Restricted to: “system”, “user”, “organization”, “api” actor_type any Y N

Meta: readonly, no-sort is_expel boolean Y N

Display name Allows: “”, null display_name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

investigative actions analysis_assigned_investigative_actions InvestigativeActions N Y

Defines/retrieves expel.io actor records child_actors Actors N Y

User accounts user_account UserAccounts N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Remediation actions assigned_remediation_actions RemediationActions N Y

Organization to resilience actions assigned_organization_resilience_actions OrganizationResilienceActions N Y

User Notification Preferences notification_preferences NotificationPreferences N Y

Expel alerts assigned_expel_alerts ExpelAlerts N Y

Defines/retrieves expel.io actor records parent_actor Actors N Y

Organization to resilience actions assigned_organization_resilience_actions_list OrganizationResilienceActions N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Investigations assigned_investigations Investigations N Y

investigative actions assigned_investigative_actions InvestigativeActions N Y

class pyexclient.workbench.ApiKeys(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io api_key records. These can only be created by a user and require an OTP token.

Resource type name is api_keys.

Example JSON record:

{           'access_token': 'string',
    'active': True,
    'assignable': True,
    'created_at': '2019-01-15T15:35:00-05:00',
    'display_name': 'string',
    'name': 'string',
    'realm': 'public',
    'role': 'expel_admin',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Only upon initial api key creation (POST), contains the bearer api key token required for api access.: readonly, no-sort access_token string Y N

Created timestamp: readonly created_at string Y N

Active Allows: null active boolean Y N

Display name Allows: null display_name string Y N

Can Api key be assigned items (e.g. investigations, etc) assignable boolean Y N

Missing Description name string Y N

Realm in which the api key can be used. Restricted to: “public”, “internal” realm any Y N

Role Restricted to: “expel_admin”, “expel_analyst”, “organization_admin”, “organization_analyst”, “system”, “anonymous”, “restricted” role any Y N

Last Updated timestamp: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.AssemblerImages(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Assembler Images

Resource type name is assembler_images.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'hash_md5': 'string',
    'hash_sha1': 'string',
    'hash_sha256': 'string',
    'platform': 'VMWARE',
    'release_date': '2019-01-15T15:35:00-05:00',
    'size': 100,
    'updated_at': '2019-01-15T15:35:00-05:00',
    'version': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Assembler image sha256 hash Allows: null hash_sha256 string Y N

Assembler image release date Allows: null release_date string Y N

Platform Restricted to: “VMWARE”, “HYPERV”, “AZURE”, “AMAZON” platform any Y N

Assembler image size Allows: null size number Y N

Assembler image md5 hash Allows: null hash_md5 string Y N

Assembler image sh1 hash Allows: null hash_sha1 string Y N

Assembler image version Allows: “”, null version string Y N

Last Updated timestamp: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.Assemblers(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Assemblers

Resource type name is assemblers.

Example JSON record:

{           'connection_status': 'Never Connected',
    'connection_status_updated_at': '2019-01-15T15:35:00-05:00',
    'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'install_code': 'string',
    'lifecycle_status': 'New',
    'lifecycle_status_updated_at': '2019-01-15T15:35:00-05:00',
    'location': 'string',
    'name': 'string',
    'status': 'string',
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'vpn_ip': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Assembler lifecycle status update timestamp: readonly lifecycle_status_updated_at string Y N

Assembler install code Allows: null install_code string Y N

Assembler life cycle status Restricted to: “New”, “Authorized”, “Transitioning”, “Transitioned”, “Transition Failed”, “Configuring”, “Configuration Failed”, “Active”, “Inactive”, “Deleted” Allows: null lifecycle_status any Y N

Assembler connection status Restricted to: “Never Connected”, “Connection Lost”, “Connected to Provisioning”, “Connected to Service” Allows: null connection_status any Y N

Last Updated timestamp: readonly updated_at string Y N

Created timestamp: readonly created_at string Y N

Assembler last status update timestamp: readonly status_updated_at string Y N

Location of assembler Allows: “”, null location string Y N

Assembler connection status update timestamp: readonly connection_status_updated_at string Y N

Name of assembler Allows: “”, null name string Y N

Assembler status Allows: “”, null: readonly, no-sort status string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Assembler VPN ip address Allows: null vpn_ip string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Vendor alerts vendor_alerts VendorAlerts N Y

Security devices security_devices SecurityDevices N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.BaseResourceObject(cls, content=None, api_type=None, conn=None)[source]¶

Bases: object

count()[source]¶

Return the number of records in a JSON API response. You can get the count for entries returned by filtering, or you can request the count of the total number of resource instances. The total number of resource instances does not require paginating overall entries.

Returns:	The number of records in a JSON API response
Return type:	int

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> print("Investigation Count: ", xc.investigations.filter_by(customer_id='1').count())
>>> print("Investigation Count: ", xc.investigations.count())

create(**kwargs)[source]¶

Create a ResourceInstance object that represents some Json API resource.

Parameters:	kwargs (dict) – Attributes to set on the new JSON API resource.
Returns:	A ResourceInstance object that represents the JSON API resource type requested by the dev.
Return type:	ResourceInstance

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> i = xc.investigations.create(title='Peter: new investigation 1', relationship_customer=CUSTOMER_GUID, relationship_assigned_to_actor=PETER_S)
>>> i.save()

filter_by(**kwargs)[source]¶

Issue a JSON API call requesting a JSON API resource is filtered by some set of attributes, id, limit, etc.

Parameters:	kwargs (dict) – The base JSON API resource type
Returns:	A BaseResourceObject object
Return type:	BaseResourceObject

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> for inv in xc.investigations.filter_by(customer_id='1'):
>>>     print(inv.title)

get(**kwargs)[source]¶

Request a JSON api resource by id.

Parameters:	id (str) – The GUID of the resource
Returns:	A BaseResourceObject object
Return type:	BaseResourceObject

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> inv = xc.investigations.get(id=investigation_guid)
>>> print(inv.title)

one_or_none()[source]¶

Return one record from a JSON API response or None if there were no records.

Returns:	A BaseResourceObject object
Return type:	BaseResourceObject

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> inv = xc.investigations.filter_by(customer_id=CUSTOMER_GUID).one_or_none()
>>> print(inv.title)

search(*args, **kwargs)[source]¶

Search based on a set of criteria made up of operators and attributes.

Parameters:	args (tuple) – Operators of relationship\|limit\|include\|sort kwargs (dict) – Fields and values to search on
Returns:	A BaseResourceObject object
Return type:	`BaseResourceObject`

Examples:

>>> # field filter
>>> for inv in xc.investigations.search(customer_id=CUSTOMER_GUID):
>>>     print(inv.title)

>>> # operator field filter
>>> for inv in xc.investigations.search(customer_id=CUSTOMER_GUID, created_at=gt("2020-01-01")):
>>>     print(inv.title)

>>> # relationship field filter
>>> for inv in xc.investigations.search(customer_id=CUSTOMER_GUID, relationship("investigative_actions.created_at", gt("2020-01-01"))):
>>>     print(inv.title)

class pyexclient.workbench.CommentHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io comment_history records

Resource type name is comment_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Comment history action Restricted to: “CREATED”, “UPDATED”, “DELETED” Allows: null action any Y N

Comment history details Allows: null: no-sort value object Y N

Investigations investigation Investigations N Y

Defines/retrieves expel.io comment records comment Comments N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.Comments(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io comment records

Resource type name is comments.

Example JSON record:

{'comment': 'string', 'created_at': '2019-01-15T15:35:00-05:00', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Comment comment string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io comment_history records comment_histories CommentHistories N Y

class pyexclient.workbench.Configurations(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io configuration records

Resource type name is configurations.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'default_value': 'object',
    'description': 'string',
    'is_override': True,
    'key': 'string',
    'metadata': {},
    'title': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'validation': {},
    'value': 'object',
    'visibility': 'EXPEL',
    'write_permission_level': 'EXPEL'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Configuration metadata Allows: null: readonly, no-sort metadata object Y N

Description of configuration value Allows: “”, null: readonly description string Y N

Default configuration value Allows: null: readonly, no-sort default_value any Y N

Title of configuration value Allows: “”, null: readonly title string Y N

Configuration key: readonly key string Y N

Write permission required Restricted to: “EXPEL”, “ORGANIZATION”, “SYSTEM” write_permission_level any Y N

Last Updated timestamp: readonly updated_at string Y N

Created timestamp: readonly created_at string Y N

Configuration value validation Allows: null: readonly, no-sort validation object Y N

Configuration value Allows: null: no-sort value any Y N

Configuration value is an override: readonly is_override boolean Y N

Configuration visibility Restricted to: “EXPEL”, “ORGANIZATION”, “SYSTEM” visibility any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.ContextLabelActions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io context_label_action records

Resource type name is context_label_actions.

Example JSON record:

{'action_type': 'ALERT_ON', 'created_at': '2019-01-15T15:35:00-05:00', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

What action to take Restricted to: “ALERT_ON”, “ADD_TO”, “SUPPRESS” action_type any Y N

Last Updated timestamp: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io context_label records context_label ContextLabels N Y

Timeline Entries timeline_entries TimelineEntries N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.ContextLabelTags(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io context_label_tag records

Resource type name is context_label_tags.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'description': 'string', 'metadata': {}, 'tag': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Metadata about the context label tag Allows: null: no-sort metadata object Y N

Description Allows: null, “” description string Y N

Tag tag string Y N

Last Updated timestamp: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io context_label records context_labels ContextLabels N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Remediation action assets remediation_action_assets RemediationActionAssets N Y

class pyexclient.workbench.ContextLabels(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io context_label records

Resource type name is context_labels.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'definition': {},
    'description': 'string',
    'ends_at': '2019-01-15T15:35:00-05:00',
    'metadata': {},
    'starts_at': '2019-01-15T15:35:00-05:00',
    'title': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Metadata about the context label Allows: null: no-sort metadata object Y N

Description Allows: null, “” description string Y N

Title Allows: null, “” title string Y N

Date/Time of when the context_label should start being tested starts_at string Y N

Definition: no-sort definition object Y N

Last Updated timestamp: readonly updated_at string Y N

Date/Time of when the context_label should end being tested Allows: null ends_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io context_label_action records context_label_actions ContextLabelActions N Y

Timeline Entries timeline_entries TimelineEntries N Y

Defines/retrieves expel.io context_label_action records add_to_actions ContextLabelActions N Y

Defines/retrieves expel.io context_label_action records suppress_actions ContextLabelActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io context_label_action records alert_on_actions ContextLabelActions N Y

Defines/retrieves expel.io context_label_tag records context_label_tags ContextLabelTags N Y

Expel alerts expel_alerts ExpelAlerts N Y

Investigations investigations Investigations N Y

class pyexclient.workbench.EngagementManagers(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io engagement_manager records

Resource type name is engagement_managers.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'display_name': 'string', 'email': 'name@company.com', 'phone_number': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Phone number Allows: null phone_number string Y N

Display name Allows: “”, null display_name string Y N

Last Updated timestamp: readonly updated_at string Y N

Email Allows: null email string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organizations Organizations N Y

class pyexclient.workbench.ExpelAlertHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Expel alert histories

Resource type name is expel_alert_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Expel alert history action Restricted to: “CREATED”, “ASSIGNED”, “STATUS_CHANGED”, “INVESTIGATING”, “TUNING_CHANGED”, “DELETED” Allows: null action any Y N

Expel alert history details Allows: null: no-sort value object Y N

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alerts expel_alert ExpelAlerts N Y

class pyexclient.workbench.ExpelAlertThresholdHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io expel_alert_threshold_history records

Resource type name is expel_alert_threshold_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Expel alert threshold history action Restricted to: “CREATED”, “BREACHED”, “ACKNOWLEDGED”, “RECOVERED”, “DELETED” action any Y N

Expel alert threshold history details Allows: null: no-sort value object Y N

Defines/retrieves expel.io expel_alert_threshold records expel_alert_threshold ExpelAlertThresholds N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.ExpelAlertThresholds(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io expel_alert_threshold records

Resource type name is expel_alert_thresholds.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'name': 'string', 'threshold': 100, 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Threshold value threshold number Y N

Last Updated timestamp: readonly updated_at string Y N

Name name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io expel_alert_threshold_history records expel_alert_threshold_histories ExpelAlertThresholdHistories N Y

Defines/retrieves expel.io expel_alert_threshold records suppresses ExpelAlertThresholds N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io expel_alert_threshold records suppressed_by ExpelAlertThresholds N Y

class pyexclient.workbench.ExpelAlerts(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Expel alerts

Resource type name is expel_alerts.

Example JSON record:

{           'activity_first_at': '2019-01-15T15:35:00-05:00',
    'activity_last_at': '2019-01-15T15:35:00-05:00',
    'alert_type': 'ENDPOINT',
    'close_comment': 'string',
    'close_reason': 'FALSE_POSITIVE',
    'created_at': '2019-01-15T15:35:00-05:00',
    'cust_disp_alerts_in_critical_incidents_count': 100,
    'cust_disp_alerts_in_incidents_count': 100,
    'cust_disp_alerts_in_investigations_count': 100,
    'cust_disp_closed_alerts_count': 100,
    'cust_disp_disposed_alerts_count': 100,
    'disposition_alerts_in_critical_incidents_count': 100,
    'disposition_alerts_in_incidents_count': 100,
    'disposition_alerts_in_investigations_count': 100,
    'disposition_closed_alerts_count': 100,
    'disposition_disposed_alerts_count': 100,
    'expel_alert_time': '2019-01-15T15:35:00-05:00',
    'expel_alias_name': 'string',
    'expel_message': 'string',
    'expel_name': 'string',
    'expel_severity': 'CRITICAL',
    'expel_signature_id': 'string',
    'expel_version': 'string',
    'git_rule_url': 'https://company.com/',
    'ref_event_id': 'string',
    'status': 'string',
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'tuning_requested': True,
    'updated_at': '2019-01-15T15:35:00-05:00',
    'vendor_alert_count': 100}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Allows: null disposition_disposed_alerts_count number Y N

Expel alert close comment Allows: “”, null close_comment string Y N

tuning requested tuning_requested boolean Y N

Expel alert status Restricted to: “OPEN”, “IN_PROGRESS”, “CLOSED” Allows: null status string Y N

URL to rule definition for alert Allows: “”, null git_rule_url string Y N

Allows: null disposition_closed_alerts_count number Y N

Last Updated timestamp: readonly updated_at string Y N

Status Updated At Allows: null: readonly status_updated_at string Y N

Created timestamp: readonly created_at string Y N

Expel alert version Allows: “”, null expel_version string Y N

Expel alert close reason Restricted to: “FALSE_POSITIVE”, “TRUE_POSITIVE”, “OTHER”, “ATTACK_FAILED”, “POLICY_VIOLATION”, “ACTIVITY_BLOCKED”, “TESTING”, “PUP_PUA”, “BENIGN”, “IT_MISCONFIGURATION”, “INCONCLUSIVE” Allows: null close_reason any Y N

Allows: null: readonly, no-sort activity_last_at string Y N

Allows: null disposition_alerts_in_critical_incidents_count number Y N

Allows: null disposition_alerts_in_incidents_count number Y N

Allows: null cust_disp_alerts_in_critical_incidents_count number Y N

Expel alert signature Allows: “”, null expel_signature_id string Y N

Expel alert severity Restricted to: “CRITICAL”, “HIGH”, “MEDIUM”, “LOW”, “TESTING”, “TUNING” Allows: null expel_severity any Y N

Expel alert type Restricted to: “ENDPOINT”, “NETWORK”, “SIEM”, “RULE_ENGINE”, “EXTERNAL”, “OTHER”, “CLOUD”, “PHISHING_SUBMISSION”, “PHISHING_SUBMISSION_SIMILAR” Allows: null alert_type any Y N

Allows: null disposition_alerts_in_investigations_count number Y N

Allows: null cust_disp_alerts_in_investigations_count number Y N

Allows: null cust_disp_disposed_alerts_count number Y N

Referring event id Allows: null ref_event_id string Y N

Expel alert message Allows: “”, null expel_message string Y N

Expel alert name Allows: “”, null expel_name string Y N

Allows: null: readonly, no-sort vendor_alert_count number Y N

Allows: null cust_disp_closed_alerts_count number Y N

Expel Alert Time first seen time: immutable expel_alert_time string Y N

Allows: null cust_disp_alerts_in_incidents_count number Y N

Allows: null: readonly, no-sort activity_first_at string Y N

Expel alert alias Allows: “”, null expel_alias_name string Y N

IP addresses source_ip_addresses IpAddresses N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Phishing submissions phishing_submissions PhishingSubmissions N Y

investigative actions investigative_actions InvestigativeActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alert histories expel_alert_histories ExpelAlertHistories N Y

Vendor alerts vendor_alerts VendorAlerts N Y

IP addresses destination_ip_addresses IpAddresses N Y

Expel alerts similar_alerts ExpelAlerts N Y

Investigative action histories investigative_action_histories InvestigativeActionHistories N Y

Vendors vendor Vendors N Y

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations related_investigations_via_involved_host_ips Investigations N Y

Vendor alert evidences are extracted from a vendor alert’s evidence summary evidence VendorAlertEvidences N Y

Investigations investigation Investigations N Y

Investigations related_investigations Investigations N Y

Vendor alerts coincident_vendor_alerts VendorAlerts N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io actor records status_last_updated_by Actors N Y

Defines/retrieves expel.io context_label records context_labels ContextLabels N Y

class pyexclient.workbench.Features(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Product features

Resource type name is features.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'name': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Missing Description name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Products products Products N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organizations Organizations N Y

class pyexclient.workbench.Files(data, conn)[source]¶

Bases: pyexclient.workbench.FilesResourceInstance

File

Resource type name is files.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'expel_file_type': 'string',
    'file_meta': {'investigative_action': {'file_type': 'string'}},
    'filename': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Metadata about the file Allows: null: no-sort file_meta object Y N

Last Updated timestamp: readonly updated_at string Y N

Filename filename string Y N

Expel file type Allows: null, “” expel_file_type string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigations Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

investigative actions investigative_actions InvestigativeActions N Y

Phishing submission attachments phishing_submission_attachment PhishingSubmissionAttachments N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Phishing submissions phishing_submission PhishingSubmissions N Y

class pyexclient.workbench.FilesResourceInstance(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

download(fd, fmt='json')[source]¶

Download data from an investigative action. This can only be called on InvestigativeAction or Files objects.

Parameters:	fd (File bytes object) – Buffer to write response too. fmt (str) – The format to request the data be returned in.

Examples:

>>> import json
>>> import pprint
>>> import tempfile
>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> with xc.investigative_actions.get(id=inv_act_id) as ia:
>>>     fd = tempfile.NamedTemporaryFile(delete=False)
>>>     ia.download(fd)
>>>     with open(fd.name, 'r') as fd:
>>>     pprint.pprint(json.loads(fd.read()))

class pyexclient.workbench.Findings(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io finding records

Resource type name is findings.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'rank': 100, 'title': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Title Allows: “”, null title string Y N

Seed Rank rank number Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.Integrations(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io integration records

Resource type name is integrations.

Example JSON record:

{           'account': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'integration_meta': {},
    'integration_type': 'pagerduty',
    'last_tested_at': '2019-01-15T15:35:00-05:00',
    'service_name': 'string',
    'status': 'UNTESTED',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Needed information for integration type Allows: null: no-sort integration_meta object Y N

Integration status Restricted to: “UNTESTED”, “TEST_SUCCESS”, “TEST_FAIL”: readonly status any Y N

Type of integration Restricted to: “pagerduty”, “slack”, “ticketing”, “service_now”, “teams”: immutable integration_type any Y N

Service account identifier account string Y N

Service display name service_name string Y N

Last Updated timestamp: readonly updated_at string Y N

Last Successful Test Allows: null: readonly last_tested_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Organization secrets. Note - these requests must be in the format of /secrets/security_device-<guid> secret Secrets N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.InvestigationFindingHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io investigation_finding_history records

Resource type name is investigation_finding_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'updated_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Investigation finding history action Restricted to: “CREATED”, “CHANGED”, “DELETED” Allows: null action any Y N

Last Updated timestamp: readonly updated_at string Y N

Investigation finding history details Allows: null: no-sort value object Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigation Investigations N Y

Investigation findings investigation_finding InvestigationFindings N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.InvestigationFindings(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Investigation findings

Resource type name is investigation_findings.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'deleted_at': '2019-01-15T15:35:00-05:00', 'finding': 'string', 'rank': 100, 'title': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Finding Allows: “”, null finding string Y N

Last Updated timestamp: readonly updated_at string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Visualization Rank rank number Y N

Title Allows: “”, null title string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io investigation_finding_history records investigation_finding_histories InvestigationFindingHistories N Y

class pyexclient.workbench.InvestigationHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Investigation histories

Resource type name is investigation_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'is_incident': True, 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Investigation history action Restricted to: “CREATED”, “ASSIGNED”, “CHANGED”, “CLOSED”, “SUMMARY”, “REOPENED”, “PUBLISHED” Allows: null action any Y N

Is Incidence is_incident boolean Y N

Investigation history details Allows: null: no-sort value object Y N

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

class pyexclient.workbench.InvestigationResilienceActionHints(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io investigation_organization_resilience_action_hint records

Resource type name is investigation_resilience_action_hints.

Example JSON record:

{}

Below are valid filter by parameters:

class pyexclient.workbench.InvestigationResilienceActions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Investigation to resilience actions

Resource type name is investigation_resilience_actions.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Organization to resilience actions organization_resilience_action OrganizationResilienceActions N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.Investigations(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Investigations

Resource type name is investigations.

Example JSON record:

{           'analyst_severity': 'CRITICAL',
    'attack_lifecycle': 'INITIAL_RECON',
    'attack_timing': 'HISTORICAL',
    'attack_vector': 'DRIVE_BY',
    'close_comment': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'critical_comment': 'string',
    'decision': 'FALSE_POSITIVE',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'detection_type': 'UNKNOWN',
    'has_hunting_status': True,
    'is_downgrade': True,
    'is_incident': True,
    'is_incident_status_updated_at': '2019-01-15T15:35:00-05:00',
    'is_surge': True,
    'last_published_at': '2019-01-15T15:35:00-05:00',
    'last_published_value': 'string',
    'lead_description': 'string',
    'open_comment': 'string',
    'properties': 'object',
    'review_requested_at': '2019-01-15T15:35:00-05:00',
    'short_link': 'string',
    'source_reason': 'HUNTING',
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'threat_type': 'TARGETED',
    'title': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Threat Type Restricted to: “TARGETED”, “TARGETED_APT”, “TARGETED_RANSOMWARE”, “BUSINESS_EMAIL_COMPROMISE”, “NON_TARGETED”, “NON_TARGETED_MALWARE”, “POLICY_VIOLATION”, “UNKNOWN” Allows: null threat_type any Y N

Experimental properties Allows: null: no-sort properties any Y N

Last Published At Allows: null last_published_at string Y N

Close Comment Allows: “”, null close_comment string Y N

Last Updated timestamp: readonly updated_at string Y N

Lead Description Allows: null lead_description string Y N

Is surge is_surge boolean Y N

Status Updated At Allows: null: readonly status_updated_at string Y N

Created timestamp: readonly created_at string Y N

Analyst Severity Restricted to: “CRITICAL”, “HIGH”, “MEDIUM”, “LOW”, “INFO” Allows: null analyst_severity any Y N

Reason the investigation/incident was opened Allows: “”, null open_comment string Y N

Decision Restricted to: “FALSE_POSITIVE”, “TRUE_POSITIVE”, “CLOSED”, “OTHER”, “ATTACK_FAILED”, “POLICY_VIOLATION”, “ACTIVITY_BLOCKED”, “TESTING”, “PUP_PUA”, “BENIGN”, “IT_MISCONFIGURATION”, “INCONCLUSIVE” Allows: null decision any Y N

Investigation short link: readonly short_link string Y N

Incident Status timestamp Allows: null: readonly is_incident_status_updated_at string Y N

Title Allows: “”, null title string Y N

Attack Vector Restricted to: “DRIVE_BY”, “PHISHING”, “PHISHING_LINK”, “PHISHING_ATTACHMENT”, “REV_MEDIA”, “SPEAR_PHISHING”, “SPEAR_PHISHING_LINK”, “SPEAR_PHISHING_ATTACHMENT”, “STRAG_WEB_COMP”, “SERVER_SIDE_VULN”, “CRED_THEFT”, “MISCONFIG”, “UNKNOWN” Allows: null attack_vector any Y N

Meta: readonly, no-sort has_hunting_status boolean Y N

Deleted At timestamp Allows: null deleted_at string Y N

Attack Timing Restricted to: “HISTORICAL”, “PRESENT” Allows: null attack_timing any Y N

Attack Lifecycle Restricted to: “INITIAL_RECON”, “DELIVERY”, “EXPLOITATION”, “INSTALLATION”, “COMMAND_CONTROL”, “LATERAL_MOVEMENT”, “ACTION_TARGETS”, “UNKNOWN” Allows: null attack_lifecycle any Y N

Review Requested At Allows: null review_requested_at string Y N

Is downgrade is_downgrade boolean Y N

Detection Type Restricted to: “UNKNOWN”, “ENDPOINT”, “SIEM”, “NETWORK”, “EXPEL”, “HUNTING”, “CLOUD” Allows: null detection_type any Y N

Last Published Value Allows: “”, null last_published_value string Y N

Is Incident is_incident boolean Y N

Critical Comment Allows: “”, null critical_comment string Y N

Source Reason Restricted to: “HUNTING”, “ORGANIZATION_REPORTED”, “DISCOVERY”, “PHISHING” Allows: null source_reason any Y N

IP addresses source_ip_addresses IpAddresses N Y

Investigation histories investigation_histories InvestigationHistories N Y

Investigation to resilience actions investigation_resilience_actions InvestigationResilienceActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alert histories expel_alert_histories ExpelAlertHistories N Y

IP addresses destination_ip_addresses IpAddresses N Y

Defines/retrieves expel.io actor records review_requested_by Actors N Y

Investigations related_investigations_via_involved_host_ips Investigations N Y

Vendor alert evidences are extracted from a vendor alert’s evidence summary evidence VendorAlertEvidences N Y

Remediation actions remediation_actions RemediationActions N Y

Expel alerts lead_expel_alert ExpelAlerts N Y

investigative actions investigative_actions InvestigativeActions N Y

Defines/retrieves expel.io investigation_finding_history records investigation_finding_histories InvestigationFindingHistories N Y

Remediation action histories remediation_action_histories RemediationActionHistories N Y

Organization to resilience actions organization_resilience_actions OrganizationResilienceActions N Y

Defines/retrieves expel.io actor records last_published_by Actors N Y

Defines/retrieves expel.io finding records findings InvestigationFindings N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Defines/retrieves expel.io context_label_action records context_label_actions ContextLabelActions N Y

Defines/retrieves expel.io actor records status_last_updated_by Actors N Y

IP addresses ip_addresses IpAddresses N Y

Investigative action histories investigative_action_histories InvestigativeActionHistories N Y

Expel alerts expel_alerts ExpelAlerts N Y

Defines/retrieves expel.io comment_history records comment_histories CommentHistories N Y

Defines/retrieves expel.io comment records comments Comments N Y

File files Files N Y

Timeline Entries timeline_entries TimelineEntries N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Organization to resilience actions organization_resilience_action_hints OrganizationResilienceActions N Y

Remediation action asset histories remediation_action_asset_histories RemediationActionAssetHistories N Y

Defines/retrieves expel.io context_label records context_labels ContextLabels N Y

Defines/retrieves expel.io actor records updated_by Actors N Y

class pyexclient.workbench.InvestigativeActionHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Investigative action histories

Resource type name is investigative_action_histories.

Example JSON record:

{'action': 'CREATED', 'created_at': '2019-01-15T15:35:00-05:00', 'deleted_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Investigative action history action Restricted to: “CREATED”, “ASSIGNED”, “CLOSED” Allows: null action any Y N

Deleted At timestamp Allows: null deleted_at string Y N

Investigative action history details Allows: null: no-sort value object Y N

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

investigative actions investigative_action InvestigativeActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alerts expel_alert ExpelAlerts N Y

class pyexclient.workbench.InvestigativeActions(data, conn)[source]¶

Bases: pyexclient.workbench.InvestigativeActionsResourceInstance

investigative actions

Resource type name is investigative_actions.

Example JSON record:

{           'action_type': 'TASKABILITY',
    'activity_authorized': True,
    'activity_verified_by': 'string',
    'capability_name': 'string',
    'close_reason': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'downgrade_reason': 'FALSE_POSITIVE',
    'files_count': 100,
    'input_args': {},
    'instructions': 'string',
    'reason': 'string',
    'result_byte_size': 100,
    'result_task_id': 'object',
    'results': 'string',
    'robot_action': True,
    'status': 'RUNNING',
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'taskability_action_id': 'string',
    'tasking_error': {},
    'title': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'workflow_job_id': 'string',
    'workflow_name': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Capability name Allows: “”, null capability_name string Y N

Verify Investigative action verified by Allows: null activity_verified_by string Y N

Task input arguments Allows: null: no-sort input_args object Y N

Verify Investigative action is authorized Allows: null activity_authorized boolean Y N

Result byte size: readonly result_byte_size number Y N

Downgrade reason Restricted to: “FALSE_POSITIVE”, “ATTACK_FAILED”, “POLICY_VIOLATION”, “ACTIVITY_BLOCKED”, “PUP_PUA”, “BENIGN”, “IT_MISCONFIGURATION”, “OTHER” Allows: null downgrade_reason any Y N

Created timestamp: readonly created_at string Y N

Result task id Allows: null: readonly result_task_id any Y N

Close Reason Allows: null close_reason string Y N

Investigative action created by robot action: readonly robot_action boolean Y N

Taskability action id Allows: “”, null taskability_action_id string Y N

Workflow name Allows: “”, null workflow_name string Y N

Status Restricted to: “RUNNING”, “FAILED”, “READY_FOR_ANALYSIS”, “CLOSED”, “COMPLETED” status any Y N

Investigative Action Type Restricted to: “TASKABILITY”, “HUNTING”, “MANUAL”, “RESEARCH”, “PIVOT”, “QUICK_UPLOAD”, “VERIFY”, “DOWNGRADE”, “WORKFLOW”, “NOTIFY” action_type any Y N

Deleted At timestamp Allows: null deleted_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Title title string Y N

Instructions Allows: “”, null instructions string Y N

Taskabilities error Allows: “”, null: no-sort tasking_error object Y N

Status Updated At Allows: null: readonly status_updated_at string Y N

Reason reason string Y N

Workflow job id Allows: “”, null workflow_job_id string Y N

Downgrade reason: readonly files_count number Y N

Results/Analysis Allows: “”, null results string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

investigative actions depends_on_investigative_action InvestigativeActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

investigative actions dependent_investigative_actions InvestigativeActions N Y

Security devices security_device SecurityDevices N Y

Expel alerts expel_alert ExpelAlerts N Y

Investigative action histories investigative_action_histories InvestigativeActionHistories N Y

File files Files N Y

Defines/retrieves expel.io actor records analysis_assigned_to_actor Actors N Y

class pyexclient.workbench.InvestigativeActionsResourceInstance(data, conn)[source]¶

Bases: pyexclient.workbench.FilesResourceInstance

upload(filename, fbytes, expel_file_type=None, file_meta=None)[source]¶

Upload data associated with an investigative action. Can only be called on InvestigativeAction objects.

Parameters:	filename (str) – Filename, this shows up in Workbench. fbytes (bytes) – A bytes string representing raw bytes to upload

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> with xc.investigative_actions.get(id=inv_act_id) as ia:
>>>     ia.upload('test.txt', b'hello world')

class pyexclient.workbench.IpAddresses(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

IP addresses

Resource type name is ip_addresses.

Example JSON record:

{'address': 'string', 'created_at': '2019-01-15T15:35:00-05:00', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

IP Address: readonly address string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Investigations investigations Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Expel alerts source_expel_alerts ExpelAlerts N Y

Vendor alerts vendor_alerts VendorAlerts N Y

Investigations destination_investigations Investigations N Y

Expel alerts destination_expel_alerts ExpelAlerts N Y

Investigations source_investigations Investigations N Y

class pyexclient.workbench.JsonApiRelationship[source]¶

Bases: object

The object acts a helper to handle JSON API relationships. The object is just a dummy that allows for setting / getting attributes that are extracted from the relationship part of the JSON API response. Additionally, the object will allow for conversion to a JSON API compliant relationship block to include in a request.

to_relationship()[source]¶

Generate a JSON API compliant relationship section.

Returns:	A dict that is JSON API compliant relationship section.
Return type:	dict

class pyexclient.workbench.NistCategories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io nist_category records

Resource type name is nist_categories.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'function_type': 'IDENTIFY', 'identifier': 'string', 'name': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Nist category abbreviated identifier identifier string Y N

Last Updated timestamp: readonly updated_at string Y N

Nist category name name string Y N

Actor type Restricted to: “IDENTIFY”, “PROTECT”, “DETECT”, “RECOVER”, “RESPOND” function_type any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io nist_subcategory records nist_subcategories NistSubcategories N Y

class pyexclient.workbench.NistSubcategories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io nist_subcategory records

Resource type name is nist_subcategories.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'identifier': 'string', 'name': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Nist subcategory abbreviated identifier identifier string Y N

Last Updated timestamp: readonly updated_at string Y N

Nist subcategory title Allows: “”, null name string Y N

Defines/retrieves expel.io nist_category records nist_category NistCategories N Y

Latest NIST subcategory scores nist_subcategory_scores NistSubcategoryScores N Y

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.NistSubcategoryScoreHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

NIST Subcategory Score History

Resource type name is nist_subcategory_score_histories.

Example JSON record:

{'action': 'SCORE_UPDATED', 'actual_score': 100, 'assessment_date': '2019-01-15T15:35:00-05:00', 'created_at': '2019-01-15T15:35:00-05:00', 'target_score': 100}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

NIST subcategory score history action Restricted to: “SCORE_UPDATED”, “COMMENT_UPDATED”, “PRIORITY_UPDATED”, “IMPORT” action any Y N

Organization target score for this nist subcategory target_score number Y N

Recorded date of the score assessment (Note: Dates with times will be truncated to the day. Warning: Dates times and timezones will be converted to UTC before they are truncated. Providing non-UTC timezones is not recommeneded.): immutable assessment_date string Y N

Organization actual score for this nist subcategory actual_score number Y N

Latest NIST subcategory scores nist_subcategory_score NistSubcategoryScores N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.NistSubcategoryScores(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Latest NIST subcategory scores

Resource type name is nist_subcategory_scores.

Example JSON record:

{           'actual_score': 100,
    'assessment_date': '2019-01-15T15:35:00-05:00',
    'category_identifier': 'string',
    'category_name': 'string',
    'comment': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'function_type': 'string',
    'is_priority': True,
    'subcategory_identifier': 'string',
    'subcategory_name': 'string',
    'target_score': 100,
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Allows: “”, null: readonly, csv_ignore, no-sort category_name string Y N

Organization actual score for this nist subcategory Allows: null actual_score number Y N

Recorded date of the score assessment (Note: Dates with times will be truncated to the day. Warning: Dates times and timezones will be converted to UTC before they are truncated. Providing non-UTC timezones is not recommeneded.) Allows: null: immutable assessment_date string Y N

Last Updated timestamp: readonly updated_at string Y N

Allows: “”, null: immutable, no-sort subcategory_identifier string Y N

Organization target score for this nist subcategory Allows: null target_score number Y N

Allows: “”, null: readonly, csv_ignore, no-sort function_type string Y N

Created timestamp: readonly created_at string Y N

Organization nist subcategory is a priority is_priority boolean Y N

Allows: “”, null: readonly, csv_ignore, no-sort subcategory_name string Y N

Allows: “”, null: readonly, csv_ignore, no-sort category_identifier string Y N

Organization comment for this nist subcategory Allows: “”, null comment string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

NIST Subcategory Score History nist_subcategory_score_histories NistSubcategoryScoreHistories N Y

Defines/retrieves expel.io nist_subcategory records nist_subcategory NistSubcategories N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.NotificationPreferences(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

User Notification Preferences

Resource type name is notification_preferences.

Example JSON record:

{'preferences': []}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Missing Description preferences array Y N

Defines/retrieves expel.io actor records actor Actors N Y

class pyexclient.workbench.OrganizationResilienceActionGroups(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io organization_resilience_action_group records

Resource type name is organization_resilience_action_groups.

Example JSON record:

{'category': 'DISRUPT_ATTACKERS', 'created_at': '2019-01-15T15:35:00-05:00', 'title': 'string', 'updated_at': '2019-01-15T15:35:00-05:00', 'visible': True}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Visible visible boolean Y N

Last Updated timestamp: readonly updated_at string Y N

Organization Resilience Group Category Restricted to: “DISRUPT_ATTACKERS”, “ENABLE_DEFENDERS” category any Y N

Group title title string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Organization to resilience actions organization_resilience_action_group_actions OrganizationResilienceActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io resilience_action_group records source_resilience_action_group ResilienceActionGroups N Y

class pyexclient.workbench.OrganizationResilienceActions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Organization to resilience actions

Resource type name is organization_resilience_actions.

Example JSON record:

{           'category': 'DISRUPT_ATTACKERS',
    'comment': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'details': 'string',
    'impact': 'LOW',
    'status': 'TOP_PRIORITY',
    'title': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'visible': True}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Details details string Y N

Title title string Y N

Visible visible boolean Y N

Status Restricted to: “TOP_PRIORITY”, “IN_PROGRESS”, “WONT_DO”, “COMPLETED” status any Y N

Category Restricted to: “DISRUPT_ATTACKERS”, “ENABLE_DEFENDERS” Allows: null category any Y N

Last Updated timestamp: readonly updated_at string Y N

Comment Allows: “”, null comment string Y N

Impact Restricted to: “LOW”, “MEDIUM”, “HIGH” impact any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigation to resilience actions investigation_resilience_actions InvestigationResilienceActions N Y

Resilience actions source_resilience_action ResilienceActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io organization_resilience_action_group records organization_resilience_action_group OrganizationResilienceActionGroups N Y

Investigations investigations Investigations N Y

Investigations investigation_hints Investigations N Y

class pyexclient.workbench.OrganizationStatuses(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Organization status

Resource type name is organization_statuses.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'enabled_login_types': [], 'restrictions': [], 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Meta: readonly created_at string Y N

Missing Description restrictions array Y N

Meta: readonly updated_at string Y N

Missing Description enabled_login_types array Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.Organizations(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io organization records

Resource type name is organizations.

Example JSON record:

{           'address_1': 'string',
    'address_2': 'string',
    'city': 'string',
    'country_code': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'hq_city': 'string',
    'hq_utc_offset': 'string',
    'industry': 'string',
    'is_surge': True,
    'name': 'string',
    'nodes_count': 100,
    'o365_tos_id': 'string',
    'postal_code': 'string',
    'region': 'string',
    'service_renewal_at': '2019-01-15T15:35:00-05:00',
    'service_start_at': '2019-01-15T15:35:00-05:00',
    'short_name': 'EXP',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'users_count': 100}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

City Allows: “”, null city string Y N

State/Province/Region Allows: “”, null region string Y N

Address 2 Allows: “”, null address_2 string Y N

The city where the organization’s headquarters is located Allows: “”, null hq_city string Y N

Last Updated timestamp: readonly updated_at string Y N

Country Code Allows: null country_code string Y N

Is surge is_surge boolean Y N

Number of users covered for this organization Allows: null users_count number Y N

Created timestamp: readonly created_at string Y N

Organization service renewal date Allows: null service_renewal_at string Y N

The organization’s primary industry Allows: “”, null industry string Y N

The organization’s operating name name string Y N

Address 1 Allows: “”, null address_1 string Y N

Postal Code Allows: null postal_code string Y N

Organization short name Allows: null short_name string Y N

Number of nodes covered for this organization Allows: null nodes_count number Y N

Organization service start date Allows: null service_start_at string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Allows: “”, null hq_utc_offset string Y N

o365 Terms of Service identifier (e.g. hubspot id, etc.) Allows: null o365_tos_id string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Latest NIST subcategory scores nist_subcategory_scores NistSubcategoryScores N Y

Defines/retrieves expel.io actor records actor Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

User Notification Preferences notification_preferences NotificationPreferences N Y

Remediation actions assigned_remediation_actions RemediationActions N Y

Defines/retrieves expel.io api_key records. These can only be created by a user and require an OTP token. api_keys ApiKeys N Y

Defines/retrieves expel.io configuration records configurations Configurations N Y

Organization to resilience actions assigned_organization_resilience_actions OrganizationResilienceActions N Y

Investigations investigations Investigations N Y

Defines/retrieves expel.io engagement_manager records engagement_manager EngagementManagers N Y

Vendor alerts vendor_alerts VendorAlerts N Y

Organization to resilience actions assigned_organization_resilience_actions_list OrganizationResilienceActions N Y

Defines/retrieves expel.io integration records integrations Integrations N Y

Defines/retrieves expel.io organization_resilience_action_group records organization_resilience_action_groups OrganizationResilienceActionGroups N Y

investigative actions assigned_investigative_actions InvestigativeActions N Y

File files Files N Y

User accounts user_accounts UserAccounts N Y

Investigation histories investigation_histories InvestigationHistories N Y

Expel alert histories expel_alert_histories ExpelAlertHistories N Y

investigative actions analysis_assigned_investigative_actions InvestigativeActions N Y

Product features features Features N Y

Organization status organization_status OrganizationStatuses N Y

User accounts user_accounts_with_roles UserAccounts N Y

SAML Identity Providers saml_identity_provider SamlIdentityProviders N Y

Assemblers assemblers Assemblers N Y

Organization to resilience actions organization_resilience_actions OrganizationResilienceActions N Y

Expel alerts expel_alerts ExpelAlerts N Y

Products products Products N Y

Defines/retrieves expel.io context_label records context_labels ContextLabels N Y

Investigations assigned_investigations Investigations N Y

Security devices security_devices SecurityDevices N Y

Expel alerts assigned_expel_alerts ExpelAlerts N Y

Defines/retrieves expel.io actor records assignables Actors N Y

Defines/retrieves expel.io context_label_tag records context_label_tags ContextLabelTags N Y

Defines/retrieves expel.io comment records comments Comments N Y

Defines/retrieves expel.io user_account_role records organization_user_account_roles UserAccountRoles N Y

class pyexclient.workbench.PhishingSubmissionAttachments(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Phishing submission attachments

Resource type name is phishing_submission_attachments.

Example JSON record:

{'file_md5': 'string', 'file_mime': 'string', 'file_name': 'string', 'file_sha256': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

File md5 hash file_md5 string Y N

File mime type file_mime string Y N

File name file_name string Y N

File sha256 hash file_sha256 string Y N

File attachment_file Files N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Phishing submissions phishing_submission PhishingSubmissions N Y

class pyexclient.workbench.PhishingSubmissionDomains(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Phishing submission domains

Resource type name is phishing_submission_domains.

Example JSON record:

{'value': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Value value string Y N

Defines/retrieves expel.io actor records created_by Actors N Y

Phishing submissions phishing_submission PhishingSubmissions N Y

class pyexclient.workbench.PhishingSubmissionHeaders(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Phishing submission headers

Resource type name is phishing_submission_headers.

Example JSON record:

{'name': 'string', 'value': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Value value string Y N

Name name string Y N

Defines/retrieves expel.io actor records created_by Actors N Y

Phishing submissions phishing_submission PhishingSubmissions N Y

class pyexclient.workbench.PhishingSubmissionUrls(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Phishing submission URLs

Resource type name is phishing_submission_urls.

Example JSON record:

{'url_type': 'https://company.com/', 'value': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

URL type url_type string Y N

Value value string Y N

Defines/retrieves expel.io actor records created_by Actors N Y

Phishing submissions phishing_submission PhishingSubmissions N Y

class pyexclient.workbench.PhishingSubmissions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Phishing submissions

Resource type name is phishing_submissions.

Example JSON record:

{           'automated_action_type': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'email_type': 'name@company.com',
    'msg_id': 'string',
    'received_at': '2019-01-15T15:35:00-05:00',
    'reported_at': '2019-01-15T15:35:00-05:00',
    'return_path': 'string',
    'sender': 'string',
    'sender_domain': 'string',
    'subject': 'string',
    'submitted_by': 'string',
    'triaged_at': '2019-01-15T15:35:00-05:00',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Email type Allows: “”, null email_type string Y N

Sender domain sender_domain string Y N

Message ID msg_id string Y N

Reported at reported_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Subject Allows: “” subject string Y N

Automated action type Allows: “”, null automated_action_type string Y N

Created timestamp: readonly created_at string Y N

Received at received_at string Y N

Submitted by submitted_by string Y N

Sender sender string Y N

Return path Allows: “” return_path string Y N

Triaged at Allows: null triaged_at string Y N

Phishing submission domains phishing_submission_domains PhishingSubmissionDomains N Y

Phishing submission attachments phishing_submission_attachments PhishingSubmissionAttachments N Y

File analysis_email_file Files N Y

File raw_body_file Files N Y

Defines/retrieves expel.io actor records created_by Actors N Y

File initial_email_file Files N Y

Phishing submission headers phishing_submission_headers PhishingSubmissionHeaders N Y

Defines/retrieves expel.io actor records updated_by Actors N Y

Phishing submission URLs phishing_submission_urls PhishingSubmissionUrls N Y

Expel alerts expel_alert ExpelAlerts N Y

class pyexclient.workbench.Products(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Products

Resource type name is products.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'description': 'string', 'name': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Missing Description description string Y N

Last Updated timestamp: readonly updated_at string Y N

Missing Description name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Product features features Features N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organizations Organizations N Y

class pyexclient.workbench.RemediationActionAssetHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Remediation action asset histories

Resource type name is remediation_action_asset_histories.

Example JSON record:

{'action': 'CREATED', 'action_type': 'BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS', 'created_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Remediation action asset history action Restricted to: “CREATED”, “COMPLETED”, “REOPENED” Allows: null action any Y N

Action type of associated parent remediation action Restricted to: “BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS”, “BLOCK_KNOWN_BAD_HASHES”, “CONTAIN_HOSTS”, “CONTAIN_INFECTED_REMOVABLE_MEDIA”, “DELETE_MALICIOUS_FILES”, “DISABLE_AND_MODIFY_AWS_ACCESS_KEYS”, “MITIGATE_VULNERABILITY”, “OTHER_REMEDIATION”, “REMOVE_AND_BLOCK_EMAIL_FORWARDING_ADDRESS”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_OTHER”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_AWS”, “REMOVE_INBOX_RULES_FOR_KNOWN_COMPROMISED_ACCOUNTS”, “RESET_CREDENTIALS_OTHER”, “RESET_CREDENTIALS_AWS”, “RESET_CREDENTIALS_O365” Allows: null action_type any Y N

Remediation action asset history details Allows: null: no-sort value object Y N

Remediation action assets remediation_action_asset RemediationActionAssets N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.RemediationActionAssets(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Remediation action assets

Resource type name is remediation_action_assets.

Example JSON record:

{'asset_type': 'ACCOUNT', 'category': 'AFFECTED_ACCOUNT', 'created_at': '2019-01-15T15:35:00-05:00', 'status': 'OPEN', 'updated_at': '2019-01-15T15:35:00-05:00', 'value': 'object'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Remediation asset type Restricted to: “ACCOUNT”, “ACCESS_KEY”, “DESCRIPTION”, “DEVICE”, “DOMAIN_NAME”, “EMAIL”, “FILE”, “HASH”, “HOST”, “INBOX_RULE_NAME”, “IP_ADDRESS” asset_type any Y N

Created timestamp: readonly created_at string Y N

Asset status Restricted to: “OPEN”, “COMPLETED” status any Y N

Remediation asset category Restricted to: “AFFECTED_ACCOUNT”, “COMPROMISED_ACCOUNT”, “FORWARDING_ADDRESS” Allows: null category any Y N

Last Updated timestamp: readonly updated_at string Y N

Remediation asset value: no-sort value alternatives Y N

Remediation actions remediation_action RemediationActions N Y

Remediation action asset histories remediation_action_asset_histories RemediationActionAssetHistories N Y

Defines/retrieves expel.io context_label_tag records context_label_tags ContextLabelTags N Y

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.RemediationActionHistories(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Remediation action histories

Resource type name is remediation_action_histories.

Example JSON record:

{'action': 'CREATED', 'action_type': 'BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS', 'created_at': '2019-01-15T15:35:00-05:00', 'value': {}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Remediation action history action Restricted to: “CREATED”, “ASSIGNED”, “COMPLETED”, “CLOSED” Allows: null action any Y N

Action type of source parent remediation action Restricted to: “BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS”, “BLOCK_KNOWN_BAD_HASHES”, “CONTAIN_HOSTS”, “CONTAIN_INFECTED_REMOVABLE_MEDIA”, “DELETE_MALICIOUS_FILES”, “DISABLE_AND_MODIFY_AWS_ACCESS_KEYS”, “MITIGATE_VULNERABILITY”, “OTHER_REMEDIATION”, “REMOVE_AND_BLOCK_EMAIL_FORWARDING_ADDRESS”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_OTHER”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_AWS”, “REMOVE_INBOX_RULES_FOR_KNOWN_COMPROMISED_ACCOUNTS”, “RESET_CREDENTIALS_OTHER”, “RESET_CREDENTIALS_AWS”, “RESET_CREDENTIALS_O365” Allows: null action_type any Y N

Remediation action history details Allows: null: no-sort value object Y N

Remediation actions remediation_action RemediationActions N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.RemediationActions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Remediation actions

Resource type name is remediation_actions.

Example JSON record:

{           'action': 'string',
    'action_type': 'BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS',
    'close_reason': 'string',
    'comment': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'detail_markdown': 'string',
    'status': 'IN_PROGRESS',
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'template_name': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'values': {},
    'version': 'V1'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Remediation Action Values: no-sort values object Y N

Action Allows: “”, null action string Y N

Remediation Action Template Name Allows: “”, null template_name string Y N

Version Restricted to: “V1”, “V2”, “V3” version any Y N

Status Restricted to: “IN_PROGRESS”, “COMPLETED”, “CLOSED” status any Y N

Last Updated timestamp: readonly updated_at string Y N

Created timestamp: readonly created_at string Y N

Status Updated At Allows: null: readonly status_updated_at string Y N

Close Reason Allows: null close_reason string Y N

Remediation action details markdown Allows: “”, null: readonly detail_markdown string Y N

Action type Restricted to: “BLOCK_COMMAND_AND_CONTROL_COMMUNICATIONS”, “BLOCK_KNOWN_BAD_HASHES”, “CONTAIN_HOSTS”, “CONTAIN_INFECTED_REMOVABLE_MEDIA”, “DELETE_MALICIOUS_FILES”, “DISABLE_AND_MODIFY_AWS_ACCESS_KEYS”, “MITIGATE_VULNERABILITY”, “OTHER_REMEDIATION”, “REMOVE_AND_BLOCK_EMAIL_FORWARDING_ADDRESS”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_OTHER”, “REMOVE_COMPROMISED_SYSTEMS_FROM_NETWORK_AWS”, “REMOVE_INBOX_RULES_FOR_KNOWN_COMPROMISED_ACCOUNTS”, “RESET_CREDENTIALS_OTHER”, “RESET_CREDENTIALS_AWS”, “RESET_CREDENTIALS_O365” Allows: null action_type any Y N

Comment Allows: “”, null comment string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records assigned_to_actor Actors N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Remediation action assets remediation_action_assets RemediationActionAssets N Y

Remediation action histories remediation_action_histories RemediationActionHistories N Y

class pyexclient.workbench.ResilienceActionGroups(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io resilience_action_group records

Resource type name is resilience_action_groups.

Example JSON record:

{'category': 'DISRUPT_ATTACKERS', 'created_at': '2019-01-15T15:35:00-05:00', 'title': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Global Resilience Group Category Restricted to: “DISRUPT_ATTACKERS”, “ENABLE_DEFENDERS” category any Y N

Group title title string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Resilience actions resilience_actions ResilienceActions N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.ResilienceActions(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Resilience actions

Resource type name is resilience_actions.

Example JSON record:

{'category': 'DISRUPT_ATTACKERS', 'created_at': '2019-01-15T15:35:00-05:00', 'details': 'string', 'impact': 'LOW', 'title': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Details details string Y N

Impact Restricted to: “LOW”, “MEDIUM”, “HIGH” impact any Y N

Title title string Y N

Last Updated timestamp: readonly updated_at string Y N

Category Restricted to: “DISRUPT_ATTACKERS”, “ENABLE_DEFENDERS” Allows: null category any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io resilience_action_group records resilience_action_group ResilienceActionGroups N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.ResourceInstance(data, conn)[source]¶

Bases: object

Represents an instance of a base resource.

classmethod create(conn, **kwargs)[source]¶

Create a new resource instance. Users need to call save() after create to write changes to the server.

Returns:	The updated resource instance
Return type:	`ResourceInstance`

Examples:

>>> i = xc.investigations.create(title='Peter: new investigation 1', relationship_customer=ORGANIZATION_ID, relationship_assigned_to_actor=ACTOR_ID)
>>> i.save()

delete(prompt_on_delete=True)[source]¶

Delete a resource instance.

Parameters:	prompt_on_delete (bool, optional) – True if user wants to be prompted when delete is issued and False otherwise., defaults to True.

Examples:

>>> inv = xc.investigations.get(id='a8bf9750-6a79-4415-9558-a56253606b9f')
>>> inv.delete()

id¶

Retreive the identifier for the resource instance.

Returns:	A GUID representing the unique instance
Return type:	str

Examples:

>>> for inv in xc.investigations.filter_by(status='OPEN'):
>>>     print("Investigation ID is %s" % inv.id)

save()[source]¶

Write changes made to a resource instance back to the sever.

Returns:	The updated resource instance
Return type:	`ResourceInstance`

Examples:

>>> i = xc.investigations.create(title='Peter: new investigation 1', relationship_customer=ORGANIZATION_ID, relationship_assigned_to_actor=ACTOR_ID)
>>> i.save()

class pyexclient.workbench.SamlIdentityProviders(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

SAML Identity Providers

Resource type name is saml_identity_providers.

Example JSON record:

{'callback_uri': 'string', 'cert': 'string', 'entity_id': 'string', 'status': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Allows: “”, null cert string Y N

Allows: “” entity_id string Y N

Allows: “” callback_uri string Y N

Restricted to: “not_configured”, “configured” status string Y N

Defines/retrieves expel.io organization records organization Organizations N Y

class pyexclient.workbench.Secrets(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Organization secrets. Note - these requests must be in the format of /secrets/security_device-<guid>

Resource type name is secrets.

Example JSON record:

{           'secret': {           'device_info': {'access_id': '7b0a343c-860e-442e-ab0b-d6f349d364d9', 'access_key': 'secret-access-key', 'source_category': 'alpha'},
                          'device_secret': {'console_url': 'https://console-access-point.com', 'password': 'password', 'username': 'admin@company.com'},
                          'two_factor_secret': 'GNFXSU2OKNJXUPTGJVQUMNDHM4YVEKRJ'}}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Allows: null secret object Y N

Defines/retrieves expel.io organization records organization Organizations N Y

class pyexclient.workbench.SecurityDevices(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Security devices

Resource type name is security_devices.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'device_spec': {},
    'device_type': 'ENDPOINT',
    'has_two_factor_secret': True,
    'location': 'string',
    'name': 'string',
    'plugin_slug': 'string',
    'status': 'healthy',
    'status_details': {},
    'status_updated_at': '2019-01-15T15:35:00-05:00',
    'task_source': 'CUSTOMER_PREMISE',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Status. Note: By default if the security device has an assembler, and that assembler is unhealthy, the status will return that information rather than the raw status of the security device. To disable this behavior, add the query parameter flag[raw_status]=true. Restricted to: “healthy”, “unhealthy”, “health_checks_not_supported” Allows: null status any Y N

Status Details. Note: By default if the security device has an assembler, and that assembler is unhealthy, the status details will return that information rather than the raw status of the security device. To disable this behavior, add the query parameter flag[raw_status]=true. Allows: null: no-sort status_details object Y N

Status Updated At Allows: null: readonly status_updated_at string Y N

Allows: “”, null plugin_slug string Y N

Last Updated timestamp: readonly updated_at string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Created timestamp: readonly created_at string Y N

Device Spec Allows: null: no-sort device_spec object Y N

Location Allows: “”, null location string Y N

Location where tasks are run Restricted to: “CUSTOMER_PREMISE”, “EXPEL_TASKPOOL” task_source any Y N

Name name string Y N

Has 2fa secret stored in vault: readonly has_two_factor_secret boolean Y N

Device Type Restricted to: “ENDPOINT”, “NETWORK”, “SIEM”, “OTHER”, “CLOUD” device_type any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Assemblers assembler Assemblers N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Security devices child_security_devices SecurityDevices N Y

investigative actions investigative_actions InvestigativeActions N Y

Vendor alerts vendor_alerts VendorAlerts N Y

Defines/retrieves expel.io organization records organization Organizations N Y

Security devices parent_security_device SecurityDevices N Y

Vendors vendor Vendors N Y

class pyexclient.workbench.TimelineEntries(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Timeline Entries

Resource type name is timeline_entries.

Example JSON record:

{           'attack_phase': 'string',
    'comment': 'string',
    'created_at': '2019-01-15T15:35:00-05:00',
    'deleted_at': '2019-01-15T15:35:00-05:00',
    'dest_host': 'string',
    'event': 'string',
    'event_date': '2019-01-15T15:35:00-05:00',
    'event_type': 'string',
    'is_selected': True,
    'src_host': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

The event, such as Powershell Attack Allows: “”, null event string Y N

The type of the event, such as Carbon Black Alert Allows: “”, null event_type string Y N

Source Host (IP or Hostname) Allows: “”, null src_host string Y N

Destination Host (IP or Hostname) Allows: “”, null dest_host string Y N

Date/Time of when the event occurred event_date string Y N

Attack phase of the Timeline Entry Allows: “”, null attack_phase string Y N

Last Updated timestamp: readonly updated_at string Y N

Comment on this Timeline Entry Allows: “”, null comment string Y N

Deleted At timestamp Allows: null deleted_at string Y N

Has been selected for final report. is_selected boolean Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io context_label_action records context_label_actions ContextLabelActions N Y

Investigations investigation Investigations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io context_label records context_labels ContextLabels N Y

Expel alerts expel_alert ExpelAlerts N Y

class pyexclient.workbench.UserAccountRoles(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Defines/retrieves expel.io user_account_role records

Resource type name is user_account_roles.

Example JSON record:

{'active': True, 'assignable': True, 'created_at': '2019-01-15T15:35:00-05:00', 'role': 'expel_admin', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

If this role is active active boolean Y N

Last Updated timestamp: readonly updated_at string Y N

Can user be assigned items (e.g. investigations, etc) assignable boolean Y N

User account role for this organization Restricted to: “expel_admin”, “expel_analyst”, “organization_admin”, “organization_analyst”, “system”, “anonymous”, “restricted” role any Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

User accounts user_account UserAccounts N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.UserAccountStatuses(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

User account status

Resource type name is user_account_statuses.

Example JSON record:

{           'active': True,
    'active_status': 'ACTIVE',
    'created_at': '2019-01-15T15:35:00-05:00',
    'invite_token_expires_at': '2019-01-15T15:35:00-05:00',
    'password_reset_token_expires_at': '2019-01-15T15:35:00-05:00',
    'restrictions': [],
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Meta: readonly created_at string Y N

Missing Description active boolean Y N

Missing Description restrictions array Y N

Allows: null: readonly invite_token_expires_at string Y N

Allows: null: readonly password_reset_token_expires_at string Y N

Restricted to: “ACTIVE”, “LOCKED”, “LOCKED_INVITED”, “LOCKED_EXPIRED”, “ACTIVE_INVITED”, “ACTIVE_EXPIRED”: readonly active_status any Y N

Meta: readonly updated_at string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

User accounts user_account UserAccounts N Y

Defines/retrieves expel.io organization records primary_organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.UserAccounts(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

User accounts

Resource type name is user_accounts.

Example JSON record:

{           'active': True,
    'active_status': 'ACTIVE',
    'assignable': True,
    'created_at': '2019-01-15T15:35:00-05:00',
    'display_name': 'string',
    'email': 'name@company.com',
    'engagement_manager': True,
    'first_name': 'string',
    'homepage_preferences': {},
    'language': 'string',
    'last_name': 'string',
    'locale': 'string',
    'phone_number': 'string',
    'timezone': 'string',
    'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Active Allows: null active boolean Y N

Can user be assigned items (e.g. investigations, etc) assignable boolean Y N

Locale Allows: “”, null locale string Y N

Is an engagement manager engagement_manager boolean Y N

Last Name last_name string Y N

Last Updated timestamp: readonly updated_at string Y N

Email email string Y N

Created timestamp: readonly created_at string Y N

Display name Allows: “”, null display_name string Y N

Language Allows: “”, null language string Y N

Timezone Allows: “”, null timezone string Y N

Phone number Allows: null phone_number string Y N

Restricted to: “ACTIVE”, “LOCKED”, “LOCKED_INVITED”, “LOCKED_EXPIRED”, “ACTIVE_INVITED”, “ACTIVE_EXPIRED”: readonly, no-sort active_status any Y N

Homepage preferences Allows: null: no-sort homepage_preferences object Y N

First Name first_name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Defines/retrieves expel.io actor records actor Actors N Y

Defines/retrieves expel.io organization records primary_organization Organizations N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Remediation actions assigned_remediation_actions RemediationActions N Y

Defines/retrieves expel.io user_account_role records user_account_roles UserAccountRoles N Y

investigative actions analysis_assigned_investigative_actions InvestigativeActions N Y

Organization to resilience actions assigned_organization_resilience_actions OrganizationResilienceActions N Y

User Notification Preferences notification_preferences NotificationPreferences N Y

Expel alerts assigned_expel_alerts ExpelAlerts N Y

Organization to resilience actions assigned_organization_resilience_actions_list OrganizationResilienceActions N Y

User account status user_account_status UserAccountStatuses N Y

Investigations assigned_investigations Investigations N Y

investigative actions assigned_investigative_actions InvestigativeActions N Y

Defines/retrieves expel.io organization records organizations Organizations N Y

class pyexclient.workbench.VendorAlertEvidences(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Vendor alert evidences are extracted from a vendor alert’s evidence summary

Resource type name is vendor_alert_evidences.

Example JSON record:

{'evidence': 'string', 'evidence_type': 'HOSTNAME'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Evidence evidence string Y N

Type Restricted to: “HOSTNAME”, “URL”, “PROCESS_ARGUMENTS”, “PROCESS_PATH”, “PROCESS_MD5”, “USERNAME”, “SRC_IP”, “DST_IP”, “PARENT_ARGUMENTS”, “PARENT_PATH”, “PARENT_MD5”, “SRC_USERNAME”, “DST_USERNAME”, “ALERT_ACTION”, “ALERT_DESCRIPTION”, “ALERT_MESSAGE”, “ALERT_NAME”, “SRC_PORT”, “DST_PORT”, “USER_AGENT”, “VENDOR_NAME”, “DOMAIN” evidence_type any Y N

Expel alerts evidenced_expel_alerts ExpelAlerts N Y

Vendor alerts vendor_alert VendorAlerts N Y

class pyexclient.workbench.VendorAlerts(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Vendor alerts

Resource type name is vendor_alerts.

Example JSON record:

{           'created_at': '2019-01-15T15:35:00-05:00',
    'description': 'string',
    'evidence_activity_end_at': '2019-01-15T15:35:00-05:00',
    'evidence_activity_start_at': '2019-01-15T15:35:00-05:00',
    'evidence_summary': [],
    'first_seen': '2019-01-15T15:35:00-05:00',
    'original_alert_id': 'string',
    'original_source_id': 'string',
    'signature_id': 'string',
    'status': 'NORMAL',
    'updated_at': '2019-01-15T15:35:00-05:00',
    'vendor_message': 'string',
    'vendor_severity': 'CRITICAL',
    'vendor_sig_name': 'string'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

First Seen first_seen string Y N

Status Restricted to: “NORMAL”, “PROVISIONAL” Allows: null: readonly status any Y N

Allows: null: immutable original_source_id string Y N

Evidence summary Allows: null: no-sort evidence_summary array Y N

Last Updated timestamp: readonly updated_at string Y N

Signature ID Allows: “”, null signature_id string Y N

Vendor alert severity Restricted to: “CRITICAL”, “HIGH”, “MEDIUM”, “LOW”, “TESTING”, “TUNING” Allows: null vendor_severity any Y N

Created timestamp: readonly created_at string Y N

Evidence activity end datetime Allows: null: immutable evidence_activity_end_at string Y N

Vendor Message Allows: “”, null vendor_message string Y N

Evidence activity start datetime Allows: null: immutable evidence_activity_start_at string Y N

Allows: null: immutable original_alert_id string Y N

Description Allows: “”, null description string Y N

Vendor Sig Name Allows: “”, null vendor_sig_name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Assemblers assembler Assemblers N Y

Security devices security_device SecurityDevices N Y

Vendor alert evidences are extracted from a vendor alert’s evidence summary evidences VendorAlertEvidences N Y

Defines/retrieves expel.io actor records created_by Actors N Y

Defines/retrieves expel.io organization records organization Organizations N Y

IP addresses ip_addresses IpAddresses N Y

Expel alerts expel_alerts ExpelAlerts N Y

Vendors vendor Vendors N Y

class pyexclient.workbench.Vendors(data, conn)[source]¶

Bases: pyexclient.workbench.ResourceInstance

Vendors

Resource type name is vendors.

Example JSON record:

{'created_at': '2019-01-15T15:35:00-05:00', 'icon': 'string', 'name': 'string', 'updated_at': '2019-01-15T15:35:00-05:00'}

Below are valid filter by parameters:

Field Description Field Name Field Type Attribute Relationship

Created timestamp: readonly created_at string Y N

Last Updated timestamp: readonly updated_at string Y N

Icon Allows: “”, null icon string Y N

Name Allows: “”, null name string Y N

Defines/retrieves expel.io actor records updated_by Actors N Y

Vendor alerts vendor_alerts VendorAlerts N Y

Security devices security_devices SecurityDevices N Y

Expel alerts expel_alerts ExpelAlerts N Y

Defines/retrieves expel.io actor records created_by Actors N Y

class pyexclient.workbench.WorkbenchClient(base_url, username=None, password=None, mfa_code=None, token=None, prompt_on_delete=True)[source]¶

Bases: pyexclient.workbench.WorkbenchCoreClient

Instantiate a client that interacts with Workbench’s API server.

If the developer specifies a username, then password and mfa_code are required inputs. If the developer has a token then username, password and mfa_code parameters are ignored.

Parameters:	cls (WorkbenchClient) – A Workbench class reference. username (str or None) – The username password (str or None) – The username’s password mfa_code (int or None) – The multi factor authenticate code generated by google authenticator. token (str or None) – The bearer token of an authorized session. Can be used instead of `username`/`password` combo.
Returns:	An initialized, and authorized Workbench client.
Return type:	WorkbenchClient

capabilities(customer_id: str)[source]¶

Get a list of capabilities for a given customer.

Parameters:	customer_id (str) – The customer ID

Examples:

>>> xc.workbench.capabilities("my-customer-guid-123")

create_auto_inv_action(customer_id: str, vendor_device_id: str, created_by_id: str, capability_name: str, input_args: dict, title: str, reason: str, investigation_id: str = None, expel_alert_id: str = None)[source]¶

Create an automatic investigative action.

Parameters:	customer_id (str) – The customer ID investigation_id (str) – The investigation ID to associate the action with. expel_alert_id (str) – The expel alert id vendor_device_id (str) – The vendor device ID, to dispatch the task against. created_by_id (str) – The user ID that created the action capability_name (str) – The name of the capability we are running. Defined in classes https://github.com/expel-io/taskabilities/tree/master/py/taskabilities/cpe/capabilities, look at name class variable. input_args (dict) – The input arguments to the capability to run. Defined in classes https://github.com/expel-io/taskabilities/tree/master/py/taskabilities/cpe/capabilities, look at name class variable. title (str) – The title of the investigative action, shows up in Workbench. reason (str) – The reason for running the investigative action, shows up in Workbench.
Returns:	Investigative action response
Return type:	InvestigativeActions

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> input_args = &#123;"user_name": 'willy.wonka@expel.io', 'time_range_start':'2019-01-30T14:00:40Z', 'time_range_end':'2019-01-30T14:45:40Z'&#125;
>>> o = xc.create_auto_inv_action(customer_guid, inv_guid, device_guid, user_guid, 'query_user', input_args, 'Query User', 'Getting user login activity to determine if login is normal')
>>> print("Investigative Action ID: ", o.id)

create_manual_inv_action(title: str, reason: str, instructions: str, investigation_id: str = None, expel_alert_id: str = None, security_device_id: str = None, action_type: str = 'MANUAL')[source]¶

Create a manual investigative action.

Parameters:	title (str) – The title of the investigative action, shows up in Workbench. reason (str) – The reason for running the investigative action, shows up in Workbench. instructions (str) – The instructions for running the investigative action. investigation_id (str) – The investigation ID to associate the action with. expel_alert_id (str) – The expel alert id security_device_id (str) – The security device ID, to dispatch the task against. action_type (str) – The type of action that will be run.
Returns:	Investigative action response
Return type:	InvestigativeActions

Examples:

>>> xc = WorkbenchClient('https://workbench.expel.io', username=username, password=password, mfa_code=mfa_code)
>>> o = xc.create_manual_inv_action('title foo', 'reason bar', 'instructions blah')
>>> print("Investigative Action ID: ", o.id)

plugins()[source]¶

Get a list of plugins.

Examples:

>>> xc.workbench.plugins()

class pyexclient.workbench.WorkbenchCoreClient(base_url, username=None, password=None, mfa_code=None, token=None, retries=3, prompt_on_delete=True)[source]¶

Bases: object

Instantiate a Workbench core client that provides just authentication and request capabilities to Workbench

If the developer specifies a username, then password and mfa_code are required inputs. If the developer has a token then username, password and mfa_code parameters are ignored.

Parameters:	cls (WorkbenchClient) – A Workbench class reference. username (str or None) – The username password (str or None) – The username’s password mfa_code (int or None) – The multi factor authenticate code generated by google authenticator. token (str or None) – The bearer token of an authorized session. Can be used instead of `username`/`password` combo.
Returns:	An initialized, and authorized Workbench client.
Return type:	WorkbenchClient

login(username, password, code)[source]¶

Authenticate as a human, this requires providing the 2FA code.

Parameters:	username (str) – The user’s e-mail address. password (str) – The user’s password. code (str) – The 2FA code
Returns:	The bearer token that allows users to call Workbench APIs.
Return type:	str

make_session()[source]¶: Create a session with Workbench

class pyexclient.workbench.base_filter(filter_value)[source]¶

Bases: pyexclient.workbench.operator

Base class for operators which take the form filter[field]. Can be used to create a basic one field filter, or subclassed by special operators for more complicated logic

class pyexclient.workbench.contains(*args)[source]¶

Bases: pyexclient.workbench.base_filter

The contains operator is used to search for fields that contain a sub string..

Parameters:	value (str) – A substring to be checked against the value of a field.

Examples:

>>> for ea in xc.expel_alerts.search(close_comment=contains("foo")):
>>>     print("%s contains foo in the close comment" % ea.expel_name)

class pyexclient.workbench.flag(filter_value)[source]¶

Bases: pyexclient.workbench.operator

Base class for operators which take the form flag[field]. Can be used to create a basic one field flag, or subclassed by special operators for more complicated logic

class pyexclient.workbench.gt(value)[source]¶

Bases: pyexclient.workbench.base_filter

The gt (greater than) operator is used to search a specific field for values greater than X.

Parameters:	value (str) – The greater than value to be used in comparison during a search.

Examples:

>>> for ea in xc.expel_alerts.search(created_at=gt("2020-01-01")):
>>>     print("%s was created after 2020-01-01" % ea.expel_name)

class pyexclient.workbench.include(include)[source]¶

Bases: pyexclient.workbench.operator

The include operator requests base resource names in a search. Cannot be used with sort or filtering. Passed as arg to search TODO enforce this constraint with asserts

Parameters:	include (str) – Include specific base resource names in request

Examples: >>> for ea in xc.expel_alerts.search(include=’organization,created_by,updated_by’): >>> print(ea.organization)

pyexclient.workbench.is_operator(value)[source]¶

Determine if a value implements an operator.

Parameters:	value (object) – The value to check
Returns:	True if value is an operator False otherwise.
Return type:	bool

class pyexclient.workbench.isnull(filter_value=True)[source]¶

Bases: pyexclient.workbench.base_filter

The isnull operator is used to search for fields that are null.

Examples:

>>> for ea in xc.expel_alerts.search(close_comment=isnull()):
>>>     print("%s has no close comment" % ea.expel_name)

class pyexclient.workbench.limit(limit)[source]¶

Bases: pyexclient.workbench.operator

The limit operator adds a limit to a search. Passed as arg to search

Parameters:	limit (int) – Limit the number of results returned.

class pyexclient.workbench.lt(value)[source]¶

Bases: pyexclient.workbench.base_filter

The lt (less than) operator is used to search a specific field for values greater than X.

Parameters:	value (str) – The less than value to be used in comparison during a search.

Examples:

>>> for ea in xc.expel_alerts.search(created_at=lt("2020-01-01")):
>>>     print("%s was created before 2020-01-01" % ea.expel_name)

class pyexclient.workbench.neq(*args)[source]¶

Bases: pyexclient.workbench.base_filter

The neq operator is used to search for for fields that are not equal to a specified value.

Parameters:	value (str) – The value to assert the field is not equal too

Examples:

>>> for ea in xc.expel_alerts.search(close_comment=neq("foo")):
>>>     print("%s has a close comment that is not equal to 'foo'" % ea.expel_name)

class pyexclient.workbench.notnull(filter_value=True)[source]¶

Bases: pyexclient.workbench.base_filter

The notnull operator is used to search for fields that are not null.

Examples:

>>> for ea in xc.expel_alerts.search(close_comment=notnull()):
>>>     print("%s has a close comment of %s" % (ea.expel_name, ea.close_comment))

class pyexclient.workbench.operator(filter_value)[source]¶

Bases: object

Base class for all operators. This should not be used directly.

class pyexclient.workbench.relationship(rel_path, value)[source]¶

Bases: pyexclient.workbench.operator

relationship operator allows for searching of resource objects based on their relationship to other resource objects. Passed as arg to search

Parameters:	rel_path (str) – A dot notation of the relationship path to a resource object. value (object) – The value the rel_path be compared to. This can be an operator, or a primitive value.

Examples:

>>> for inv_action in xc.investigative_actions.search(relationship("investigation.close_comment", notnull()):
>>>     print("Found investigative action associated with an investigation that has no close comment.")

class pyexclient.workbench.sort(sort, order='asc')[source]¶

Bases: pyexclient.workbench.operator

The sort operator passes a sort request to a search. Can add multiple sort operators to a single search. If no sort is provided the default of sorting by created_at (asc) -> id (asc) will be used. Passed as arg to search TODO enforce this with asserts

Parameters:	sort (str) – The column to sort on. Expects asc or desc. The database will translate asc->+ and desc->-

class pyexclient.workbench.startswith(swith)[source]¶

Bases: pyexclient.workbench.base_filter

The startswith operator is used to search for values that start with a specified string..

Parameters:	value (str) – The startswith string

Examples:

>>> for ea in xc.expel_alerts.search(close_comment=startswith("foo")):
>>>     print("%s starts with foo in the close comment" % ea.expel_name)

class pyexclient.workbench.window(start, end)[source]¶

Bases: pyexclient.workbench.base_filter

The window operator is used to search a specific field that is within a window (range) of values

Parameters:	start (Union[str, int, datetime.datetime]) – The begining of the window range end (str) – The end of the window range

Examples:

>>> for ea in xc.expel_alerts.search(created_at=window("2020-01-01", "2020-05-01")):
>>>     print("%s was created after 2020-01-01 and before 2020-05-01" % ea.expel_name)