Skip to content

Case

Case

Bases: object

Handles the case methods

_assert_cid(cid)

Verifies that the provided cid is set. This does not verify the validity of the cid. If an invalid CID is set, the requests are emitted but will likely fail.

Parameters:

Name Type Description Default
cid int

Case ID

required

Returns:

Type Description
int

CaseID as int

add_asset(name, asset_type, analysis_status, compromised=None, tags=None, description=None, domain=None, ip=None, additional_info=None, ioc_links=None, custom_attributes=None, cid=None)

Adds an asset to the target case id.

If they are strings, asset_types and analysis_status are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
name str

Name of the asset to add

required
asset_type Union[str, int]

Name or ID of the asset type

required
description str

Description of the asset

None
domain str

Domain of the asset

None
ip str

IP of the asset

None
additional_info str

Additional information,

None
analysis_status Union[str, int]

Status of the analysis

required
compromised bool

Set to true if asset is compromised

None
tags List[str]

List of tags

None
ioc_links List[int]

List of IOC to link to this asset

None
custom_attributes dict

Custom attributes of the asset

None
cid int

int - Case ID

None

Returns:

Type Description
ApiResponse

APIResponse

add_case(case_name, case_description, case_customer, soc_id, custom_attributes=None, create_customer=False)

Creates a new case. If create_customer is set to true and the customer doesn't exist, it is created. Otherwise an error is returned.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
case_name str

case_name

required
case_description str

Description of the case

required
case_customer Union[str, int]

Name or ID of the customer

required
soc_id str

SOC Number

required
custom_attributes dict

Custom attributes of the case

None
create_customer

Set to true to create the customer is doesn't exists. (Default value = False)

False

Returns:

Type Description
ApiResponse

ApiResponse object

add_event(title, date_time, content=None, raw_content=None, source=None, linked_assets=None, linked_iocs=None, category=None, tags=None, color=None, display_in_graph=None, display_in_summary=None, custom_attributes=None, cid=None, timezone_string=None)

Adds a new event to the timeline.

If it is a string, category is lookup-ed up before the addition request is issued. it can be either a name or an ID. For performances prefer an ID as it is used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
title str

Title of the event

required
date_time datetime

Datetime of the event, including timezone

required
content str

Content of the event (displayed in timeline on GUI)

None
raw_content str

Raw content of the event (displayed in detailed event on GUI)

None
source str

Source of the event

None
linked_assets list

List of assets to link with this event

None
linked_iocs list

List of IOCs to link with this event

None
category Union[int, str]

Category of the event (MITRE ATT@CK)

None
color str

Left border of the event in the timeline

None
display_in_graph bool

Set to true to display in graph page - Default to true

None
display_in_summary bool

Set to true to display in Summary - Default to false

None
tags list

A list of strings to add as tags

None
custom_attributes str

Custom attributes of the event

None
timezone_string str

Timezone in format +XX:XX or -XX:XX. If none, +00:00 is used

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

add_evidence(filename, file_size, description=None, file_hash=None, custom_attributes=None, cid=None)

Adds a new evidence to the target case.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
filename str

name of the evidence

required
file_size int

Size of the file

required
description str

Description of the evidence

None
file_hash str

hash of the evidence

None
custom_attributes dict

Custom attributes of the evidences

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

add_global_task(title, status, assignee, description=None, tags=None)

Adds a new task.

If they are strings, status and assignee are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Parameters:

Name Type Description Default
title str

Title of the task

required
description str

Description of the task

None
assignee Union[str, int]

Assignee ID or username

required
tags list

Tags of the task

None
status Union[str, int]

String or status ID, need to be a valid status

required

Returns:

Type Description
ApiResponse

APIResponse object

add_ioc(value, ioc_type, description=None, ioc_tlp=None, ioc_tags=None, custom_attributes=None, cid=None)

Adds an ioc to the target case id.

If they are strings, ioc_tlp and ioc_type are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
value str

