cybersift-sdk 0.1.3.1

A python helper for the various CyberSift APIs

CyberSift SDK

This is a simple Python SDK for CyberSift Products which provides helper methods to interact with SIEM and Tutela REST APIs.

SIEM SDK Python Library

Overview

The SIEM (Security Information and Event Management) SDK is a Python wrapper designed to interact with a SIEM backend. It provides functionalities to manage user authentication and retrieve liveliness data of various agents connected to the system. This library uses Python's requests library to interact with a remote SIEM server.

Installation

pip install cybersift-sdk

Usage

Initialization

To initialize the SDK, create an instance of the SIEM class. You can provide an optional backend URL (default is http://localhost:5601).

from cybersift.siem import SIEM

# Default URL
siem = SIEM()

# Custom backend URL
siem = SIEM(backend="http://your-siem-backend.com")

Functions

login(username: str, password: str, totp: str = "") -> bool

Authenticates the user with the SIEM backend using a username, password, and optional Time-based One-Time Password (TOTP) for two-factor authentication. Returns True on successful login and False otherwise.

siem.login(username="admin", password="your_password", totp="123456")

Use Case:

• User Authentication: This method is used to authenticate with the SIEM server before making any subsequent requests.

getAgentLiveliness() -> Union[Dict, bool]

Fetches the liveliness information of all agents in the SIEM system. Returns a dictionary containing hostnames, their types, last-contact timestamps, and statuses. Returns False if the request fails.

liveliness_data = siem.getAgentLiveliness()
if liveliness_data:
    print(liveliness_data)

Use Case:

• Monitoring Active Agents: This method is used to retrieve the status and last contact time of active agents in the SIEM system.

getDeadAgents() -> Union[list, bool]

Fetches a list of agents that are considered dead (not responsive or have an unknown status). Returns a list of dead agents or False if the request fails.

dead_agents = siem.getDeadAgents()
if dead_agents:
    print(dead_agents)

Use Case:

• Identifying Dead Agents: This method helps system administrators monitor and identify agents that are no longer responsive in the SIEM environment.

close()

Closes the current session.

siem.close()

Use Case:

• Session Management: This method is used to terminate the session once operations are completed to free up resources.

Example Workflow

from cybersift.siem import SIEM

# Initialize SIEM instance
siem = SIEM()

# Login to the system
if siem.login(username="admin", password="password123", totp=""):
    # Get live agents
    live_agents = siem.getAgentLiveliness()
    if live_agents:
        print("Live Agents:", live_agents)
    
    # Get dead agents
    dead_agents = siem.getDeadAgents()
    if dead_agents:
        print("Dead Agents:", dead_agents)

# Close the session
siem.close()

Error Handling

• If any request fails, a message will be printed with the status code and the response details.

Tutela SDK Python Library

Overview

The Tutela SDK is a Python library designed to interact with the Tutela backend services for managing assets, retrieving cloud inventory, software information, compliance alerts, and more. It uses Python's requests library to communicate with the backend via REST API.

Installation

pip install cybersift-sdk

Usage

Initialization

To initialize the SDK, create an instance of the Tutela class. The backend URL can be passed as an optional argument (default is https://cs-vas-backend.cybersift.io).

from cybersift.tutela import Tutela

# Default backend URL
tutela = Tutela()

# Custom backend URL
tutela = Tutela(backend="https://your-backend-url")

Functions

login(username: str, password: str) -> bool

Authenticates the user by performing a login request with the provided username and password. Returns True on successful login, False otherwise.

tutela.login(username="admin", password="your_password")

Use Case:

• User Authentication: This method logs the user into the backend system to access protected endpoints.

check_login() -> bool

Checks if the user is currently logged in by making a request to the /checkLogin endpoint. Returns True if the user is logged in, False otherwise.

if tutela.check_login():
    print("User is logged in!")

Use Case:

• Session Validation: This method is used to verify if the current session is authenticated and active.

get_host_agents() -> Union[Dict, bool]

Fetches the list of host agents (local assets) from the backend. Returns a dictionary of host agents if successful, or False if the request fails.

host_agents = tutela.get_host_agents()
if host_agents:
    print(host_agents)

Use Case:

• Host Asset Retrieval: This method retrieves information about all host agents monitored by the system.

get_cloud_assets() -> Union[Dict, bool]

Fetches the cloud inventory assets by making a request to the backend. Returns a dictionary of cloud assets or False if the request fails.

cloud_assets = tutela.get_cloud_assets()
if cloud_assets:
    print(cloud_assets)

Use Case:

• Cloud Asset Inventory: This method retrieves cloud-based assets managed by the system.

get_hosts_with_software(software: str) -> Union[Dict, bool]

Fetches the hosts that have the specified software installed by searching the asset inventory. Returns a dictionary of hosts that match the search or False if the request fails.

hosts_with_software = tutela.get_hosts_with_software(software="nginx")
if hosts_with_software:
    print(hosts_with_software)

Use Case:

• Software Search: This method allows users to search for hosts that have a specific software installed.

get_eol_info() -> Union[Dict, bool]

Fetches information on End-of-Life (EOL) software. Returns a dictionary containing EOL software details or False if the request fails.

eol_info = tutela.get_eol_info()
if eol_info:
    print(eol_info)

Use Case:

• EOL Monitoring: This method provides details about software that has reached its end-of-life.

get_compliance_alerts(query="false") -> Union[Dict, bool]

Fetches compliance alerts from the backend based on a search query. Returns a dictionary of compliance alerts or False if the request fails.

compliance_alerts = tutela.get_compliance_alerts(query="Security")
if compliance_alerts:
    print(compliance_alerts)

Use Case:

• Compliance Monitoring: This method is used to retrieve alerts related to system compliance issues based on specified search criteria.

get_all_compliance_alerts(query="false") -> Union[Dict, bool]

Fetches all (resolved and pending) compliance alerts from the backend based on a search query. Behaves exactly the same as get_compliance_alerts(). Returns a dictionary of compliance alerts or False if the request fails. The only difference is that get_all_compliance_alerts() will not return any alerts that are resolved, while this method will return all alerts (resolved and pending).

Use Case:

• Audit Compliance Monitoring: This method is used to retrieve which hosts comply with a best practice and which do not.

close()

Closes the current session.

tutela.close()

Use Case:

• Session Management: This method is used to close the session once all operations are completed.

Example Workflow

from cybersift.tutela import Tutela

# Initialize Tutela instance
tutela = Tutela()

# Login to the system
if tutela.login(username="admin", password="password123"):
    # Check login status
    if tutela.check_login():
        print("Logged in!")

    # Get host agents
    host_agents = tutela.get_host_agents()
    if host_agents:
        print("Host Agents:", host_agents)

    # Get cloud assets
    cloud_assets = tutela.get_cloud_assets()
    if cloud_assets:
        print("Cloud Assets:", cloud_assets)

    # Get hosts with specific software
    hosts_with_nginx = tutela.get_hosts_with_software(software="nginx")
    if hosts_with_nginx:
        print("Hosts with NGINX:", hosts_with_nginx)

# Close the session
tutela.close()

Error Handling

• If any request fails, the method prints the status code and the response details to the console.

Development Guide

# run test suite
python3 setup.py test

# build for distribution (pip)
python -m build

# upload to pip
twine upload dist/*