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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyswarm_api
-Version: 4.2.0
+Version: 4.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polyswarm_api"
-version = "4.2.0"
+version = "4.3.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.3.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.3.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.3.0'
 __release_url__ = 'https://api.github.com/repos/polyswarm/polyswarm-api/releases/latest'
 
 from . import api

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

@@ -939,6 +939,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 +1606,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 +1622,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 +1639,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 +1677,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.3.0}/src/polyswarm_api/api.py

@@ -1139,6 +1139,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 +1948,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 +1966,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 +1983,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 +2024,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.3.0}/src/polyswarm_api/core.py

@@ -330,7 +330,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 +356,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 +396,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
 

polyswarm_api-4.3.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.3.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

{polyswarm_api-4.2.0 → polyswarm_api-4.3.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.3.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