Value of the IOC

required
ioc_type Union[str, int]

Type of IOC, either name or type ID

required
description str

Optional - Description of the IOC

None
ioc_tlp Union[str, int]

TLP name or tlp ID. Default is orange

None
ioc_tags list

List of tags to add

None
custom_attributes dict

Custom attributes of the ioc

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse

add_note(note_title, note_content, group_id, custom_attributes=None, cid=None)

Creates a new note. Case ID and group note ID need to match the case in which the note is stored.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
cid int

Case ID

None
note_title str

Title of the note

required
note_content str

Content of the note

required
group_id int

Target group to attach the note to

required
custom_attributes dict

Custom attributes of the note

None

Returns:

Type Description
ApiResponse

APIResponse object

add_notes_group(group_title=None, cid=None)

Creates a new notes group in the target cid case. Group_title can be an existing group, there is no uniqueness.

Parameters:

Name Type Description Default
cid int

Case ID

None
group_title str

Name of the group to add

None

Returns:

Type Description
ApiResponse

APIResponse object

add_task(title, status, assignee, description=None, tags=None, custom_attributes=None, cid=None)

Adds a new task to the target case.

If they are strings, status and assignee are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
title str

Title of the task

required
description str

Description of the task

None
assignee Union[str, int]

Assignee ID or username

required
cid int

Case ID

None
tags list

Tags of the task

None
status Union[str, int]

String or status ID, need to be a valid status

required
custom_attributes dict

Custom attributes of the task

None

Returns:

Type Description
ApiResponse

APIResponse object

add_task_log(message, cid=None)

Adds a new task log that will appear under activities

Parameters:

Name Type Description Default
message str

Message to log

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

ApiResponse

asset_exists(asset_id, cid=None)

Returns true if asset_id exists in the context of the current case or cid. This method is an overlay of get_asset and thus not performant.

Parameters:

Name Type Description Default
asset_id int

Asset to lookup

required
cid int

Case ID

None

Returns:

Type Description
bool

True if exists else false

case_id_exists(cid)

Checks if a case id is valid by probing the summary endpoint. This method returns true if the probe was successful. If False is returned it might not indicate the case doesn't exist but might be the result of a request malfunction (server down, invalid API token, etc).

Parameters:

Name Type Description Default
cid int

Case ID to check

required

Returns:

Type Description
bool

True if case ID exists otherwise false

delete_asset(asset_id, cid=None)

Deletes an asset identified by asset_id. CID must match the case in which the asset is stored.

Parameters:

Name Type Description Default
asset_id int

ID of the asset to delete

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

delete_case(cid)

Deletes a case based on its ID. All objects associated to the case are deleted. This includes : - assets, - iocs that are only referenced in this case - notes - summary - events - evidences - tasklogs

Parameters:

Name Type Description Default
cid int

Case to delete

required

Returns:

Type Description
ApiResponse

ApiResponse

delete_event(event_id, cid=None)

Deletes an event from its ID. CID must match the case in which the event is stored

Parameters:

Name Type Description Default
event_id int

Event to delete

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

delete_evidence(evidence_id, cid=None)

Deletes an evidence from its ID. evidence_id needs to be an existing evidence in the target case.

Parameters:

Name Type Description Default
evidence_id int

int - Evidence to delete

required
cid int

int - Case ID

None

Returns:

Type Description

APIResponse object

delete_global_task(task_id)

Deletes a global task from its ID. task_id needs to be an existing task in the database.

Parameters:

Name Type Description Default
task_id int

int - Task to delete

required

Returns:

Type Description
ApiResponse

APIResponse object

delete_ioc(ioc_id, cid=None)

Deletes an IOC from its ID. CID must match the case in which the ioc is stored.

Parameters:

Name Type Description Default
ioc_id int

ID of the ioc

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

delete_note(note_id, cid=None)

Deletes a note. note_id needs to be a valid existing note in the target case.

