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

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polyswarm_api"
-version = "4.2.0"
+version = "4.4.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.2.0"
+current_version = "4.4.0"
 commit = true
 tag = false
 sign_tags = true
@@ -76,11 +76,17 @@ search = "__version__ = '{current_version}'"
 replace = "__version__ = '{new_version}'"
 
 [tool.pytest.ini_options]
-log_cli = true
-# Default live-log level. INFO keeps the useful app request/response lines while
-# dropping the DEBUG firehose (VCR per-request match trace, parse traces) that
-# otherwise bloats CI logs ~1000x. Override per-run with the TESTS_LOG_LEVEL env
-# var (e.g. TESTS_LOG_LEVEL=DEBUG to log everything); see test/conftest.py.
+# Live logging OFF by default. When on, pytest streams log records as the run goes
+# AND forces every test onto its own nodeid line (verbose-style) — ~130 lines of
+# pure noise on a green xdist run. With it off the run prints dots + an end
+# summary, and a FAILING test still shows its captured logs (at log_level, below)
+# plus the traceback. Opt back into live streaming with TESTS_LOG_CLI=1 (or an
+# explicit --log-cli-level) when debugging a live run; see test/conftest.py.
+log_cli = false
+# Level used for live logging when it's opted into (TESTS_LOG_CLI=1). INFO keeps
+# the useful app request/response lines while dropping the DEBUG firehose (VCR
+# per-request match trace, parse traces) that otherwise bloats logs ~1000x.
+# TESTS_LOG_LEVEL overrides both this and the captured-log level (conftest.py).
 log_cli_level = "INFO"
 log_format = "%(asctime)s %(levelname)-2s [%(name)s:%(filename)s:%(lineno)d:%(funcName)1s()] %(message)s"
 python_files = ["test_*.py", "*_test.py"]
@@ -95,7 +101,6 @@ filterwarnings = [
 asyncio_mode = "auto"
 addopts = [
     "--continue-on-collection-errors",
-    "-v",
     "-s",
-    "-rxXs",
+    "-ra",
 ]

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

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

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

@@ -18,7 +18,7 @@ import logging
 import time
 
 from polyswarm_api import exceptions, resources, settings
-from polyswarm_api.core import PolyswarmRequest
+from polyswarm_api.core import PolyswarmRequest, _as_result_bound
 
 from .session import AsyncPolyswarmSession
 
@@ -502,23 +502,35 @@ class PolySwarmAsyncAPI:
         return await self._single(resources.LiveYaraRuleset.delete(self, rule_id=rule_id))
 
     async def live_feed(self, since=None, rule_name=None, family=None,
-                           polyscore_lower=None, polyscore_upper=None, community=None):
+                           polyscore_lower=None, polyscore_upper=None, community=None,
+                           livescan_id=None, max_results=None):
         """
         Get live hunts feed
 
-        :param since: Fetch results from the last "since" minutes
+        :param since: Window in SECONDS (this said "minutes" in earlier releases and was
+            wrong). Absent or 0 means no time filter at all.
         :param rule_name: Filter hunt results on the provided rule name (exact match).
         :param family: Filter hunt results based on the family name (exact match).
         :param polyscore_lower: Polyscore lower bound for the hunt results.
         :param polyscore_upper: Polyscore upper bound for the hunt results.
         :param community: Community to retrieve live results from, or public/private.
+        :param livescan_id: Scope the feed to one live hunt's results.
+        :param max_results: Total results to yield, not a page size — paging
+            continues in the server's own chunks until the total is reached.
+            None, 0 or a negative means no bound: every page, as before.
         :return: Generator of HuntResult resources
         """
+        bound = _as_result_bound(max_results)
+        yielded = 0
         async for item in self._paginate(resources.LiveHuntResult.list(
             self, since=since, rule_name=rule_name, family=family,
             polyscore_lower=polyscore_lower, polyscore_upper=polyscore_upper,
+            livescan_id=livescan_id,
             community=community or self.community)):
             yield item
