Arctic Security Library

A Python library to access Arctic Security's Sharing API endpoints and retrieve event data.

Documentation

Full documentation, including API reference guides and examples, is available at: https://arcticsecurity.github.io/arcticsecurity-python/

Installation

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.

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 synchronize all event data. It uses pagination with opaque continuation tokens to ensure no events are missed.

Here Sync means keeping your own copy of the events synchronized. It is unrelated to the Sharing API's synchronous endpoints: both classes use the asynchronous ones.

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"')

# Load the token stored by the previous run, or None on the first run
token = None

while True:
    res = sync.read(token=token, pagesize=1000)
    # process res.events...

    # res.token is None when the server reported no position; keep the old one
    if res.token is not None:
        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, AuthError, NetworkError, Retry, TimeoutError, InvalidTokenError, ServerError).
• Optional timeout and user-agent customization

Versioning

Follows Semantic Versioning v2.

Development

uv is required.

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.