polyswarm-api 3.7.0__tar.gz → 3.9.0__tar.gz

{polyswarm-api-3.7.0/src/polyswarm_api.egg-info → polyswarm-api-3.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: polyswarm-api
-Version: 3.7.0
+Version: 3.9.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Home-page: https://github.com/polyswarm/polyswarm-api
 Author: PolySwarm Developers

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0}/setup.py

@@ -9,7 +9,7 @@ with open('README.md', 'r') as readme:
 
 setup(
     name='polyswarm-api',
-    version='3.7.0',
+    version='3.9.0',
     description='Client library to simplify interacting with the PolySwarm consumer API',
     long_description=long_description,
     long_description_content_type='text/markdown',

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0}/src/polyswarm_api/__init__.py

@@ -1,5 +1,5 @@
 # https://www.python.org/dev/peps/pep-0008/#module-level-dunder-names
-__version__ = '3.7.0'
+__version__ = '3.9.0'
 __release_url__ = 'https://api.github.com/repos/polyswarm/polyswarm-api/releases/latest'
 
 from . import api

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0}/src/polyswarm_api/api.py

@@ -1,3 +1,4 @@
+import io
 import logging
 import time
 
@@ -211,22 +212,33 @@ class PolyswarmAPI:
         logger.info('Deleting known good ioc %s', id)
         return resources.IOC.delete_known_good(self, id).result()
 
-    def submit(self, artifact, artifact_type=resources.ArtifactType.FILE, artifact_name=None, scan_config=None):
+    def submit(
+            self,
+            artifact,
+            artifact_type=resources.ArtifactType.FILE,
+            artifact_name=None,
+            scan_config=None,
+            preprocessing=None,
+    ):
         """
-        Submit artifacts to polyswarm and return UUIDs
+        Submit artifacts to polyswarm
 
         :param artifact: A file-like, path to file, url or LocalArtifact instance
         :param artifact_type: The ArtifactType or strings containing "file" or "url"
         :param artifact_name: An appropriate filename for the Artifact
         :param scan_config: The scan configuration to be used, e.g.: "default", "more-time", "most-time"
+        :param preprocessing: Preprocessing settings to be applied to the artifact, None means no preprocessing,
+                              otherwise a dict with the following attributes can be passed:
+                              - type (string): either "zip" or "qrcode", the first mean the file is a zip that
+                                the server has to decompress to then scan the content (only one file inside allowed).
+                                "qrcode" means the file is a QR Code image with a URL as payload, and you want
+                                to scan the URL, not the actual file (artifact_type has to be "URL").
+                              - password (string, optional): will use this password to decompress the zip file.
         :return: An ArtifactInstance resource
         """
         logger.info('Submitting artifact of type %s', artifact_type)
         artifact_type = resources.ArtifactType.parse(artifact_type)
-        # TODO This is a python 2.7 check if artifact is a file-like instance, consider changing
-        #  to isinstance(artifact, io.IOBase) when deprecating 2.7 and implementing making LocalHandle
-        #  inherit io.IOBase, although this will change the method delegation logic in the resource
-        if hasattr(artifact, 'read') and hasattr(artifact.read, '__call__'):
+        if isinstance(artifact, io.IOBase):
             artifact = resources.LocalArtifact.from_handle(self, artifact, artifact_name=artifact_name or '',
                                                            artifact_type=artifact_type)
         elif isinstance(artifact, str):
@@ -234,16 +246,27 @@ class PolyswarmAPI:
                 artifact = resources.LocalArtifact.from_path(self, artifact, artifact_type=artifact_type,
                                                              artifact_name=artifact_name)
             elif artifact_type == resources.ArtifactType.URL:
-                artifact = resources.LocalArtifact.from_content(self, artifact, artifact_name=artifact_name or artifact,
-                                                                artifact_type=artifact_type)
+                if preprocessing and preprocessing['type'] == 'qrcode':
+                    artifact = resources.LocalArtifact.from_path(self,
+                                                                 artifact,
+                                                                 artifact_type=artifact_type,
+                                                                 artifact_name=artifact_name)
+                else:
+                    artifact = resources.LocalArtifact.from_content(self,
+                                                                    artifact,
+                                                                    artifact_name=artifact_name or artifact,
+                                                                    artifact_type=artifact_type)
         if artifact_type == resources.ArtifactType.URL:
             scan_config = scan_config or 'more-time'
         if isinstance(artifact, resources.LocalArtifact):