+            yielded += 1
+            if bound is not None and yielded >= bound:
+                return
 
     async def live_feed_delete(self, result_ids):
         """
@@ -684,15 +696,45 @@ class PolySwarmAsyncAPI:
         logger.info('Delete ruleset %s', ruleset_id)
         return await self._single(resources.YaraRuleset.delete(self, id=ruleset_id, community=self.community))
 
-    async def ruleset_list(self):
+    async def ruleset_list(self, name=None, status=None, favorites_only=None,
+                           has_new_results=None):
         """
         List all YaraRulesets for the current account.
+
+        All filters are optional and conjunctive:
+        :param name: Case-insensitive substring match on the ruleset name.
+        :param status: 'active' returns only rulesets whose live hunt is
+            currently running.
+        :param favorites_only: True returns only favorited rulesets.
+        :param has_new_results: True returns only rulesets whose stored
+            new-results counter is positive. The counter (and its window) is
+            maintained server-side by a scheduled refresh; rows carry it as
+            ``new_results_count`` with ``new_results_counted_at`` marking when
+            it was last refreshed. There is no per-request window parameter.
         :return: A generator of YaraRuleset resources
         """
         logger.info('List rulesets')
-        async for item in self._paginate(resources.YaraRuleset.list(self, community=self.community)):
+        async for item in self._paginate(resources.YaraRuleset.list(
+                self, name=name, status=status, favorites_only=favorites_only,
+                has_new_results=has_new_results, community=self.community)):
             yield item
 
+    async def ruleset_favorite(self, ruleset_id, favorite=True):
+        """
+        Favorite or unfavorite a YaraRuleset. Idempotent; works while a live
+        hunt is running. Favorites are shared by the whole team and capped
+        (the response carries favorites_used / favorites_limit); when the
+        budget is exhausted the server refuses with a machine-readable
+        FAVORITE_LIMIT error.
+
+        :param ruleset_id: Id of the ruleset
+        :param favorite: True to star, False to unstar
+        :return: A YaraRulesetFavorite resource
+        """
+        logger.info('%s ruleset %s', 'Favorite' if favorite else 'Unfavorite', ruleset_id)
+        return await self._single(resources.YaraRulesetFavorite.update(
+            self, id=ruleset_id, favorite=favorite, community=self.community))
+
     async def tag_link_get(self, sha256):
         """
         Fetch the Tags and Families associated with the given sha256.
@@ -939,6 +981,13 @@ class PolySwarmAsyncAPI:
         :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
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before any write (the handle is the caller's and arrives
+            already open, so "before the file is opened" would be the wrong reason here).
         """
         logger.info('Downloading %s into handle', hash_)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)
@@ -1599,6 +1648,12 @@ class PolySwarmAsyncAPI:
         :param hash_: Hashable (Artifact, LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5.
         :param hash_type: Hash type; auto-detected from the literal if not provided.
         :return: A ``LocalArtifact`` resource with its handle already closed.
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
         """
         logger.info('Downloading %s into %s', hash_, out_dir)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)
@@ -1609,7 +1664,15 @@ class PolySwarmAsyncAPI:
         return artifact
 
     async def download_id(self, out_dir, instance_id):