Parameters:

Name Type Description Default
cid int

Case ID

None
note_id int

Name of the note to delete

required

Returns:

Type Description
ApiResponse

APIResponse object

delete_notes_group(group_id, cid=None)

Deletes a notes group. All notes in the target groups are deleted ! There is not way to get the notes back. Case ID needs to match the case where the group is stored.

Parameters:

Name Type Description Default
cid int

Case ID

None
group_id int

ID of the group

required

Returns:

Type Description
ApiResponse

APIResponse object

delete_task(task_id, cid=None)

Deletes a task from its ID. CID must match the case in which the task is stored.

Parameters:

Name Type Description Default
task_id int

Task to delete

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

filter_events(filter_str=None, cid=None)

Returns a list of events from the timeline, filtered with the same query types used in the UI.

Parameters:

Name Type Description Default
filter_str dict

Filter the timeline as in the UI

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

get_asset(asset_id, cid=None)

Returns an asset information from its ID.

Parameters:

Name Type Description Default
asset_id int

ID of the asset to fetch

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

get_case(cid)

Gets an existing case from its ID

Parameters:

Name Type Description Default
cid int

CaseID to fetch

required

Returns:

Type Description
ApiResponse

ApiResponse object

get_event(event_id, cid=None)

Returns an event from the timeline

Parameters:

Name Type Description Default
event_id int

ID of the event to fetch

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

get_evidence(evidence_id, cid=None)

Returns an evidence from its ID. evidence_id needs to be an existing evidence in the target case.

Parameters:

Name Type Description Default
evidence_id int

Evidence ID to lookup

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

get_global_task(task_id)

Returns a global task from its ID.

Parameters:

Name Type Description Default
task_id int

Task ID to lookup

required

Returns:

Type Description
ApiResponse

APIResponse object

get_ioc(ioc_id, cid=None)

Returns an IOC. ioc_id needs to be an existing ioc in the provided case ID.

Parameters:

Name Type Description Default
ioc_id int

IOC ID

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

get_note(note_id, cid=None)

Fetches a note. note_id needs to be a valid existing note in the target case.

Parameters:

Name Type Description Default
cid int

Case ID

None
note_id int

ID of the note to fetch

required

Returns:

Type Description
ApiResponse

APIResponse object

get_notes_group(group_id, cid=None)

Returns a notes group based on its ID. The group ID needs to match the CID where it is stored.

Parameters:

Name Type Description Default
group_id int

Group ID to fetch

required
cid int

Case ID (Default value = None)

None

Returns:

Type Description
ApiResponse

APIResponse object

get_summary(cid=None)

Returns the summary of the specified case id.

Parameters:

Name Type Description Default
cid int

Case ID (Default value = None)

None

Returns:

Type Description
ApiResponse

APIResponse object

get_task(task_id, cid=None)

Returns a task from its ID. task_id needs to be a valid task in the target case.

Parameters:

Name Type Description Default
task_id int

Task ID to lookup

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

list_assets(cid=None)

Returns a list of all assets of the target case.

Parameters:

Name Type Description Default
cid int

int - Case ID

None

Returns:

Type Description
ApiResponse

APIResponse

list_cases()

Returns a list of all the cases

:return: ApiResponse

list_events(filter_by_asset=0, cid=None)

Returns a list of events from the timeline. filter_by_asset can be used to return only the events linked to a specific asset. In case the asset doesn't exist, an empty timeline is returned.

Parameters:

Name Type Description Default
filter_by_asset int

Select the timeline of a specific asset by setting an existing asset ID

0
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

list_evidences(cid=None)

Returns a list of evidences.

Parameters:

Name Type Description Default
cid int

Case ID

None

Returns:

Type Description
ApiResponse

ApiResponse object

list_global_tasks()

Returns:

Type Description
ApiResponse

return: ApiResponse object

list_iocs(cid=None)

Returns a list of all iocs of the target case.

Parameters:

