polyswarm-api 4.0.0__tar.gz → 4.2.0__tar.gz

{polyswarm_api-4.0.0/src/polyswarm_api.egg-info → polyswarm_api-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyswarm_api
-Version: 4.0.0
+Version: 4.2.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Author-email: PolySwarm Developers <info@polyswarm.io>
 License: MIT

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polyswarm_api"
-version = "4.0.0"
+version = "4.2.0"
 description = "Client library to simplify interacting with the PolySwarm consumer API"
 readme = "README.md"
 requires-python = ">=3.10,<4"
@@ -55,7 +55,7 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.bumpversion]
-current_version = "4.0.0"
+current_version = "4.2.0"
 commit = true
 tag = false
 sign_tags = true

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/__init__.py

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

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/aio/api.py

@@ -767,6 +767,49 @@ class PolySwarmAsyncAPI:
         async for item in self._paginate(resources.Tag.list(self)):
             yield item
 
+    async def known_good_create(self, sha256, source, sha1=None, md5=None,
+                                filename=None, mimetype=None, metadata=None):
+        """
+        Record a hash as a known-good binary (internal-only). The first feed for a
+        sha256 creates the searchable reference; a different ``source`` for an
+        existing sha256 just records that feed.
+
+        :param sha256: The sha256 of the known-good binary.
+        :param source: The feed/source flagging this hash (becomes a metadata tool).
+        :param sha1: Optional sha1.
+        :param md5: Optional md5.
+        :param filename: Optional filename.
+        :param mimetype: Optional mimetype.
+        :param metadata: Optional dict of extra feed metadata.
+        :return: A KnownGood resource
+        """
+        logger.info('Create known-good %s from %s', sha256, source)
+        return await self._single(resources.KnownGood.create(
+            self, sha256=sha256, source=source, sha1=sha1, md5=md5,
+            filename=filename, mimetype=mimetype, metadata=metadata,
+            community=self.community))
+
+    async def known_good_get(self, sha256):
+        """
+        Fetch a known-good entry by sha256.
+        :param sha256: The sha256 to look up.
+        :return: A KnownGood resource
+        """
+        logger.info('Get known-good %s', sha256)
+        return await self._single(resources.KnownGood.get(
+            self, sha256=sha256, community=self.community))
+
+    async def known_good_delete(self, sha256):
+        """
+        Delete a known-good entry by sha256 (the same key used to retrieve it).
+        Leaves any existing instances intact; only future submissions of that
+        sha256 stop being short-circuited.
+        :param sha256: The sha256 of the known-good entry to delete.
+        :return: A KnownGood resource (the deletion result)
+        """
+        logger.info('Delete known-good %s', sha256)
+        return await self._single(resources.KnownGood.delete(self, sha256=sha256))
+
     async def family_create(self, name):
         """
         Create a Family.
@@ -982,7 +1025,8 @@ class PolySwarmAsyncAPI:
         report_task = await self._single(resources.ReportLLMPostProcessing.create(self,
                                                                instance_id=instance_id,
                                                                cape_sandbox_task_id=cape_sandbox_task_id,
-                                                               triage_sandbox_task_id=triage_sandbox_task_id))
+                                                               triage_sandbox_task_id=triage_sandbox_task_id,
+                                                               community=self.community))
         return report_task
 
     async def llm_report_get(self, report_task_id):
@@ -1608,8 +1652,11 @@ class PolySwarmAsyncAPI:
                 self, hash_.hash, hash_.hash_type, require_scan=require_scan,
             ),
         )
-        # exists_hash is a HEAD; ``result`` is the status code. Any 2xx means the
-        # artifact is known — the endpoint returns 200 for present / 404 for absent,
-        # so a 2xx check is correct and not brittle to a non-200 success code.
-        return int(result) // 100 == 2
+        # exists_hash is a HEAD; ``result`` is the status code. The endpoint returns
+        # 200 when the artifact is present and 204 when it is absent ("the request
+        # worked, but there was no matching artifact, so nothing was returned"). Only
+        # a 200 means the artifact exists — 204 (and 404) both mean "absent" → False.
+        # NB: this is deliberately ``== 200``, not a ``// 100 == 2`` 2xx check, because
+        # 204 is a successful 2xx that means the opposite of "exists".
+        return int(result) == 200
 

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/aio/session.py

@@ -148,6 +148,19 @@ class AsyncPolyswarmSession:
                 await response.aread()
                 _raise_for_status(response, request)
 
+            if response.status_code == 204:
+                # A 204 is the "no data / absent" signal on a download: the request
+                # succeeded but there is nothing to write ("the request worked, but
+                # there was no matching artifact, so nothing was returned"). The
+                # shared ``parse_response`` maps a parser-backed 204 to
+                # ``NoResultsException``; the streaming path bypasses ``parse_response``,
+                # so mirror that rule explicitly here. Without it, an absent artifact
+                # would be written out as a successful *empty* file instead of
+                # surfacing "no results".
+                raise exceptions.NoResultsException(
+                    request, 'The request returned no results.',
+                )
+
             pk = request.parser_kwargs or {}
             handle, name, created = request.result_parser.open_destination(
                 pk.get('folder'), pk.get('handle'), pk.get('artifact_name'), response,

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/api.py

@@ -925,6 +925,67 @@ class PolyswarmAPI:
         for item in self._paginate(resources.Tag.list(self)):
             yield item
 
+    def known_good_create(
+        self,
+        sha256,
+        source,
+        sha1=None,
+        md5=None,
+        filename=None,
+        mimetype=None,
+        metadata=None,
+    ):
+        """
+        Record a hash as a known-good binary (internal-only). The first feed for a
+        sha256 creates the searchable reference; a different ``source`` for an
+        existing sha256 just records that feed.
+
+        :param sha256: The sha256 of the known-good binary.
+        :param source: The feed/source flagging this hash (becomes a metadata tool).
+        :param sha1: Optional sha1.
+        :param md5: Optional md5.
+        :param filename: Optional filename.
+        :param mimetype: Optional mimetype.
+        :param metadata: Optional dict of extra feed metadata.
+        :return: A KnownGood resource
+        """
+        logger.info("Create known-good %s from %s", sha256, source)
+        return self._single(
+            resources.KnownGood.create(
+                self,
+                sha256=sha256,
+                source=source,
+                sha1=sha1,
+                md5=md5,
+                filename=filename,
+                mimetype=mimetype,
+                metadata=metadata,
+                community=self.community,
+            )
+        )
+
+    def known_good_get(self, sha256):
+        """
+        Fetch a known-good entry by sha256.
+        :param sha256: The sha256 to look up.
+        :return: A KnownGood resource
+        """
+        logger.info("Get known-good %s", sha256)
+        return self._single(
+            resources.KnownGood.get(self, sha256=sha256, community=self.community)
+        )
+
+    def known_good_delete(self, sha256):
+        """
+        Delete a known-good entry by sha256 (the same key used to retrieve it).
+        Leaves any existing instances intact; only future submissions of that
+        sha256 stop being short-circuited.
+        :param sha256: The sha256 of the known-good entry to delete.
+        :return: A KnownGood resource (the deletion result)
+        """
+        logger.info("Delete known-good %s", sha256)
+        return self._single(resources.KnownGood.delete(self, sha256=sha256))
+
     def family_create(self, name):
         """
         Create a Family.