-            instance = resources.ArtifactInstance.create(self,
-                                                         artifact_name=artifact.artifact_name,
-                                                         artifact_type=artifact.artifact_type.name,
-                                                         scan_config=scan_config,
-                                                         community=self.community).result()
+            instance = resources.ArtifactInstance.create(
+                self,
+                artifact_name=artifact.artifact_name,
+                artifact_type=artifact.artifact_type.name,
+                scan_config=scan_config,
+                community=self.community,
+                preprocessing=preprocessing,
+            ).result()
             instance.upload_file(artifact)
             return resources.ArtifactInstance.update(self, id=instance.id, community=self.community).result()
         else:
@@ -690,13 +713,43 @@ class PolyswarmAPI:
         return resources.SandboxTask.create(self, artifact_id=instance_id, provider_slug=provider_slug, vm_slug=vm_slug,
                                             network_enabled=network_enabled).result()
 
-    def sandbox_file(self, artifact, provider_slug, vm_slug, artifact_type=resources.ArtifactType.FILE, artifact_name=None, network_enabled=True):
-        logger.info('Sandboxing file in provider %s vm %s', provider_slug, vm_slug)
+    def sandbox_file(
+            self,
+            artifact,
+            provider_slug,
+            vm_slug,
+            artifact_type=resources.ArtifactType.FILE,
+            artifact_name=None,
+            network_enabled=True,
+            preprocessing=None,
+    ):
+        """
+        Submit artifacts to Polyswarm Sandboxing system.
+
+        :param artifact: A file-like, path to file, url or LocalArtifact instance
+        :param artifact_name: An appropriate filename for the Artifact
+        :artifact_type: the type of artifact to be submitted, default FILE. Use URL type
+                        with the preprocessing field to scan URLs inside QR Code images
+        :param network_enabled: Whether the VM has to have Internet connection enabled or not.
+        :param provider_slug: the slug of the provider that is going to execute the sandboxing, e.g.
+                              'cape' or 'triage'.
+                              Use `sandbox_providers()` to get the list of providers.
+        :param vm_slug: The slug of the virtual machine used for the sandboxing, depending on the
+                        VM chosen is the OS and software that is going to host the sandboxing. Each
+                        provider (provider_slug) support different VMs, so check with `sandbox_providers()`
+                        the list of VMs available.
+        :param preprocessing: Preprocessing settings to be applied to the artifact, None means no preprocessing,
+                              otherwise a dict with the following attributes can be passed:
+                              - type (string): either "zip" or "qrcode", the first mean the file is a zip that
+                                the server has to decompress to then scan the content (only one file inside allowed).
+                                "qrcode" means the file is a QR Code image with a URL as payload, and you want
+                                to scan the URL, not the actual file (artifact_type has to be "URL").
+                              - password (string, optional): will use this password to decompress the zip file.
+        :return: An ArtifactInstance resource
+        """
+        logger.info('Sandboxing %s in provider %s vm %s', artifact_type.name.lower(), provider_slug, vm_slug)
         artifact_type = resources.ArtifactType.parse(artifact_type)
-        # TODO This is a python 2.7 check if artifact is a file-like instance, consider changing
-        #  to isinstance(artifact, io.IOBase) when deprecating 2.7 and implementing making LocalHandle
-        #  inherit io.IOBase, although this will change the method delegation logic in the resource
-        if hasattr(artifact, 'read') and hasattr(artifact.read, '__call__'):
+        if isinstance(artifact, io.IOBase):
             artifact = resources.LocalArtifact.from_handle(self, artifact, artifact_name=artifact_name or '',
                                                            artifact_type=artifact_type)
         elif isinstance(artifact, str):
@@ -708,29 +761,84 @@ class PolyswarmAPI:
                                                                 artifact_name=artifact_name or artifact,
                                                                 artifact_type=artifact_type)
         if isinstance(artifact, resources.LocalArtifact):