-        """Download an artifact by its instance id into ``out_dir``."""
+        """Download an artifact by its instance id into ``out_dir``.
+
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
+        """
         logger.info('Downloading %s into %s', instance_id, out_dir)
         artifact = await self._single(
             resources.LocalArtifact.download_id(self, instance_id, folder=out_dir),
@@ -1618,7 +1681,21 @@ class PolySwarmAsyncAPI:
         return artifact
 
     async def download_sandbox_artifact(self, out_dir, sandbox_task_id, instance_id):
-        """Download a sandbox-produced artifact (e.g. PCAP, dropped file) into ``out_dir``."""
+        """Download a sandbox-produced artifact (e.g. PCAP, dropped file) into ``out_dir``.
+
+        The known-good gate applies to **every** sandbox artifact by its own sha256 —
+        dropped file, screenshot, report, … — with no sample-vs-evidence carve-out
+        server-side, so any member whose digest is catalogued (and eligible) raises below.
+        In practice that is almost always a dropped file; evidence collides only on byte
+        identity, and the empty-file digest is refused at the catalogue boundary instead.
+
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
+        """
         logger.info('Downloading sandbox artifact %s %s', sandbox_task_id, instance_id)
         sandbox_artifact = await self._single(
             resources.LocalArtifact.download_sandbox_artifact(
@@ -1642,8 +1719,29 @@ class PolySwarmAsyncAPI:
 
         :param hash_: Hashable (Artifact, LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5.
         :param hash_type: Hash type; auto-detected if not provided.
-        :param require_scan: If True, only count artifacts that have been scanned.
+        :param require_scan: If True, only count artifacts that have been *scanned*.
+            Being catalogued as known-good is **not** a scan: the platform never scans
+            such a sample, so a hash whose only record is a known-good reference reports
+            absent under ``require_scan`` (and present without it, because that reference
+            is a real searchable record).
         :return: ``True`` if the artifact exists in PolySwarm's index.
+
+        .. note::
+           This is an existence probe, and its status codes are a **frozen contract**:
+           ``200`` means found, ``204`` means not found, and anything else means the
+           *request* was wrong.
+
+           Only ``200`` is ``True``. ``204`` and ``404`` are both ``False`` — the server
+           answers ``204`` for absent, and ``404`` is tolerated as absent for historical
+           reasons.
+
+           A non-2xx status does not raise here, and the reason is the **method**, not a
+           missing result parser: ``parse_response`` short-circuits ``HEAD``, setting the
+           status code as the result and returning before it reaches the non-2xx→exception
+           mapping (which otherwise applies whether or not a parser is set). So on this
+           endpoint a server error also collapses to ``False``, indistinguishable from a
+           genuine "does not exist" — which is why neither side may widen what counts as
+           found. See ``specs/03-endpoints.md``.
         """
         logger.info('Exists for hash %s', hash_)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)

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

@@ -20,7 +20,7 @@ import io
 import logging
 
 from polyswarm_api import exceptions, resources, settings
-from polyswarm_api.core import PolyswarmRequest
+from polyswarm_api.core import PolyswarmRequest, _as_result_bound
 
 from .session import PolyswarmSession
 
@@ -568,18 +568,27 @@ class PolyswarmAPI:
         polyscore_lower=None,
         polyscore_upper=None,
         community=None,
+        livescan_id=None,
+        max_results=None,
     ):
         """
         Get live hunts feed
 
-        :param since: Fetch results from the last "since" minutes
+        :param since: Window in SECONDS (this said "minutes" in earlier releases and was
+            wrong). Absent or 0 means no time filter at all.
         :param rule_name: Filter hunt results on the provided rule name (exact match).
         :param family: Filter hunt results based on the family name (exact match).
         :param polyscore_lower: Polyscore lower bound for the hunt results.
         :param polyscore_upper: Polyscore upper bound for the hunt results.
         :param community: Community to retrieve live results from, or public/private.
+        :param livescan_id: Scope the feed to one live hunt's results.
+        :param max_results: Total results to yield, not a page size — paging
+            continues in the server's own chunks until the total is reached.
+            None, 0 or a negative means no bound: every page, as before.
         :return: Generator of HuntResult resources
         """
+        bound = _as_result_bound(max_results)
+        yielded = 0
         for item in self._paginate(
             resources.LiveHuntResult.list(
                 self,
@@ -588,10 +597,14 @@ class PolyswarmAPI:
                 family=family,
                 polyscore_lower=polyscore_lower,
                 polyscore_upper=polyscore_upper,
+                livescan_id=livescan_id,
                 community=community or self.community,
             )
         ):
             yield item
+            yielded += 1
+            if bound is not None and yielded >= bound:
+                return
 
     def live_feed_delete(self, result_ids):
         """
@@ -823,17 +836,58 @@ class PolyswarmAPI:
             resources.YaraRuleset.delete(self, id=ruleset_id, community=self.community)
         )
 
-    def ruleset_list(self):
+    def ruleset_list(
+        self, name=None, status=None, favorites_only=None, has_new_results=None
+    ):
         """
         List all YaraRulesets for the current account.
+
+        All filters are optional and conjunctive:
+        :param name: Case-insensitive substring match on the ruleset name.
+        :param status: 'active' returns only rulesets whose live hunt is
+            currently running.
+        :param favorites_only: True returns only favorited rulesets.
+        :param has_new_results: True returns only rulesets whose stored
+            new-results counter is positive. The counter (and its window) is
+            maintained server-side by a scheduled refresh; rows carry it as
+            ``new_results_count`` with ``new_results_counted_at`` marking when
+            it was last refreshed. There is no per-request window parameter.
         :return: A generator of YaraRuleset resources
         """
         logger.info("List rulesets")
         for item in self._paginate(
-            resources.YaraRuleset.list(self, community=self.community)
+            resources.YaraRuleset.list(
+                self,
+                name=name,
+                status=status,
+                favorites_only=favorites_only,
+                has_new_results=has_new_results,
+                community=self.community,
+            )
         ):
             yield item
 
+    def ruleset_favorite(self, ruleset_id, favorite=True):
+        """
+        Favorite or unfavorite a YaraRuleset. Idempotent; works while a live
+        hunt is running. Favorites are shared by the whole team and capped
+        (the response carries favorites_used / favorites_limit); when the
+        budget is exhausted the server refuses with a machine-readable
+        FAVORITE_LIMIT error.
+
+        :param ruleset_id: Id of the ruleset
+        :param favorite: True to star, False to unstar
+        :return: A YaraRulesetFavorite resource
+        """
+        logger.info(
+            "%s ruleset %s", "Favorite" if favorite else "Unfavorite", ruleset_id
+        )
+        return self._single(
+            resources.YaraRulesetFavorite.update(
+                self, id=ruleset_id, favorite=favorite, community=self.community
+            )
+        )
+
     def tag_link_get(self, sha256):
         """
         Fetch the Tags and Families associated with the given sha256.
@@ -1139,6 +1193,13 @@ class PolyswarmAPI:
         :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
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before any write (the handle is the caller's and arrives
+            already open, so "before the file is opened" would be the wrong reason here).
         """
         logger.info("Downloading %s into handle", hash_)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)
@@ -1941,6 +2002,12 @@ class PolyswarmAPI:
         :param hash_: Hashable (Artifact, LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5.
         :param hash_type: Hash type; auto-detected from the literal if not provided.
         :return: A ``LocalArtifact`` resource with its handle already closed.
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
         """
         logger.info("Downloading %s into %s", hash_, out_dir)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)
@@ -1953,7 +2020,15 @@ class PolyswarmAPI:
         return artifact
 
     def download_id(self, out_dir, instance_id):
-        """Download an artifact by its instance id into ``out_dir``."""
+        """Download an artifact by its instance id into ``out_dir``.
+
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
+        """
         logger.info("Downloading %s into %s", instance_id, out_dir)
         artifact = self._single(
             resources.LocalArtifact.download_id(self, instance_id, folder=out_dir),
@@ -1962,7 +2037,21 @@ class PolyswarmAPI:
         return artifact
 
     def download_sandbox_artifact(self, out_dir, sandbox_task_id, instance_id):
-        """Download a sandbox-produced artifact (e.g. PCAP, dropped file) into ``out_dir``."""
+        """Download a sandbox-produced artifact (e.g. PCAP, dropped file) into ``out_dir``.
+
+        The known-good gate applies to **every** sandbox artifact by its own sha256 —
+        dropped file, screenshot, report, … — with no sample-vs-evidence carve-out
+        server-side, so any member whose digest is catalogued (and eligible) raises below.
+        In practice that is almost always a dropped file; evidence collides only on byte
+        identity, and the empty-file digest is refused at the catalogue boundary instead.
+
+        :raises KnownGoodWithheldException: the sha256 is catalogued as a known-good binary,
+            so its bytes are withheld by design. A ``NotFoundException`` subclass, so existing
+            ``except NotFoundException`` handling still catches it; catch it specifically to
+            tell a deliberate refusal apart from a missing artifact, and read
+            ``.sources`` for the feeds that flagged it. Nothing is written to the destination —
+            the status is checked before the file is opened.
+        """
         logger.info("Downloading sandbox artifact %s %s", sandbox_task_id, instance_id)
         sandbox_artifact = self._single(
             resources.LocalArtifact.download_sandbox_artifact(
@@ -1989,8 +2078,29 @@ class PolyswarmAPI:
 
         :param hash_: Hashable (Artifact, LocalArtifact, Hash) or hex-encoded SHA256/SHA1/MD5.
         :param hash_type: Hash type; auto-detected if not provided.
-        :param require_scan: If True, only count artifacts that have been scanned.
+        :param require_scan: If True, only count artifacts that have been *scanned*.
+            Being catalogued as known-good is **not** a scan: the platform never scans
+            such a sample, so a hash whose only record is a known-good reference reports
+            absent under ``require_scan`` (and present without it, because that reference
+            is a real searchable record).
         :return: ``True`` if the artifact exists in PolySwarm's index.
+
+        .. note::
+           This is an existence probe, and its status codes are a **frozen contract**:
+           ``200`` means found, ``204`` means not found, and anything else means the
+           *request* was wrong.
+
+           Only ``200`` is ``True``. ``204`` and ``404`` are both ``False`` — the server
+           answers ``204`` for absent, and ``404`` is tolerated as absent for historical
+           reasons.
+
+           A non-2xx status does not raise here, and the reason is the **method**, not a
+           missing result parser: ``parse_response`` short-circuits ``HEAD``, setting the
+           status code as the result and returning before it reaches the non-2xx→exception
+           mapping (which otherwise applies whether or not a parser is set). So on this
+           endpoint a server error also collapses to ``False``, indistinguishable from a
+           genuine "does not exist" — which is why neither side may widen what counts as
+           found. See ``specs/03-endpoints.md``.
         """
         logger.info("Exists for hash %s", hash_)
         hash_ = resources.Hash.from_hashable(hash_, hash_type=hash_type)

{polyswarm_api-4.2.0 → polyswarm_api-4.4.0}/src/polyswarm_api/core.py

@@ -16,7 +16,8 @@ parsing logic have a single source of truth:
   builders (``create``, ``get``, ``head``, ``update``, ``delete``,
   ``list``) construct ``PolyswarmRequest`` descriptors.
 - ``Hashable`` + ``is_valid_*`` validators, ``parse_isoformat``,
-  ``_normalise_bool_params``, ``RequestParamsEncoder``.
+  ``_normalise_bool_params``, ``RequestParamsEncoder``,
+  ``_as_result_bound``.
 
 Both transports import from here.
 """
@@ -330,7 +331,9 @@ def _raise_for_status(response, request):
 
     Shared by ``parse_response`` (buffered/JSON path) and the session's
     streaming-download path, so both raise identically (429/404/422/other,
-    plus the non-JSON-body fallbacks). The response body must already be
+    plus the non-JSON-body fallbacks). A 404 whose ``errors`` payload carries the
+    ``KNOWN_GOOD`` code raises the ``NotFoundException`` subclass
+    ``KnownGoodWithheldException``. The response body must already be
     readable — streaming callers ``read()`` / ``aread()`` it first. **Always
     raises; never returns.**
     """
@@ -354,6 +357,17 @@ def _raise_for_status(response, request):
         )
         raise exceptions.UsageLimitsExceededException(request, message)
     elif request.status_code == 404:
+        # A download refused because the artifact is a known-good binary carries a
+        # machine-readable code in the error envelope's ``errors`` slot. Raise the
+        # ``NotFoundException`` subclass so callers can tell "withheld by design"
+        # apart from a plain miss; every other 404 stays a plain NotFoundException.
+        # The raw ``sources`` payload goes in as-is — the exception normalises it
+        # into the documented list-of-feed-names shape.
+        errors = request.errors
+        if isinstance(errors, dict) and errors.get('code') == 'KNOWN_GOOD':
+            raise exceptions.KnownGoodWithheldException(
+                request, request._result, sources=errors.get('sources'),
+            )
         raise exceptions.NotFoundException(request, request._result)
     elif request.status_code == 422:
         raise exceptions.FailedInstanceException(request, request._result)
@@ -383,7 +397,23 @@ def _bad_status_message(request):
         f'Message: {request._result}'
     )
     if request.errors:
-        errors = '\n'.join(str(error) for error in request.errors)
+        # Two ``errors`` shapes are in play. The legacy shape is a **list** of
+        # per-error entries — one rendered line each. The way-forward shape is a
+        # **mapping** carrying the machine-readable code plus its context
+        # (``{'code': 'KNOWN_GOOD', 'known_good': True, 'sources': [...]}``), and the
+        # server forwards it on every status, not just the 404 the code was
+        # introduced for. Iterating a mapping yields only its KEYS, so rendering it
+        # like a list would drop every value from the message the caller sees —
+        # render it as ``key=value`` lines instead.
+        # The same reasoning applies to a bare string: iterating it yields characters, so
+        # `"errors": "some prose"` would render one letter per line. Only genuinely
+        # sequence-shaped payloads get the line-per-entry treatment.
+        if isinstance(request.errors, dict):
+            errors = '\n'.join(f'{k}={v}' for k, v in request.errors.items())
+        elif isinstance(request.errors, (list, tuple)):
+            errors = '\n'.join(str(error) for error in request.errors)
+        else:
+            errors = str(request.errors)
         message = f'{message}\nErrors:\n{errors}'
     return message
 
@@ -639,6 +669,16 @@ class BaseJsonResource(BaseResource):
         )
 
 
