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

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

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

{polyswarm_api-4.3.0 → polyswarm_api-4.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polyswarm_api"
-version = "4.3.0"
+version = "4.5.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.3.0"
+current_version = "4.5.0"
 commit = true
 tag = false
 sign_tags = true

{polyswarm_api-4.3.0 → polyswarm_api-4.5.0}/src/polyswarm_api/__init__.py

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

{polyswarm_api-4.3.0 → polyswarm_api-4.5.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,82 @@ 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, sort=None,
+                           exclude_favorites=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 exclude_favorites: True returns only the rulesets that are NOT
+            favorited — the inverse of ``favorites_only``, and refused together
+            with it (a contradiction, answered with an error rather than an
+            empty list). It exists for clients that render the favorites as
+            their own list: the favorites are a separate, unpaginated fetch
+            bounded by the account's budget, so leaving them in the paginated
+            list too makes a page either repeat a row or come back short.
+            Appended to the signature rather than placed beside
+            ``favorites_only`` so a positional caller keeps working.
+        :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.
+        :param sort: ``'active_first'`` returns the rulesets that carry a live
+            hunt link first, newest first within each block. Default (None) is
+            newest first. "Newest first" is the server's own insertion key, NOT
+            the ``id`` on the rows you get back — that one is unique but
+            unordered, so dedupe with it and never resume or bound a walk with
+            it. Applied SERVER-side, across pages — the list is
+            keyset-paginated, so a client-side sort would only ever reorder one
+            page; the SDK never re-orders rows. Reuse a page's ``offset`` only
+            with the same ``sort``: the server refuses a cursor minted under
+            the other order.
+
+            Two server-side properties of that key, neither of them SDK
+            behaviour. It ranks on the stored link, which is a WIDER predicate
+            than the one ``livescan_id`` is rendered under: a legacy row whose
+            hunt was stopped without clearing the link ranks in the leading
+            block while still serializing ``livescan_id`` as ``None``. Read the
+            field to decide whether a ruleset is running; never the position.
+
+            And the key is MUTABLE, unlike that default: a ruleset whose
+            live hunt stops mid-walk falls back into the idle block below the
+            cursor and is yielded twice, and one started mid-walk moves above
+            the cursor and is skipped for the rest of that walk. That is a
+            property of the walk, so starting fresh from the first page does
+            not avoid it. This generator streams pages and does not dedupe —
+            dedupe by ``id`` if you consume more than one page.
         :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, sort=sort,
+                exclude_favorites=exclude_favorites,
+                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.

{polyswarm_api-4.3.0 → polyswarm_api-4.5.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,100 @@ 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,
+        sort=None,
+        exclude_favorites=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 exclude_favorites: True returns only the rulesets that are NOT
+            favorited — the inverse of ``favorites_only``, and refused together
+            with it (a contradiction, answered with an error rather than an
+            empty list). It exists for clients that render the favorites as
+            their own list: the favorites are a separate, unpaginated fetch
+            bounded by the account's budget, so leaving them in the paginated
+            list too makes a page either repeat a row or come back short.
+            Appended to the signature rather than placed beside
+            ``favorites_only`` so a positional caller keeps working.
+        :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.
+        :param sort: ``'active_first'`` returns the rulesets that carry a live
+            hunt link first, newest first within each block. Default (None) is
+            newest first. "Newest first" is the server's own insertion key, NOT
+            the ``id`` on the rows you get back — that one is unique but
+            unordered, so dedupe with it and never resume or bound a walk with
+            it. Applied SERVER-side, across pages — the list is
+            keyset-paginated, so a client-side sort would only ever reorder one
+            page; the SDK never re-orders rows. Reuse a page's ``offset`` only
+            with the same ``sort``: the server refuses a cursor minted under
+            the other order.
+
+            Two server-side properties of that key, neither of them SDK
+            behaviour. It ranks on the stored link, which is a WIDER predicate
+            than the one ``livescan_id`` is rendered under: a legacy row whose
+            hunt was stopped without clearing the link ranks in the leading
+            block while still serializing ``livescan_id`` as ``None``. Read the
+            field to decide whether a ruleset is running; never the position.
+
+            And the key is MUTABLE, unlike that default: a ruleset whose
+            live hunt stops mid-walk falls back into the idle block below the
+            cursor and is yielded twice, and one started mid-walk moves above
+            the cursor and is skipped for the rest of that walk. That is a
+            property of the walk, so starting fresh from the first page does
+            not avoid it. This generator streams pages and does not dedupe —
+            dedupe by ``id`` if you consume more than one page.
         :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,
+                sort=sort,
+                exclude_favorites=exclude_favorites,
+                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.

{polyswarm_api-4.3.0 → polyswarm_api-4.5.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.
 """
@@ -668,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.3.0 → polyswarm_api-4.5.0}/src/polyswarm_api/resources.py

@@ -746,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'
 
@@ -766,6 +805,11 @@ class LiveHuntResult(core.BaseJsonResource):
         self.sha1 = content.get('sha1')
         self.rule_name = content['rule_name']
         self.tags = content['tags']
+        # `.get()`, not a subscript -- both keys are additive, so an older server omits
+        # them. None is AMBIGUOUS on both (four causes) and is never a claim that the
+        # evidence is complete. Contract: specs/05-downstream-contract.md.
+        self.matched_strings = content.get('matched_strings')
+        self.matched_strings_dropped = content.get('matched_strings_dropped')
         self.polyscore = content['polyscore']
         self.malware_family = content['malware_family']
         self.detections = content['detections']
@@ -794,6 +838,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):
@@ -814,6 +868,11 @@ class HistoricalHuntResult(core.BaseJsonResource):
         self.created = core.parse_isoformat(content['created'])
         self.rule_name = content['rule_name']
         self.tags = content['tags']
+        # `.get()`, not a subscript -- both keys are additive, so an older server omits
+        # them. None is AMBIGUOUS on both (four causes) and is never a claim that the
+        # evidence is complete. Contract: specs/05-downstream-contract.md.
+        self.matched_strings = content.get('matched_strings')
+        self.matched_strings_dropped = content.get('matched_strings_dropped')
         self.polyscore = content['polyscore']
         self.malware_family = content['malware_family']
         self.detections = content['detections']

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

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