-            task = resources.SandboxTask.create_file(self,
-                                                     artifact_name=artifact.artifact_name,
-                                                     artifact_type=artifact.artifact_type.name,
-                                                     community=self.community,
-                                                     provider_slug=provider_slug,
-                                                     vm_slug=vm_slug,
-                                                     network_enabled=network_enabled).result()
+            task = resources.SandboxTask.create_file(
+                self,
+                artifact_name=artifact.artifact_name,
+                artifact_type=artifact.artifact_type.name,
+                community=self.community,
+                provider_slug=provider_slug,
+                vm_slug=vm_slug,
+                network_enabled=network_enabled,
+                preprocessing=preprocessing,
+            ).result()
             task.upload_file(artifact)
             return resources.SandboxTask.update_file(self, id=task.id, community=self.community).result()
         else:
             raise exceptions.InvalidValueException(
                 'Artifacts should be a path to a file or a LocalArtifact instance')
 
-    def sandbox_url(self, url, provider_slug, vm_slug, browser=None):
+    def sandbox_url(self,
+                    url,
+                    provider_slug,
+                    vm_slug,
+                    browser=None,
+                    artifact=None,
+                    artifact_name=None,
+                    preprocessing=None):
+        """
+        Submit URL to Polyswarm Sandboxing system.
+        :param url: A string with the URL to be submitted. Set to `None` if the URL is provided
+                    through a QR Code image in the artifact param (see artifact and preprocessing params).
+        :param provider_slug: the slug of the provider that is going to execute the sandboxing, e.g.
+                              'cape' or 'triage'.
+                              Use `sandbox_providers()` to get the list of providers.
+        :param vm_slug: The slug of the virtual machine used for the sandboxing, depending on the
+                        VM chosen is the OS and software that is going to host the sandboxing. Each
+                        provider (provider_slug) support different VMs, so check with `sandbox_providers()`
+                        the list of VMs available.
+        :param browser: browser name, e.g. 'edge' or 'firefox'.
+        :param artifact: A file-like, path to file, or LocalArtifact instance (default None). The url
+                         param has to be None to use this param. For now QR Code image files
+                         are supported
+        :param artifact_name: name of the artifact, if None (default) the URL string is used as a name,
+                              or the file name if artifact is provided (QR Code image file).
+        :param preprocessing: Preprocessing settings to be applied to the artifact, None means no preprocessing,
+                              otherwise a dict with the following attributes can be passed:
+                              - type (string): only "qrcode" is supported for URL sandboxing:
+                                the file is a QR Code image with a URL as payload, and you want
+                                to scan the URL, not the actual file. This argument has to be used with the
+                                `artifact` param, and `url` set to `None`.
+        """
         logger.info('Sandboxing url in provider %s vm %s', provider_slug, vm_slug)
-        artifact = resources.LocalArtifact.from_content(self, url, artifact_name=url, artifact_type='URL')
+        if artifact and url:
+            raise exceptions.InvalidValueException("Cannot use artifact with url param")
+        if artifact:
+            if not preprocessing or preprocessing.get('type') != 'qrcode':
+                raise exceptions.InvalidValueException("Only artifact of type qrcode is supported")
+            if isinstance(artifact, str):
+                artifact = resources.LocalArtifact.from_path(self,
+                                                             artifact,
+                                                             artifact_type='URL',
+                                                             artifact_name=artifact_name)
+            else:
+                artifact = resources.LocalArtifact.from_handle(self,
+                                                               artifact,
+                                                               artifact_name=artifact_name or '',
+                                                               artifact_type='URL')
+        else:
+            artifact_name = url
+            artifact = resources.LocalArtifact.from_content(self,
+                                                            url,
+                                                            artifact_name=artifact_name,
+                                                            artifact_type='URL')
         task = resources.SandboxTask.create_file(self,
-                                                 artifact_name=url,
+                                                 artifact_name=artifact_name,
                                                  artifact_type="URL",
                                                  community=self.community,
                                                  provider_slug=provider_slug,
                                                  vm_slug=vm_slug,
                                                  browser=browser,
+                                                 preprocessing=preprocessing,
                                                  network_enabled=True).result()
         task.upload_file(artifact)
         return resources.SandboxTask.update_file(self, id=task.id, community=self.community).result()
@@ -823,18 +931,62 @@ class PolyswarmAPI:
         logger.info('List events')
         return resources.Events.list(self, **kwargs).result()
 