+def _as_result_bound(max_results):
+    """The caller's result bound, or None when there isn't one.
+
+    None, 0 and negatives all mean "no bound".
+    """
+    if not max_results or max_results < 0:
+        return None
+    return max_results
+
+
 # ── Hash helpers ───────────────────────────────────────────────────
 
 

polyswarm_api-4.4.0/src/polyswarm_api/exceptions.py

@@ -0,0 +1,135 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class PolyswarmException(Exception):
+    pass
+
+
+#########################################
+# API layer exceptions
+#########################################
+
+class PolyswarmAPIException(PolyswarmException):
+    pass
+
+
+class TimeoutException(PolyswarmAPIException):
+    pass
+
+
+#########################################
+# Request layer exceptions
+#########################################
+
+class RequestException(PolyswarmException):
+    def __init__(self, request, *args):
+        super().__init__(*args)
+        self.request = request
+
+
+class UsageLimitsExceededException(RequestException):
+    pass
+
+
+class NotFoundException(RequestException):
+    pass
+
+
+def _normalise_sources(sources):
+    """Coerce a server-supplied ``sources`` payload into a list of feed names.
+
+    ``.sources`` is published as a list of strings and consumers iterate it, so a
+    bare ``'nsrl'`` cannot be handed through — it would iterate as characters.
+    The server sends a list of strings today; a feed-dict entry (the shape the
+    instance-level ``known_good`` field uses) yields ``feed['tool']`` defensively
+    rather than being dropped. Anything unrecognised becomes ``[]`` and is logged,
+    so a discard is never silent. The raw payload stays at ``exc.request.errors``.
+    """
+    if isinstance(sources, str):
+        return [sources]
+    if isinstance(sources, list):
+        names = []
+        for source in sources:
+            if isinstance(source, str):
+                names.append(source)
+            elif isinstance(source, dict) and isinstance(source.get('tool'), str):
+                names.append(source['tool'])
+            else:
+                logger.warning('Dropping unrecognised known-good sources entry: %r', source)
+        return names
+    if sources is not None:
+        logger.warning('Dropping unrecognised known-good sources payload: %r', sources)
+    return []
+
+
+class KnownGoodWithheldException(NotFoundException):
+    """404 for a known-good binary: the platform never stores or serves its bytes.
+
+    Subclasses ``NotFoundException`` so every existing ``except NotFoundException``
+    handler keeps working unchanged; catch this subclass only when the caller wants
+    to tell "withheld by design" apart from a plain "not found". The metadata the
+    platform holds about the artifact is still readable through the search /
+    instance endpoints.
+    """
+
+    def __init__(self, request, *args, sources=None):
+        super().__init__(request, *args)
+        # Known-good feeds that flagged the hash (e.g. ``['nsrl']``); always a list
+        # of strings — normalised here, at the boundary, so the documented shape
+        # holds whatever the envelope carried. Empty when the server named none.
+        self.sources = _normalise_sources(sources)
+
+
+class NoResultsException(RequestException):
+    pass
+
+
+class FailedInstanceException(RequestException):
+    pass
+
+
+#########################################
+# Types layer exceptions
+#########################################
+
+
+class TypeException(PolyswarmException):
+    pass
+
+
+class MissingAPIInstanceException(TypeException):
+    pass
+
+
+class InvalidJSONResponseException(TypeException):
+    pass
+
+
+class DecodeErrorException(TypeException):
+    pass
+
+
+class InvalidValueException(TypeException):
+    pass
+
+
+class ArtifactDeletedException(TypeException):
+    pass
+
+
+class InvalidYaraRulesException(TypeException):
+    pass
+
+
+class NotImportedException(TypeException):
+    pass
+
+
+#########################################
+# Warnings
+#########################################
+
+class APIWarning(Warning):
+    pass

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

