Modules

IntelOwl class

class pyintelowl.pyintelowl.IntelOwl(token: str, instance_url: str, certificate: Optional[str] = None, proxies: Optional[dict] = None, logger: Optional[Logger] = None, cli: bool = False)[source]

Bases: object

analyzer_healthcheck(analyzer_name: str) → Optional[bool][source]

Send analyzer(docker-based) health check request.

Method: GET Endpoint: /api/analyzer/{analyzer_name}/healthcheck

Parameters:

analyzer_name (str) – name of analyzer

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

success or not

Return type:

Bool

ask_analysis_availability(md5: str, analyzers: Optional[List[str]] = None, check_reported_analysis_too: bool = False, minutes_ago: Optional[int] = None) → Dict[source]

Search for already available analysis.

Endpoint: /api/ask_analysis_availability

Parameters:

  • md5 (str) – md5sum of the observable or file

  • analyzers (List[str], optional) –

  • trigger. (list of analyzers to) –

  • analyzers. (Defaults to None meaning automatically select all configured) –

  • check_reported_analysis_too (bool, optional) –

  • False. (Check against all existing jobs. Defaults to) –

  • minutes_ago (int, optional) –

  • analysis. (number of minutes to check back for) –

  • limits. (Default is None so the check does not have any time) –

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

JSON body

Return type:

Dict

connector_healthcheck(connector_name: str) → Optional[bool][source]

Send connector health check request.

Method: GET Endpoint: /api/connector/{connector_name}/healthcheck

Parameters:

connector_name (str) – name of connector

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

success or not

Return type:

Bool

create_tag(label: str, color: str)[source]

Creates new tag by sending a POST Request Endpoint: /api/tags

Parameters:

  • label ([str]) – [Label of the tag to be created]

  • color ([str]) – [Color of the tag to be created]

delete_job_by_id(job_id: int) → bool[source]

Send delete job request.

Method: DELETE Endpoint: /api/jobs/{job_id}

Parameters:

job_id (int) – id of job to kill

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

deleted or not

Return type:

Bool

delete_tag_by_id(tag_id: int) → bool[source]

Send delete tag request.

Method: DELETE Endpoint: /api/tags/{tag_id}

Parameters:

tag_id (int) – id of tag to delete

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

deleted or not

Return type:

Bool

download_sample(job_id: int) → bytes[source]

Download file sample from job.

Method: GET Endpoint: /api/jobs/{job_id}/download_sample

Parameters:

job_id (int) – id of job to download sample from

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

Raw file data.

Return type:

Bytes

edit_tag(tag_id: Union[int, str], label: str, color: str)[source]

Edits existing tag by sending PUT request Endpoint: api/tags

Parameters:

  • id ([int]) – [Id of the existing tag]

  • label ([str]) – [Label of the tag to be created]

  • color ([str]) – [Color of the tag to be created]

get_all_jobs() → List[Dict[str, Any]][source]

Fetch list of all jobs.

Endpoint: /api/jobs

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

Dict with 3 keys: “count”, “total_pages”, “results”

Return type:

Dict

get_all_tags() → List[Dict[str, str]][source]

Fetch list of all tags.

Endpoint: /api/tags

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

List of tags

Return type:

List[Dict[str, str]]

get_analyzer_configs()[source]

Get current state of analyzer_config.json from the IntelOwl instance.

Endpoint: /api/get_analyzer_configs

get_connector_configs()[source]

Get current state of connector_config.json from the IntelOwl instance.

Endpoint: /api/get_connector_configs

get_job_by_id(job_id: Union[int, str]) → Dict[str, Any][source]

Fetch job info by ID. Endpoint: /api/jobs/{job_id}

Parameters:

job_id (Union[int, str]) – Job ID

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

JSON body.

Return type:

Dict[str, Any]

static get_md5(to_hash: AnyStr, type_='observable') → str[source]

Returns md5sum of given observable or file object.

Parameters:

  • to_hash (AnyStr) – either an observable string, file contents as bytes or path to a file

  • type (Union["observable", "binary", "file"], optional) – observable, binary, file. Defaults to “observable”.

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

md5sum

Return type:

str

get_playbook_configs()[source]

Get current state of playbook_config.json from the IntelOwl instance.

Endpoint: /api/get_playbook_configs

get_tag_by_id(tag_id: Union[int, str]) → Dict[str, str][source]

Fetch tag info by ID.

Endpoint: /api/tag/{tag_id}

Parameters:

tag_id (Union[int, str]) – Tag ID

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

Dict with 3 keys: id, label and color.

Return type:

Dict[str, str]

kill_analyzer(job_id: int, analyzer_name: str) → bool[source]

Send kill running/pending analyzer request.

Method: PATCH Endpoint: /api/jobs/{job_id}/analyzer/{analyzer_name}/kill

Parameters:

  • job_id (int) – id of job

  • analyzer_name (str) – name of analyzer to kill

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

killed or not

Return type:

Bool

kill_connector(job_id: int, connector_name: str) → bool[source]

Send kill running/pending connector request.

Method: PATCH Endpoint: /api/jobs/{job_id}/connector/{connector_name}/kill

Parameters:

  • job_id (int) – id of job

  • connector_name (str) – name of connector to kill

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

killed or not

Return type:

Bool

kill_running_job(job_id: int) → bool[source]

Send kill_running_job request.

Method: PATCH Endpoint: /api/jobs/{job_id}/kill

Parameters:

job_id (int) – id of job to kill

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

killed or not

Return type:

Bool

logger: Logger
retry_analyzer(job_id: int, analyzer_name: str) → bool[source]

Send retry failed/killed analyzer request.

Method: PATCH Endpoint: /api/jobs/{job_id}/analyzer/{analyzer_name}/retry