-    def report_create(self, **kwargs):
-        return resources.ReportTask.create(self, **kwargs).result()
-
-    def report_get(self, **kwargs):
-        return resources.ReportTask.get(self, **kwargs).result()
+    def report_create(self,
+                      type,
+                      format,
+                      instance_id=None,
+                      sandbox_task_id=None,
+                      template_id=None,
+                      template_metadata=None,
+                      **kwargs):
+        """
+        Create a report, either 'pdf' or 'html' (format argument).
+        Regarding the type argument, either instance_id (type='scan')
+        or sandbox_task_id (type='sandbox') has to be provided.
+        """
+        report = resources.ReportTask.create(self,
+                                             type=type,
+                                             format=format,
+                                             instance_id=instance_id,
+                                             sandbox_task_id=sandbox_task_id,
+                                             template_id=template_id,
+                                             template_metadata=template_metadata,
+                                             **kwargs).result()
+        return report
+
+    def report_get(self, id, **kwargs):
+        return resources.ReportTask.get(self, id=id, **kwargs).result()
 
     def report_download(self, report_id, folder):
         report = resources.ReportTask.get(self, id=report_id).result()
+        if report.state == 'PENDING':
+            raise exceptions.InvalidValueException('Report is in PENDING state, wait for completion first')
+        if report.state == 'FAILED':
+            raise exceptions.InvalidValueException("Report is in FAILED state, won't be generated")
         result = report.download_report(folder=folder).result()
         result.handle.close()
         return result
 
+    def report_wait_for(self, report_id, timeout=settings.DEFAULT_REPORT_TIMEOUT):
+        """
+        Wait for a Report to finish successfully.
+
+        :param report_id: Report id to wait for
+        :param timeout: Maximum time in seconds to wait before raising a TimeoutException
+        :return: The ReportTask resource waited on, either in 'SUCCEEDED' or 'FAILED' state
+        """
+        logger.info('Waiting for report %s', report_id)
+        start = time.time()
+        while True:
+            report_result = self.report_get(id=report_id)
+            if report_result.state != 'PENDING':
+                return report_result
+            elif -1 < timeout < time.time() - start:
+                raise exceptions.TimeoutException(
+                    f'Timed out waiting for report {report_id} to finish. Please try again.')
+            else:
+                time.sleep(settings.POLL_FREQUENCY)
+
     def report_template_logo_download(self, template_id, folder):
         report = resources.ReportTemplate.get(self, id=template_id).result()
         result = report.download_logo(folder).result()
@@ -851,11 +1003,50 @@ class PolyswarmAPI:
         result = report.upload_logo(logo_file, content_tpe).result()
         return result
 
-    def report_template_create(self, **kwargs):
-        return resources.ReportTemplate.create(self, **kwargs).result()
-
-    def report_template_update(self, template_id, **kwargs):
-        return resources.ReportTemplate.update(self, id=template_id, **kwargs).result()
+    def report_template_create(self,
+                               template_name,
+                               is_default=False,
+                               primary_color=None,
+                               footer_text=None,
+                               last_page_text=None,
+                               includes=None,
+                               **kwargs):
+        """
+        Create a template for reports.
+        A team account can have multiple templates, and setting is_default=True
+        makes it the default when a report is created without specifying template_id
+        (see report_create method).
+        The includes argument can be a list with sections to be included
+        in the reports. The list can include any of the following section names:
+        summary, detections, fileMetadata, network, droppedFiles, extractedConfig, analysis.
+        """
+        return resources.ReportTemplate.create(self,
+                                               template_name=template_name,
+                                               is_default=is_default,
+                                               primary_color=primary_color,
+                                               footer_text=footer_text,
+                                               last_page_text=last_page_text,
+                                               includes=includes,
+                                               **kwargs).result()
+
+    def report_template_update(self,
+                               template_id,
+                               template_name=None,
+                               is_default=None,
+                               primary_color=None,
+                               footer_text=None,
+                               last_page_text=None,
+                               includes=None,
+                               **kwargs):
+        return resources.ReportTemplate.update(self,
+                                               id=template_id,
+                                               template_name=template_name,
+                                               is_default=is_default,
+                                               primary_color=primary_color,
+                                               footer_text=footer_text,
+                                               last_page_text=last_page_text,
+                                               includes=includes,
+                                               **kwargs).result()
 
     def report_template_get(self, template_id):
         return resources.ReportTemplate.get(self, id=template_id).result()