@@ -275,9 +275,14 @@ class ArtifactInstance(core.BaseJsonResource, core.Hashable):
         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).
+        # Friendly REPORTED-state NAME (e.g. 'KNOWN_GOOD' / 'SETTLED' / 'STORED' /
+        # 'NOT_STORED'). The server derives it from its two-predicate known-good model
+        # (artifact-index specs/05): 'KNOWN_GOOD' while the file is currently known-good,
+        # 'NOT_STORED' for a submission it declined as known-good whose hash is no longer
+        # currently known-good (nothing was ever stored; a fresh submit works), otherwise
+        # the instance's own persisted state. Additive alongside the numeric
+        # bounty_state, and optional — older servers omit it, so .get() yields None
+        # (no behaviour change).
         self.state = content.get('state')
 
         # ArtifactInstance fields
@@ -741,12 +746,51 @@ class YaraRuleset(core.BaseJsonResource):
         self.modified = core.parse_isoformat(content.get('modified'))
         self.deleted = content.get('deleted')
         self.yara = content.get('yara')
+        # Hunt-page tracking fields. All additive — an older server simply
+        # leaves them None.
+        self.favorite = content.get('favorite')
+        self.favorited_at = core.parse_isoformat(content.get('favorited_at'))
+        # Number of rules in the ruleset body. None means "no answer" (the
+        # server could not or has not counted), which is different from 0.
+        self.rule_count = content.get('rule_count')
+        self.historical_hunt_count = content.get('historical_hunt_count')
+        # Live results collected in the product window — a STORED counter the
+        # server refreshes on a schedule, always present on list rows with a
+        # running live hunt. None means "not yet refreshed / no live hunt",
+        # which is different from 0 ("refreshed, nothing new").
+        self.new_results_count = content.get('new_results_count')
+        # When the server last refreshed the counter — the staleness marker
+        # that makes a stored count trustworthy (None iff the count is None).
+        self.new_results_counted_at = core.parse_isoformat(
+            content.get('new_results_counted_at'))
 
 
 class LiveYaraRuleset(YaraRuleset):
     RESOURCE_ENDPOINT = '/hunt/rule/live'
 
 
