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