@@ -1201,6 +1262,7 @@ class PolyswarmAPI:
                 instance_id=instance_id,
                 cape_sandbox_task_id=cape_sandbox_task_id,
                 triage_sandbox_task_id=triage_sandbox_task_id,
+                community=self.community,
             )
         )
         return report_task
@@ -1940,7 +2002,10 @@ class PolyswarmAPI:
                 require_scan=require_scan,
             ),
         )
-        # exists_hash is a HEAD; ``result`` is the status code. Any 2xx means the
-        # artifact is known — the endpoint returns 200 for present / 404 for absent,
-        # so a 2xx check is correct and not brittle to a non-200 success code.
-        return int(result) // 100 == 2
+        # exists_hash is a HEAD; ``result`` is the status code. The endpoint returns
+        # 200 when the artifact is present and 204 when it is absent ("the request
+        # worked, but there was no matching artifact, so nothing was returned"). Only
+        # a 200 means the artifact exists — 204 (and 404) both mean "absent" → False.
+        # NB: this is deliberately ``== 200``, not a ``// 100 == 2`` 2xx check, because
+        # 204 is a successful 2xx that means the opposite of "exists".
+        return int(result) == 200

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/resources.py

@@ -266,6 +266,19 @@ class ArtifactInstance(core.BaseJsonResource, core.Hashable):
         metadata_json = content.get('metadata') or []
         metadata = {metadata['tool']: metadata['tool_metadata'] for metadata in metadata_json}
         self.metadata = Metadata(metadata, api)