Name Type Description Default
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse

list_notes_groups(cid=None)

Returns a list of notes groups of the target cid case

Parameters:

Name Type Description Default
cid int

Case ID (Default value = None)

None

Returns:

Type Description
ApiResponse

APIResponse object

list_tasks(cid=None)

Returns a list of tasks linked to the provided case.

Parameters:

Name Type Description Default
cid int

Case ID

None

Returns:

Type Description
ApiResponse

ApiResponse object

search_notes(search_term, cid=None)

Searches in notes. Case ID and group note ID need to match the case in which the notes are stored. Only the titles and notes ID of the matching notes are return, not the actual content. Use % for wildcard.

Parameters:

Name Type Description Default
cid int

int - Case ID

None
search_term str

str - Term to search in notes

required

Returns:

Type Description
ApiResponse

APIResponse object

set_cid(cid)

Sets the current cid for the Case instance. It can be override be setting the cid of each method though not recommended to keep consistency.

Parameters:

Name Type Description Default
cid int

Case ID

required

Returns:

Type Description
bool

Always true

set_summary(summary_content=None, cid=None)

Sets the summary of the specified case id.

Warning

This completely replace the current content of the summary. Any co-worker working on the summary will receive an overwrite order from the server. The order is immediately received by web socket. This method should probably be only used when setting a new case.

Parameters:

Name Type Description Default
summary_content str

Content of the summary to push. This will completely replace the current content (Default value = None)

None
cid int

Case ID (Default value = None)

None

Returns:

Type Description
ApiResponse

APIResponse object

trigger_manual_hook(hook_ui_name, module_name, targets, target_type, cid=None)

Triggers a module hook call. These can only be used with manual hooks. The request is sent to the target module and processed asynchronously. The server replies immediately after queuing the task. Success feedback from this endpoint does not implies the hook processing was successful.

Parameters:

Name Type Description Default
hook_ui_name str

Hook name, as defined by the module on the UI

required
module_name str

Module associated with the hook name

required
targets list

List of IDs of objects to be processed

required
target_type str

Target type of targets

required
cid int

Case ID

None

Returns:

Type Description
ApiResponse

ApiResponse object

update_asset(asset_id, name=None, asset_type=None, tags=None, analysis_status=None, description=None, domain=None, ip=None, additional_info=None, ioc_links=None, compromised=None, custom_attributes=None, cid=None, no_sync=False)

Updates an asset. asset_id needs to be an existing asset in the target case cid.

If they are strings, asset_types and analysis_status are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
asset_id int

ID of the asset to update

required
name str

Name of the asset

None
asset_type Union[str, int]

Name or ID of the asset type

None
tags List[str]

List of tags

None
description str

Description of the asset

None
domain str

Domain of the asset

None
ip str

IP of the asset

None
additional_info str

Additional information,

None
analysis_status Union[str, int]

Status of the analysis

None
ioc_links List[int]

List of IOC to link to this asset

None
compromised bool

True is asset is compromised

None
custom_attributes dict

Custom attributes of the asset

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse

update_event(event_id, title=None, date_time=None, content=None, raw_content=None, source=None, linked_assets=None, linked_iocs=None, category=None, tags=None, color=None, display_in_graph=None, display_in_summary=None, custom_attributes=None, cid=None, timezone_string=None)

Updates an event of the timeline. event_id needs to be an existing event in the target case.

If it is a string, category is lookup-ed up before the addition request is issued. it can be either a name or an ID. For performances prefer an ID as it is used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
event_id int

Event ID to update

required
title str

Title of the event

None
date_time datetime

Datetime of the event, including timezone

None
content str

Content of the event (displayed in timeline on GUI)

None
raw_content str

Raw content of the event (displayed in detailed event on GUI)

None
source str

Source of the event

None
linked_assets list

List of assets to link with this event

None
linked_iocs list

List of IOCs to link with this event

None
category Union[int, str]

