The Evident Security Platform API (version 2.0) is designed to allow users granular control over their Amazon Web Service security experience by allowing them to review alerts, monitor signatures, and create custom signatures.

This Python package is automatically generated by the Swagger Codegen project:

• API version: v2_sdk
• Package version: 1.0.0.rc1
• Build package: io.swagger.codegen.languages.PythonClientCodegen

Python 2.7 and 3.4+

pip install esp_sdk

Or you can install directly from Github

pip install git+https://github.com/EvidentSecurity/esp-sdk-python.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/EvidentSecurity/esp-sdk-python.git)

Then import the package:

import esp_sdk

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import esp_sdk

You must set your access_key_id and your secret_access_key. You can set these directly:

config = esp_sdk.Configuration()
config.access_key_id = '<your key>'
config.secret_access_key = '<your secret key>'

or with environment variables:

os.environ['ESP_ACCESS_KEY_ID'] = '<your key>'
os.environ['ESP_SECRET_ACCESS_KEY'] = '<your secret key>'

Get your HMAC keys from the Evident.io website, esp.evident.io

Users of Evident.io's AWS marketplace PSAAS/appliance will need to set the host for their appliance instance. You can set this directly:

config = esp_sdk.Configuration().host = '<host for appliance instance>'

The host needs to include the scheme. Example: config.host = 'https://api.evident.io' This is the default.

Alternatively, the site can also be set with an environment variable.

export ESP_HOST=<host for appliance instance>

Please follow the installation procedure and then run the following:

from __future__ import print_function
import time
import esp_sdk
from esp_sdk.rest import ApiException
from pprint import pprint


# create an instance of the API class
api_instance = esp_sdk.APIKeysApi()
include = 'include_example' # str | Related objects that can be included in the response:  user See Including Objects for more information. (optional)
name = 'name_example' # str | The name of the API Key (optional)

try:
    # Create a(n) API Key
    api_response = api_instance.create(include=include, name=name)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling APIKeysApi->create: %s\n" % e)

The response objects have an errors collection. If the API call returns a non fatal response, like validation issues, you can check the errors object to see what went wrong.

> t = esp_sdk.TeamsApi().create(1, '')
# => t.errors = ["Name can't be blank"]

When an error is thrown, you can rescue the error and check the error message:

> c = esp_sdk.SignaturesApi().run(1, 9999, 'us-east-1')
# =>  esp_sdk.rest.ApiException: (404)
# =>  Reason: Failed.  Response code = 404.  Response message = Couldn't find ExternalAccount

Evident.io API endpoints that return a collection of objects allows for paging and only returns a limited number of items at a time. The Evident.io SDK returns an esp_sdk.PaginatedCollection object that provides methods for paginating through the collection.

> alerts = esp_sdk.AlertsApi().list(345)
> alerts.current_page_number # => "1"
> page2 = alerts.next_page()
> alerts.current_page_number # => "1"
> page2.current_page_number # => "2"
> page1 = page2.previous_page()
> page1.current_page_number # => "1"
> last_page = alerts.last_page()
> last_page.current_page_number # => "25"
> page4 = alerts.page(4)
> page4.current_page_number # => "4"

The __iter__ function on esp_sdk.PaginatedCollection allows you to iterate through the entire collection, making additional API calls to get the next page, until it is on the last page.

> alerts = esp_sdk.AlertsApi().list(345)
> [a.id for a in alerts]

See esp_sdk.PaginatedCollection for all the pagination methods available.

Most of the objects in the Evident.io SDK have a corresponding API call associated with it. That means if you want an object's associated object, then you will make another API call using the associated objects api. For example:

> external_account = esp_sdk.ExternalAccountsApi().show(3)
> organization = esp_sdk.OrganizationsApi().show(external_account.organization_id)
> sub_organization = esp_sdk.SubOrganizationsApi().show(external_account.sub_organization_id)
> team = esp_sdk.TeamsApi().show(external_account.team_id)

The above code will make 4 calls to the Evident.io API. 1 each for the external account, organization, sub_organization and team. The JSON API Specification, which the Evident.io API tries to follow, provides a means for returning nested objects in a single call. With the SDK, that can be done by providing a comma separated string of the relations wanted in an +include+ option.