+        # Flagging-feed metadata for a known-good binary: a list of
+        # {tool, tool_metadata, created, updated} entries (one per feed that
+        # flagged this sha256 as known-good), or None for a normal artifact.
+        # Optional + additive — absent on responses from older servers, so use
+        # .get() (older recorded responses parse to None, no behaviour change).
+        self.known_good = content.get('known_good')
+        self.known_good_sources = sorted(
+            {feed['tool'] for feed in self.known_good if feed.get('tool')}
+        ) if self.known_good else []
+        # Friendly bounty-state NAME (e.g. 'KNOWN_GOOD' / 'SETTLED' / 'STORED'),
+        # additive alongside the numeric bounty_state. Optional — older servers
+        # omit it, so .get() yields None (no behaviour change).
+        self.state = content.get('state')
 
         # ArtifactInstance fields
         self.id = content.get('id')
@@ -859,6 +872,23 @@ class Tag(core.BaseJsonResource):
         self.name = content.get('name')
 
 
+class KnownGood(core.BaseJsonResource):
+    # sha256 is the natural unique key for a known-good entry, and it's the key
+    # for BOTH retrieve and delete — so RESOURCE_ID_KEYS=['sha256'] lets the base
+    # _get_params / _delete_params route it into the query string with no override.
+    RESOURCE_ENDPOINT = '/known-good'
+    RESOURCE_ID_KEYS = ['sha256']
+
+    def __init__(self, content, api=None):
+        super().__init__(content, api=api)
+        self.id = content.get('id')
+        self.sha256 = content.get('sha256')
+        self.artifact_instance_id = content.get('artifact_instance_id')
+        # feed names (metadata tools) that flagged this hash as known-good
+        self.sources = content.get('sources', [])
+        self.created = core.parse_isoformat(content.get('created'))
+
+
 #####################################################################
 # Nested Resources
 #####################################################################

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0}/src/polyswarm_api/session.py

@@ -151,6 +151,20 @@ class PolyswarmSession:
                 response.read()
                 _raise_for_status(response, request)
 
+            if response.status_code == 204:
+                # A 204 is the "no data / absent" signal on a download: the request
+                # succeeded but there is nothing to write ("the request worked, but
+                # there was no matching artifact, so nothing was returned"). The
+                # shared ``parse_response`` maps a parser-backed 204 to
+                # ``NoResultsException``; the streaming path bypasses ``parse_response``,
+                # so mirror that rule explicitly here. Without it, an absent artifact
+                # would be written out as a successful *empty* file instead of
+                # surfacing "no results".
+                raise exceptions.NoResultsException(
+                    request,
+                    "The request returned no results.",
+                )
+
             pk = request.parser_kwargs or {}
             handle, name, created = request.result_parser.open_destination(
                 pk.get("folder"),

{polyswarm_api-4.0.0 → polyswarm_api-4.2.0/src/polyswarm_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyswarm_api
-Version: 4.0.0
+Version: 4.2.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Author-email: PolySwarm Developers <info@polyswarm.io>
 License: MIT