@@ -863,8 +1054,11 @@ class PolyswarmAPI:
     def report_template_delete(self, template_id):
         return resources.ReportTemplate.delete(self, id=template_id).result()
 
-    def report_template_list(self, is_default=None):
-        params = {}
-        if is_default is not None:
-            params['is_default'] = is_default
-        return resources.ReportTemplate.list(self, **params).result()
+    def report_template_list(self, is_default=None, **kwargs):
+        return resources.ReportTemplate.list(self, is_default=is_default, **kwargs).result()
+
+    def account_whois(self, **kwargs):
+        return resources.WhoIs.get(self, **kwargs).result()
+
+    def account_features(self, **kwargs):
+        return resources.AccountFeatures.get(self, **kwargs).result()

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0}/src/polyswarm_api/resources.py

@@ -1019,6 +1019,8 @@ class SandboxTask(core.BaseJsonResource):
         self.sha256 = content['sha256']
         self.report = content['report']
         self.upload_url = content['upload_url']
+        self.config = content['config']
+        self.artifact = content['artifact']
         self.sandbox_artifacts = [SandboxArtifact(a, api=api) for a in content.get('sandbox_artifacts', [])]
 
     def upload_file(self, artifact, attempts=3, **kwargs):
@@ -1203,3 +1205,48 @@ class ReportTemplate(core.BaseJsonResource):
             },
             result_parser=self.__class__
         ).execute()
+
+
+class AccountFeatures(core.BaseJsonResource):
+    RESOURCE_ENDPOINT = "/public/accounts"
+
+    def __init__(self, content, api=None):
+        super().__init__(content, api=api)
+        self.account_number = content['account_number']
+        self.user_account_number = content.get('user_account_number')
+        self.account_plan_name = content['account_plan_name']
+        self.plan_period_start = content['plan_period_start']
+        self.plan_period_end = content['plan_period_end']
+        self.window_start = content['window_start']
+        self.window_end = content['window_end']
+        self.tenant = content.get('tenant')
+        self.daily_api_limit = content['daily_api_limit']
+        self.daily_api_remaining = content['daily_api_remaining']
+        self.has_stream_access = content['has_stream_access']
+        self.is_trial = content['is_trial']
+        self.is_trial_expired = content['is_trial_expired']
+        self.trial_started_at = content['trial_started_at']
+        self.trial_ended_at = content['trial_ended_at']
+        self.features = []
+        for feature in content['features']:
+            self.features.append({
+                'base_uses': feature['base_uses'],
+                'name': feature['name'],
+                'overage': feature['overage'],
+                'remaining_uses': feature['remaining_uses'],
+                'tag': feature['tag'],
+                'value': feature['value'],
+            })
+
+
+class WhoIs(core.BaseJsonResource):
+    RESOURCE_ENDPOINT = "/public/accounts/whois"
+
+    def __init__(self, content, api=None):
+        super().__init__(content, api=api)
+        self.account_number = content['account_number']
+        self.user_account_number = content.get('user_account_number')
+        self.account_name = content['account_name']
+        self.account_type = content['account_type']
+        self.communities = content['communities']
+        self.tenant = content.get('tenant')

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0}/src/polyswarm_api/settings.py

@@ -7,6 +7,7 @@ DEFAULT_GLOBAL_API = 'https://api.polyswarm.network/v3'
 DEFAULT_PERMALINK_BASE = os.getenv('POLYSWARM_PORTAL_URI', 'https://polyswarm.network/scan/results/file')
 DEFAULT_COMMUNITY = 'default'
 DEFAULT_SCAN_TIMEOUT = 60*15
+DEFAULT_REPORT_TIMEOUT = 30
 RESULT_CHUNK_SIZE = 100
 POLL_FREQUENCY = 1
 

{polyswarm-api-3.7.0 → polyswarm-api-3.9.0/src/polyswarm_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: polyswarm-api
-Version: 3.7.0
+Version: 3.9.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Home-page: https://github.com/polyswarm/polyswarm-api
 Author: PolySwarm Developers