Threat Response API Module

Python API Module for Threat Response APIs.

Installation

• Local

pip install --upgrade .
pip show threatresponse

• GitHub

pip install --upgrade git+https://github.com/CiscoSecurity/tr-05-api-module.git[@branch_name_or_release_version]
pip show threatresponse

• PyPi

pip install --upgrade threatresponse[==release_version]
pip show threatresponse

Usage

from threatresponse import ThreatResponse

client = ThreatResponse(
    client_id='<YOUR TR CLIENT ID>',  # required
    client_password='<YOUR TR CLIENT PASSWORD>',  # required
    region='<YOUR TR REGION>',  # optional
    logger=<SOME LOGGER INSTANCE>,  # optional
    proxy='<SOME PROXY URL>',  # optional
    environment='<SPECIFIC ENVIRONMENT>' # optional
)

• client_id and client_password credentials must be taken from an existing API client for accessing the Cisco Threat Response APIs. The official documentation on how to create such a client can be found here. Make sure to properly set some scopes which will grant the client different (ideally minimum) privileges.
• region must be one of: '' or 'us' (default), 'eu', 'apjc'. Other regions are not supported yet.
• logger must be an (already configured) instance of the built-in logging.Logger class (or one of its descendants).
• timeout must be a number (int or float) meaning the default amount of time (in seconds) to wait for the server to send data before giving up and raising an exception. Can be overwritten by explicitly specifying timeout on each call to any endpoint.
• proxy must be a URL in the format: http[s]://[username[:password]@]host[:port].
• environment must be a dict in the format: { 'visibility': 'https://www.example.com', 'private_intel': 'https://www.example.come', 'global_intel': 'https://www.example.com', } By default will be used: { 'visibility': 'https://visibility{region}.amp.cisco.com', 'private_intel': 'https://private.intel{region}.amp.cisco.com', 'global_intel': 'https://intel{region}.amp.cisco.com', }

Concrete Usage

• Inspect

Inspect allows to find an observable in a concrete string.

response = client.inspect.inspect({'content': 'example.com'})

• Observe

Observe returns summary for an observable.

response = client.enrich.observe.observables(
    [{'type': 'sha256', 'value': '8A32950CD96C5EF88F9DCBB66A08F59A7E8D8E5FECCDE9E115FBAA46D9AF88F9'}]
)

• Deliberate

Deliberate returns judgments based on added modules.

response = client.enrich.deliberate.observables(
    [{'type': 'sha256', 'value': '8A32950CD96C5EF88F9DCBB66A08F59A7E8D8E5FECCDE9E115FBAA46D9AF88F9'}]
)

Commands

For your convenience, we have made some predefined commands that you can use.

• Verdicts

Verdicts returns verdicts from all modules if the modules are configured. Accepts multiple observables.

response = client.commands.verdict(
    'string with observables ("8A32950CD96C5EF88F9DCBB66A08F59A7E8D8E5FECCDE9E115FBAA46D9AF88F9, cisco.com")'
)

• Targets

Targets returns all available targets if the modules are configured. Accepts multiple observables.

response = client.commands.targets(
    'string with observables ("8A32950CD96C5EF88F9DCBB66A08F59A7E8D8E5FECCDE9E115FBAA46D9AF88F9, cisco.com")'
)

Available Endpoints

Switch between .private_intel and .global_intel if necessary.

Actor

actor = client.private_intel.actor

Available methods:

• actor.post()
• actor.get()
• actor.put()
• actor.delete()
• actor.external_id()
• actor.search.get()
• actor.search.delete()
• actor.search.count()
• actor.metric.histogram()
• actor.metric.topn()
• actor.metric.cardinality()

Asset

asset = client.private_intel.asset

Available methods:

• asset.post()
• asset.get()
• asset.put()
• asset.delete()
• asset.external_id()
• asset.search.get()
• asset.search.delete()
• asset.search.count()
• asset.metric.histogram()
• asset.metric.topn()
• asset.metric.cardinality()

Asset mapping

asset_mapping = client.private_intel.asset_mapping

Available methods:

• asset_mapping.post()
• asset_mapping.get()
• asset_mapping.put()
• asset_mapping.delete()
• asset_mapping.expire()
• asset_mapping.external_id()
• asset_mapping.search.get()
• asset_mapping.search.delete()
• asset_mapping.search.count()
• asset_mapping.metric.histogram()
• asset_mapping.metric.topn()
• asset_mapping.metric.cardinality()

Asset properties

asset_properties = client.private_intel.asset_properties

Available methods:

• asset_properties.post()
• asset_properties.get()
• asset_properties.put()
• asset_properties.delete()
• asset_properties.expire()
• asset_properties.external_id()
• asset_properties.search.get()
• asset_properties.search.delete()
• asset_properties.search.count()
• asset_properties.metric.histogram()
• asset_properties.metric.topn()
• asset_properties.metric.cardinality()