+class YaraRulesetFavorite(core.BaseJsonResource):
+    """The favorite-toggle response: the ruleset's new star state plus the
+    team's budget usage, so callers can render "N of M used" without counting
+    client-side."""
+    RESOURCE_ENDPOINT = '/hunt/rule/favorite'
+    # The toggle's payload ({id, favorite}) rides the JSON body — the server
+    # reads BOTH from the body — so the default RESOURCE_ID_KEYS (['id'])
+    # would move `id` into the query string and the server would 400 with
+    # "A valid rule id must be provided". `community` stays a query-string
+    # key to match where every ruleset GET/list sends it (the server accepts
+    # it from either the query or the body, but never from both at once).
+    RESOURCE_ID_KEYS = ['community']
+
+    def __init__(self, content, api=None):
+        super().__init__(content, api=api)
+        self.id = content.get('id')
+        self.favorite = content.get('favorite')
+        self.favorited_at = core.parse_isoformat(content.get('favorited_at'))
+        self.favorites_used = content.get('favorites_used')
+        self.favorites_limit = content.get('favorites_limit')
+
+
 class LiveHuntResult(core.BaseJsonResource):
     RESOURCE_ENDPOINT = '/hunt/live'
 
@@ -789,6 +833,16 @@ class HistoricalHunt(core.BaseJsonResource):
         self.progress = content['progress']
         self.results_csv_uri = content['results_csv_uri']
         self.communities = content.get('communities')