Parameters:

  • job_id (int) – id of job

  • analyzer_name (str) – name of analyzer to retry

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

success or not

Return type:

Bool

retry_connector(job_id: int, connector_name: str) → bool[source]

Send retry failed/killed connector request.

Method: PATCH Endpoint: /api/jobs/{job_id}/connector/{connector_name}/retry

Parameters:

  • job_id (int) – id of job

  • connector_name (str) – name of connector to retry

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

success or not

Return type:

Bool

send_analysis_batch(rows: List[Dict])[source]

Send multiple analysis requests. Can be mix of observable or file analysis requests.

Used by the pyintelowl CLI.

Parameters:

rows (List[Dict]) – Each row should be a dictionary with keys, value, type, check, tlp, analyzers_list, connectors_list, runtime_config tags_list.

send_file_analysis_playbook_request(filename: str, binary: bytes, tlp: Optional[typing_extensions.Literal[WHITE, GREEN, AMBER, RED, CLEAR]] = None, playbooks_requested: Optional[List[str]] = None, runtime_configuration: Optional[Dict] = None, tags_labels: Optional[List[str]] = None) → Dict[source]

Send playbook analysis request for a file.

Endpoint: /api/playbook/analyze_multiple_files

Parameters:

  • filename (str) – Filename

  • binary (bytes) – File contents as bytes

  • playbooks_requested (List[str], optional) – List of specific playbooks to invoke. Defaults to [] i.e. all playbooks.

  • tlp (str, optional) – TLP for the analysis. (options: WHITE, GREEN, AMBER, RED). Defaults to WHITE.

  • runtime_configuration (Dict, optional) – Overwrite configuration for analyzers. Defaults to {}.

  • tags_labels (List[str], optional) – List of tag labels to assign (creates non-existing tags)

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

JSON body

Return type:

Dict

send_file_analysis_request(filename: str, binary: bytes, tlp: Optional[typing_extensions.Literal[WHITE, GREEN, AMBER, RED, CLEAR]] = None, analyzers_requested: Optional[List[str]] = None, connectors_requested: Optional[List[str]] = None, runtime_configuration: Optional[Dict] = None, tags_labels: Optional[List[str]] = None) → Dict[source]

Send analysis request for a file.

Endpoint: /api/analyze_file

Parameters:

  • filename (str) – Filename

  • binary (bytes) – File contents as bytes

  • analyzers_requested (List[str], optional) – List of analyzers to invoke Defaults to [] i.e. all analyzers.

  • connectors_requested (List[str], optional) – List of specific connectors to invoke. Defaults to [] i.e. all connectors.

  • tlp (str, optional) – TLP for the analysis. (options: WHITE, GREEN, AMBER, RED). Defaults to WHITE.

  • runtime_configuration (Dict, optional) – Overwrite configuration for analyzers. Defaults to {}.

  • tags_labels (List[str], optional) – List of tag labels to assign (creates non-existing tags)

Raises:

IntelOwlClientException – on client/HTTP error

Returns:

JSON body

Return type:

Dict

send_observable_analysis_playbook_request(observable_name: str, tlp: Optional[typing_extensions.Literal[WHITE, GREEN, AMBER, RED, CLEAR]] = None, playbooks_requested: Optional[List[str]] = None, runtime_configuration: Optional[Dict] = None, tags_labels: Optional[List[str]] = None, observable_classification: Optional[str] = None) → Dict[source]

Send playbook analysis request for an observable.

Endpoint: /api/playbook/analyze_multiple_observables

Parameters:

  • observable_name (str) – Observable value

  • playbooks_requested (List[str], optional) – List of specific playbooks to invoke. Defaults to [] i.e. all playbooks.

  • tlp (str, optional) – TLP for the analysis. (options: WHITE, GREEN, AMBER, RED). Defaults to WHITE.

  • runtime_configuration (Dict, optional) – Overwrite configuration for analyzers. Defaults to {}.

  • tags_labels (List[str], optional) – List of tag labels to assign (creates non-existing tags)

  • observable_classification (str) – Observable classification, Default to None. By default launch analysis with an automatic classification. (options: url, domain, hash, ip, generic)

Raises:
Returns:

JSON body

Return type:

Dict

send_observable_analysis_request(observable_name: str, tlp: Optional[typing_extensions.Literal[WHITE, GREEN, AMBER, RED, CLEAR]] = None, analyzers_requested: Optional[List[str]] = None, connectors_requested: Optional[List[str]] = None, runtime_configuration: Optional[Dict] = None, tags_labels: Optional[List[str]] = None, observable_classification: Optional[str] = None) → Dict[source]

Send analysis request for an observable.

Endpoint: /api/analyze_observable

Parameters:

  • observable_name (str) – Observable value

  • analyzers_requested (List[str], optional) – List of analyzers to invoke Defaults to [] i.e. all analyzers.

  • connectors_requested (List[str], optional) – List of specific connectors to invoke. Defaults to [] i.e. all connectors.

  • tlp (str, optional) – TLP for the analysis. (options: WHITE, GREEN, AMBER, RED). Defaults to WHITE.

  • runtime_configuration (Dict, optional) – Overwrite configuration for analyzers. Defaults to {}.

  • tags_labels (List[str], optional) – List of tag labels to assign (creates non-existing tags)

  • observable_classification (str) – Observable classification, Default to None. By default launch analysis with an automatic classification. (options: url, domain, hash, ip, generic)

Raises:
Returns:

JSON body

Return type:

Dict

property session: Session

Internal use only.

IntelOwlClientException class

class pyintelowl.exceptions.IntelOwlClientException(*args, **kwargs)[source]

Bases: RequestException

property error_detail: Union[Dict, AnyStr]