polyswarm_api.api

Module Contents

polyswarm_api.api.logger

class polyswarm_api.api.PolyswarmAPI(key, uri=None, community=None, timeout=None, verify=True, **kwargs)

Bases: object

A synchronous interface to the public and private PolySwarm APIs.

engines

refresh_engine_cache(self)

Rrefresh the cached engine listing

wait_for(self, scan, timeout=settings.DEFAULT_SCAN_TIMEOUT)

Wait for a Scan to scan successfully

Parameters

• scan – Scan id to wait for

• timeout – Maximum time in seconds to wait before raising a TimeoutException

Returns

The ArtifactInstance resource waited on

exists(self, hash_, hash_type=None)

Search for the latest scans matching the given hash and hash_type.

Parameters

• hash – A Hashable object (Artifact, local.LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5

• hash_type – Hash type of the provided hash_. Will attempt to auto-detect if not explicitly provided.

Returns

A boolean if the instance exists for search.

search(self, hash_, hash_type=None)

Search for the latest scans matching the given hash and hash_type.

Parameters

• hash – A Hashable object (Artifact, local.LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5

• hash_type – Hash type of the provided hash_. Will attempt to auto-detect if not explicitly provided.

Returns

Generator of ArtifactInstance resources

search_url(self, url)

Search for the latest scan matching the given url.

Parameters

url – A url to be searched by exact match

Returns

Generator of ArtifactInstance resources

search_scans(self, hash_)

Search for all scans ever made matching the given sha256.

Parameters

hash – A Hashable object (Artifact, local.LocalArtifact, Hash) or hex-encoded SHA256

Returns

Generator of ArtifactInstance resources

metadata_mapping(self)

search_by_metadata(self, query, include=None, exclude=None, ips=None, urls=None, domains=None)

Search artifacts by metadata

Parameters

• query – A query string

• include – A list of fields to be included in the result (.* wildcards are accepted)

• exclude – A list of fields to be excluded from the result (.* wildcards are accepted)

Returns

Generator of ArtifactInstance resources

iocs_by_hash(self, hash_type, hash_value, hide_known_good=False)

Retrieve IOCs by artifact hash

Parameters

• hash_type – Hash type of the provided hash_

• hash_value – A list of fields to be included in the result (.* wildcards are accepted)

Returns

Generator of IOC resources

search_by_ioc(self, ip=None, domain=None, ttp=None, imphash=None)

Search artifacts by IOC (ip, domain, ttp, or imphash)

Parameters

• ip – ip address to search by

• domain – domain address to search by

• ttp – ttp to search by

• imphash – ImpHash to search by

Returns

Generator of ArtifactInstance resources

check_known_hosts(self, ips=[], domains=[])

Check if ip addresses or domains are known.

:param ips :param domains :return: Generator of IOC resources

add_known_good_host(self, type, source, host)

Add a known good ip or domain.

:param type :param source :param host :return: IOC resource

update_known_good_host(self, id, type, source, host, good)

Update a known ip or domain.

:param type :param source :param host :return: IOC resource

delete_known_good_host(self, id)

submit(self, artifact, artifact_type=resources.ArtifactType.FILE, artifact_name=None, scan_config=None)

Submit artifacts to polyswarm and return UUIDs

Parameters

• artifact – A file-like, path to file, url or LocalArtifact instance

• artifact_type – The ArtifactType or strings containing “file” or “url”

• artifact_name – An appropriate filename for the Artifact

• scan_config – The scan configuration to be used, e.g.: “default”, “more-time”, “most-time”

Returns

An ArtifactInstance resource

lookup(self, scan)

Lookup a scan by Scan id.

Parameters

scan – The Scan UUID to lookup

Returns

An ArtifactInstance resource

rescan(self, hash_, hash_type=None, scan_config=None)

Rescan a file based on and existing hash in the Polyswarm platform

Parameters

• hash – Hashable object (Artifact, local.LocalArtifact, or Hash) or hex-encoded SHA256/SHA1/MD5

• hash_type – Hash type of the provided hash_. Will attempt to auto-detect if not explicitly provided.

• scan_config – The scan configuration to be used, e.g.: “default”, “more-time”, “most-time”

Returns

A ArtifactInstance resources

rescan_id(self, scan, scan_config=None)

Re-execute a new scan based on an existing scan.

Parameters

• scan – Id of the existing scan

• scan_config – The scan configuration to be used, e.g.: “default”, “more-time”, “most-time”

Returns

A ArtifactInstance resource

_parse_rule(self, rule)

live_start(self, rule_id)

Create a new live hunt_id, and replace the currently running YARA rules.

Parameters

rule_id – Yara ruleset id

Returns

The ruleset with the associated live hunt

live_stop(self, rule_id)

Stop a live hunt.

Parameters

rule_id – Yara ruleset id

Returns

The ruleset without an associate live hunt

live_feed(self, since=None, rule_name=None, family=None, polyscore_lower=None, polyscore_upper=None, community=None)

Get live hunts feed

Parameters

• since – Fetch results from the last “since” minutes

• rule_name – Filter hunt results on the provided rule name (exact match).

• family – Filter hunt results based on the family name (exact match).

• polyscore_lower – Polyscore lower bound for the hunt results.

• polyscore_upper – Polyscore upper bound for the hunt results.

• community – Community to retrieve live results from, or public/private.

Returns

Generator of HuntResult resources

live_feed_delete(self, result_ids)

Delete live feed results

Parameters

result_ids – Live Feed Result IDs

Returns

The deleted LiveHuntResult resources

live_result(self, result_id)

Get yara ruleset for the live hunt result

Parameters

result_id – Live result id

Returns

Generator of HuntResult resources

historical_create(self, rule=None, ruleset_name=None)

Run a new historical hunt.

Parameters

• rule – YaraRuleset object or string containing YARA rules to install

• ruleset_name – Name of the ruleset.

Returns

The created Hunt resource

historical_get(self, hunt=None)

Get a historical hunt.

Parameters

hunt – Hunt ID

Returns

The Hunt resource

historical_update(self, hunt)

Cancel a historical hunt :param hunt: The historical hunt id :return: The deleted HistoricalHunt resource

historical_delete(self, hunt)

Delete a historical hunts.

Parameters

hunt – Hunt ID

Returns

The deleted Hunt resource

historical_list(self, since=None)

List all historical hunts

Returns

Generator of Hunt resources

historical_result(self, result_id)

Get historical hunt result

Parameters

result_id – Historical result id

Returns

HistoricalHuntResult resource

historical_results(self, hunt=None, rule_name=None, family=None, polyscore_lower=None, polyscore_upper=None, community=None)

Get results from a historical hunt

Parameters

• hunt – ID of the hunt (None if latest hunt results are desired)

• rule_name – Filter hunt results on the provided rule name (exact match).

• family – Filter hunt results based on the family name (exact match).

• polyscore_lower – Polyscore lower bound for the hunt results.

• polyscore_upper – Polyscore upper bound for the hunt results.

• community – Community to retrieve live results from, or public/private.

Returns

Generator of HuntResult resources

historical_results_delete(self, result_ids)

Delete historical scan results

Parameters

result_ids – Historical Hunt Result IDs

Returns

The deleted HuntResult resources

historical_delete_list(self, historical_ids)

Delete a historical hunts.

Parameters

historical_ids – Historical Hunt IDs

Returns

The deleted Hunt resource

ruleset_create(self, name, rules, description=None)

Create a Yara Ruleset from the provided rules with the given name in the polyswarm platform. :param name: Name of the ruleset :param rules: Yara rules as a string :param description: Description of the ruleset :return: A YaraRuleset resource

ruleset_get(self, ruleset_id=None)

Retrieve a YaraRuleset from the polyswarm platform by its Id. :param ruleset_id: Id of the ruleset :return: A YaraRuleset resource

ruleset_update(self, ruleset_id, name=None, rules=None, description=None)

Update an existing YaraRuleset in the polyswarm platform by its Id. :param ruleset_id: Id of the ruleset :param name: New name of the ruleset :param rules: New yara rules as a string :param description: New description of the ruleset :return: The updated YaraRuleset resource

ruleset_delete(self, ruleset_id)

Delete a YaraRuleset from the polyswarm platform by its Id. :param ruleset_id: Id of the ruleset :return: A YaraRuleset resource

ruleset_list(self)

List all YaraRulesets for the current account. :return: A generator of YaraRuleset resources

tag_link_get(self, sha256)

Fetch the Tags and Families associated with the given sha256.

Parameters

sha256 – The sha256 of the artifact.

Returns

A TagLink resource

tag_link_update(self, sha256, tags=None, families=None, emerging=None, remove=False)

Update a TagLink with the given type or value by its id. :param sha256: The sha256 of the artifact. :param tags: A list of tags to be added or removed. :param families: A list of families to be added or removed. :param remove: A flag indicating if we should remove the provided tags/families. :return: A TagLink resource

tag_link_list(self, tags=None, families=None, or_tags=None, or_families=None)

Fetch all existing TagLinks for the provided tags. :param tags: A list of tags that must be associated with the TagLinks listed. :param families: A list of families that must be associated with the TagLinks listed. :param or_tags: A list of tags where the TagLinks must be associated with at least one. :param or_families: A list of families where the TagLinks must be associated with at least one. :return: A TagLink resource

tag_create(self, name)

Create a Tag. :param name: The tag we want to create. :return: A Tag resource

tag_get(self, name)

Fetch a Tag. :param name: The tag we want to fetch. :return: A Tag resource

tag_delete(self, name)

Delete a Tag. :param name: The tag we want to delete. :return: A Tag resource

tag_list(self)

Fetch all existing Tags. :return: A generator of Tag resources

family_create(self, name)

Create a Family. :param name: The family name. :return: A MalwareFamily resource

family_get(self, name)

Fetch a Family. :param name: The family name. :return: A MalwareFamily resource

family_delete(self, name)

Delete a Family. :param name: The family name. :return: A MalwareFamily resource

family_update(self, family_name, emerging=True)

Update the Family emerging status. :param family_name: The family name. :param emerging: A flag indicating if the family should be marked as emerging at this point in time. :return: A MalwareFamily resource

family_list(self)

Fetch all existing Families :return: A generator of MalwareFamily resources

assertions_create(self, engine_id, date_start, date_end)

assertions_get(self, assertions_id)

assertions_delete(self, assertions_id)

assertions_list(self, engine_id)

votes_create(self, engine_id, date_start, date_end)

votes_get(self, votes_id)

votes_delete(self, votes_id)

votes_list(self, engine_id)

download(self, out_dir, hash_, hash_type=None)

Grab the data of artifact identified by hash, and write the data to a file in the provided directory under a file named after the hash_. :param out_dir: Destination directory to download the file. :param hash_: The hash we should use to lookup the artifact to download. :param hash_type: Hash type of the provided hash_. Will attempt to auto-detect if not explicitly provided. :return: A LocalArtifact resource

download_id(self, out_dir, instance_id)

Grab the data of artifact identified by hash, and write the data to a file in the provided directory under a file named after the hash_. :param out_dir: Destination directory to download the file. :param instance_id: The instance id we should use to lookup the artifact to download. :return: A LocalArtifact resource

sandbox(self, instance_id, provider_slug, vm_slug)

sandbox_file(self, artifact, provider_slug, vm_slug, artifact_type=resources.ArtifactType.FILE, artifact_name=None)

sandbox_providers(self)

List sandboxes available in polyswarm.

sandbox_task_status(self, sandbox_task_id)

Check the status of a sandbox task.

sandbox_task_latest(self, sha256, sandbox)

Check the latest status of a sandbox task.

sandbox_my_tasks_list(self, **kwargs)

Check the latest status of a sandbox task.

sandbox_task_list(self, sha256, **kwargs)

Check the list of a sandbox tasks.

download_archive(self, out_dir, s3_path)

Grab the data in the s3 path provided in the stream() method, and write the contents in the provided directory. :param out_dir: Destination directory to download the file. :param s3_path: Target S3 object to download. :return: A LocalArtifact resource

download_to_handle(self, hash_, fh, hash_type=None)

Grab the data of artifact identified by hash, and write the data to a file handle :param hash_: The hash we should use to lookup the artifact to download. :param fh: A file-like object which we are going to write the contents of the artifact to. :param hash_type: Hash type of the provided hash_. Will attempt to auto-detect if not explicitly provided. :return: A LocalHandle resource

stream(self, since=settings.MAX_SINCE_TIME_STREAM)

Access the stream of artifacts (ask info@polyswarm.io about access)

Parameters

since – Fetch results from the last “since” minutes (up to 2 days)

Returns

Generator of ArtifactArchive resources

rerun_metadata(self, hashes, analyses=None, skip_es=None)

tool_metadata_create(self, instance_id, tool, tool_metadata)

tool_metadata_list(self, instance_id)

__repr__(self)