+        # Source-rule provenance. rule_id is the ruleset this hunt was
+        # triggered from (None for raw-yara hunts and hunts predating the
+        # tracking); rule_modified is a freeze-time audit timestamp.
+        self.rule_id = content.get('rule_id')
+        self.rule_modified = core.parse_isoformat(content.get('rule_modified'))
+        # Tri-state: has the source ruleset's body changed SINCE THE HUNT
+        # FROZE IT? True/False when the server could compare; None means
+        # unknown (no source rule, or nothing to compare against) — not
+        # "unchanged".
+        self.source_rule_changed = content.get('source_rule_changed')
 
 
 class HistoricalHuntList(HistoricalHunt):

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

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

polyswarm_api-4.2.0/src/polyswarm_api/exceptions.py

@@ -1,85 +0,0 @@
-class PolyswarmException(Exception):
-    pass
-
-
-#########################################
-# API layer exceptions
-#########################################
-
-class PolyswarmAPIException(PolyswarmException):
-    pass
-
-
-class TimeoutException(PolyswarmAPIException):
-    pass
-
-
-#########################################
-# Request layer exceptions
-#########################################
-
-class RequestException(PolyswarmException):
-    def __init__(self, request, *args):
-        super().__init__(*args)
-        self.request = request
-
-
-class UsageLimitsExceededException(RequestException):
-    pass
-
-
-class NotFoundException(RequestException):
-    pass
-
-
-class NoResultsException(RequestException):
-    pass
-
-
-class FailedInstanceException(RequestException):
-    pass
-
-
-#########################################
-# Types layer exceptions
-#########################################
-
-
-class TypeException(PolyswarmException):
-    pass
-
-
-class MissingAPIInstanceException(TypeException):
-    pass
-
-
-class InvalidJSONResponseException(TypeException):
-    pass
-
-
-class DecodeErrorException(TypeException):
-    pass
-
-
-class InvalidValueException(TypeException):
-    pass
-
-
-class ArtifactDeletedException(TypeException):
-    pass
-
-
-class InvalidYaraRulesException(TypeException):
-    pass
-
-
-class NotImportedException(TypeException):
-    pass
-
-
-#########################################
-# Warnings
-#########################################
-
-class APIWarning(Warning):
-    pass