Quickstart

Eager to get started? This page gives a good introduction in how to get started with Cybsi Cloud SDK.

First, make sure that:

• Cybsi Cloud SDK is installed and up-to date.

Let’s get started with some simple examples.

Get objects from collection

Cybsi Cloud serves threat intelligence. In our case threat intelligence is condensed into collections of objects. Often such objects represent indicators of compromise.

In other words, Cybsi Cloud has collections of objects associated with malicious software, phishing sites, botnets and so on. It also has collections of definitely harmless files, IP addresses and domain names.

In the example below we get list of object from the collection named “phishing”.

#!/usr/bin/env python3
from cybsi.cloud import Client, Config
from cybsi.cloud.pagination import chain_pages

if __name__ == "__main__":
    config = Config(api_key="the cryptic string")

    with Client(config) as client:
        collection_id = "phishing"

        # Retrieve collection schema, it describes all attributes
        # of objects you can encounter in the collection.
        schema_view = client.iocean.collections.view_schema(collection_id=collection_id)
        print(schema_view.schema)

        # Retrieve first page of collection objects.
        start_page, _ = client.iocean.objects.filter(
            collection_id=collection_id,
        )

        for obj in chain_pages(start_page):
            # Do something with the object.
            print(obj)

Use AsyncClient instead of Client if you have an asynchronous application.

Get object changes in the collection

In the example below we get objects changes happened in the collection.

#!/usr/bin/env python3
import time
from typing import Iterable, Optional

from cybsi.cloud import Client, Config
from cybsi.cloud.iocean import ObjectChangeView
from cybsi.cloud.pagination import Cursor, Page


def main():
    config = Config(api_key="the cryptic string")

    with Client(config) as client:
        collection_id = "phishing"
        _, changes_cursor = client.iocean.objects.filter(
            collection_id=collection_id,
        )

        process_changes(client, collection_id, changes_cursor)


def process_changes(client: Client, collection_id: str, changes_cursor: Cursor):
    fetcher = ChangesFetcher(client, collection_id, changes_cursor)
    while True:
        handle_changes(fetcher.changes())
        # Do not forget to persist last changes cursor
        changes_cursor = fetcher.cursor

        time.sleep(10)


class ChangesFetcher:
    def __init__(self, client: Client, collection_id: str, changes_cursor: Cursor):
        self._client = client
        self._collection_id = collection_id
        self._changes_cursor = changes_cursor

    def changes(self) -> Iterable[ObjectChangeView]:
        """Lazily fetch all available collection changes."""
        page: Optional[Page[ObjectChangeView]] = self._client.iocean.objects.changes(
            collection_id=self._collection_id, cursor=self._changes_cursor
        )

        while page:
            # changes page may return empty cursor.
            # Do not save empty cursor to prevent last cursor lost.
            if page.cursor is not None:
                self._changes_cursor = page.cursor
            yield from page
            page = page.next_page()

    @property
    def cursor(self):
        """Current cursor required to fetch next changes page."""
        return self._changes_cursor


def handle_changes(changes: Iterable[ObjectChangeView]):
    """Handle collection changes."""
    cnt = 0
    for item in changes:
        # Do something with item
        cnt += 1
        pass
    print(f"handled {cnt} changes")


if __name__ == "__main__":
    main()

Working with tasks

You also can working with enrichment tasks. Create tasks for enriching indicators and get their results. The results of the enrichment are objects corresponding to a given schema.

See enrichment tasks examples for more information.