arcticsecurity 0.1.0__py3-none-any.whl

arcticsecurity/sharing_api/__init__.py

@@ -0,0 +1,4 @@
+# ruff: noqa: F401 F403
+
+from .errors import *
+from .sharing_api import Query, Sync, query

arcticsecurity/sharing_api/_api_client.py

@@ -0,0 +1,376 @@
+"""
+Sharing API client.
+"""
+
+import json
+import logging
+import re
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Optional, Union
+from urllib.parse import parse_qs, urlparse, urlunparse
+
+import httpx
+
+from . import _version
+from .errors import (
+    ConfigError,
+    Error,
+    InvalidTokenError,
+    NetworkError,
+    Retry,
+    ServerError,
+    TimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Timeout:
+    def __init__(self, timeout: Optional[float]):
+        self._max_duration = timeout or 0
+        self._start_ts = time.monotonic()
+
+    def start(self) -> None:
+        self._start_ts = time.monotonic()
+
+    def stop(self) -> None:
+        pass
+
+    def check(self) -> None:
+        if 0 < self._max_duration < time.monotonic() - self._start_ts:
+            raise TimeoutError("Query timed out")
+
+
+@dataclass
+class Query:
+    """Handle one 3-phase async query.
+
+    Check for timeout every time client is accessed.
+    """
+
+    _client: httpx.Client
+    timeout: Timeout
+
+    # Query details for introspection
+    post_url: Optional[httpx.URL] = None
+
+    def __enter__(self) -> "Query":
+        self._client.__enter__()
+        self.timeout.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> Any:
+        self.timeout.stop()
+        return self._client.__exit__(exc_type, exc, tb)
+
+    @property
+    def client(self) -> httpx.Client:
+        self.timeout.check()
+        return self._client
+
+
+class _ApiClient:
+    """Sharing API client."""
+
+    # Allowed query parameters
+    allowed_params = {
+        "filter",
+        "projection",
+        "limit",
+        "token",
+        "start",
+        "end",
+        "sort",
+        "reverse",
+    }
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        user_agent: Optional[str] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        sleep_before_first_status_query: float = 0.5,
+        sleep_after_50x_error_within_query: float = 10,
+    ):
+        self.urls = _ShareUrls(url)
+        self.user_agent = user_agent or _version.user_agent
+
+        # Transport to use in httpx client. Should only be defined in testing
+        self.transport = transport
+        # Time to wait for before first GET status after POST query
+        self.sleep_before_first_status_query = sleep_before_first_status_query
+        # Time to wait after 50x response within a query. These are typically
+        # transitory errors on the server side
+        self.sleep_after_50x_error_within_query = sleep_after_50x_error_within_query
+
+    def _get_client(self) -> httpx.Client:
+        """Initiaze new client."""
+        return httpx.Client(
+            base_url=self.urls.base_url,
+            follow_redirects=True,
+            timeout=60,
+            headers={
+                **self.urls.authorization_header,
+                "USER-AGENT": self.user_agent,
+                "ACCEPT-ENCODING": "gzip",
+                "ACCEPT": "application/json",
+            },
+            transport=self.transport,
+        )
+
+    def _init_query(self, timeout: Optional[float]) -> Query:
+        return Query(
+            self._get_client(),
+            Timeout(timeout),
+        )
+
+    def async_query(
+        self,
+        params: Optional[dict[str, Union[str, Sequence[str], int, float]]] = None,
+        timeout: Optional[float] = None,
+    ) -> httpx.Response:
+        """Execute 3-phase async query."""
+        qp = {**self.urls.qp, **(params or {})}
+        invalid_params = qp.keys() - self.allowed_params
+        if invalid_params:
+            raise ConfigError(f"Invalid query parameters: {invalid_params}")
+
+        with self._init_query(timeout) as query:
+            status_url = self._async_post_query(query, qp)
+            time.sleep(self.sleep_before_first_status_query)
+            result_url = self._async_get_result_url(query, status_url)
+            return self._async_get_result_response(query, result_url)
+
+    def _async_post_query(
+        self,
+        query: Query,
+        params: Optional[dict[str, Union[str, Sequence[str], int, float]]] = None,
+    ) -> str:
+        """POST async query.
+
+        Returns status url.
+        """
+        try:
+            response = query.client.post(url=self.urls.async_path, params=params)
+            query.post_url = response.request.url
+        except httpx.RequestError as error:
+            raise NetworkError(
+                f"Downloading {error.request.url} failed: {error}",
+                url=str(error.request.url),
+            )
+
+        if self._server_unavailable(response.status_code):
+            logger.debug(
+                f"Error posting job, retry later ({response.status_code} {response.text})"
+            )
+            # Server error on initial post -> suggest retrying whole query later again
+            raise Retry(
+                after=response.headers.get("Retry-After", 10), url=str(response.url)
+            )
+        elif (invalid_inputs := self._invalid_input_error(response)) is not None:
+            raise ConfigError(invalid_inputs, url=str(response.url))
+        elif response.status_code == 500:
+            raise ServerError(
+                f"Sharing API server error 500 for submit, {response.text}",
+                url=str(response.url),
+            )
+        elif response.status_code != 202:
+            raise NetworkError(
+                f"Unexpected status {response.status_code} for submit, {response.text}",
+                url=str(response.request.url),
+            )
+
+        try:
+            return response.headers["Location"]
+        except KeyError:
+            raise Error("Location header missing from response", url=str(response.url))
+
+    def _async_get_result_url(self, query: Query, url: str) -> str:
+        """GET async result url from status url."""
+        while True:
+            try:
+                response = query.client.get(url=url, follow_redirects=False)
+            except httpx.RequestError as error:
+                raise NetworkError(
+                    f"Downloading {error.request.url} failed: {error}",
+                    url=str(error.request.url),
+                )
+
+            if response.status_code == 302:
+                # results are ready
+                break
+            elif response.status_code == 202:
+                time.sleep(int(response.headers.get("Retry-After", 1)))
+            elif response.status_code == 500:
+                raise ServerError(
+                    f"Sharing API server error 500 getting status, {response.text}",
+                    url=str(response.url),
+                )
+            elif self._server_unavailable(response.status_code):
+                logger.debug(
+                    f"Error getting status, try again after {self.sleep_after_50x_error_within_query} secs ({response.status_code} {response.text})"
+                )
+                time.sleep(self.sleep_after_50x_error_within_query)
+            elif response.status_code == 410:
+                if response.headers.get("X-STATUS") == "Job expired":
+                    raise Error("The query has expired", url=str(response.url))
+                else:
+                    raise Retry(
+                        "Job no longer exists (may have become stale)",
+                        url=str(response.url),
+                    )
+            else:
+                raise Retry(
+                    f"Unexpected status {response.status_code} loading results, {response.text}",
+                    url=str(response.url),
+                )
+
+        try:
+            return response.headers["Location"]
+        except KeyError:
+            raise Error("Location header missing from response", url=str(response.url))
+
+    def _async_get_result_response(self, query: Query, url: str) -> httpx.Response:
+        """GET async result response."""
+        while True:
+            try:
+                response = query.client.get(url)
+            except httpx.RequestError as error:
+                raise NetworkError(
+                    f"Downloading {error.request.url} failed: {error}",
+                    url=str(error.request.url),
+                )
+
+            if response.status_code == 200:
+                break
+            elif response.status_code == 410:
+                if response.headers.get("X-STATUS") == "Job expired":
+                    raise Error("The query has expired", url=str(response.url))
+                else:
+                    raise Retry(
+                        "Results have been fetched already", url=str(response.url)
+                    )
+            elif response.status_code == 500:
+                raise ServerError(
+                    f"Sharing API server error 500 fetching results, {response.text}",
+                    url=str(response.url),
+                )
+            elif self._server_unavailable(response.status_code):
+                # sleep only 1 sec since results are stored only for a limited time
+                logger.debug(
+                    f"Error getting results, try again after {self.sleep_after_50x_error_within_query} secs ({response.status_code} {response.text})"
+                )
+                time.sleep(self.sleep_after_50x_error_within_query)
+            elif self._is_invalid_token_error(response):
+                assert query.post_url is not None  # for mypy
+                raise InvalidTokenError(
+                    query.post_url.params.get("token"), url=str(response.url)
+                )
+            else:
+                raise Retry(
+                    f"Unexpected status {response.status_code} fetching results, {response.text}",
+                    url=str(response.url),
+                )
+
+        return response
+
+    @staticmethod
+    def _server_unavailable(status: int) -> bool:
+        """Does status mean server is unavailable?
+
+        502 / 503 / 504 typically overloaded system. All of these should be
+        transient on a valid hub url.
+        """
+        return status in (502, 503, 504)
+
+    @staticmethod
+    def _is_invalid_token_error(response: httpx.Response) -> bool:
+        """Does response contain "invalid token" error.
+
+        {"title": "400 Bad Request", "errors": [{"type": "storage", "key": "token", "message": "Invalid token: foo"}]}%
+        """
+        if response.status_code != 400:
+            return False
+
+        try:
+            for error in response.json().get("errors", ()):
+                if error.get("key") == "token" and error.get("message", "").startswith(
+                    "Invalid token"
+                ):
+                    return True
+        except json.decoder.JSONDecodeError:
+            return False
+
+        return False
+
+    @staticmethod
+    def _invalid_input_error(response: httpx.Response) -> Optional[Any]:
+        """If response contains "invalid inputs" error, return it.
+
+        {'title': '400 Invalid input(s)', 'description': '2 invalid input(s)', 'errors': [{'key': 'start', 'type': 'query validation', 'message': "Invalid start: ['foo']"}, {'key': 'startt', 'type': 'query validation', 'message': 'Unknown parameter: startt'}]}
+        """
+        if response.status_code != 400:
+            return None
+
+        try:
+            d = response.json()
+            if d.get("title") == "400 Invalid input(s)":
+                return d.get("errors", [])
+        except json.decoder.JSONDecodeError:
+            return None
+
+        return None
+
+
+@dataclass
+class _ShareUrls:
+    """Share url handling."""
+
+    base_url: str
+    sync_path: str
+    async_path: str
+    authorization_header: dict[str, str]
+    qp: dict[str, list[str]]
+
+    def __init__(self, sync_url: str):
+        """Build urls from a sync url.
+
+        The provided sync url must have apikey query parameter, which will be
+        separated from the url and used in the Authorization header on async api
+        queries. All the query parameters are parsed and saved in `qp`, this is
+        to allow merging them with the parameters provided in the url.
+        (by default httpx overrides qp's in url)
+
+        >>> _ShareUrls("https://example.com/shares/v2/share-id?apikey=api-key&filter=foo=bar")
+        _ShareUrls(base_url='https://example.com', sync_path='/shares/v2/share-id', async_path='/shares/v2/async/share-id', authorization_header={'Authorization': 'token api-key'}, qp={'filter': ['foo=bar']})
+        >>> str(_ShareUrls("https://example.com/shares/v2/share-id?apikey=api-key&filter=foo=bar"))
+        'https://example.com//shares/v2/async/share-id'
+        >>> _ShareUrls("https://example.com/shares/v2/share-id?filter=foo=bar")
+        Traceback (most recent call last):
+        arcticsecurity.sharing_api.errors.ConfigError: API share url must have apikey parameter
+        """
+        o = urlparse(sync_url)
+        qp = parse_qs(o.query, keep_blank_values=True)
+
+        if "apikey" not in qp:
+            raise ConfigError("API share url must have apikey parameter")
+        elif len(qp["apikey"]) > 1:
+            raise ConfigError("API share url must have exactly one apikey parameter")
+
+        self.base_url = urlunparse(o._replace(path="", query=""))
+        self.sync_path = o.path
+        self.async_path = re.sub(r"^/shares(/v2)?", "/shares/v2/async", o.path)
+        self.authorization_header = {"Authorization": f"token {qp.pop('apikey')[0]}"}
+        self.qp = qp
+
+    def __str__(self) -> str:
+        return f"{self.base_url}/{self.async_path}"

