Welcome to Threat Stack Python Client’s documentation!

The Threat Stack Python Client is a library which allows Python developers to write software that makes use of Threat Stack REST API.

Contents:

Installation

Install via pip:

pip install threatstack

Usage

Resource Types

  • agents
  • alerts
  • cve vulnerabilities
  • rulesets and rules
  • servers

For details on each resource please refer to the Threat Stack API documentation.

Create a new client

Import and create a new Threat Stack client:

from threatstack import ThreatStack

client = ThreatStack(api_key="<API_KEY>", org_id="<ORG_ID>")

Additional optional parameters can be specified when creating a new client object:

# default api_version: 2
# default http request timeout = 120

client = ThreatStack(
    api_key=<"API_KEY>",
    org_id="<ORG_ID>",
    api_version=[1 or 2],
    timeout=<SECONDS>
)

See ‘V1 Client Documentation’ for using the V1 ThreatStack API Client.

Time Ranges

Time ranges can be specified when listing resources using the start and end parameters:

now = datetime.now()
one_hour_ago = now - timedelta(hours=1)

alerts = client.alerts.list(start=one_hour_ago.isoformat(), end=now.isoformat())

for alert in alerts:
    details = client.alerts.get(alert["id"])

Agents

Listing Agents:

agents = client.agents.list()

# iterate over results
for agent in agents:
    print agent["id"]

# query parameters
agents = client.agents.list(type=<"monitor" or "investigate">, hostname=<"hostname">, instanceId="<instanceId">)

Offline Agents:

By default only online agents will be listed. To get offline agents set offline to True.

offline_agents = client.agents.list(offline=True)

Get agent by ID:

agent = client.agents.get("<agent_id>")

Alerts

Listing Alerts:

alerts = client.alerts.list(severity=<1, 2, or 3>)

Get Alert by ID:

alert = client.alerts.get("<alert_id>")

List all dismissed alerts:

dismissed = client.alerts.list(dismissed=True)

Get severity counts for alerts:

sev_counts = client.alerts.severity_counts()

Get an event for an alert:

event = client.alerts.event(alert_id="<alert_id>", event_id="<event_id>")

CVE Vulnerabilities

List all vulnerabilities:

vulns = client.vulnerabilities.list()

# query parameters
vulns = client.vulnerabilities.list(package="<package_name>", server="<instanceId/hostname>", agent="<agentId>")

Get a vulnerability by CVE number:

cve = client.vulnerabilities.get("<cve_number>")

List all suppressed vulnerabilities:

vulns = client.vulnerabilties.list(suppressed=True)

# same query params can be used as with list
vulns = client.vulnerabilities.list(suppressed=True, package="<package_name>", server="<instanceId/hostname>", agent="<agentId>")

Rulesets & Rules

List all rulesets:

rulesets = client.rulesets.list()

# query parameters
rulesets = client.rulesets.list(agentId="<agent_id>")

Get a ruleset:

ruleset = client.ruleset.get("<ruleset_id>")

Get all rules for a ruleset:

rules = client.ruleset.rules(ruleset_id="<ruleset_id>")

Get a rule for a ruleset:

rule = client.ruleset.rules(ruleset_id="<ruleset_id>", rule_id="<rule_id>")

Servers

Get all servers:

servers = client.servers.list()

Get all non-monitored servers:

non_monitored = client.servers.list(non_monitored=True)