V1 Client Documentation¶

Resource Types¶

agents
alerts
logs
organizations
policies

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

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

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

client = ThreatStack(
    api_key=<"API_KEY>",
    org_id="<ORG_ID>",
    api_version=1,
    timeout=120
)

Listing Resources¶

All resource types support a list method which returns a generator. The generator can be used to iterate over the results. NOTE: The list method uses the default time range for the resouce (see Time Ranges below).

Listing Agents:

agents = client.agents.list()

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

Listing Alerts:

alerts = client.alerts.list()

Listing Logs:

logs = client.logs.list()

Listing Organizations:

orgs = client.organizations.list()

Listing Policies:

policies = client.policies.list()

Time Ranges

Each resource type has a default date/time range that is applied by the Threat Stack API when listing items. Please refer to the Threat Stack API documentation for additional information on these default date/time ranges. To specify a date/time range other than the default, the start and end parameters can be used.

Using a date range:

alerts = client.alerts.list(start="2017-05-01", end="2017-05-31")

Using a date and time range:

alerts = client.alerts.list(
    start="2017-05-01 08:00:00",
    end="2017-05-01 09:00:00"
)

Using datetime:

from datetime import datetime, timedelta

end = datetime.now()
start = end - timedelta(hours=1)
alerts = client.alerts.list(start=start, end=end)

Pagination

The Agents, Alerts, and Logs resource types support pagination. This allows you to control the page and count values when retrieving a list of items. Please refer to the Threat Stack API documentation for additional information on pagination.

# default page: 0
# default count: 20

agents = client.agents.list(page=2, count=10)

Field Filters

When listing resources you can limit the fields that are returned from the ThreatStack API for each resource. Please refer to the Threat Stack API documentation for additional information on partial responses.

Only retrieve agent hostname and IP address:

agents = client.agents.list(fields=["hostname", "ip_address"])

Getting a Specific Resource¶

All resource types other than Logs and Organizations support the get method. This method allows you to retrieve details about a specific resource given its unique identifier. The get method returns a Python dict.

Getting an Agent:

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

Getting an Alert:

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

Getting a Policy:

policy = client.policy.get("<POLICY_ID>")

If the resource is not found by the ThreatStack API, and empty dict is returned from the client.

agent = client.agents.get("<AGENT_ID">)
if agent:
    print agent
else:
    print "Agent not found"

Additional Methods¶

Organizations¶

The Organizations resource has a users method which returns a list of users for a given organization.

Get users for an Organization:

users = client.organization.users("<org_id>")

Additional Examples¶

Retrieve list of alert ID’s from the last hour and then get details for each alert:

from datetime import datetime, timedelta
from threatstack import ThreatStack, ThreatStackAPIError

client = ThreatStack("<API_KEY>")

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

try:
    alerts = client.alerts.list(start=one_hour_ago, end=now, fields=["id"])

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

except ThreatStackAPIError:
    print "The ThreatStack API returned an error response."