arcticsecurity/sharing_api/_version.py

@@ -0,0 +1,11 @@
+"""
+Library version info.
+"""
+
+import platform as platform_library
+
+library_name = "sharing-api"
+version = "0.1.0"
+platform = platform_library.platform()
+python_version = platform_library.python_version()
+user_agent = f"{library_name}-v{version}-{platform}-py{python_version}"

arcticsecurity/sharing_api/errors.py

@@ -0,0 +1,84 @@
+"""
+Sharing API errors
+"""
+
+from typing import Any, Optional, Union
+
+__all__ = [
+    "Error",
+    "ConfigError",
+    "InvalidTokenError",
+    "ServerError",
+    "NetworkError",
+    "TimeoutError",
+    "Retry",
+]
+
+
+class Error(Exception):
+    """Base class for all errors."""
+
+    def __init__(self, *args: Any, url: Optional[str] = None, **kwargs: Any):
+        self.url = url
+        super().__init__(*args, **kwargs)
+
+
+class ConfigError(Error):
+    """User error in query configuration.
+
+    This error may be raised by this library or by the server.
+    """
+
+    pass
+
+
+class InvalidTokenError(Error):
+    """The server responded with "invalid token" error."""
+
+    pass
+
+
+class ServerError(Error):
+    """The server responded with a error message.
+
+    This results from a server which doesn't operate properly at the moment.
+    """
+
+    pass
+
+
+class NetworkError(Error):
+    """Error communicating with the sharing API server.
+
+    This results from error communicating the with the sharing API server.
+    """
+
+    pass
+
+
+class TimeoutError(Error):
+    """Query to sharing API server timed out.
+
+    The three-phase query to the sharing API exceeded the configured timeout.
+    """
+
+    pass
+
+
+class Retry(NetworkError):
+    """Network error that should be retried.
+
+    This is raised from errors that are likely transient and may succeed if retried
+    after some time.
+    """
+
+    def __init__(self, *args: Any, after: Union[str, int, None] = None, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+
+        if after is None:
+            self.after = None
+        else:
+            try:
+                self.after = int(after)
+            except ValueError:
+                self.after = None

arcticsecurity/sharing_api/sharing_api.py

@@ -0,0 +1,349 @@
+"""
+Sharing API client.
+"""
+
+import json
+import logging
+import time
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Optional, Union
+
+from ._api_client import _ApiClient
+from .errors import ConfigError, ServerError
+
+logger = logging.getLogger(__name__)
+Event = dict[str, Union[str, list[str]]]
+
+
+@dataclass(frozen=True)
+class SyncReadResponse:
+    events: list[Event]
+    token: Optional[str]
+    has_more: bool
+
+
+class Sync:
+    """Sync events from sharing API."""
+
+    allowed_user_provided_qps = {
+        "filter",
+        "projection",
+    }
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        filter: Optional[str] = None,
+        projection: Optional[Iterable[str]] = None,
+        start: Union[datetime, int, float, None] = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize Sync class.
+
+        Args:
+            url: Sharing API url, must include `apikey` query parameter.
+            filter: Rulelang filter.
+            projection: List of event field names to include in the results. Note that the list of keys provided by the server can only be limited by this parameter.
+            start: Start time for the initial query. Can also be set with seek(). Default value `None` means current time. Positive numbers are interpret as epoch time. Non-positive numbers are interpret as that many seconds in the past.
+        """
+
+        # Check args
+        if not isinstance(url, str):
+            raise TypeError(f"url must be string not {type(url)}")
+
+        if not (filter is None or isinstance(filter, str)):
+            raise TypeError(f"filter must be string or None, not {type(filter)}")
+
+        if not (
+            projection is None
+            or (
+                isinstance(projection, Iterable)
+                and not isinstance(projection, str)
+                and all(isinstance(x, str) for x in projection)
+            )
+        ):
+            raise TypeError(
+                "projection must be a list of key names, each an instance of str"
+            )
+
+        user_agent = kwargs.pop("user_agent", None)
+        if not (user_agent is None or isinstance(user_agent, str)):
+            raise TypeError(
+                f"user_agent must be string or None, not {type(user_agent)}"
+            )
+
+        if kwargs:
+            raise ValueError(f"Unknown parameter(s) {tuple(kwargs.keys())}")
+
+        # Initialize client
+        self.api_client = _ApiClient(url, user_agent=user_agent)
+
+        invalid_qps_in_url = (
+            self.api_client.urls.qp.keys() - self.allowed_user_provided_qps
+        )
+        if invalid_qps_in_url:
+            raise ConfigError(f"Invalid qps in url: {invalid_qps_in_url}")
+
+        self.qp = {
+            "filter": filter,
+            "projection": projection,
+            "sort": "_id",
+        }
+
+        self.start = self._seek(start)
+
+    def read(
+        self,
+        *,
+        token: Optional[str] = None,
+        pagesize: int = 1000,
+        timeout: Optional[float] = 600,
+    ) -> SyncReadResponse:
+        """Sync events from sharing API
+
+        Events are returned sorted by insertion time.
+
+        Args:
+            token: Continuation token. If not given, the start time set earlier is used.
+            pagesize: Maximum number of events to return.
+            timeout: Timeout for the operation in [s].
+
+        Returns:
+            Batch of events and a continuation token for the next query.
+        """
+        if not (token is None or isinstance(token, str)):
+            raise TypeError(f"token must be string or None, not {type(token)}")
+
+        if not isinstance(pagesize, int):
+            raise TypeError(f"pagesize must be int not {type(pagesize)}")
+
+        if not (timeout is None or isinstance(timeout, (int, float))):
+            raise TypeError(f"timeout must be float or None, not {type(timeout)}")
+
+        qp = _remove_none_values(
+            {
+                **self.qp,
+                **{
+                    "token": token,
+                    "limit": pagesize if pagesize != 0 else None,
+                },
+            }
+        )
+
+        if "token" not in qp:
+            qp["start"] = self.start
+
+        resp = self.api_client.async_query(qp, timeout=timeout)
+
+        try:
+            token = resp.headers["x-next-token"]
+            has_more = True
+        except KeyError:
+            token = resp.headers.get("x-last-inserted-token", None)
+            has_more = False
+
+        try:
+            return SyncReadResponse(
+                resp.json(),
+                token,
+                has_more,
+            )
+        except json.decoder.JSONDecodeError:
+            logger.error(f"Invalid response from server {resp.content=}")
+            raise ServerError(f"Invalid response from server {resp}")
+
+    def seek(self, ts: Union[datetime, int, float, None]) -> None:
+        """Set sync start to specific time.
+
+        Args:
+            ts: See start in __init__.
+        """
+        self.start = self._seek(ts)
+
+    def _seek(self, ts: Union[datetime, int, float, None]) -> float:
+        """Set sync start to specific time."""
+        if not (ts is None or isinstance(ts, (int, float, datetime))):
+            raise TypeError(f"ts must be int, float, datetime or None, not {type(ts)}")
+
+        if ts is None:
+            return time.time()
+        elif isinstance(ts, (int, float)):
+            return float(ts)
+        else:
+            return ts.timestamp()
+
+    def __str__(self) -> str:
+        return f"Sync({self.api_client.urls})"
+
+
+class Query:
+    """Query events from sharing API."""
+
+    allowed_user_provided_qps = {
+        "filter",
+        "projection",
+        "limit",
+        "start",
+        "end",
+        "reverse",
+    }
+
+    def __init__(self, url: str, **kwargs: Any):
+        """
+        Initialize Query class.
+
+        Args:
+            url: Sharing API url, must include `apikey` query parameter.
+        """
+
+        # Check args
+        if not isinstance(url, str):
+            raise TypeError(f"url must be string not {type(url)}")
+
+        user_agent = kwargs.pop("user_agent", None)
+        if not (user_agent is None or isinstance(user_agent, str)):
+            raise TypeError(
+                f"user_agent must be string or None, not {type(user_agent)}"
+            )
+
+        if kwargs:
+            raise ValueError(f"Unknown parameter(s) {tuple(kwargs.keys())}")
+
+        # Initialize client
+        self.api_client = _ApiClient(url, user_agent=user_agent)
+
+        invalid_qps_in_url = (
+            self.api_client.urls.qp.keys() - self.allowed_user_provided_qps
+        )
+        if invalid_qps_in_url:
+            raise ConfigError(f"Invalid qps in url: {invalid_qps_in_url}")
+
+    def query(
+        self,
+        *,
+        filter: Optional[str] = None,
+        projection: Optional[Iterable[str]] = None,
+        start: Union[datetime, int, float, None] = None,
+        end: Union[datetime, int, float, None] = None,
+        reverse: bool = False,
+        max_events: int = 0,
+        timeout: Optional[float] = 600,
+        **kwargs: Any,
+    ) -> Iterator[Event]:
+        """Query sharing API.
+
+        Events are returned sorted by timestamp.
+
+        Args:
+            filter: Rulelang filter.
+            projection: List of event field names to include in the results. Note that the list of keys provided by the server can only be limited by this parameter.
+            start: Start time for the query. Default value `None` means forever. Positive numbers are interpret as epoch time. Non-positive numbers are interpret as that many seconds in the past.
+            end: End time for the query. Default value `None` means current time. Positive numbers are interpret as epoch time. Non-positive numbers are interpret as that many seconds in the past.
+            reverse: Return events in reverse order.
+            max_events: Maximum number of events to generate.
+            timeout: Timeout for one sharing API query fetching more events in [s].
+
+        Returns:
+            Generator yielding events matching the query.
+        """
+        if not (filter is None or isinstance(filter, str)):
+            raise TypeError(f"filter must be string or None, not {type(filter)}")
+
+        if not (
+            projection is None
+            or (
+                isinstance(projection, Iterable)
+                and not isinstance(projection, str)
+                and all(isinstance(x, str) for x in projection)
+            )
+        ):
+            raise TypeError(
+                "projection must be a list of key names, each an instance of str"
+            )
+
+        if not (start is None or isinstance(start, (int, float, datetime))):
+            raise TypeError(
+                f"start must be int, float, datetime or None, not {type(start)}"
+            )
+
+        if not (end is None or isinstance(end, (int, float, datetime))):
+            raise TypeError(
+                f"end must be int, float, datetime or None, not {type(end)}"
+            )
+
+        if not isinstance(reverse, bool):
+            raise TypeError(f"reverse must be bool, not {type(bool)}")
+
+        if not isinstance(max_events, int):
+            raise TypeError(f"max_events must be int, not {type(max_events)}")
+
+        if not (timeout is None or isinstance(timeout, (int, float))):
+            raise TypeError(f"timeout must be float or None, not {type(timeout)}")
+
+        pagesize = kwargs.pop("pagesize", 1000)
+        if not isinstance(pagesize, int):
+            raise TypeError(f"pagesize must be int, not {type(kwargs.get('pagesize'))}")
+
+        if kwargs:
+            raise ValueError(f"Unknown parameter(s) {tuple(kwargs.keys())}")
+
+        qp = _remove_none_values(
+            {
+                "filter": filter,
+                "projection": projection,
+                "start": _build_start_end(start),
+                "end": _build_start_end(end),
+                "reverse": "" if reverse else None,
+                "limit": pagesize,
+            }
+        )
+
+        more = True
+        token = None
+        n_events = 0
+
+        while more:
+            resp = self.api_client.async_query(qp, timeout=timeout)
+            events = resp.json()
+            logger.debug(f"queried, got {len(events)} events")
+
+            try:
+                token = resp.headers["x-next-token"]
+            except KeyError:
+                more = False
+            else:
+                qp["token"] = token
+                more = True
+
+            for event in events:
+                yield event
+                n_events += 1
+                if 0 < max_events <= n_events:
+                    more = False
+                    break
+
+    def __str__(self) -> str:
+        return f"Query({self.api_client.urls})"
+
+
+def query(url: str, **kwargs: Any) -> Iterable[Event]:
+    """Shortcut to Query(url).query()."""
+    return Query(url).query(**kwargs)
+
+
+def _remove_none_values(d: dict[str, Optional[Any]]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _build_start_end(ts: Union[datetime, int, float, None]) -> Union[int, float, None]:
+    """Build start / end query parameter."""
+    if ts is None:
+        return None
+    elif isinstance(ts, (int, float)):
+        return ts
+    else:
+        return ts.timestamp()

arcticsecurity-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: arcticsecurity
+Version: 0.1.0
+Summary: Library to access Arctic Security APIs
+Author: Arctic Security
+Author-email: Arctic Security <pypi@arcticsecurity.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.9
+Project-URL: Home, https://github.com/arcticsecurity/arcticsecurity-python
+Project-URL: Issues, https://github.com/arcticsecurity/arcticsecurity-python/issues
+Description-Content-Type: text/markdown
+
+# Arctic Security Library
+
+A Python library to access Arctic Security's Sharing API endpoints and retrieve event data.
+
+## Installation
+
+```bash
+pip install arcticsecurity
+```
+
+Python >= 3.9 is required.
+
+## Quick Start
+
+The library supports two distinct ways to retrieve events from the Sharing API: `Query` and `Sync`.
+
+### Query
+
+Use the `Query` class to perform one-off queries for specific events.
+
+```python
+from arcticsecurity.sharing_api import Query
+
+url = "https://example.com/shares/v2/share-id?apikey=YOUR_API_KEY"
+for event in Query(url).query(filter='"network owner"="Example Co"', max_events=50):
+    print(event)
+```
+
+### Sync
+
+Use the `Sync` class to reliably fetch all event data. It uses pagination with opaque continuation tokens to ensure no events are missed.
+
+```python
+from arcticsecurity.sharing_api import Sync
+
+url = "https://example.com/shares/v2/share-id?apikey=YOUR_API_KEY"
+sync = Sync(url, filter='"network owner"="Example Co"')
+
+# Fetch token from previous run
+token = ...
+
+while True:
+    res = sync.read(token=token, pagesize=1000)
+    if not res.events:
+        break
+    # process res.events...
+
+    token = res.token
+
+    if not res.has_more:
+       break
+
+# store the token for the next run
+```
+
+## Common features
+
+- Robust error handling with specific exceptions (`ConfigError`, `NetworkError`, `Retry`, `TimeoutError`, `InvalidTokenError`, `ServerError`).
+- Optional timeout and user-agent customization
+
+## Versioning
+
+Follows [Semantic Versioning v2](https://semver.org/spec/v2.0.0.html).
+
+## Development
+
+[uv](https://docs.astral.sh/uv/) is required.
+
+```bash
+uv sync --group dev
+
+uv run ruff check .
+uv run pytest --doctest-modules
+
+uv run mypy --config-file pyproject.toml -p arcticsecurity
+uv run ty check
+
+uv run mkdocs build
+uv run mkdocs serve
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Please add tests for any new behavior.
+
+## Status
+
+Experimental (`0.1.x`); the API may evolve. Pin the library version for production use.

arcticsecurity-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+arcticsecurity/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arcticsecurity/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arcticsecurity/sharing_api/__init__.py,sha256=B0TgFkilX9dAaEyHRi1hO4CMX_jr5VFzFR2JICNCYT8,91
+arcticsecurity/sharing_api/_api_client.py,sha256=8i_8kvsGfnufMqH1lHHHuE1q3V5XgdOK5deWSqX-B3I,13563
+arcticsecurity/sharing_api/_version.py,sha256=Icv4zNjQLmDfNstVPJvkTQ1TO0T-Iac7S79XmZsG2BA,277
+arcticsecurity/sharing_api/errors.py,sha256=elWNc3v2d8GlXtySsQYvCL25QBEa8JCjw-ySXpbmx6Q,1711
+arcticsecurity/sharing_api/sharing_api.py,sha256=a7jivPbfddlaVe1uKAqchbCttuMHWs6EYgP3Jeg6sr8,11336
+arcticsecurity-0.1.0.dist-info/licenses/LICENSE,sha256=zwVs8Z8wzlOjkzY9dM65qoFgzhRTrvOHKy4wFVPlxQg,1072
+arcticsecurity-0.1.0.dist-info/WHEEL,sha256=iCTolw4aw2dP3yfM-EQCGTDsFCXL_ymmbYnBRVH7plA,81
+arcticsecurity-0.1.0.dist-info/METADATA,sha256=qqUSUP0k9F-uLgVBFsrQ1_irFjZIdMxmcLXLf9YIGBA,3189
+arcticsecurity-0.1.0.dist-info/RECORD,,

arcticsecurity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.11
+Root-Is-Purelib: true
+Tag: py3-none-any

arcticsecurity-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arctic Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.