> external_account = esp_sdk.ExternalAccountsApi().show(3, include='organization,sub_orgnanization,team')

> external_account = esp_sdk::ExternalAccountsApi().list(id_eq: 3, include='organization,sub_organization,team')

With that call, organization, sub_organization and team will all come back in the response, and calling, external_account.organization, external_account.sub_organization and external_account.team will return the associated object.

You can nest include requests with the dot property. For example, requesting external_account.team on an alert will expand the external_account property into a full External Account object, and will then expand the team property on that external account into a full Team object. Deep nesting is available as well: external_account.team.sub_organization.organization

alert = esp_sdk.AlertsApi().show(1, include='tags,external_account.team')

alerts = esp_sdk.AlertsApi().list(4, include='tags,external_account.team')

Most objects' show and list methods accept the +include+ option. Those methods that accept the +include+ option are documented with the available associations that are includable.

For objects that implement list, parameters can be passed that will filter the results based on the search criteria specified. The criteria that can be specified depends on the object. Each object is documented whether it implements list or not, and if so, which attributes can be included in the search criteria.

The primary method of searching is by using what is known as predicates.

Predicates are used within Evident.io API search queries to determine what information to match. For instance, the cont predicate, when added to the name attribute, will check to see if `name`` contains a value using a wildcard query.

esp_sdk.SignaturesApi().list(filter={ "name_cont": 'dns' })
#=> will return signatures `where name LIKE '%dns%'`

The syntax for queries on an associated relationship is to just append the association name to the attribute:

esp_sdk.SuppressionsApi().list(filter={ "regions_code_eq": 'us_east_1' })
#=> will return suppressions that have a region relationship `where code = 'us_east_1'`

Add multiple attributes and predicates to form complex queries:

esp_sdk.SuppressionsApi().list(filter={ "regions_code_start": 'us', "created_by_email_eq": 'bob@mycompany.com', resource_not_null: '1' })
#=> will return suppressions that have a region relationship `where code LIKE 'us%'` and created_by relationship `where email = 'bob@mycompany.com'` and `resource IS NOT NULL`

You can also change the combinator for complex queries from the default AND to OR by adding the m: 'or' parameter

esp_sdk.SuppressionsApi().list(filter={ "regions_code_start": 'us', "created_by_email_eq": 'bob@mycompany.com', resource_not_null: '1', m: 'or' })
#=> will return suppressions that have a region relationship `where code LIKE 'us%'` **OR** created_by relationship `where email = 'bob@mycompany.com'` **OR** `resource IS NOT NULL`

Please note: any attempt to use a predicate for an attribute that does not exist will return a 422 (Unprocessable Entity) response. For instance, this will not work:

esp_sdk.SuppressionsApi().list(filter={ "bad_attribute_eq": 'something' })
#=> esp_sdk.ApiError()iled.  Response code = 422.  Response message = Invalid search term bad_attribute_eq.

Also note: any attempt to use a predicate for an attribute that exists on the object, but is not a documented searchable attribute will silently fail and will be excluded from the search criteria.

Below is a list of the available predicates and their opposites.

The eq predicate returns all records where a field is exactly equal to a given value:

esp_sdk.SuppressionsApi().list(filter={ "regions_code_eq": 'us_east_1' })
#=> will return suppressions that have a region relationship `where code = 'us_east_1'`

Opposite: not_eq

The lt predicate returns all records where a field is less than a given value:

from datetime import datetime, timedelta
esp_sdk.ReportsApi().list(filter={ "created_at_lt": datetime.now() - timedelta(hours = 1) })
#=> will return reports `where created_at < '2015-11-11 16:25:30'`

Opposite: gt (greater than)

The lteq predicate returns all records where a field is less than or equal to a given value:

from datetime import datetime, timedelta
esp_sdk.ReportsApi().list(filter={ "created_at_lteq": datetime.now() - timedelta(hours = 1) })
#=> will return reports `where created_at <= '2015-11-11 16:25:30'`

Opposite: gteq (greater than or equal to)

The in predicate returns all records where a field is within a specified list:

esp_sdk.SignaturesApi().list(filter={ "risk_level_in": ['Low', 'Medium'] })
#=> will return signatures `where risk_level IN ('Low', 'Medium')`

Opposite: not_in

The cont predicate returns all records where a field contains a given value:

esp_sdk.SignaturesApi().list(filter={ "name_cont": 'dns' })
#=> will return signatures `where name LIKE '%dns%'`

Opposite: not_cont

Please note: This predicate is only available on attributes listed in the "Valid Matching Searchable Attributes"" section for each implemented where method.

The cont_any predicate returns all records where a field contains any of given values:

esp_sdk.SignaturesApi().list(filter={ "name_cont_any": ['dns', 'EC2'] })
#=> will return signatures `where name LIKE '%dns%' or name LIKE '%EC2%'`

Opposite: not_cont_any

Please note: This predicate is only available on attributes listed in the "Valid Matching Searchable Attributes"" section for each implemented where method.

The start predicate returns all records where a field begins with a given value:

esp_sdk.SignaturesApi().list(filter={ "name_start": 'dns' })
#=> will return signatures `where name LIKE 'dns%'`

Opposite: not_start

Please note: This predicate is only available on attributes listed in the "Valid Matching Searchable Attributes"" section for each implemented where method.

The end predicate returns all records where a field ends with a given value:

esp_sdk.SignaturesApi().list(filter={ "name_end": 'dns' })
#=> will return signatures `where name LIKE '%dns'`

Opposite: not_end

Please note: This predicate is only available on attributes listed in the "Valid Matching Searchable Attributes"" section for each implemented where method.

The present predicate returns all records where a field is present (not null and not a blank string).

esp_sdk.SignaturesApi().list(filter={ "identifier_present": '1' })
#=> will return signatures `where identifier IS NOT NULL AND identifier != ''`

Opposite: blank

The null predicate returns all records where a field is null:

esp_sdk.SignaturesApi().list(filter={ "identifier_null": 1 })
#=> will return signatures `where identifier IS NULL`

Opposite: not_null

Lists can also be sorted by adding the sorts parameter with the field to sort by to the filter parameter.

esp_sdk.SignaturesApi().list(filter={ "name_cont": 'dns', "sorts": 'risk_level desc' })
#=> will return signatures `where name LIKE '%dns%'` sorted by `risk_level` in descending order.

Lists can be sorted by multiple fields by specifying an ordered array.

esp_sdk.SignaturesApi().list(filter={ "name_cont": 'dns', "sorts": ['risk_level desc', 'created_at'] })
#=> will return signatures `where name LIKE '%dns%'` sorted by `risk_level` in descending order and then by `created_at` in ascending order.

All URIs are relative to https://api.evident.io/

The description of the filter parameter for the list endpoints have the searchable attributes separated into different lists.

These attributes can be used with predicates that look for an exact match such as eq

These attributes can be used with predicates that look for a string that matches the supplied string such as cont

These attributes cannot be used with every predicate. Only with the predicates listed.

These are associations you can search through. See the documentation for each association to see which attributes are searchable.

These attributes can be passed with the sorts key to sort the response.

• Alert
• ApiKey
• Attribution
• AuditLog
• AuditLogFile
• AzureGroup
• ComplianceControl
• ComplianceDomain
• ComplianceStandard
• CustomComplianceControl
• CustomComplianceDomain
• CustomComplianceStandard
• CustomSignature
• CustomSignatureDefinition
• CustomSignatureResult
• CustomSignatureResultAlert
• ExportedReport
• ExternalAccount
• ExternalAccountAmazonIam
• ExternalAccountAzure
• ExternalAccountUserAttributionChannel
• Integration
• IntegrationAmazonSns
• IntegrationHipchat
• IntegrationJira
• IntegrationPagerDuty
• IntegrationServicenow
• IntegrationSlack
• IntegrationWebhook
• Meta
• Metadata
• Organization
• PaginatedCollection
• Plan
• Region
• Report
• Role
• ScanInterval
• ScheduledExport
• ScheduledExportResult
• Service
• Signature
• Stat
• StatComplianceControl
• StatCustomComplianceControl
• StatCustomSignature
• StatRegion
• StatService
• StatSignature
• SubOrganization
• Subscription
• Suppression
• Tag
• Team
• User