Category of the event (MITRE ATT@CK)

None
color str

Left border of the event in the timeline

None
display_in_graph bool

Set to true to display in graph page - Default to true

None
display_in_summary bool

Set to true to display in Summary - Default to false

None
tags list

A list of strings to add as tags

None
custom_attributes dict

Custom attributes of the event

None
timezone_string str

Timezone in format +XX:XX or -XX:XX. If none, +00:00 is used

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

update_evidence(evidence_id, filename=None, file_size=None, description=None, file_hash=None, custom_attributes=None, cid=None)

Updates an evidence of the matching case. evidence_id needs to be an existing evidence in the target case.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
evidence_id int

ID of the evidence

required
filename str

name of the evidence

None
file_size int

Size of the file

None
description str

Description of the evidence

None
file_hash str

hash of the evidence

None
custom_attributes dict

custom attributes of the evidences

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

update_global_task(task_id, title=None, status=None, assignee=None, description=None, tags=None)

Updates a task. task_id needs to be an existing task in the database.

If they are strings, status and assignee are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Parameters:

Name Type Description Default
task_id int

ID of the task to update

required
title str

Title of the task

None
description str

Description of the task

None
assignee Union[int, str]

Assignee ID or assignee username

None
tags list

Tags of the task

None
status Union[str, int]

String status, need to be a valid status

None

Returns:

Type Description
ApiResponse

APIResponse object

update_ioc(ioc_id, value=None, ioc_type=None, description=None, ioc_tlp=None, ioc_tags=None, custom_attributes=None, cid=None)

Updates an existing IOC. ioc_id needs to be an existing ioc in the provided case ID.

If they are strings, ioc_tlp and ioc_type are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
ioc_id int

IOC ID to update

required
value str

Value of the IOC

None
ioc_type Union[str, int]

Type of IOC, either name or type ID

None
description str

Description of the IOC

None
ioc_tlp Union[str, int]

TLP name or tlp ID. Default is orange

None
ioc_tags list

List of tags to add,

None
custom_attributes dict

Custom attributes of the IOC

None
cid int

Case ID

None

Returns:

Type Description
ApiResponse

APIResponse object

update_note(note_id, note_title=None, note_content=None, custom_attributes=None, cid=None)

Updates a note. note_id needs to be a valid existing note in the target case. Only the content of the set fields is replaced.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
cid int

Case ID

None
note_id int

Name of the note to update

required
note_content str

Content of the note

None
note_title str

Title of the note

None
custom_attributes dict

Custom attributes of the note

None

Returns:

Type Description
ApiResponse

APIResponse object

update_notes_group(group_id, group_title, cid=None)

Updates a notes group in the target cid case. group_id need to be an existing group in the target case. group_title can be an existing group, there is no uniqueness.

Parameters:

Name Type Description Default
cid int

Case ID

None
group_id int

Group ID to update

required
group_title str

Name of the group

required

Returns:

Type Description
ApiResponse

APIResponse object

update_task(task_id, title=None, status=None, assignee=None, description=None, tags=None, custom_attributes=None, cid=None)

Updates a task. task_id needs to be a valid task in the target case.

If they are strings, status and assignee are lookup-ed up before the addition request is issued. Both can be either a name or an ID. For performances prefer an ID as they're used directly in the request without prior lookup.

Custom_attributes is an undefined structure when the call is made. This method does not allow to push a new attribute structure. The submitted structure must follow the one defined by administrators in the UI otherwise it is ignored.

Parameters:

Name Type Description Default
task_id int

ID of the task to update

required
title str

Title of the task

None
description str

Description of the task

None
assignee Union[int, str]

Assignee ID or assignee username

None
cid int

Case ID

None
tags list

Tags of the task

None
status Union[str, int]

String status, need to be a valid status

None
custom_attributes dict

Custom attributes of the task

None

Returns:

Type Description
ApiResponse

APIResponse object


Last update: 2022-03-20
Back to top