Attack Pattern

attack_pattern = client.private_intel.attack_pattern

Available methods:

• attack_pattern.post()
• attack_pattern.get()
• attack_pattern.put()
• attack_pattern.delete()
• attack_pattern.external_id()
• attack_pattern.search.get()
• attack_pattern.search.delete()
• attack_pattern.search.count()
• attack_pattern.metric.histogram()
• attack_pattern.metric.topn()
• attack_pattern.metric.cardinality()

Bulk

bulk = client.private_intel.bulk

Available methods:

• bulk.post()
• bulk.get()

Bundle

bundle = client.private_intel.bundle

Available methods:

• bundle.export.post()
• bundle.export.get()
• bundle.import_.post()

Campaign

campaign = client.private_intel.campaign

Available methods:

• campaign.post()
• campaign.get()
• campaign.put()
• campaign.delete()
• campaign.external_id()
• campaign.search.get()
• campaign.search.delete()
• campaign.search.count()
• campaign.metric.histogram()
• campaign.metric.topn()
• campaign.metric.cardinality()

Casebook

casebook = client.private_intel.casebook

Available methods:

• casebook.post()
• casebook.get()
• casebook.put()
• casebook.delete()
• casebook.external_id()
• casebook.observables()
• casebook.texts()
• casebook.bundle()
• casebook.patch()
• casebook.search.get()
• casebook.search.delete()
• casebook.search.count()
• casebook.metric.histogram()
• casebook.metric.topn()
• casebook.metric.cardinality()

COA

coa = client.private_intel.coa

Available methods:

• coa.post()
• coa.get()
• coa.put()
• coa.delete()
• coa.external_id()
• coa.search.get()
• coa.search.delete()
• coa.search.count()
• coa.metric.histogram()
• coa.metric.topn()
• coa.metric.cardinality()

DataTable

data_table = client.private_intel.data_table

Available methods:

• data_table.post()
• data_table.get()
• data_table.delete()
• data_table.external_id()

Enrich

enrich = client.enrich

Available methods:

• enrich.health()
• enrich.health(_id)
• enrich.deliberate.observables()
• enrich.deliberate.sighting()
• enrich.deliberate.sighting_ref()
• enrich.observe.observables()
• enrich.observe.sighting()
• enrich.observe.sighting_ref()
• enrich.refer.observables()
• enrich.refer.sighting()
• enrich.refer.sighting_ref()

Event

event = client.private_intel.event

Available methods:

• event.history()
• event.get()
• event.delete()
• event.search.get()
• event.search.delete()
• event.search.count()

Feed

feed = client.private_intel.feed

Available methods:

• feed.view.txt()
• feed.view()
• feed.post()
• feed.put()
• feed.get()
• feed.delete()
• feed.external_id()
• feed.search.get()
• feed.search.delete()
• feed.search.count()

Feedback

feedback = client.private_intel.feedback

Available methods:

• feedback.post()
• feedback.get()
• feedback.delete()
• feedback.external_id()
• feedback.get(_id)

GraphQL

graph = client.private_intel.graphql

Available methods:

• graphql.post()

Identity Assertion

identity_assertion = client.private_intel.identity_assertion

Available methods:

• identity_assertion.post()
• identity_assertion.get()
• identity_assertion.put()
• identity_assertion.delete()
• identity_assertion.external_id()
• identity_assertion.search.get()
• identity_assertion.search.delete()
• identity_assertion.search.count()
• identity_assertion.metric.histogram()
• identity_assertion.metric.topn()
• identity_assertion.metric.cardinality()

Incident

incident = client.private_intel.incident

Available methods:

• incident.post()
• incident.get()
• incident.put()
• incident.delete()
• incident.external_id()
• incident.link()
• incident.status()
• incident.sightings.incidents()
• incident.patch()
• incident.search.get()
• incident.search.delete()
• incident.search.count()
• incident.metric.histogram()
• incident.metric.topn()
• incident.metric.cardinality()

Indicator

indicator = client.private_intel.indicator

Available methods:

• indicator.post()
• indicator.get()
• indicator.put()
• indicator.delete()
• indicator.external_id()
• indicator.judgements.indicators()
• indicator.sightings.indicators()
• indicator.search.get()
• indicator.search.delete()
• indicator.search.count()
• indicator.metric.histogram()
• indicator.metric.topn()
• indicator.metric.cardinality()

Inspect

inspect = client.inspect

Available methods:

• inspect.inspect()

Int

int = client.int

Available methods:

• int.integration.get(_id)
• int.integration.patch(_id)
• int.integration.delete(_id)
• int.integration.get()
• int.integration.post()
• int.module_instance.get(_id)
• int.module_instance.patch(_id)
• int.module_instance.delete(_id)
• int.module_instance.get()
• int.module_instance.post()
• int.module_type.get(_id)
• int.module_type.patch(_id)
• int.module_type.delete(_id)
• int.module_type.get()
• int.module_type.post()
• int.module_type_patch.get()
• int.module_type_patch.post()
• int.module_type_patch.get(_id)
• int.module_type_patch.put(_id)
• int.module_type_patch.delete(_id)
• int.module_type_patch.action_preview(_id)

Investigation

investigation = client.private_intel.investigation

Available methods:

• investigation.post()
• investigation.get()
• investigation.put()
• investigation.delete()
• investigation.external_id()
• investigation.search.get()
• investigation.search.delete()
• investigation.search.count()
• investigation.metric.histogram()
• investigation.metric.topn()
• investigation.metric.cardinality()

Judgment

judgment = client.private_intel.judgment

Available methods:

• judgment.post()
• judgment.get()
• judgment.put()
• judgment.delete()
• judgment.expire()
• judgment.external_id()
• judgment.judgments()
• judgment.search.get()
• judgment.search.delete()
• judgment.search.count()
• judgment.metric.histogram()
• judgment.metric.topn()
• judgment.metric.cardinality()

Malware

malware = client.private_intel.malware

Available methods:

• malware.post()
• malware.get()
• malware.put()
• malware.delete()
• malware.external_id()
• malware.search.get()
• malware.search.delete()
• malware.search.count()
• malware.metric.histogram()
• malware.metric.topn()
• malware.metric.cardinality()

Metrics

metrics = client.private_intel.metrics

Available methods:

• metrics.get()

Profile

profile = client.profile

Available methods:

• profile.whoami()
• profile.org.get()
• profile.org.post()

Properties

properties = client.private_intel.properties

Available methods:

• properties.get()

Relationship

relationship = client.private_intel.relationship

Available methods:

• relationship.post()
• relationship.get()
• relationship.put()
• relationship.delete()
• relationship.external_id()
• relationship.search.get()
• relationship.search.delete()
• relationship.search.count()
• relationship.metric.histogram()
• relationship.metric.topn()
• relationship.metric.cardinality()

Response

response = client.response

Available methods:

• response.respond.observables()
• response.respond.sighting()
• response.respond.trigger()

Sighting

sighting = client.private_intel.sighting

Available methods:

• sighting.post()
• sighting.get()
• sighting.put()
• sighting.delete()
• sighting.external_id()
• sighting.sightings()
• sighting.search.get()
• sighting.search.delete()
• sighting.search.count()
• sighting.metric.histogram()
• sighting.metric.topn()
• sighting.metric.cardinality()

SSE Device

sse_device = client.sse_device

Available methods:

• sse_device.get_all()
• sse_device.get_by_id()
• sse_device.post()
• sse_device.patch()
• sse_device.token()
• sse_device.re_token()
• sse_device.api_proxy()
• sse_device.delete()

SSE Tenant

sse_tenant = client.sse_tenant

Available methods:

• sse_tenant.get_token()

Target record

target_record = client.private_intel.target_record

Available methods:

• target_record.post()
• target_record.get()
• target_record.put()
• target_record.delete()
• target_record.external_id()
• target_record.search.get()
• target_record.search.delete()
• target_record.search.count()
• target_record.metric.histogram()
• target_record.metric.topn()
• target_record.metric.cardinality()

Status

status = client.private_intel.status

Available methods:

• status.get()

Tool

tool = client.private_intel.tool

Available methods:

• tool.post()
• tool.get()
• tool.put()
• tool.delete()
• tool.external_id()
• tool.search.get()
• tool.search.delete()
• tool.search.count()
• tool.metric.histogram()
• tool.metric.topn()
• tool.metric.cardinality()

User Management

user_mgmt = client.user_mgmt

Available methods:

• user_mgmt.users.get()
• user_mgmt.users.post()
• user_mgmt.batch.users()
• user_mgmt.search.users()

Verdict

verdict = client.private_intel.verdict

Available methods:

• verdict.get()

Version

version = client.private_intel.version

Available methods:

• version.get()

Vulnerability

vulnerability = client.private_intel.vulnerability

Available methods:

• vulnerability.cpe_match_strings()
• vulnerability.post()
• vulnerability.get()
• vulnerability.put()
• vulnerability.delete()
• vulnerability.external_id()
• vulnerability.search.get()
• vulnerability.search.delete()
• vulnerability.search.count()
• vulnerability.metric.histogram()
• vulnerability.metric.topn()
• vulnerability.metric.cardinality()

Weakness

weakness = client.private_intel.weakness

Available methods:

• weakness.post()
• weakness.get()
• weakness.put()
• weakness.delete()
• weakness.external_id()
• weakness.search.get()
• weakness.search.delete()
• weakness.search.count()
• weakness.metric.histogram()
• weakness.metric.topn()
• weakness.metric.cardinality()