NAV
json ruby

Introduction

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 documentation includes examples of raw JSON responses in the right panel, as well as examples on how to use each endpoint with our Ruby SDK. The Ruby examples contained within this document are designed to showcase specific examples and do not demonstrate every usage of the SDK. Please check out the SDK documentation for more information on the Ruby SDK.

The endpoint for our API is located at: https://api.evident.io.

Authentication

The Evident Security Platform (version 2.0) API uses the authentication method HMAC-SHA1. This is the same authentication method used by Amazon, which requires you to sign your requests with your secret key.

Headers

Date: Mon, 21 Oct 2015 04:20:01 GMT
Content-MD5: Wn+B9XU1p7jk1YmgJmDevA==
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: APIAuth abc:fN9pbUcJVoYVcfNEZ8lFPsU3KWI=

Add the following headers to your request:

Header Note
Date Uses the RFC1123 spec. Note: Must be in the GMT timezone. For example: Mon, 21 Oct 2015 04:20:01 GMT
Content-MD5 This is a MD5 hexdigest of the request body. Use an empty string for GET requests. See details below on how to build the md5.
Authorization Set to the public key and encoded string for the request. See details below on how to build the string. Prefix with ApiAuth.
Content-Type Only supports application/vnd.api+json
Accept Only supports application/vnd.api+json

Content-MD5 Header

On OSX replace md5sum with md5

# Generate MD5
> echo -n '{"data":{"attributes":{"name":"Testing"}}}' | md5sum
5a7f81f57535a7b8e4d589a02660debc

# Convert MD5 to hex dump and then base 64 it
> echo -n '5a7f81f57535a7b8e4d589a02660debc' | xxd -r -p | base64
Wn+B9XU1p7jk1YmgJmDevA==

# Header
Content-MD5: Wn+B9XU1p7jk1YmgJmDevA==
Digest::MD5.base64digest '{"data":{"attributes":{"name":"Testing"}}}'
#=> "Wn+B9XU1p7jk1YmgJmDevA=="

The Content-MD5 header should include a MD5 base64 hexdigest of the request body. If you are making a GET request you may md5 an empty string, or leave the header blank.

Generating the header requires 3 steps:

  1. Generate MD5 sum
  2. Hex dump the MD5 sum
  3. Base64 the hex dump

Authorization Header

Assuming we have the following headers:

POST /api/v2/external_accounts
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Date: Mon, 21 Oct 2015 04:20:01 GMT
Content-MD5: Wn+B9XU1p7jk1YmgJmDevA==

The canonical string would look like

POST,application/vnd.api+json,Wn+B9XU1p7jk1YmgJmDevA==,/api/v2/external_accounts,Mon, 21 Oct 2015 04:20:01 GMT

Encode the string

> echo -n "POST,application/vnd.api+json,Wn+B9XU1p7jk1YmgJmDevA==,/api/v2/external_accounts,Mon, 21 Oct 2015 04:20:01 GMT" | openssl dgst -sha1 -binary -hmac "abc123" | base64
fN9pbUcJVoYVcfNEZ8lFPsU3KWI=

End Result

Full HTTP Request Example:
Public Key: 'abc'
Secret Key: 'abc123'

POST /api/v2/external_accounts
Authorization: APIAuth abc:fN9pbUcJVoYVcfNEZ8lFPsU3KWI=
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Date: Mon, 21 Oct 2015 04:20:01 GMT
Content-MD5: Wn+B9XU1p7jk1YmgJmDevA==

Building the authorization header takes multiple steps. You must build a canonical string of multiple headers, then take that string and encode it with HMAC-SHA1. Finally take the result of that and place it in the Authorization header.

Build Canonical String

Create a canonical string using your HTTP headers containing the HTTP method, content-type, content-MD5, request URI and the timestamp. The URI should only contain the relative path. The other values should be an exact match to the header sent in the request.

'HTTP method,content-type,content-MD5,URI,timestamp'

Encode String

Use the HMAC-SHA1 algorithm to encode the string with your secret key.

Example:

String: POST,application/vnd.api+json,Wn+B9XU1p7jk1YmgJmDevA==,/api/v2/external_accounts,Mon, 21 Oct 2015 04:20:01 GMT

Secret key: abc123

HMAC-SHA1 encoded string: fN9pbUcJVoYVcfNEZ8lFPsU3KWI=

Add Authorization Header

Add an Authorization header with the ‘APIAuth’, the public key, and the encoded canonical string. Public Key: 'abc’

Authorization: APIAuth abc:fN9pbUcJVoYVcfNEZ8lFPsU3KWI=

Error Codes

The Evident Security Platform (version 2.0) uses the following error codes:

Code Name Meaning
400 Bad Request Something is wrong with your request.
401 Unauthorized Your API key is wrong or you do not have access to the resource requested.
403 Forbidden The request was valid, but the server is refusing action. You might not have the necessary permissions for a resource.
404 Not Found The specified resource could not be found.
406 Not Acceptable The Accept/Content-Type headers were not set or have an unsupported value.
422 Unprocessable Entity The requested change could not be made. See errors in the response body for more details.
429 Too Many Requests The user has sent too many requests in a given amount of time (“rate limiting”).
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We’re temporarily offline for maintenance. Please try again later.

422 Errors

{
  "errors": [
    {
      "meta": {
        "name": "can't be blank"
      },
      "status": "422",
      "title": "Name can't be blank"
    }
  ]
}

Errors that are returned with a 422 status code will include a message in the body to help diagnose the error. Look for an errors array that may contain multiple objects. Each object will have a title key containing a human-readable error message.

429 Errors

{
  "errors": [
    "Request limit exceeded. Please try again later."
  ]
}

Errors that are returned with a 429 status code will include a message in the body to help diagnose the error. Look for an errors array that will have a string containing the human readable error message. In addition to this, we will provide you with the following three headers to assist you in calculating proper retry/backoff logic.

Response Headers

Header Type Description Example
X-RateLimit-Limit String How many total transactions you are allowed to send within your timeframe. “120”
X-RateLimit-Remaining String How many transactions you have remaining. Using all of the remaining transactions prior to the rate limit resetting will cause you to receive a 429 error response. “0”
X-RateLimit-Reset String ISO 8601 timestamp of when your rate limit will be reset. “2016-12-13T18:38:00Z”

Pagination

{
  "data": [],
  "links": {
    "first": "https://api.evident.io/api/v2/users.json?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://api.evident.io/api/v2/users.json?page%5Bnumber%5D=70&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/users.json?page%5Bnumber%5D=4&page%5Bsize%5D=20",
    "prev": "https://api.evident.io/api/v2/users.json?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/users.json?page%5Bnumber%5D=3&page%5Bsize%5D=20"
  }
}

All top-level endpoints will be automatically paginated. Pass page[number] to specify the page number to return, and page[size] to specify how many records to return per page. Page size defaults to 20 and can range between 1 and 100 items.

Requests to the top-level endpoints will include a links object at the root of the response. Links will include the first, previous, self, next, and last links when available.

Including Objects

curl -G https://api.evident.io/api/v2/alerts/1 \
   -H "Authorization: ApiAuth abc123:abc123" \
   -H "Accept: application/vnd.api+json" \
   -d include=tags,external_account.team
alert = ESP::Alert.find(1, include: 'tags,external_account.team')
#=> <ESP::Alert:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"alerts"...}>

alerts = ESP::Alert.where(report_id: 4, include: 'tags,external_account.team')
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Alert:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"alerts"...>
{
  "data": {
    "id": "1",
    "type": "alerts",
    "attributes": {
      "created_at": "2015-09-23T15:04:02.000Z",
      "status": "pass",
      "resource": "",
      "updated_at": "2015-09-23T15:04:02.000Z",
      "started_at": "2015-09-23T15:04:02.000Z",
      "ended_at": null
    },
    "relationships": {
      "external_account": {
        "data": {
          "id": "1",
          "type": "external_accounts"
        },
        "links": {
          "related": "https://localhost:3000/api/v2/external_accounts/1.json"
        }
      },
      "region": {
        "links": {
          "related": "https://localhost:3000/api/v2/regions/1.json"
        }
      },
      "signature": {
        "links": {
          "related": "https://localhost:3000/api/v2/signatures/9.json"
        }
      },
      "custom_signature": {
        "links": {
          "related": null
        }
      },
      "suppression": {
        "links": {
          "related": null
        }
      },
      "metadata": {
        "links": {
          "related": "https://localhost:3000/api/v2/alerts/1/metadata.json"
        }
      },
      "cloud_trail_events": {
        "links": {
          "related": "https://localhost:3000/api/v2/alerts/1/cloud_trail_events.json"
        }
      },
      "tags": {
        "data": [
        ]
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "external_accounts",
      "attributes": {
        "account": "762160981991",
        "arn": "arn:aws:iam::762160981991:role/Evident-Service-Role-Kevin",
        "created_at": "2015-09-23T14:43:47.000Z",
        "external_id": "913310e7-6a9c-49f7-bd69-120721ec1122",
        "name": "Dev",
        "throttle_level": "none",
        "updated_at": "2015-09-23T14:43:47.000Z"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "https://localhost:3000/api/v2/organizations/1.json"
          }
        },
        "sub_organization": {
          "links": {
            "related": "https://localhost:3000/api/v2/sub_organizations/1.json"
          }
        },
        "team": {
          "data": {
            "id": "1",
            "type": "teams"
          },
          "links": {
            "related": "https://localhost:3000/api/v2/teams/1.json"
          }
        }
      }
    },
    {
      "id": "1",
      "type": "teams",
      "attributes": {
        "name": "Default Team",
        "created_at": "2015-09-23T14:37:48.000Z",
        "updated_at": "2015-09-23T14:37:48.000Z"
      },
      "relationships": {
        "sub_organization": {
          "links": {
            "related": "https://localhost:3000/api/v2/sub_organizations/1.json"
          }
        },
        "organization": {
          "links": {
            "related": "https://localhost:3000/api/v2/organizations/1.json"
          }
        },
        "external_accounts": {
          "links": {
            "related": "https://localhost:3000/api/v2/external_accounts.json?filter%5Bteam_id_eq%5D=1"
          }
        }
      }
    }
  ]
}

Many objects contain the ID of a related object in their response properties. For example, an Alert will have an associated External Account ID. Those objects can be included inline with the include request parameter. Objects that can be included are noted in this documentation. Some endpoints may automatically include related objects. This parameter is available on all API requests, and applies to the response of that request only.

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

You can include multiple objects at once by identifying multiple items comma separated in the include parameter.

When including objects, the main object will be in the data node, and all included objects will be in the included node of the response. The relationships that are included will also contain data nodes with the id and type of the related object. This can be used to retreive the full object from the included node.

Request Parameters

When making a request there are two different ways to send parameters, which depends on the type of request. With GET requests you will add parameters to the URL in query form, however with POST/PATCH requests the parameters go in the body according to the JSON API specification.

GET Requests

For GET requests, any attributes will appear in the URL for the request. Depending on the parameter, it may be part of the base url, otherwise the parameter will be added as a query parameter.

In the example below we are requesting the alerts for report 123 while also requesting the second page of alerts in batches of 50.

/api/v2/reports/123/alerts.json?page[number]=2&page[size]=50

POST/PATCH Requests

When not referencing an existing object, such as a create…

{
  "data": {
    "type": "sub_organizations",
    "attributes": {
      "name": "Demo Account"
    }
  }
}

or, in reference to an existing object, such as an update…

{
  "data": {
    "id": 5,
    "type": "sub_organizations",
    "attributes": {
      "name": "Demo Account"
    }
  }
}

For POST and PATCH requests the attributes go in the body of the request. The body must be JSON formatted and include a data object. The data object should include a type key referencing the object type and an attributes object which may contain the attributes necessary for the object you are creating or updating. If the request is for an existing object, the id of the object should be included as well at the same level as type.

In the JSON example we are creating a Sub Organization which only requires the parameter name.

Searching Lists

When returning a collection of objects from many of the list endpoints, parameters can be passed in order to filter and sort the list.

Filtering

For endpoints that allow it, parameters can be passed that will filter the results based on the search criteria specified. All search criteria must be within a filter parameter. The criteria that can be specified depends on the endpoint. Each endpoint in this documentation that allows searching, has columns in the Attributes table for that endpoint that indicates which attributes can be added to the filter parameter to filter the list.

Searching

ESP::Signature.where(name_cont: 'dns')
#=> will return signatures `where name LIKE '%dns%'`

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 will check to see if an attribute called “name” contains a value using a wildcard query. So adding that to the filter parameter:

/api/v2/signatures.json?filter[name_cont]=dns

will return signatures where name LIKE '%dns%'

Conditions on Relationships

ESP::Suppression.where(regions_code_eq: 'us_east_1')
#=> will return suppressions that have a region relationship `where code = 'us_east_1'`

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

/api/v2/suppressions.json?filter[regions_code_eq]=us_east_1

will return suppressions that have a region relationship where code = 'us_east_1'

Complex Filtering

ESP::Suppression.where(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`
ESP::Suppression.where(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`

Add multiple attributes and predicates to form complex queries:

/api/v2/suppressions.json?filter[created_by_email_eq]=bob@mycompany.com&filter[regions_code_start]=us&filter[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 the 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

/api/v2/suppressions.json?filter[created_by_email_eq]=bob@mycompany.com&filter[m]=or&filter[regions_code_start]=us&filter[resource_not_null]=1

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

Using PUT

Complex queries will run into trouble because of URL length limits in most browsers. For this reason, you can optionally switch to a PUT request instead, and place the search criteria in the body placing the criteria in the filter parameter.

curl https://api.evident.io/api/v2/suppressions \ -X PUT \ -H "Authorization: ApiAuth abc123:abc123" \ -H "Accept: application/vnd.api+json" \ -d 'filter[regions_code_start]=us' \ -d 'filter[created_by_email_eq]=bob@mycompany.com' \ -d 'filter[resource_not_null]=1'

Bad Attributes

ESP::Suppression.where(bad_attribute_eq: 'something')
#=> ActiveResource::ResourceInvalid: Failed.  Response code = 422.  Response message = Invalid search term bad_attribute_eq.

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:

/api/v2/suppressions.json?filter[bad_attribute_eq]=something

will return {"errors":[{"status":422,"title":"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 in the Attributes table will silently fail and will be excluded from the search criteria.

Available Predicates

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

eq (equals)

ESP::Suppression.where(regions_code_eq: 'us_east_1')
#=> will return suppressions that have a region relationship `where code = 'us_east_1'`

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

/api/v2/suppressions.json?filter[regions_code_eq]=us_east_1

will return suppressions that have a region relationship where code = 'us_east_1'

Opposite: not_eq

lt (less than)

ESP::Report.where(created_at_lt: 1.hour.ago)
#=> will return reports `where created_at < '2015-11-11 16:25:30'`

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

/api/v2/reports.json.json?filter[created_at_lt]=2015-11-11+16:25:30

will return reports where created_at < '2015-11-11 16:25:30'

Opposite: gt (greater than)

lteq (less than or equal to)

ESP::Report.where(created_at_lteq: 1.hour.ago)
#=> will return reports `where created_at <= '2015-11-11 16:25:30'`

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

/api/v2/reports.json?filter[created_at_lt]=2015-11-11+16:25:30

will return reports where created_at <= '2015-11-11 16:25:30'

Opposite: gteq (greater than or equal to)

in

ESP::Signature.where(risk_level_in: ['Low', 'Medium'])
#=> will return signatures `where risk_level IN ('Low', 'Medium')`

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

’/api/v2/signatures.json?filter[risk_level_in][]=Low&filter[risk_level_in][]=Medium’

will return signatures where risk_level IN ('Low', 'Medium')

Opposite: not_in

cont (contains)

ESP::Signature.where(name_cont: 'dns')
#=> will return signatures `where name LIKE '%dns%'`

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

/api/v2/signatures.json?filter[name_cont]=dns

will return signatures where name LIKE '%dns%'

Opposite: not_cont

Please note: This predicate is only available on attributes where the Matching Searchable column of the Attributes table is marked with a Yes. All endpoints that allow searching have an Attributes table defined.

cont_any (contains any)

ESP::Signature.where(name_cont_any: ['dns', 'EC2'])
#=> will return signatures `where name LIKE '%dns%' or name LIKE '%EC2%'`

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

/api/v2/signatures.json?filter[name_cont_any][]=dns&filter[name_cont_any][]=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 where the Matching Searchable column of the Attributes table is marked with a Yes. All endpoints that allow searching have an Attributes table defined.

start (starts with)

ESP::Signature.where(name_start: 'dns')
#=> will return signatures `where name LIKE 'dns%'`

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

/api/v2/signatures.json?filter[name_start]=dns

will return signatures where name LIKE 'dns%'

Opposite: not_start

Please note: This predicate is only available on attributes where the Matching Searchable column of the Attributes table is marked with a Yes. All endpoints that allow searching have an Attributes table defined.

end (ends with)

ESP::Signature.where(name_end: 'dns')
#=> will return signatures `where name LIKE '%dns'`

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

/api/v2/signatures.json?filter[name_end]=dns

will return signatures where name LIKE '%dns'

Opposite: not_end

Please note: This predicate is only available on attributes where the Matching Searchable column of the Attributes table is marked with a Yes. All endpoints that allow searching have an Attributes table defined.

present

ESP::Signature.where(identifier_present: '1')
#=> will return signatures `where identifier IS NOT NULL AND identifier != ''`

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

/api/v2/signatures.json?filter[identifier_present]=1

will return signatures where identifier IS NOT NULL AND identifier != ''

Opposite: blank

null

ESP::Signature.where(identifier_null: 1)
#=> will return signatures `where identifier IS NULL`

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

/api/v2/signatures.json?filter[identifier_null]=1

will return signatures where identifier IS NULL

Opposite: not_null

Sorting

ESP::Signature.where(name_cont: 'dns', sorts: 'risk_level desc')
#=> will return signatures `where name LIKE '%dns%'` sorted by `risk_level` in descending order.

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

/api/v2/signatures.json?filter[name_cont]=dns&filter[sorts]=risk_level+desc

will return signatures where name LIKE '%dns%' sorted by risk_level in descending order.

ESP::Signature.where(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.

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

/api/v2/signatures.json?filter[name_cont]=dns&filter[sorts][]=risk_level+desc&filter[sorts][]=created_at

will return signatures where name LIKE '%dns%' sorted by risk_level in descending order and then by created_at in ascending order.

Alerts

Attributes

Attribute Type Description
created_at String ISO 8601 timestamp when the resource was created
ended_at String ISO 8601 timestamp when the alert stopped being active
resource String Resource identifier in Amazon.
started_at String ISO 8601 timestamp when the alert started being active
status String Status of the alert.
risk_level String Status of the alert.
updated_at String ISO 8601 timestamp when the resource was last updated

Alert Searching

The Alert API does not allow all the searching predicates that are available on other endpoints. Below is a complete list of all the available search terms and predicates for alerts.

See Searching Lists and Including Objects for more information.

Search Term Note
status_in
status_eq
resource_or_tag_cont Matches any resource, or tag with a key of “Name” that contains the given value.
suppressed Valid values are ‘true’ and 'false’
not_suppressed Valid values are 'true’ and 'false’
region_id_in
region_id_eq
risk_level_in
risk_level_eq
signature_name_cont This will search on both signature and custom signature
signature_identifier_cont This will search on both signature and custom signature
signature_service_id_in This will search on both signature and custom signature
external_account_id_in
external_account_id_eq
external_account_team_id_in
external_account_team_id_eq
cloud_trail_events_present Valid values are 'true’ and 'false’
Sort Term
first_seen
status
risk_level
signature_name
signature_identifier
region_code
external_account_team_name

Alert Status Values

Value Description
pass This alert indicates that one of your business assets has successfully been validated against a Signature by ESP.
fail This alert indicates that one of your AWS resources has failed a validation against a Signature or Custom Signature by ESP. It is recommended that all failures be reviewed.
warn This alert indicates that one of your business assets has triggered a warning during a validation against a Signature or Custom Signature by ESP. A warning should be considered a potential security risk and should be reviewed in a timely manner.
error This alert indicates that a validation check against one of your business assets has failed. The most common cause of errors is the lack of access to the service being audited.
info This alert contains important information for you to review.

Relationships

Relation Includable n Note
custom_signature Yes one Either a signature or custom signature but not both will be present.
external_account Yes one
region Yes one
signature Yes one Either a signature or custom signature but not both will be present.
suppression Yes one If present the alert was suppressed.
metadata Yes one
cloud_trail_events Yes many These may be added up to 10 minutes after the alert was created.
tags Yes many

List

{
  "data": [
    {
      "id": "5",
      "type": "alerts",
      "attributes": {
        "created_at": "2015-12-08T22:21:47.837Z",
        "status": "fail",
        "resource": "resource-6",
        "updated_at": "2015-12-08T22:21:47.844Z",
        "started_at": "2015-12-08T22:20:47.833Z",
        "ended_at": null
      },
      "relationships": {
        "external_account": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts/6.json"
          }
        },
        "region": {
          "links": {
            "related": "https://api.evident.io/api/v2/regions/6.json"
          }
        },
        "signature": {
          "links": {
            "related": "https://api.evident.io/api/v2/signatures/4.json"
          }
        },
        "custom_signature": {
          "links": {
            "related": null
          }
        },
        "suppression": {
          "links": {
            "related": "https://api.evident.io/api/v2/suppressions/1.json"
          }
        },
        "metadata": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/metadata.json"
          }
        },
        "cloud_trail_events": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/cloud_trail_events.json"
          }
        },
        "tags": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/tags.json"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=453&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

alerts = ESP::Alert.where(report_id: 54)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Alert:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"alerts"...>
alerts.count
#=> 20
alerts.first.status
#=> "fail"

A successful call to this API returns a paginated list of alerts for the specified report_id.

HTTP Request

GET https://api.evident.io/api/v2/reports/<REPORT_ID>/alerts

Optional parameters may also be supplied to filter the returned collection

Request Parameters

Parameter Required Description
report_id Yes The ID of the report to retrieve alerts for
region_id No Return only alerts for this region.
status No Return only alerts for the give status(es). Valid values are fail, warn, error, pass, info
first_seen No Return only alerts that have started within a number of hours of the report. For example, first_seen of 3 will return alerts that started showing up within the last 3 hours of the report.
suppressed No Return only suppressed alerts
team_id No Return only alerts for the given team.
external_account_id No Return only alerts for the given external id.
service_id No Return only alerts on signatures with the given service.
signature_severity No Return only alerts for signatures with the given risk_level. Valid values are Low, Medium, High
signature_name No Return only alerts for signatures with the given name.
resource No Return only alerts for the given resource or tag.
signature_identifier No Return only alerts for signatures with the given identifier.

Show

{
  "data": {
    "id": "5",
    "type": "alerts",
    "attributes": {
      "created_at": "2015-12-08T22:21:47.837Z",
      "status": "fail",
      "resource": "resource-6",
      "updated_at": "2015-12-08T22:21:47.844Z",
      "started_at": "2015-12-08T22:20:47.833Z",
      "ended_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/6.json"
        }
      },
      "region": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions/6.json"
        }
      },
      "signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/signatures/4.json"
        }
      },
      "custom_signature": {
        "links": {
          "related": null
        }
      },
      "suppression": {
        "links": {
          "related": "https://api.evident.io/api/v2/suppressions/1.json"
        }
      },
      "metadata": {
        "links": {
          "related": "https://api.evident.io/api/v2/alerts/5/metadata.json"
        }
      },
      "cloud_trail_events": {
        "links": {
          "related": "https://api.evident.io/api/v2/alerts/5/cloud_trail_events.json"
        }
      },
      "tags": {
        "links": {
          "related": "https://api.evident.io/api/v2/alerts/5/tags.json"
        }
      }
    }
  }
}

alert = ESP::Alert.find 3
#=> <ESP::Alert:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"alerts"...}>
alert.status
#=> "pass"

You may also use the alert object to create a suppression for a region, signature, or unique_identifier. Pass a string for the reason. See the Suppression section for more details.

alert.suppress_region("We do not use this region")
alert.suppress_signature("This signature does not apply to us.")
alert.suppress_unique_identifier("This identifier gives false alerts, turn off the noise.")

A successful call to this API returns all the attributes of the alert.

HTTP Request

GET https://api.evident.io/api/v2/alerts/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the alert to retrieve

Audit Logs

Attributes

Attribute Type Description
created_at String ISO 8601 timestamp when the audit_log was created.
updated_at String ISO 8601 timestamp when the audit_log was last updated.
item_type String The type of object that was attempting to be accessed resulting in the audit_log record.
item_id Integer ID of the object that was attempting to be accessed resulting in the audit_log record. In some cases this can be nil as we will not always have an ID for the object. This mostly occurs on failed creates.
action String Action that was taken on the object being logged.
successful Boolean Boolean representation of whether the action taken on the object was successful.
access_denied Boolean Boolean representation of whether the users access was denied while taking the specified action on the object.
user_ip String IP address of the user that attempted to perform the action on the object.
platform String This will return either “API” or “UI” depending on what platform the request was generated on.

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
organization Yes one Yes See Organization Attributes for searchable attributes.
users Yes many No

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "21",
      "type": "audit_logs",
      "attributes": {
        "item_type": "FakeObject",
        "item_id": 17,
        "action": "create",
        "successful": true,
        "access_denied": false,
        "user_ip": "192.168.4.11",
        "platform": "API",
        "created_at": "2017-03-09T19:11:07.000Z",
        "updated_at": "2017-03-09T19:11:07.000Z"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/30.json"
          }
        },
        "user": {
          "links": {
            "related": "https://api.evident.io/api/v2/users/29.json"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/audit_logs?page%5Bnumber%5D=22&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/audit_logs?page%5Bnumber%5D=23&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/audit_logs?page%5Bnumber%5D=24&page%5Bsize%5D=20"
  }
}

A successful call to this API returns a paginated list of audit logs.

HTTP Request

GET https://api.evident.io/api/v2/audit_logs

Show

{
  "data":  {
    "id":             "1",
    "type":           "audit_logs",
    "attributes":     {
      "item_type":    "FakeObject",
      "item_id":      70307117662620,
      "action":         "create",
      "successful":     true,
      "access_denied":  false,
      "user_ip":        "192.168.4.11",
      "platform":       "API",
      "created_at":     "2017-02-24T17:19:59.000Z",
      "updated_at":     "2017-02-24T17:19:59.000Z"
    },
    "relationships":  {
      "organization":  {
        "links":  {
          "related":  "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "user":          {
        "links":  {
          "related":  "https://api.evident.io/api/v2/users/1.json"
        }
      }
    }
  }
}

A successful call to this API returns a specific audit log identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/audit_log/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the audit log file to retrieve.

Audit Log Files

Attributes

Attribute Type Description
created_at String ISO 8601 timestamp when the file object was created.
updated_at String ISO 8601 timestamp when the file object was last updated.
file_name String File name of the file object being returned. This attribute will be nil if the file is still processing.
format String Format of the file object being returned (currently only CSV is supported).
url String URL where the file object can be downloaded.

Relationships

Relation Includable n Searchable Note
organization Yes one Yes See Organization Attributes for searchable attributes.
users Yes many No

Create

{
  "data": {
    "id": "1004",
    "type": "audit_log_files",
    "attributes": {
      "file_name": "test.csv",
      "format": "csv",
      "created_at": "2017-03-07T18:55:33.722Z",
      "updated_at": "2017-03-07T18:55:33.722Z",
      "url": "https://evident-test-export-reports.s3-us-west-1.amazonaws.com/test.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=stubbed-akid%2F20170307%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Date=20170307T185533Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=5bfe8cc003ebc263f3f5449f58573cfd7184f38f2584d9eb60e06e3405c55da7"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/2.json"
        }
      },
      "user": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1003.json"
        }
      }
    }
  }
}

A successful call to this API creates a new audit log file. The body of the request must contain a json api compliant hash of attributes with type audit_log_files. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/audit_logs/export/files

Request Parameters

No request parameters are needed/required for this request.

Show

{
  "data": {
    "id": "1004",
    "type": "audit_log_files",
    "attributes": {
      "file_name": "test.csv",
      "format": "csv",
      "created_at": "2017-03-07T18:55:33.722Z",
      "updated_at": "2017-03-07T18:55:33.722Z",
      "url": "https://evident-test-export-reports.s3-us-west-1.amazonaws.com/test.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=stubbed-akid%2F20170307%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Date=20170307T185533Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=5bfe8cc003ebc263f3f5449f58573cfd7184f38f2584d9eb60e06e3405c55da7"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/2.json"
        }
      },
      "user": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1003.json"
        }
      }
    }
  }
}

A successful call to this API returns a specific audit log file identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/audit_logs/export/files/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the audit log file to retrieve.

Cloud Trail Events

Attributes

Attribute Type Description
event_id String GUID generated by CloudTrail to uniquely identify each event.
event_name String The requested action, which is one of the actions listed in the API Reference for the service.
event_time String ISO 8601 timestamp when the cloud trail event occurred.
ip_address String The apparent IP address that the request was made from for the given event.
user_agent String The agent through which the request was made, such as the AWS Management Console or an AWS SDK.
username String The user name associated with the cloud trail event.

Relationships

Relation Includable n Note
alert No one

List

{
  "data": [
    {
      "id": "999",
      "type": "cloud_trail_events",
      "attributes": {
        "event_id": "3975fc3c-0d81-4db1-a921-ab398b463753",
        "event_name": "RunInstances",
        "event_time": "2015-10-16T00:52:42.000Z",
        "ip_address": "marketplace.amazonaws.com",
        "user_agent": "marketplace.amazonaws.com",
        "username": "ADMIN"
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/alerts/1927/cloud_trail_events?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/alerts/1927/cloud_trail_events?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/alerts/1927/cloud_trail_events?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

cloud_trail_events = ESP::CloudTrailEvent.for_alert(1194)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::CloudTrailEvent:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"cloud_trail_events"...>
cloud_trail_events.count
#=> 20
cloud_trail_events.first.event_name
#=> "AuthorizeSecurityGroupIngress"

A successful call to this API returns a paginated list of cloud trail events for the given alert_id.

HTTP Request

GET https://api.evident.io/api/v2/alerts/<ALERT_ID>/cloud_trail_events

Request Parameters

Parameter Required Description
alert_id Yes The ID of the alert to retrieve cloud trail events for

Show

{
  "data": {
      "id": "999",
      "type": "cloud_trail_events",
      "attributes": {
        "event_id": "3975fc3c-0d81-4db1-a921-ab398b463753",
        "event_name": "RunInstances",
        "event_time": "2015-10-16T00:52:42.000Z",
        "ip_address": "marketplace.amazonaws.com",
        "user_agent": "marketplace.amazonaws.com",
        "username": "ADMIN"
      }
    }
}

cloud_trail_event = ESP::CloudTrailEvent.find 3
#=> <ESP::CloudTrailEvent:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"cloud_trail_events"...}>
cloud_trail_event.event_name
#=> "AuthorizeSecurityGroupIngress"

A successful call to this API returns the cloud trail event.

HTTP Request

GET https://api.evident.io/api/v2/cloud_trail_events/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the cloud trail event to retrieve

Contact Requests

Contact requests are used to send a support or feature request to Evident.io.

Attributes

Attribute Type Description
title String Subject of your message
description String Body of your message
request_type String Type of contact request

Create

{
  "data": {
    "id": "1",
    "type": "contact_requests",
    "attributes": {
      "created_at": "2015-10-28T22:31:19.465Z",
      "description": "Testing via api",
      "request_type": "support",
      "title": "Testing2",
      "updated_at": "2015-10-28T22:31:19.465Z"
    },
    "relationships": {
      "user": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      }
    }
  }
}

contact_request = ESP::ContactRequest.create(request_type: 'feature', title: 'My great feature idea', description: 'This is my idea for a really useful feature...')
#=> <ESP::ContactRequest:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"contact_requests"...}>
contact_request.title
#=> "My great feature idea"

A successful call to this API creates a contact request. The body of the request must contain a json api compliant hash of attributes with type contact_requests. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/contact_requests

Request Parameters

Parameter Required Description
title Yes Subject of your message
description Yes Body of your message
request_type Yes Type of contact request. Supported values are support for support requests and feature for a feature request

Custom Signatures

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
description String The description of the custom signature
identifier String The identifier of the custom signature
name String The name of the custom signature Yes Yes Yes
resolution String Details for how to resolve this custom signature
risk_level String The risk-level of the problem identified by the custom signature. Valid values are Low, Medium, High Yes No Yes
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
organization Yes one Yes See Organization Attributes for searchable attributes.
teams Yes many Yes See Team Attributes for searchable attributes.
definitions Yes many Yes See Custom Signature Definition Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "custom_signatures",
      "attributes": {
        "created_at": "2016-06-01T18:01:52.517Z",
        "description": "Test description",
        "identifier": "AWS::Test::001",
        "name": "Test",
        "resolution": "Test resolution",
        "risk_level": "Medium",
        "updated_at": "2016-06-01T18:01:52.517Z"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/2.json"
          }
        },
        "teams": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams.json?filter%5Bcustom_signatures_id_eq%5D=1"
          }
        },
        "definitions": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signature_definitions.json?filter%5Bcustom_signature_id_eq%5D=1"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/custom_signatures?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/custom_signatures?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/custom_signatures?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

custom_signatures = ESP::CustomSignature.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::CustomSignature:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"custom_signatures"...>
custom_signatures.count
#=> 20
custom_signatures.first.risk_level
#=> "Low"

A successful call to this API returns a paginated list of custom signatures.

HTTP Request

GET https://api.evident.io/api/v2/custom_signatures

Show

{
  "data": {
    "id": "1",
    "type": "custom_signatures",
    "attributes": {
      "created_at": "2016-06-01T18:01:52.517Z",
      "description": "Test description",
      "identifier": "AWS::Test::001",
      "name": "Test",
      "resolution": "Test resolution",
      "risk_level": "Medium",
      "updated_at": "2016-06-01T18:01:52.517Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/2.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bcustom_signatures_id_eq%5D=1"
        }
      },
      "definitions": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_definitions.json?filter%5Bcustom_signature_id_eq%5D=1"
        }
      }
    }
  }
}

custom_signature = ESP::CustomSignature.find 3
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"custom_signatures"...}>
custom_signature.risk_level
#=> "Low"

You may also use the custom signature object to create a suppression for that custom signature. See the Suppression section for more details.

custom_signature.suppress(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')

A successful call to this API returns a specific custom signature identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/custom_signatures/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "custom_signatures",
    "attributes": {
      "created_at": "2016-06-01T18:01:52.517Z",
      "description": "Test description",
      "identifier": "AWS::Test::001",
      "name": "Test",
      "resolution": "Test resolution",
      "risk_level": "Medium",
      "updated_at": "2016-06-01T18:01:52.517Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/2.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bcustom_signatures_id_eq%5D=1"
        }
      },
      "definitions": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_definitions.json?filter%5Bcustom_signature_id_eq%5D=1"
        }
      }
    }
  }
}

custom_signature = ESP::CustomSignature.create(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"custom_signatures"...}>
custom_signature.id
#=> 3

A successful call to this API creates a new custom signature. The body of the request must contain a json api compliant hash of attributes with type custom_signatures. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/custom_signatures

Request Parameters

Parameter Required Description
description The description of the custom signature that is displayed on alerts
identifier Yes The identifier to use for the custom signature. Common format is AWS:- such as AWS:IAM-001
name Yes The name of the custom signature
resolution Details for how to resolve this custom signature that is displayed on alerts
risk_level Yes The risk-level of the problem identified by the custom signature
team_ids No The team IDs this custom signature should run for. If no teams are selected the custom signature will not be run.

Update

{
  "data": {
    "id": "1",
    "type": "custom_signatures",
    "attributes": {
      "created_at": "2016-06-01T18:01:52.517Z",
      "description": "Test description",
      "identifier": "AWS::Test::001",
      "name": "Test",
      "resolution": "Test resolution",
      "risk_level": "Medium",
      "updated_at": "2016-06-01T18:01:52.517Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/2.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bcustom_signatures_id_eq%5D=1"
        }
      },
      "definitions": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_definitions.json?filter%5Bcustom_signature_id_eq%5D=1"
        }
      }
    }
  }
}

custom_signature = ESP::CustomSignature.find(3)
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"custom_signatures"...}>
custom_signature.resolution = "None.  It's only a test."
custom_signature.save
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"custom_signatures", resolution=>"None.  It's only a test."...}>

A successful call to this API updates a specific custom signature identified by the id parameter. The body of the request must contain a json api compliant hash of attributes with type custom_signatures. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/custom_signatures/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature to update
description The description of the custom signature that is displayed on alerts
identifier The identifier to use for the custom signature. Common format is AWS:- such as AWS:IAM-001
name The name of the custom signature
resolution Details for how to resolve this custom signature that is displayed on alerts
risk_level The risk-level of the problem identified by the custom signature
team_ids No The team IDs this custom signature should run for. If no teams are selected the custom signature will not be run.

Destroy

{
  "success": "Demo Signature has been destroyed"
}
custom_signature = ESP::CustomSignature.find(3)
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"custom_signatures"...}>
custom_signature.destroy
custom_signature = ESP::CustomSignature.find(3)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find CustomSignature.

A successful call to this API destroys a specific custom signature identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/custom_signatures/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature to destroy

Custom Signatures Definitions

A Custom Signature Definition holds a version of the code that is run as part of the Custom Signature. The definitions may be edited until activated. When activated they will be validated, and if there are no errors the definition will be made active and the previous active definition will be archived.

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
code String The code for this definition No No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
language String The language of the definition Yes No No
version_number Integer Version of definition Yes No No
status String Status of the definition Yes No No
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Definition Status Values

Value Description
editable The definition is editable. While editable it may also be removed and updated.
validating The definition has been marked for activation and is being validated. When validations complete, the definition will be marked active if there are no errors, or return back to editable if there are.
active The definition is active and will be run on reports.
archived The definition is no longer active. It may not be removed.

Relationships

Relation Includable n Searchable Note
custom_signature Yes one Yes See Custom Signature Attributes for searchable attributes.
results Yes many Yes See Custom Signature Result Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "custom_signature_definitions",
      "attributes": {
        "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
        "updated_at": "2016-06-01T17:15:27.000Z",
        "created_at": "2016-06-01T17:15:27.000Z",
        "version_number": 1,
        "language": "ruby",
        "status": "editable"
      },
      "relationships": {
        "custom_signature": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
          }
        },
        "results": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
          }
        }
      }
    }
  ]
}

definitions = ESP::CustomSignature::Definition.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::CustomSignature::Definition:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"custom_signature_definitions"...>
definitions.count
#=> 20
definitions.first.status
#=> "editable"

A successful call to this API returns a paginated list of custom signature definitions.

HTTP Request

GET https://api.evident.io/api/v2/custom_signature_definitions

Show

{
  "data": {
    "id": "1",
    "type": "custom_signature_definitions",
    "attributes": {
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "updated_at": "2016-06-01T17:15:27.000Z",
      "created_at": "2016-06-01T17:15:27.000Z",
      "version_number": 1,
      "language": "ruby",
      "status": "editable"
    },
    "relationships": {
      "custom_signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
        }
      },
      "results": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
        }
      }
    }
  }
}

definition = ESP::CustomSignature::Definition.find !
#=> <ESP::CustomSignature::Definition:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_definitions"...}>
definition.risk_level
#=> "Low"

A successful call to this API returns a specific custom signature definition identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/custom_signature_definitions/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature definition to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "custom_signature_definitions",
    "attributes": {
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "updated_at": "2016-06-01T17:15:27.000Z",
      "created_at": "2016-06-01T17:15:27.000Z",
      "version_number": 1,
      "language": "ruby",
      "status": "editable"
    },
    "relationships": {
      "custom_signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
        }
      },
      "results": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
        }
      }
    }
  }
}

definition = ESP::CustomSignature::Definition.create(custom_signature_id: 1)
#=> <ESP::CustomSignature::Definition:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_definitions"...}>
definition.id
#=> 1

A successful call to this API creates a new custom signature definition. The body of the request must contain a json api compliant hash of attributes with type custom_signature_definitions. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/custom_signature_definitions

Request Parameters

Parameter Required Description
custom_signature_id Yes ID of the custom signature this definition should belong to.

Update

{
  "data": {
    "id": "1",
    "type": "custom_signature_definitions",
    "attributes": {
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "updated_at": "2016-06-01T17:15:27.000Z",
      "created_at": "2016-06-01T17:15:27.000Z",
      "version_number": 1,
      "language": "ruby",
      "status": "editable"
    },
    "relationships": {
      "custom_signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
        }
      },
      "results": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
        }
      }
    }
  }
}

definition = ESP::CustomSignature::Definition.find(1)
#=> <ESP::CustomSignature::Definition:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_definitions"...}>
definition.code = "None. It's only a test."
definition.save
#=> <ESP::CustomSignature::Definition:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_definitions", code=>"None. It's only a test."...}>

A successful call to this API updates a specific custom signature definition identified by the id parameter. The body of the request must contain a json api compliant hash of attributes with type custom_signature_definitions. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/custom_signature_definitions/<ID>

Request Parameters

Parameter Required Description
code The code for the definition
language The language of the code

Destroy

{
  "success": "Custom Signature Definition has been destroyed"
}
definition = ESP::CustomSignature::Definition.find(1)
#=> <ESP::CustomSignature:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_definitions"...}>
definition.destroy
definition = ESP::CustomSignature::Definition.find(1)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find CustomSignature::Definition.

A successful call to this API destroys a specific custom signature definition identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/custom_signature_definitions/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature definition to destroy

Activate

{
  "data": {
    "id": "1",
    "type": "custom_signature_definitions",
    "attributes": {
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "updated_at": "2016-06-01T17:15:27.000Z",
      "created_at": "2016-06-01T17:15:27.000Z",
      "version_number": 1,
      "language": "ruby",
      "status": "editable"
    },
    "relationships": {
      "custom_signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
        }
      },
      "results": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
        }
      }
    }
  }
}

definition = ESP::CustomSignature::Definition.find 1
#<ESP::CustomSignature::Definition:0x007f89252be5c0 @attributes={"id"=>"1", "type"=>"custom_signature_definitions" ...>
definition.activate

A successful call to this API activates and returns a specific custom signature definition identified by the id parameter. The definition must have a status of editable to be activated.

HTTP Request

PATCH https://api.evident.io/api/v2/custom_signature_definitions/<ID>/active

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature definition to activate

Archive

{
  "data": {
    "id": "1",
    "type": "custom_signature_definitions",
    "attributes": {
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "updated_at": "2016-06-01T17:15:27.000Z",
      "created_at": "2016-06-01T17:15:27.000Z",
      "version_number": 1,
      "language": "ruby",
      "status": "editable"
    },
    "relationships": {
      "custom_signature": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
        }
      },
      "results": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results.json?filter%5Bdefinition_id_eq%5D=1"
        }
      }
    }
  }
}

definition = ESP::CustomSignature::Definition.find 1
#<ESP::CustomSignature::Definition:0x007f89252be5c0 @attributes={"id"=>"1", "type"=>"custom_signature_definitions" ...>
definition.archive

A successful call to this API archives and returns a specific custom signature definition identified by the id parameter. The definition must have a status of active to be archived.

HTTP Request

PATCH https://api.evident.io/api/v2/custom_signature_definitions/<ID>/archive

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature definition to archive

Custom Signature Results

Custom Signature Results are the results from on demand runs of a Custom Signature Definition. When created the definition will start running. Once it is complete the definition status will change status from running to complete if there are no errors, or to the failed status if there are.

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
code String The code used for this result No No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
error_messages Array Error messages that occurred while running the code No No No
language String The language of the code Yes No No
status String Status of the result Yes No No
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Result Status Values

Value Description
running The result is currently running
complete The result has completed running successfully. Request alerts for the list of alerts generated.
failed An error occurred while running. See error_messages for a description of the issue. There may or may not be alerts for this result.

Relationships

Relation Includable n Searchable Note
definition Yes one Yes See Custom Signature Definition Attributes for searchable attributes.
region Yes one Yes See Region Attributes for searchable attributes.
external_account Yes one Yes See External Account Attributes for searchable attributes.
alerts No many No

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "custom_signature_results",
      "attributes": {
        "created_at": "2016-06-01T17:26:02.142Z",
        "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
        "language": "ruby",
        "status": "running",
        "updated_at": "2016-06-01T17:26:02.142Z",
        "error_messages": []
      },
      "relationships": {
        "external_account": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts/2.json"
          }
        },
        "region": {
          "links": {
            "related": "https://api.evident.io/api/v2/regions/1.json"
          }
        },
        "definition": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signature_definitions/1.json"
          }
        },
        "alerts": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signature_results/1/alerts.json"
          }
        }
      }
    }
  ]
}

results = ESP::CustomSignature::Result.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::CustomSignature::Result:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"custom_signature_resultss"...>
results.count
#=> 20
results.first.status
#=> "complete"

A successful call to this API returns a paginated list of custom signature results.

HTTP Request

GET https://api.evident.io/api/v2/custom_signature_results

Show

{
  "data": {
    "id": "1",
    "type": "custom_signature_results",
    "attributes": {
      "created_at": "2016-06-01T17:26:02.142Z",
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "language": "ruby",
      "status": "running",
      "updated_at": "2016-06-01T17:26:02.142Z",
      "error_messages": []
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/2.json"
        }
      },
      "region": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions/1.json"
        }
      },
      "definition": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_definitions/1.json"
        }
      },
      "alerts": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results/1/alerts.json"
        }
      }
    }
  }
}

result = ESP::CustomSignature::Result.find 3
#=> <ESP::CustomSignature::Result:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_results"...}>
result.status
#=> "complete"

A successful call to this API returns a specific custom signature result identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/custom_signature_results/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature result to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "custom_signature_results",
    "attributes": {
      "created_at": "2016-06-01T17:26:02.142Z",
      "code": "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n",
      "language": "ruby",
      "status": "running",
      "updated_at": "2016-06-01T17:26:02.142Z",
      "error_messages": []
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/2.json"
        }
      },
      "region": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions/1.json"
        }
      },
      "definition": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_definitions/1.json"
        }
      },
      "alerts": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signature_results/1/alerts.json"
        }
      }
    }
  }
}

code = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
result = ESP::CustomSignature::Result.create(code: code, language: "ruby", external_account_id: 1, region_id: 1, custom_signature_definition_id: 1)
#=> <ESP::CustomSignature::Result:0x007fb82acd3298 @attributes={"id"=>"1", "type"=>"custom_signature_results"...}>
result.id
#=> 1

A successful call to this API creates a new custom signature result. The body of the request must contain a json api compliant hash of attributes with type custom_signature_results. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/custom_signature_results

Request Parameters

Parameter Required Description
code Yes The code to run
custom_signature_definition_id Yes ID of the custom signature definition this result should belong to.
external_account_id Yes ID of the external account the code should run for.
language Yes The language of the code
region_id Yes ID of the region the code should run for.
region No Code of the region the result code should run for. Ex: us-east-1. This can be sent instead of region_id

Alerts

{
  "data": [
    {
      "id": "1",
      "type": "custom_signature_result_alerts",
      "attributes": {
        "created_at": "2016-06-01T17:34:01.280Z",
        "status": "fail",
        "resource": "resource-6",
        "metadata": {
          "abc": 123
        },
        "tags": [
          {
            "key": "abc",
            "value": "123",
          },
          {
            "key": "def",
            "value": "456",
          }
        ],
        "updated_at": "2016-06-01T17:34:01.280Z",
      },
      "relationships": {
        "external_account": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts/10.json"
          }
        },
        "region": {
          "links": {
            "related": "https://api.evident.io/api/v2/regions/8.json"
          }
        },
        "custom_signature": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signatures/3.json"
          }
        }
      }
    }
  ]
}

alerts = ESP::CustomSignature::Result::Alert.for_result(1)
#=> #<ActiveResource::PaginatedCollection:0x007f892419fa00 @elements=[#<ESP::CustomSignature::Result::Alert:0x007f892419f6e0 @attributes={"id"=>"", "type"=>"custom_signature_result_alerts" ...}>

Returns the alerts for a given result. Note that this format is slightly different than the standard alert format.

A successful call to this API returns a list of alerts for the custom signature result identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/custom_signature_results/<ID>/alerts

Request Parameters

Parameter Required Description
id Yes The ID of the custom signature result to retrieve

External Accounts

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
account String The name of the account created
arn String Amazon Resource Name for the IAM role Yes No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
external_id String External identifier set on the role
name String The name of the resource Yes Yes Yes
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
organization Yes one Yes See Organization Attributes for searchable attributes.
sub_organization Yes one Yes See Sub Organization Attributes for searchable attributes.
team Yes one Yes See Team Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "external_accounts",
      "attributes": {
        "account": "123456789012",
        "arn": "arn:aws:iam::123456789012:role/Evident-Service-Role",
        "created_at": "2015-08-26T13:25:57.000Z",
        "cloudtrail_name": null,
        "external_id": "61ef0343-abcd-4dd1-a16c-bbbe3d4564014",
        "name": "Demo Account",
        "updated_at": "2015-10-16T02:30:17.000Z"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "sub_organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
          }
        },
        "team": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams/1.json"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/external_accounts?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/external_accounts?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/external_accounts?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

external_accounts = ESP::ExternalAccount.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::ExternalAccount:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"external_accounts"...>
external_accounts.count
#=> 20
external_accounts.first.name
#=> "The Resource Name"

A successful call to this API returns a paginated list of external accounts.

HTTP Request

GET https://api.evident.io/api/v2/external_accounts

Show

{
  "data": {
    "id": "1",
    "type": "external_accounts",
    "attributes": {
      "account": "123456789012",
      "arn": "arn:aws:iam::123456789012:role/Evident-Service-Role",
      "created_at": "2015-08-26T13:25:57.000Z",
      "cloudtrail_name": null,
      "external_id": "61ef0343-abcd-4dd1-a16c-bbbe3d4564014",
      "name": "Demo Account",
      "updated_at": "2015-10-16T02:30:17.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

external_account = ESP::ExternalAccount.find 3
#=> <ESP::ExternalAccount:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"external_accounts"...}>
external_account.name
#=> "The Resource Name"

A successful call to this API returns an external account identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/external_accounts/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the external account to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "external_accounts",
    "attributes": {
      "account": "123456789012",
      "arn": "arn:aws:iam::123456789012:role/Evident-Service-Role",
      "created_at": "2015-08-26T13:25:57.000Z",
      "cloudtrail_name": null,
      "external_id": "61ef0343-abcd-4dd1-a16c-bbbe3d4564014",
      "name": "Demo Account",
      "updated_at": "2015-10-16T02:30:17.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

external_account = ESP::ExternalAccount.create(arn: 'arn:from:aws', external_id: 'c40e6af4-a5a0-422a-9a42-3d7d236c3428', team_id: 8)
#=> <ESP::ExternalAccount:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"external_accounts"...}>
external_account.id
#=> 3

A successful call to this API creates an external account and returns the newly created external account. The body of the request must contain a json api compliant hash of attributes with type external_accounts. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/external_accounts

Parameter Required Description
arn Yes Amazon Resource Name for the IAM role
external_id Yes External identifier set on the role
name The name for this external account
team_id Yes The ID of the team the external account will belong to

Update

{
  "data": {
    "id": "1",
    "type": "external_accounts",
    "attributes": {
      "account": "123456789012",
      "arn": "arn:aws:iam::123456789012:role/Evident-Service-Role",
      "created_at": "2015-08-26T13:25:57.000Z",
      "cloudtrail_name": null,
      "external_id": "61ef0343-abcd-4dd1-a16c-bbbe3d4564014",
      "name": "Demo Account",
      "updated_at": "2015-10-16T02:30:17.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

external_account = ESP::ExternalAccount.find(3)
#=> <ESP::ExternalAccount:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"external_accounts"...}>
external_account.name = "Test Account"
external_account.save
#=> <ESP::ExternalAccount:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"external_accounts", name=>"Test Account"...}>

A successful call to this API updates an external account and returns the newly updated external account. The body of the request must contain a json api compliant hash of attributes with type external_accounts. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/external_accounts/<ID>

Parameter Required Description
arn Yes Amazon Resource Name for the IAM role
external_id Yes External identifier set on the role
name The name for this external account
sub_organization_id Yes The ID of the sub organization the external account will belong to
team_id Yes The ID of the team the external account will belong to

Delete

{
  "success": "Demo Account has been destroyed"
}
external_account = ESP::ExternalAccount.find(3)
#=> <ESP::ExternalAccount:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"external_accounts"...}>
external_account.destroy
external_account = ESP::ExternalAccount.find(3)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find ExternalAccount.

A successful call to this API deletes an external account identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/external_accounts/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the external account to retrieve

Update User Attribution

{
  "data": {
    "id": "1",
    "type": "external_accounts",
    "attributes": {
      "account": "123456789012",
      "arn": "arn:aws:iam::123456789012:role/Evident-Service-Role",
      "created_at": "2015-08-26T13:25:57.000Z",
      "cloudtrail_name": null,
      "external_id": "61ef0343-abcd-4dd1-a16c-bbbe3d4564014",
      "name": "Demo Account",
      "updated_at": "2015-10-16T02:30:17.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

A successful call to this API updates an external account with attribution and returns the newly updated external account. Sending in a blank cloudtrail_name will disable user attribution on the given account. The body of the request must contain a json api compliant hash of attributes with type external_accounts. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/external_accounts/<ID>/user_attribution

Parameter Required Description
cloudtrail_name Yes Amazon CloudTrail name

Metadata

Attributes

Attribute Type Description
data Object Contains metadata returned by the signature. The object will be different for each alert depending on signature and status.

For Alert

{
  "data": {
    "id": "999",
    "type": "metadata",
    "attributes": {
      "data": {
        "deep_inspection": {
          "network_acl_id": "acl-abcd1234",
          "subnet_id": "subnet-1234abcd"
        },
        "resource_id": "subnet-1234abcd"
      }
    }
  }
}

metadata = ESP::Metadata.for_alert(1194)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Metadata:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"metadata"...>
metadata.count
#=> 20
metadata.first.data
#=> "AuthorizeSecurityGroupIngress"

A successful call to this API returns the metadata for the given alert_id.

HTTP Request

GET https://api.evident.io/api/v2/alerts/<ALERT_ID>/metadata

Request Parameters

Parameter Required Description
alert_id Yes The ID of the alert to retrieve metadata for

Show

{
  "data": {
    "id": "999",
    "type": "metadata",
    "attributes": {
      "data": {
        "deep_inspection": {
          "network_acl_id": "acl-abcd1234",
          "subnet_id": "subnet-1234abcd"
        },
        "resource_id": "subnet-1234abcd"
      }
    }
  }
}

metadata = ESP::Metadata.find 3
#=> <ESP::Metadata:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"metadata"...}>
metadata.data
#=> {
        "deep_inspection": {
          "network_acl_id": "acl-abcd1234",
          "subnet_id": "subnet-1234abcd"
        },
        "resource_id": "subnet-1234abcd"
      }

A successful call to this API returns the metadata object.

HTTP Request

GET https://api.evident.io/api/v2/metadata/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the metadata object to retrieve

Organizations

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
name String Name of the organization Yes Yes No
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
custom_signatures Yes many No
external_accounts Yes many No
sub_organizations Yes many No
teams Yes many No
users Yes many No

List

{
  "data": [
    {
      "id": "1",
      "type": "organizations",
      "attributes": {
        "created_at": "2015-10-16T00:11:43.000Z",
        "name": "Demo Organization",
        "updated_at": "2015-10-16T00:25:10.000Z"
      },
      "relationships": {
        "custom_signatures": {
          "links": {
            "related": "https://api.evident.io/api/v2/custom_signatures.json?filter%5Borganization_id_eq%5D=1"
          }
        },
        "external_accounts": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Borganization_id_eq%5D=1"
          }
        },
        "sub_organizations": {
          "links": {
            "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
          }
        },
        "teams": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
          }
        },
        "users": {
          "links": {
            "related": "https://api.evident.io/api/v2/users.json?filter%5Borganization_id_eq%5D=1"
          }
        }
      }
    }
  ],
  "links": {}
}

organizations = ESP::Organization.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Organization:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"organizations"...>
organizations.count
#=> 1
organizations.first.name
#=> "Organization Name"

A successful call to this API returns a paginated list of organizations.

HTTP Request

GET https://api.evident.io/api/v2/organizations

Show

{
  "data": {
    "id": "1",
    "type": "organizations",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Demo Organization",
      "updated_at": "2015-09-09T04:04:18.000Z"
    },
    "relationships": {
      "custom_signatures": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures.json?filter%5Borganization_id_eq%5D=1"
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Borganization_id_eq%5D=1"
        }
      },
      "sub_organizations": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
        }
      },
      "users": {
        "links": {
          "related": "https://api.evident.io/api/v2/users.json?filter%5Borganization_id_eq%5D=1"
        }
      }
    }
  }
}

organization = ESP::Organization.find 3
#=> <ESP::Organization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"organizations"...}>
organization.name
#=> "Organization Name"

A successful call to this API returns a single organization.

HTTP Request

GET https://api.evident.io/api/v2/organizations/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the organization to retrieve

Update

{
  "data": {
    "id": "1",
    "type": "organizations",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Demo Organization",
      "updated_at": "2015-09-09T04:04:18.000Z"
    },
    "relationships": {
      "custom_signatures": {
        "links": {
          "related": "https://api.evident.io/api/v2/custom_signatures.json?filter%5Borganization_id_eq%5D=1"
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Borganization_id_eq%5D=1"
        }
      },
      "sub_organizations": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Borganization_id_eq%5D=1"
        }
      },
      "users": {
        "links": {
          "related": "https://api.evident.io/api/v2/users.json?filter%5Borganization_id_eq%5D=1"
        }
      }
    }
  }
}

organization = ESP::Organization.find(3)
#=> <ESP::Organization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"organizations"...}>
organization.name = "We changed our Name"
organization.save
#=> <ESP::Organization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"organizations", name=>"We changed our Name"...}>

A successful call to this API updates a single organization.

HTTP Request

PATCH https://api.evident.io/api/v2/organizations/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the organization to update
name The new name of the organization

Regions

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
code String AWS region code. This code is underscored. Yes Yes No

See Searching Lists and Including Objects for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "regions",
      "attributes": {
        "code": "ap_northeast_1",
        "created_at": "2015-10-19T05:03:10.000Z",
        "updated_at": null
      }
    }
  ],
  "links": {}
}

regions = ESP::Region.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Region:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"regions"...>
regions.count
#=> 10
regions.first.code
#=> "us_east_1"

A successful call to this API returns a paginated list of supported AWS regions.

HTTP Request

GET https://api.evident.io/api/v2/regions

Show

{
  "data": {
    "id": "1",
    "type": "regions",
    "attributes": {
      "code": "ap_northeast_1",
      "created_at": "2015-10-19T05:03:10.000Z",
      "updated_at": null
    }
  }
}

region = ESP::Region.find 3
#=> <ESP::Region:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"regions"...}>
region.code
#=> "us_east_1"

You may also use the region object to create a suppression for that region. See the Suppression section for more details.

region.suppress(external_account_ids: [5], reason: 'My very good reason for creating this suppression')

A successful call to this API returns a single region.

HTTP Request

GET https://api.evident.io/api/v2/regions/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the region to retrieve

Reports

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the alert was created Yes No Yes
status String Status of the report
updated_at String ISO 8601 timestamp when the alert was last updated

See Searching Lists and Including Objects for more information.

Report Status Values

Value Description
complete The report has completed processing.
partial Most of the alerts have been processed. Stats are available for the processed alerts.
processing This report is still being processed. Some alerts may have been processed. Stats have not yet been generated.
queued The report has been queued and processing will begin soon.

Relationships

Relation Includable n Searchable Note
alerts No many No Use the /reports/<REPORT_ID>/alerts endpoint to get alerts for a given report.
organization Yes one Yes See Organization Attributes for searchable attributes.
sub_organization Yes one Yes See Sub Organization Attributes for searchable attributes.
team Yes one Yes See Team Attributes for searchable attributes.
external_account Yes one Yes See External Account Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "reports",
      "attributes": {
        "created_at": "2015-10-16T03:30:02.000Z",
        "status": "complete",
        "updated_at": "2015-10-16T03:31:28.000Z"
      },
      "relationships": {
        "alerts": {
          "links": {
            "related": "https://api.evident.io/api/v2/reports/1/alerts.json"
          }
        },
        "external_account": {
          "links": {
            "related": "http://test.host/api/v2/external_accounts/1.json"
          }
        },
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "sub_organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
          }
        },
        "team": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams/1.json"
          }
        }
      }
    }
  ],
  "links": {}
}

reports = ESP::Report.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Report:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"reports"...>
reports.count
#=> 20
reports.first.status
#=> "complete"

A successful call to this API returns a paginated list of reports.

HTTP Request

GET https://api.evident.io/api/v2/reports

Show

{
  "data": {
    "id": "1",
    "type": "reports",
    "attributes": {
      "created_at": "2015-10-15T01:30:09.000Z",
      "status": "complete",
      "updated_at": "2015-10-15T01:32:06.000Z"
    },
    "relationships": {
      "alerts": {
        "links": {
          "related": "https://api.evident.io/api/v2/reports/1/alerts.json"
        }
      },
      "external_account": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts/1.json"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

report = ESP::Report.find 3
#=> <ESP::Report:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"reports"...}>
report.status
#=> "complete"

This endpoint retrieves a specific report.

HTTP Request

GET https://api.evident.io/api/v2/reports/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the report to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "reports",
    "attributes": {
      "created_at": "2015-10-15T01:30:09.000Z",
      "status": "complete",
      "updated_at": "2015-10-15T01:32:06.000Z"
    },
    "relationships": {
      "alerts": {
        "links": {
          "related": "https://api.evident.io/api/v2/reports/1/alerts.json"
        }
      },
      "external_account": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts/1.json"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      },
      "team": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams/1.json"
        }
      }
    }
  }
}

report = ESP::Report.create(team_id: 4)
#=> <ESP::Report:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"reports"...}>
report.status
#=> 'queued'

This endpoint creates a report for the given team. The report will start out in a queued state. You may query the report at the show action to watch the status. The body of the request must contain a json api compliant hash of attributes with type reports. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/reports

Request Parameters

Parameter Required Description
team_id Yes The ID of the team to create a report for

Export

{
  "success": "Your export has been started."
}
ESP::Report::Export::Integration.create(report_ids: [1], integration_id: 1)
#=> #<Net::HTTPOK 200 OK readbody=true>

This endpoint exports all alerts on reports to the given integration. This is only supported for active Amazon SNS, Amazon SQS, and Webhook integrations.

HTTP Request

POST https://api.evident.io/api/v2/reports/export/integrations

Request Parameters

Parameter Required Description
report_ids Yes An array of report IDs.
integration_id Yes The ID of the integration to send the alerts to.

Roles

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created
name String The name of the role Yes Yes Yes
updated_at String ISO 8601 timestamp when the resource was updated No No Yes

See Searching Lists and Including Objects for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "roles",
      "attributes": {
        "name": "manager",
        "created_at": "2015-10-19T05:03:10.000Z",
        "updated_at": null
      }
    }
  ],
  "links": {}
}

roles = ESP::Role.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Role:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"roles"...>
roles.count
#=> 2
roles.first.name
#=> "manager"

A successful call to this API returns a paginated list of roles available to the caller.

HTTP Request

GET https://api.evident.io/api/v2/roles

Show

{
  "data": {
    "id": "1",
    "type": "roles",
    "attributes": {
      "created_at": "2015-10-19T05:03:10.000Z",
      "name": "manager",
      "updated_at": null
    }
  }
}

role = ESP::Role.find 2
#=> <ESP::Role:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"roles"...}>
role.name
#=> "manager"

A successful call to this API returns a specific role identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/roles/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the role to retrieve

Scan Intervals

Attributes

Attribute Type Description
created_at String ISO 8601 timestamp when the resource was created
interval Integer The interval, in minutes, this service will be scanned.
updated_at String ISO 8601 timestamp when the resource was last updated

Relationships

Relation Includable n Note
external_account Yes one
service Yes one

List

{
  "data": [
    {
      "attributes": {
        "created_at": "2016-02-04T21:49:19.000Z",
        "interval": 30,
        "updated_at": "2016-02-04T21:49:23.000Z"
      },
      "id": "1",
      "relationships": {
        "external_account": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts/1.json"
          }
        },
        "service": {
          "links": {
            "related": "https://api.evident.io/api/v2/services/4.json"
          }
        }
      },
      "type": "scan_intervals"
    }
  ],
  "links": {}
}

external_account = ESP::ExternalAccount.first
#=> #<ESP::ExternalAccount:0x007fd2119bae48 @attributes={"id"=>"1", "type"=>"external_accounts" ...>
scan_intervals = external_accounts.scan_intervals
#=> #<ActiveResource::PaginatedCollection:0x007fab942c17c0 @elements=[#<ESP::ScanInterval:0x007fab942c14c8 @attributes={"id"=>"1", ... >
scan_intervals.first.interval
#=> 15

A successful call to this API returns a paginated list of scan intervals.

HTTP Request

GET https://api.evident.io/api/v2/external_accounts/<EXTERNAL_ACCOUNT_ID>/scan_intervals

Request Parameters

Parameter Required Description
external_account_id Yes The ID of the external account to retrieve

Show

{
  "data": {
    "id": "1003",
    "type": "scan_intervals",
    "attributes": {
      "interval": 15,
      "created_at": "2016-02-08T20:25:43.740Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/1001.json"
        }
      },
      "service": {
        "links": {
          "related": "https://api.evident.io/api/v2/services/1002.json"
        }
      }
    }
  }
}

scan_interval = ESP::ScanInterval.find(1)
#=> #<ESP::ScanInterval:0x007fab950d2f80 @attributes={"interval"=>15, "external_account_id"=>"1", "service_id"=>"1", "id"=>"1", "type"=>"scan_intervals"...>
scan_interval.interval
#=> 15

A successful call to this API returns a scan interval for an external account identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/scan_intervals/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the scan interval to retrieve

Create

{
  "data": {
    "id": "1003",
    "type": "scan_intervals",
    "attributes": {
      "interval": 15,
      "created_at": "2016-02-08T20:25:43.740Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/1001.json"
        }
      },
      "service": {
        "links": {
          "related": "https://api.evident.io/api/v2/services/1002.json"
        }
      }
    }
  }
}

scan_interval = ESP::ScanInterval.create(interval: 15, external_account_id: 1, service_id: 1)
#=> #<ESP::ScanInterval:0x007fab950d2f80 @attributes={"interval"=>15, "external_account_id"=>"1", "service_id"=>"1", "id"=>"3", "type"=>"scan_intervals"...>
scan_interval.id
#=> 3

A successful call to this API creates a scan interval for an external account and returns the newly created scan interval. The body of the request must contain a json api compliant hash of attributes with type scan_intervals. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/scan_intervals

Parameter Required Description
external_account_id Yes The ID of the external account this scan interval is for
interval Yes The interval, in minutes, this service will be scanned.
service_id Yes The service ID this scan interval is for

Update

{
  "data": {
    "id": "1003",
    "type": "scan_intervals",
    "attributes": {
      "interval": 15,
      "created_at": "2016-02-08T20:25:43.740Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts/1001.json"
        }
      },
      "service": {
        "links": {
          "related": "https://api.evident.io/api/v2/services/1002.json"
        }
      }
    }
  }
}

scan_interval = ESP::ScanInterval.find(1)
#=> #<ESP::ScanInterval:0x007fab950d2f80 @attributes={"interval"=>15, "external_account_id"=>"1", "service_id"=>"1", "id"=>"1", "type"=>"scan_intervals"...>
scan_interval.interval = 30
scan_interval.save
#=> #<ESP::ScanInterval:0x007fab950d2f80 @attributes={"interval"=>30, "external_account_id"=>"1", "service_id"=>"1", "id"=>"1", "type"=>"scan_intervals"...>

A successful call to this API updates a scan interval and returns the newly updated scan interval. The body of the request must contain a json api compliant hash of attributes with type scan_intervals. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/scan_intervals/<ID>

Parameter Required Description
external_account_id Yes The ID of the external account this scan interval is for
interval Yes The interval, in minutes, this service will be scanned.
service_id Yes The service ID this scan interval is for

Delete

{
  "success": "Scan Interval has been removed. The default interval will be used."
}
scan_interval = ESP::ScanInterval.find(1)
#=> #<ESP::ScanInterval:0x007fab950d2f80 @attributes={"interval"=>30, "external_account_id"=>"1", "service_id"=>"1", "id"=>"1", "type"=>"scan_intervals"...>
scan_interval.destroy
scan_interval = ESP::ScanInterval.find(1)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find ScanInterval.

A successful call to this API deletes a scan interval identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/scan_intervals/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the scan interval to delete

Services

Attributes

Attribute Type Description
code String The code associated with this service
created_at String ISO 8601 timestamp when the resource was created
default_interval Integer Default interval used for scans if a scan interval was not created.
minimum_interval Integer Minimum interval allowed for scans on this service.
name String The name of the service
policy_name String The policy name of the service. This matches the namespace set by Amazon here.
updated_at String ISO 8601 timestamp when the resource was last updated

List

{
  "data": [
    {
      "id": "1",
      "type": "services",
      "attributes": {
        "code": "IAM",
        "created_at": "2015-08-14T05:13:05.000Z",
        "default_interval": 15,
        "minimum_interval": 15,
        "name": "IAM",
        "policy_name": "iam",
        "updated_at": "2015-08-14T05:13:21.000Z"
      }
    },
    {
      "id": "2",
      "type": "services",
      "attributes": {
        "code": "RDS",
        "created_at": "2015-08-14T05:13:06.000Z",
        "default_interval": 15,
        "minimum_interval": null,
        "name": "RDS",
        "policy_name": "rds",
        "updated_at": "2015-08-14T05:13:21.000Z"
      }
    },
    {
      "attributes": {
        "code": "CUSTOM",
        "created_at": "2015-08-14T05:13:21.000Z",
        "default_interval": 15,
        "minimum_interval": null,
        "name": "Custom",
        "policy_name": null,
        "updated_at": "2015-08-14T05:13:21.000Z"
      },
      "id": "12",
      "type": "services"
    }
  ],
  "links": {}
}

services = ESP::Service.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Service:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"services"...>
services.count
#=> 12
services.first.name
#=> "EC2"

A successful call to this API returns a paginated list of services.

HTTP Request

GET https://api.evident.io/api/v2/services

Show

{
  "data": {
    "id": "1",
    "type": "services",
    "attributes": {
      "code": "IAM",
      "created_at": "2015-08-14T05:13:05.000Z",
      "default_interval": 15,
      "minimum_interval": null,
      "name": "IAM",
      "policy_name": "iam",
      "updated_at": "2015-08-14T05:13:21.000Z"
    }
  }
}

service = ESP::Service.find 3
#=> <ESP::Service:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"services"...}>
service.name
#=> "EC2"

A successful call to this API returns a specific service identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/services/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the service to retrieve

Signatures

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
description String The description of the user Yes Yes No
identifier String The identifier of the signature Yes Yes Yes
name String The name of the signature Yes Yes Yes
resolution String Details for how to resolve this signature Yes Yes No
risk_level String The risk-level of the problem identified by the signature. Valid values are Low, Medium, High Yes No Yes
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
service Yes one No

List

{
  "data": [
    {
      "id": "1",
      "type": "signatures",
      "attributes": {
        "created_at": "2015-08-14T05:13:05.000Z",
        "description": "\"Verify that the IAM policy you created when configuring the Evident role does not have extra permissions.\"",
        "identifier": "AWS:IAM-011",
        "name": "IAM policy attached to the Evident role is too permissive",
        "resolution": "\"When creating the relationship between Evident.io and your AWS account, you were asked to use the AWS Managed SecurityAudit Policy.  Please review the role you have created and ensure it provides no more privileges than the SecurityAudit Policy and there are no resources you have granted Evident elevated privileges.While you may customize this role and restrict what Evident.io has access too, please do not add any permissions to this role without guidance from Evident.Please review the steps here on setting up the correct Role for Evident to scan your account:IMPORTANT: Use the following steps to Create Role & Cross-Account Access (AWS Identity / ARN)\\n    1.  Log into your Amazon Management Console (https://console.aws.amazon.com/).\\n    2.  On the AWS Services page, select the IAM service.\\n    3.  Select Roles on the left menu.\\n    4.  Select Create New Role.\\n    5.  ESP recommends that you name the role Evident-Service-Role. Click Next Step.\\n    6.  Select the radio button Role for Cross-Account Access.\\n    7.  Select Allows IAM users from a 3rd party AWS account to access this account.\\n    8.  Enter the Account ID of the ESP service.\\n    9.  Enter the External ID field of the AWS dialog box. \\n    10. Verify that Require MFA is not enabled.\\n    11. Click Next Step.\\n    12. Select the SecurityAudit from Amazon's pre-configured policies. Click Next Step.\\n    13. In the Review step, copy the Role ARN string to paste in the last step.\\n    14. Click Create Role.\\n    15. Return to ESP and paste the Role ARN into the ARN field and click Save.\\n    16. Enter the appropriate information into the Name, Sub Organization, and Team fields.\\n    17. Click Submit\\nIf there are any questions, please sent an email to support@evident.io.\"",
        "risk_level": "Medium",
        "updated_at": "2015-10-03T00:00:11.000Z"
      },
      "relationships": {
        "service": {
          "links": {
            "related": "https://api.evident.io/api/v2/services/3.json"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/signatures?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/signatures?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/signatures?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

signatures = ESP::Signature.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Signature:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"signatures"...>
signatures.count
#=> 20
signatures.first.risk_level
#=> "Low"

A successful call to this API returns a paginated list of signatures.

HTTP Request

GET https://api.evident.io/api/v2/signatures

Show

{
  "data": {
    "id": "1",
    "type": "signatures",
    "attributes": {
      "created_at": "2015-08-14T05:13:05.000Z",
      "description": "\"Verify that the IAM policy you created when configuring the Evident role does not have extra permissions.\"",
      "identifier": "AWS:IAM-011",
      "name": "IAM policy attached to the Evident role is too permissive",
      "resolution": "\"When creating the relationship between Evident.io and your AWS account, you were asked to use the AWS Managed SecurityAudit Policy.  Please review the role you have created and ensure it provides no more privileges than the SecurityAudit Policy and there are no resources you have granted Evident elevated privileges.While you may customize this role and restrict what Evident.io has access too, please do not add any permissions to this role without guidance from Evident.Please review the steps here on setting up the correct Role for Evident to scan your account:IMPORTANT: Use the following steps to Create Role & Cross-Account Access (AWS Identity / ARN)\\n    1.  Log into your Amazon Management Console (https://console.aws.amazon.com/).\\n    2.  On the AWS Services page, select the IAM service.\\n    3.  Select Roles on the left menu.\\n    4.  Select Create New Role.\\n    5.  ESP recommends that you name the role Evident-Service-Role. Click Next Step.\\n    6.  Select the radio button Role for Cross-Account Access.\\n    7.  Select Allows IAM users from a 3rd party AWS account to access this account.\\n    8.  Enter the Account ID of the ESP service.\\n    9.  Enter the External ID field of the AWS dialog box. \\n    10. Verify that Require MFA is not enabled.\\n    11. Click Next Step.\\n    12. Select the SecurityAudit from Amazon's pre-configured policies. Click Next Step.\\n    13. In the Review step, copy the Role ARN string to paste in the last step.\\n    14. Click Create Role.\\n    15. Return to ESP and paste the Role ARN into the ARN field and click Save.\\n    16. Enter the appropriate information into the Name, Sub Organization, and Team fields.\\n    17. Click Submit\\nIf there are any questions, please sent an email to support@evident.io.\"",
      "risk_level": "Medium",
      "updated_at": "2015-10-03T00:00:11.000Z"
    },
    "relationships": {
      "service": {
        "links": {
          "related": "https://api.evident.io/api/v2/services/1.json"
        }
      }
    }
  }
}

signature = ESP::Signature.find 3
#=> <ESP::Signature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"signatures"...}>
signature.risk_level
#=> "Low"

You may also use the signature object to create a suppression for that signature. See the Suppression section for more details.

signature.suppress(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')

A successful call to this API returns a specific signature identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/signatures/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the signature to retrieve

Run

{
  "data": [
    {
      "id": "5",
      "type": "alerts",
      "attributes": {
        "created_at": "2015-12-08T22:21:47.837Z",
        "status": "fail",
        "resource": "resource-6",
        "updated_at": "2015-12-08T22:21:47.844Z",
        "started_at": "2015-12-08T22:20:47.833Z",
        "ended_at": null
      },
      "relationships": {
        "external_account": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts/6.json"
          }
        },
        "region": {
          "links": {
            "related": "https://api.evident.io/api/v2/regions/6.json"
          }
        },
        "signature": {
          "links": {
            "related": "https://api.evident.io/api/v2/signatures/4.json"
          }
        },
        "custom_signature": {
          "links": {
            "related": null
          }
        },
        "suppression": {
          "links": {
            "related": "https://api.evident.io/api/v2/suppressions/1.json"
          }
        },
        "metadata": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/metadata.json"
          }
        },
        "cloud_trail_events": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/cloud_trail_events.json"
          }
        },
        "tags": {
          "links": {
            "related": "https://api.evident.io/api/v2/alerts/5/tags.json"
          }
        }
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=453&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/reports/7824/alerts?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

signature = ESP::Signature.find(3)
alerts = signature.run(external_account_id: 3, regions: ['us_east_1'])
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Alert:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"alerts"...>

A successful call to this API returns a list of alerts for the specific signature identified by the id parameter. The body of the request must contain a json api compliant hash of attributes with type signatures. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/signatures/<ID>/run

Request Parameters

Parameter Required Description
id Yes The ID of the signature to run
external_account_id Yes The ID of the external account to run this signature against
region Yes A single region name to run this signature against

Signature Custom Risk Levels

Attributes

Attribute Type Description
created_at String ISO 8601 timestamp when the resource was created
risk_level String The risk-level of the problem identified by the signature. Valid values are Low, Medium, High
updated_at String ISO 8601 timestamp when the resource was last updated

Relationships

Relation Includable n Note
external_account Yes one
signature Yes one

List

{
  "data": [
    {
      "id": "1004",
      "type": "signature_custom_risk_levels",
      "attributes": {
        "risk_level": "low",
        "created_at": "2016-10-14T17:56:48.586Z",
        "updated_at": null
      },
      "relationships": {
        "external_account": {
          "links": {
            "related": "http://test.host/api/v2/external_accounts/1001.json"
          }
        },
        "signature": {
          "links": {
            "related": "http://test.host/api/v2/signatures/1003.json"
          }
        }
      }
    }
  ],
  "links": {}
}

A successful call to this API returns a paginated list of signature custom risk levels.

HTTP Request

GET https://api.evident.io/api/v2/external_accounts/<EXTERNAL_ACCOUNT_ID>/signature_custom_risk_levels

Request Parameters

Parameter Required Description
external_account_id Yes The ID of the external account to retrieve

Show

{
  "data": {
    "id"           : "1004",
    "type"         : "signature_custom_risk_levels",
    "attributes"   : {
      "risk_level": "low",
      "created_at": "2016-10-14T17:56:48.586Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts/1001.json"
        }
      },
      "signature"       : {
        "links": {
          "related": "http://test.host/api/v2/signatures/1003.json"
        }
      }
    }
  }
}

A successful call to this API returns a signature custom risk level for an external account identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/signature_custom_risk_level/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the signature custom risk level to retrieve

Create

{
  "data": {
    "id"           : "1004",
    "type"         : "signature_custom_risk_levels",
    "attributes"   : {
      "risk_level": "low",
      "created_at": "2016-10-14T17:56:48.586Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts/1001.json"
        }
      },
      "signature"       : {
        "links": {
          "related": "http://test.host/api/v2/signatures/1003.json"
        }
      }
    }
  }
}

A successful call to this API creates a signature custom risk level for an external account and returns the newly created signature custom risk level. The body of the request must contain a json api compliant hash of attributes with type signature_custom_risk_levels. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/signature_custom_risk_levels

Parameter Required Description
external_account_id Yes The ID of the external account this signature custom risk level is for
risk_level Yes The risk-level of the problem identified by the signature. Valid values are Low, Medium, High
signature_id Yes The signature ID this signature custom risk level is for

Update

{
  "data": {
    "id"           : "1004",
    "type"         : "signature_custom_risk_levels",
    "attributes"   : {
      "risk_level": "low",
      "created_at": "2016-10-14T17:56:48.586Z",
      "updated_at": null
    },
    "relationships": {
      "external_account": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts/1001.json"
        }
      },
      "signature"       : {
        "links": {
          "related": "http://test.host/api/v2/signatures/1003.json"
        }
      }
    }
  }
}

A successful call to this API updates an signature custom risk level and returns the newly updated signature custom risk level. The body of the request must contain a json api compliant hash of attributes with type signature_custom_risk_levels. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/signature_custom_risk_levels/<ID>

Parameter Required Description
external_account_id Yes The ID of the external account this signature custom risk level is for
risk_level Yes The risk-level of the problem identified by the signature. Valid values are Low, Medium, High
signature_id Yes The signature ID this signature custom risk level is for

Delete

{
  "success": "Custom Risk Level has been removed. The default risk level will be used."
}

A successful call to this API deletes a signature custom risk level identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/signature_custom_risk_levels/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the signature custom risk level to delete

Stats

Attributes

Stats include fields for each combination of time period, status, and signature risk level.

Attribute Type
new_1h_high_pass Integer
new_1d_high_pass Integer
new_1w_high_pass Integer
old_high_pass Integer
new_1h_high_fail Integer
new_1d_high_fail Integer
new_1w_high_fail Integer
old_high_fail Integer
new_1h_high_warn Integer
new_1d_high_warn Integer
new_1w_high_warn Integer
old_high_warn Integer
new_1h_high_error Integer
new_1d_high_error Integer
new_1w_high_error Integer
old_high_error Integer
new_1h_medium_pass Integer
new_1d_medium_pass Integer
new_1w_medium_pass Integer
old_medium_pass Integer
new_1h_medium_fail Integer
new_1d_medium_fail Integer
new_1w_medium_fail Integer
old_medium_fail Integer
new_1h_medium_warn Integer
new_1d_medium_warn Integer
new_1w_medium_warn Integer
old_medium_warn Integer
new_1h_medium_error Integer
new_1d_medium_error Integer
new_1w_medium_error Integer
old_medium_error Integer
new_1h_low_pass Integer
new_1d_low_pass Integer
new_1w_low_pass Integer
old_low_pass Integer
new_1h_low_fail Integer
new_1d_low_fail Integer
new_1w_low_fail Integer
old_low_fail Integer
new_1h_low_warn Integer
new_1d_low_warn Integer
new_1w_low_warn Integer
old_low_warn Integer
new_1h_low_error Integer
new_1d_low_error Integer
new_1w_low_error Integer
old_low_error Integer
suppressed_high_pass Integer
suppressed_high_fail Integer
suppressed_high_warn Integer
suppressed_high_error Integer
suppressed_medium_pass Integer
suppressed_medium_fail Integer
suppressed_medium_warn Integer
suppressed_medium_error Integer
suppressed_low_pass Integer
suppressed_low_fail Integer
suppressed_low_warn Integer
suppressed_low_error Integer
new_1h_high_info Integer
new_1d_high_info Integer
new_1w_high_info Integer
old_high_info Integer
new_1h_medium_info Integer
new_1d_medium_info Integer
new_1w_medium_info Integer
old_medium_info Integer
new_1h_low_info Integer
new_1d_low_info Integer
new_1w_low_info Integer
old_low_info Integer
suppressed_high_info Integer
suppressed_medium_info Integer
suppressed_low_info Integer

Time Periods

Period Description
new_1h Count of alerts new in the last hour relative to the report created time.
new_1d Count of alerts new in the last day relative to the report created time. This count includes the alerts counted in the last hour.
new_1w Count of alerts new in the last hour relative to the report created time. This count includes the alerts counted in the last hour/day.
old Count of alerts older than 1 week relative to the report created time.

Relationships

Relation Includable n Note
report Yes one
regions Yes many
services Yes many
signatures Yes many
custom_signatures Yes many

For Report

 {
   "data": {
     "id":            "1",
     "type":          "stats",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
       "report":            {
         "links": {
           "related": "https://api.evident.io/api/v2/reports/1.json"
         }
       },
       "regions":           {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/regions.json"
         }
       },
       "signatures":        {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/signatures.json"
         }
       },
       "custom_signatures": {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/custom_signatures.json"
         }
       }
     }
   }
 }

stat = ESP::Stat.for_report(54)
#=> #<ESP::Stat:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stats"...>
stat.total
#=> 2141

A successful call to this API returns all the stats of all the alerts for a report identified by the report_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.

HTTP Request

GET https://api.evident.io/api/v2/reports/<REPORT_ID>/stats

Request Parameters

Parameter Required Description
report_id Yes The ID of the report to retrieve stats for

Latest for Teams

 {
   "data": [
   {
     "id":            "1",
     "type":          "stats",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
       "report":            {
         "links": {
           "related": "https://api.evident.io/api/v2/reports/1.json"
         }
       },
       "regions":           {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/regions.json"
         }
       },
       "signatures":        {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/signatures.json"
         }
       },
       "custom_signatures": {
         "links": {
           "related": "https://api.evident.io/api/v2/stats/1/custom_signatures.json"
         }
       }
     }
   }
   ],
   "links": {}
 }

stats = ESP::Stat.latest_for_teams
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Stat:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stats"...>
stats.count
#=> 20
stats.first.total
#=> 2141

A successful call to this API returns all the stats for the most recent report of each team accessible by the given API key.

HTTP Request

GET https://api.evident.io/api/v2/stats/latest_for_teams

Region Stats

Attributes

Stats include fields for each combination of time period, status, and signature risk level.

Attribute Type
new_1h_high_pass Integer
new_1d_high_pass Integer
new_1w_high_pass Integer
old_high_pass Integer
new_1h_high_fail Integer
new_1d_high_fail Integer
new_1w_high_fail Integer
old_high_fail Integer
new_1h_high_warn Integer
new_1d_high_warn Integer
new_1w_high_warn Integer
old_high_warn Integer
new_1h_high_error Integer
new_1d_high_error Integer
new_1w_high_error Integer
old_high_error Integer
new_1h_medium_pass Integer
new_1d_medium_pass Integer
new_1w_medium_pass Integer
old_medium_pass Integer
new_1h_medium_fail Integer
new_1d_medium_fail Integer
new_1w_medium_fail Integer
old_medium_fail Integer
new_1h_medium_warn Integer
new_1d_medium_warn Integer
new_1w_medium_warn Integer
old_medium_warn Integer
new_1h_medium_error Integer
new_1d_medium_error Integer
new_1w_medium_error Integer
old_medium_error Integer
new_1h_low_pass Integer
new_1d_low_pass Integer
new_1w_low_pass Integer
old_low_pass Integer
new_1h_low_fail Integer
new_1d_low_fail Integer
new_1w_low_fail Integer
old_low_fail Integer
new_1h_low_warn Integer
new_1d_low_warn Integer
new_1w_low_warn Integer
old_low_warn Integer
new_1h_low_error Integer
new_1d_low_error Integer
new_1w_low_error Integer
old_low_error Integer
suppressed_high_pass Integer
suppressed_high_fail Integer
suppressed_high_warn Integer
suppressed_high_error Integer
suppressed_medium_pass Integer
suppressed_medium_fail Integer
suppressed_medium_warn Integer
suppressed_medium_error Integer
suppressed_low_pass Integer
suppressed_low_fail Integer
suppressed_low_warn Integer
suppressed_low_error Integer
new_1h_high_info Integer
new_1d_high_info Integer
new_1w_high_info Integer
old_high_info Integer
new_1h_medium_info Integer
new_1d_medium_info Integer
new_1w_medium_info Integer
old_medium_info Integer
new_1h_low_info Integer
new_1d_low_info Integer
new_1w_low_info Integer
old_low_info Integer
suppressed_high_info Integer
suppressed_medium_info Integer
suppressed_low_info Integer

Time Periods

Period Description
new_1h Count of alerts new in the last hour relative to the report created time.
new_1d Count of alerts new in the last day relative to the report created time. This count includes the alerts counted in the last hour.
new_1w Count of alerts new in the last hour relative to the report created time. This count includes the alerts counted in the last hour/day.
old Count of alerts older than 1 week relative to the report created time.

Relationships

Relation Includable n Note
region Yes one

List

 {
   "data": [
   {
     "id":            "1",
     "type":          "stat_regions",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
            "region": {
              "links": {
                "related": "https://api.evident.io/api/v2/regions/1.json"
              }
            }
          }
   }
   ],
   "links": {}
 }

stats = ESP::StatRegion.for_stat(54)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::StatRegion:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stat_regions"...>
stats.count
#=> 10
stats.first.total
#=> 2141

A successful call to this API returns all the stats of all the regions for a report identified by the stat_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.

HTTP Request

GET https://api.evident.io/api/v2/stats/<STAT_ID>/regions

Request Parameters

Parameter Required Description
stat_id Yes The ID of the stat to retrieve region stats for

Service Stats

Attributes

Stats include fields for each combination of time period, status, and signature risk level.

Attribute Type
new_1h_high_pass Integer
new_1d_high_pass Integer
new_1w_high_pass Integer
old_high_pass Integer
new_1h_high_fail Integer
new_1d_high_fail Integer
new_1w_high_fail Integer
old_high_fail Integer
new_1h_high_warn Integer
new_1d_high_warn Integer
new_1w_high_warn Integer
old_high_warn Integer
new_1h_high_error Integer
new_1d_high_error Integer
new_1w_high_error Integer
old_high_error Integer
new_1h_medium_pass Integer
new_1d_medium_pass Integer
new_1w_medium_pass Integer
old_medium_pass Integer
new_1h_medium_fail Integer
new_1d_medium_fail Integer
new_1w_medium_fail Integer
old_medium_fail Integer
new_1h_medium_warn Integer
new_1d_medium_warn Integer
new_1w_medium_warn Integer
old_medium_warn Integer
new_1h_medium_error Integer
new_1d_medium_error Integer
new_1w_medium_error Integer
old_medium_error Integer
new_1h_low_pass Integer
new_1d_low_pass Integer
new_1w_low_pass Integer
old_low_pass Integer
new_1h_low_fail Integer
new_1d_low_fail Integer
new_1w_low_fail Integer
old_low_fail Integer
new_1h_low_warn Integer
new_1d_low_warn Integer
new_1w_low_warn Integer
old_low_warn Integer
new_1h_low_error Integer
new_1d_low_error Integer
new_1w_low_error Integer
old_low_error Integer
suppressed_high_pass Integer
suppressed_high_fail Integer
suppressed_high_warn Integer
suppressed_high_error Integer
suppressed_medium_pass Integer
suppressed_medium_fail Integer
suppressed_medium_warn Integer
suppressed_medium_error Integer
suppressed_low_pass Integer
suppressed_low_fail Integer
suppressed_low_warn Integer
suppressed_low_error Integer
new_1h_high_info Integer
new_1d_high_info Integer
new_1w_high_info Integer
old_high_info Integer
new_1h_medium_info Integer
new_1d_medium_info Integer
new_1w_medium_info Integer
old_medium_info Integer
new_1h_low_info Integer
new_1d_low_info Integer
new_1w_low_info Integer
old_low_info Integer
suppressed_high_info Integer
suppressed_medium_info Integer
suppressed_low_info Integer

Time Periods

Period Description
new_1h Count of alerts new in the last hour relative to the report created time.
new_1d Count of alerts new in the last day relative to the report created time. This count includes the alerts counted in the last hour.
new_1w Count of alerts new in the last hour relative to the report created time. This count includes the alerts counted in the last hour/day.
old Count of alerts older than 1 week relative to the report created time.

Relationships

Relation Includable n Note
service Yes one

List

 {
   "data": [
   {
     "id":            "1",
     "type":          "stat_services",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
            "service": {
              "links": {
                "related": "https://api.evident.io/api/v2/services/1.json"
              }
            }
          }
   }
   ],
   "links": {}
 }

stats = ESP::StatService.for_stat(54)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::StatService:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stat_services"...>
stats.count
#=> 10
stats.first.total
#=> 2141

A successful call to this API returns all the stats of all the services for a report identified by the stat_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.

HTTP Request

GET https://api.evident.io/api/v2/stats/<STAT_ID>/services

Request Parameters

Parameter Required Description
stat_id Yes The ID of the stat to retrieve service stats for

Signature Stats

Attributes

Stats include fields for each combination of time period and status.

Attribute Type Description
new_1h_pass Integer
new_1d_pass Integer
new_1w_pass Integer
old_pass Integer
new_1h_fail Integer
new_1d_fail Integer
new_1w_fail Integer
old_fail Integer
new_1h_warn Integer
new_1d_warn Integer
new_1w_warn Integer
old_warn Integer
new_1h_error Integer
new_1d_error Integer
new_1w_error Integer
old_error Integer
suppressed_pass Integer
suppressed_fail Integer
suppressed_warn Integer
suppressed_error Integer
new_1h_info Integer
new_1d_info Integer
new_1w_info Integer
old_info Integer
suppressed_info Integer

Time Periods

Period Description
new_1h Count of alerts new in the last hour relative to the report created time.
new_1d Count of alerts new in the last day relative to the report created time. This count includes the alerts counted in the last hour.
new_1w Count of alerts new in the last hour relative to the report created time. This count includes the alerts counted in the last hour/day.
old Count of alerts older than 1 week relative to the report created time.

Relationships

Relation Includable n Note
signature Yes one

List

 {
   "data": [
   {
     "id":            "1",
     "type":          "stat_signatures",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
            "signature": {
              "links": {
                "related": "https://api.evident.io/api/v2/signatures/1.json"
              }
            }
          }
   }
   ],
   "links": {}
 }

stats = ESP::StatSignature.for_stat(54)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::StatSignature:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stat_signatures"...>
stats.count
#=> 10
stats.first.total
#=> 2141

A successful call to this API returns all the stats of all the signatures for a report identified by the stat_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all signatures for the selected hour.

HTTP Request

GET https://api.evident.io/api/v2/stats/<STAT_ID>/signatures

Request Parameters

Parameter Required Description
stat_id Yes The ID of the stat to retrieve signature stats for

Custom Signature Stats

Attributes

Stats include fields for each combination of time period and status.

Attribute Type Description
new_1h_pass Integer
new_1d_pass Integer
new_1w_pass Integer
old_pass Integer
new_1h_fail Integer
new_1d_fail Integer
new_1w_fail Integer
old_fail Integer
new_1h_warn Integer
new_1d_warn Integer
new_1w_warn Integer
old_warn Integer
new_1h_error Integer
new_1d_error Integer
new_1w_error Integer
old_error Integer
suppressed_pass Integer
suppressed_fail Integer
suppressed_warn Integer
suppressed_error Integer
new_1h_info Integer
new_1d_info Integer
new_1w_info Integer
old_info Integer
suppressed_info Integer

Time Periods

Period Description
new_1h Count of alerts new in the last hour relative to the report created time.
new_1d Count of alerts new in the last day relative to the report created time. This count includes the alerts counted in the last hour.
new_1w Count of alerts new in the last hour relative to the report created time. This count includes the alerts counted in the last hour/day.
old Count of alerts older than 1 week relative to the report created time.

Relationships

Relation Includable n Note
custom_signature Yes one

List

 {
   "data": [
   {
     "id":            "1",
     "type":          "stat_custom_signatures",
     "attributes":    {
       "new_1h_high_pass":        1,
       "new_1d_high_pass":        4,
       "new_1w_high_pass":        3,
       "old_high_pass":           1,
       "new_1h_high_fail":        2,
       "new_1d_high_fail":        1,
       "new_1w_high_fail":        4,
       "old_high_fail":           0,
       "new_1h_high_warn":        3,
       "new_1d_high_warn":        1,
       "new_1w_high_warn":        2,
       "old_high_warn":           2,
       "new_1h_high_error":       0,
       "new_1d_high_error":       3,
       "new_1w_high_error":       1,
       "old_high_error":          1,
       "new_1h_medium_pass":      2,
       "new_1d_medium_pass":      4,
       "new_1w_medium_pass":      4,
       "old_medium_pass":         3,
       "new_1h_medium_fail":      1,
       "new_1d_medium_fail":      2,
       "new_1w_medium_fail":      1,
       "old_medium_fail":         0,
       "new_1h_medium_warn":      2,
       "new_1d_medium_warn":      3,
       "new_1w_medium_warn":      2,
       "old_medium_warn":         1,
       "new_1h_medium_error":     3,
       "new_1d_medium_error":     2,
       "new_1w_medium_error":     2,
       "old_medium_error":        2,
       "new_1h_low_pass":         4,
       "new_1d_low_pass":         1,
       "new_1w_low_pass":         1,
       "old_low_pass":            0,
       "new_1h_low_fail":         1,
       "new_1d_low_fail":         4,
       "new_1w_low_fail":         1,
       "old_low_fail":            0,
       "new_1h_low_warn":         3,
       "new_1d_low_warn":         3,
       "new_1w_low_warn":         4,
       "old_low_warn":            2,
       "new_1h_low_error":        2,
       "new_1d_low_error":        4,
       "new_1w_low_error":        1,
       "old_low_error":           4,
       "suppressed_high_pass":    4,
       "suppressed_high_fail":    3,
       "suppressed_high_warn":    0,
       "suppressed_high_error":   4,
       "suppressed_medium_pass":  2,
       "suppressed_medium_fail":  0,
       "suppressed_medium_warn":  1,
       "suppressed_medium_error": 2,
       "suppressed_low_pass":     3,
       "suppressed_low_fail":     4,
       "suppressed_low_warn":     0,
       "suppressed_low_error":    4,
       "new_1h_high_info":        1,
       "new_1d_high_info":        0,
       "new_1w_high_info":        0,
       "old_high_info":           2,
       "new_1h_medium_info":      0,
       "new_1d_medium_info":      1,
       "new_1w_medium_info":      3,
       "old_medium_info":         4,
       "new_1h_low_info":         2,
       "new_1d_low_info":         1,
       "new_1w_low_info":         0,
       "old_low_info":            3,
       "suppressed_high_info":    2,
       "suppressed_medium_info":  2,
       "suppressed_low_info":     3
     },
     "relationships": {
            "custom_signature": {
              "links": {
                "related": "https://api.evident.io/api/v2/custom_signatures/1.json"
              }
            }
          }
   }
   ],
   "links": {}
 }

stats = ESP::StatCustomSignature.for_stat(54)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::StatCustomSignature:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"stat_custom_signatures"...>
stats.count
#=> 10
stats.first.total
#=> 2141

A successful call to this API returns all the stats of all the custom signatures for a report identified by the stat_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all custom_signatures for the selected hour.

HTTP Request

GET https://api.evident.io/api/v2/stats/<STAT_ID>/custom_signatures

Request Parameters

Parameter Required Description
stat_id Yes The ID of the stat to retrieve custom_signature stats for

Sub Organizations

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
name String Name of the Sub-Organization Yes Yes Yes
created_at String ISO 8601 timestamp when the resource was created No No Yes
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
external_accounts Yes many No
organization Yes one Yes See Organization Attributes for searchable attributes.
teams Yes many No

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "sub_organizations",
      "attributes": {
        "created_at": "2015-08-14T05:03:10.000Z",
        "name": "Default Sub Organization",
        "updated_at": "2015-08-27T14:12:44.000Z"
      },
      "relationships": {
        "external_accounts": {
          "links": {
            "related": "http://test.host/api/v2/external_accounts.json?filter%5Bsub_organization_id_eq%5D=1"
          }
        },
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "teams": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bsub_organization_id_eq%5D=1"
          }
        }
      }
    }
  ],
  "links": {}
}

sub_organizations = ESP::SubOrganization.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::SubOrganization:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"sub_organizations"...>
sub_organizations.count
#=> 20
sub_organizations.first.name
#=> "Sub Organization Name"

A successful call to this API returns a paginated list of sub organizations.

HTTP Request

GET https://api.evident.io/api/v2/sub_organizations

Show

{
  "data": {
    "id": "1",
    "type": "sub_organizations",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Default Sub Organization",
      "updated_at": "2015-08-27T14:12:44.000Z"
    },
    "relationships": {
      "external_accounts": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts.json?filter%5Bsub_organization_id_eq%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bsub_organization_id_eq%5D=1"
        }
      }
    }
  }
}

sub_organization = ESP::SubOrganization.find 3
#=> <ESP::SubOrganization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"sub_organizations"...}>
sub_organization.name
#=> "Sub Organization Name"

A successful call to this API returns a specific sub organization identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/sub_organizations/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the sub organization to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "sub_organizations",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Default Sub Organization",
      "updated_at": "2015-08-27T14:12:44.000Z"
    },
    "relationships": {
      "external_accounts": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts.json?filter%5Bsub_organization_id_eq%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bsub_organization_id_eq%5D=1"
        }
      }
    }
  }
}

sub_organization = ESP::SubOrganization.create(name: "Sub Organization Name")
#=> <ESP::SubOrganization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"sub_organizations"...}>
sub_organization.id
#=> 3

A successful call to this API creates a new sub organization. The body of the request must contain a json API compliant hash of attributes with type sub_organizations. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/sub_organizations

Request Parameters

Parameter Required Description
name Yes The name of the sub organization

Update

{
  "data": {
    "id": "1",
    "type": "sub_organizations",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Default Sub Organization",
      "updated_at": "2015-08-27T14:12:44.000Z"
    },
    "relationships": {
      "external_accounts": {
        "links": {
          "related": "http://test.host/api/v2/external_accounts.json?filter%5Bsub_organization_id_eq%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bsub_organization_id_eq%5D=1"
        }
      }
    }
  }
}

sub_organization = ESP::SubOrganization.find(3)
#=> <ESP::SubOrganization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"sub_organizations"...}>
sub_organization.name = "Name Changed"
sub_organization.save
#=> <ESP::SubOrganization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"sub_organizations", name=>"Name Changed"...}>

A successful call to this API updates a specific sub organization identified by the id parameter. The body of the request must contain a json API compliant hash of attributes with type sub_organizations. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/sub_organizations/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the sub organization to update
name The new name of the sub organization

Destroy

{
  "success": "Sub Organization Name has been destroyed"
}
sub_organization = ESP::SubOrganization.find(3)
#=> <ESP::SubOrganization:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"sub_organizations"...}>
sub_organization.destroy
sub_organization = ESP::SubOrganization.find(3)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find SubOrganization.

A successful call to this API destroys a specific sub organization identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/sub_organizations/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the sub organization to destroy

Suppressions

Suppressions Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created No No Yes
reason String The reason for the suppresion
resource String The resource string this suppression will suppress alerts for. Yes Yes No
status String The status of this suppresion
suppression_type String Type of suppression. Possible values are unique_identifiers, regions, and signatures Yes Yes Yes
updated_at String ISO 8601 timestamp when the suppression was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
organization Yes one
created_by Yes one Yes User who created the suppression See User Attributes for searchable attributes.
external_accounts Yes many No External accounts this suppression will suppress alerts for.
regions Yes many Yes Regions this suppression will suppress alerts for. See Region Attributes for searchable attributes.
signatures Yes many Yes Signatures this suppression will suppress alerts for. Will be empty on regions suppressions types. See Signature Attributes for searchable attributes.
custom_signatures Yes many No Custom Signatures this suppression will suppress alerts for. Will be empty on regions suppression types

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "suppressions",
      "attributes": {
        "created_at": "2015-10-23T15:40:17.000Z",
        "reason": "Test",
        "resource": "sg-12345",
        "status": "active",
        "suppression_type": "unique_identifiers",
        "updated_at": "2015-10-23T15:40:17.000Z"
      },
      "relationships": {
        "created_by": {
          "links": {
            "related": "https://api.evident.io/api/v2/users/1.json"
          }
        },
        "custom_signatures": {
          "links": {
            "related": null
          }
        },
        "external_accounts": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
          }
        },
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "regions": {
          "links": {
            "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
          }
        },
        "signatures": {
          "links": {
            "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
          }
        }
      }
    }
  ],
  "links": {}
}

suppressions = ESP::Suppression.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Suppression:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"suppressions"...>
suppressions.count
#=> 20
suppressions.first.status
#=> "active"

A successful call to this API returns a paginated list of suppressions.

HTTP Request

GET https://api.evident.io/api/v2/suppressions

Show

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression.find 3
#=> <ESP::Suppression:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.status
#=> "active"

A successful call to this API returns a specific suppression identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/suppressions/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the suppression to retrieve

Deactivate

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression.find 3
#=> <ESP::Suppression:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.deactivate!
suppression.status
#=> "inactive"

A successful call to this API will deactivate a suppression identified by the id parameter.

HTTP Request

PATCH https://api.evident.io/api/v2/suppressions/<ID>/deactivate

Request Parameters

Parameter Required Description
id Yes The ID of the suppression to deactivate

Create Signature Suppression

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression::Signature.create(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
#=> <ESP::Suppression::Signature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.id
#=> 3

A successful call to this API creates a new signature suppression for the supplied signature_ids or custom_signature_ids. The body of the request must contain a json API compliant hash of attributes with type suppression/signatures. see Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/suppressions/signatures

Request Parameters

Parameter Required Description
signature_ids Conditional An array of signatures identified by signature_id to suppress. Required if custom_signature_ids is blank.
custom_signature_ids Conditional An array of custom signatures identified by custom_signature_id to suppress. Required if signature_ids is blank.
regions Yes An array of region names to suppress.
external_account_ids Yes An Array of the external accounts identified by external_account_id to suppress the signature or custom signature on.
reason Yes The reason for creating the suppression.
resource String The resource string this suppression will suppress alerts for.

Create Signature Suppression by Alert

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression::Signature.create(alert_id: 5, reason: 'My very good reason for creating this suppression')
#=> <ESP::Suppression::Signature:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.id
#=> 3

A successful call to this API creates a new signature suppression based on the supplied alert_id. The body of the request must contain a json api compliant hash of attributes with type suppression/signatures. see Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/suppressions/alert/<ALERT_ID>/signatures

Request Parameters

Parameter Required Description
alert_id Yes The id for the alert you want to create a suppression for.
reason Yes The reason for creating the suppression.

Create Region Suppression

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression::Region.create(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
#=> <ESP::Suppression::Region:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.id
#=> 3

A successful call to this API creates a new region suppression for the supplied regions . The body of the request must contain a json api compliant hash of attributes with type suppression/regions. see Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/suppressions/regions

Request Parameters

Parameter Required Description
regions Yes An array of region names to suppress.
external_account_ids Yes An Array of the external accounts identified by external_account_id to suppress the signature or custom signature on.
reason Yes The reason for creating the suppression.
resource String The resource string this suppression will suppress alerts for.

Create Region Suppression by Alert

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression::Region.create(alert_id: 5, reason: 'My very good reason for creating this suppression')
#=> <ESP::Suppression::Region:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.id
#=> 3

A successful call to this API creates a new region suppression based on the supplied alert_id. The body of the request must contain a json api compliant hash of attributes with type suppression/signatures. see Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/suppressions/alert/<ALERT_ID>/regions

Request Parameters

Parameter Required Description
alert_id Yes The id for the alert you want to create a suppression for.
reason Yes The reason for creating the suppression.

Create Unique Identifier Suppression by Alert

{
  "data": {
    "id": "1",
    "type": "suppressions",
    "attributes": {
      "created_at": "2015-10-23T15:40:17.000Z",
      "reason": "Test",
      "resource": "sg-12345",
      "status": "active",
      "suppression_type": "unique_identifiers",
      "updated_at": "2015-10-23T15:40:17.000Z"
    },
    "relationships": {
      "created_by": {
        "links": {
          "related": "https://api.evident.io/api/v2/users/1.json"
        }
      },
      "custom_signatures": {
        "links": {
          "related": null
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "regions": {
        "links": {
          "related": "https://api.evident.io/api/v2/regions.json?filter%5Bid_in%5D%5B%5D=1"
        }
      },
      "signatures": {
        "data": [
          {
            "id": "59",
            "type": "signatures"
          }
        ],
        "links": {
          "related": "https://api.evident.io/api/v2/signatures.json?filter%5Bid_in%5D%5B%5D=1"
        }
      }
    }
  }
}

suppression = ESP::Suppression::UniqueIdentifier.create(alert_id: 5, reason: 'My very good reason for creating this suppression')
#=> <ESP::Suppression::UniqueIdentifier:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"suppressions"...}>
suppression.id
#=> 3

A successful call to this API creates a new unique identifier suppression based on the supplied alert_id. The body of the request must contain a json api compliant hash of attributes with type suppression/signatures. see Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/suppressions/alert/<ALERT_ID>/unique_identifiers

Request Parameters

Parameter Required Description
alert_id Yes The id for the alert you want to create a suppression for.
reason Yes The reason for creating the suppression.

Tags

Attributes

Attribute Type Description
key String Tag key name in AWS
value String Tag value in AWS
created_at String ISO 8601 timestamp when the resource was created
updated_at String ISO 8601 timestamp when the resource was last updated

List

{
  "data": [
    {
      "id": "1",
      "type": "tags",
      "attributes": {
        "created_at": "2015-10-20T21:10:35.000Z",
        "key": "Name",
        "updated_at": "2015-10-20T21:10:35.000Z",
        "value": "Demo Instance"
      }
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/alerts/1/tags?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/alerts/1/tags?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/alerts/1/tags?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

tags = ESP::Tag.for_alert(1194)
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Tag:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"tags"...>
tags.count
#=> 20
tags.first.key
#=> "aws:cloudformation:logical-id"

A successful call to this API returns a paginated list of supported AWS tags for the given alert id.

HTTP Request

GET https://api.evident.io/api/v2/alerts/<ALERT_ID>/tags

Request Parameters

Parameter Required Description
alert_id Yes The ID of the alert to list tags for

Show

{
  "data": {
    "id": "1",
    "type": "tags",
    "attributes": {
      "created_at": "2015-10-20T21:10:35.000Z",
      "key": "Name",
      "updated_at": "2015-10-20T21:10:35.000Z",
      "value": "Demo Instance"
    }
  }
}

tag = ESP::Tag.find 3
#=> <ESP::Tag:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"tags"...}>
tag.key
#=> "aws:cloudformation:logical-id"

A successful call to this API returns a single tag.

HTTP Request

GET https://api.evident.io/api/v2/tags/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the tag to retrieve

Teams

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
name String Name of the Team Yes Yes No
created_at String ISO 8601 timestamp when the resource was created No No Yes
updated_at String ISO 8601 timestamp when the resource was last updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
custom_signatures Yes many Yes
external_accounts Yes many No
organization Yes one Yes See Organization Attributes for searchable attributes.
sub_organization Yes one Yes See Sub Organization Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "attributes": {
        "created_at": "2015-10-01T02:14:04.000Z",
        "name": "Default Team",
        "updated_at": "2015-10-01T02:14:04.000Z"
      },
      "id": "1",
      "relationships": {
        "custom_signatures": {
          "links": {
            "related": "http://test.host/api/v2/custom_signatures.json?filter%5Bteams_id_eq%5D=1"
          }
        },
        "external_accounts": {
          "links": {
            "related": "https://api.evident.io/api/v2/external_accounts.json"
          }
        },
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "sub_organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
          }
        }
      },
      "type": "teams"
    }
  ],
  "links": {
    "last": "https://api.evident.io/api/v2/teams?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://api.evident.io/api/v2/teams?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "self": "https://api.evident.io/api/v2/teams?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

teams = ESP::Team.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::Team:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"teams"...>
teams.count
#=> 20
teams.first.name
#=> "Team Name"

A successful call to this API returns a paginated list of teams associated with the calling user.

HTTP Request

GET https://api.evident.io/api/v2/teams

Show

{
  "data": {
    "id": "1",
    "type": "teams",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Demo Team",
      "updated_at": "2015-09-09T15:12:10.000Z"
    },
    "relationships": {
      "custom_signatures": {
        "links": {
          "related": "http://test.host/api/v2/custom_signatures.json?filter%5Bteams_id_eq%5D=1"
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      }
    }
  }
}

team = ESP::Team.find 3
#=> <ESP::Team:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"teams"...}>
team.name
#=> "Team Name"

You may also use the team object to create a report. See the Report section for more details.

alert.create_report
#=> <ESP::Report:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"reports"...}>
report.status
#=> 'queued'

A successful call to this API returns a single team identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/teams/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the team to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "teams",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Demo Team",
      "updated_at": "2015-09-09T15:12:10.000Z"
    },
    "relationships": {
      "custom_signatures": {
        "links": {
          "related": "http://test.host/api/v2/custom_signatures.json?filter%5Bteams_id_eq%5D=1"
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      }
    }
  }
}

team = ESP::Team.create(name: "Team Name", sub_organization_id: 6)
#=> <ESP::Team:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"teams"...}>
team.id
#=> 3

A successful call to this API updates a single team. The body of the request must contain a json api compliant hash of attributes with type teams. see Request Parameters

HTTP Request

POST https://api.evident.io/api/v2/teams

Request Parameters

Parameter Required Description
id Yes The ID of the team to update
sub_organization_id Yes The ID of the sub organization to attach this team to
name Yes The name of the sub organization

Update

{
  "data": {
    "id": "1",
    "type": "teams",
    "attributes": {
      "created_at": "2015-08-14T05:03:10.000Z",
      "name": "Demo Team",
      "updated_at": "2015-09-09T15:12:10.000Z"
    },
    "relationships": {
      "custom_signatures": {
        "links": {
          "related": "http://test.host/api/v2/custom_signatures.json?filter%5Bteams_id_eq%5D=1"
        }
      },
      "external_accounts": {
        "links": {
          "related": "https://api.evident.io/api/v2/external_accounts.json"
        }
      },
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations/1.json"
        }
      }
    }
  }
}

team = ESP::Team.find(3)
#=> <ESP::Team:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"teams"...}>
team.name = "Name Changed"
team.save
#=> <ESP::Team:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"teams", name=>"Name Changed"...}>

A successful call to this API updates a single team. The body of the request must contain a json api compliant hash of attributes with type teams. see Request Parameters

HTTP Request

PATCH https://api.evident.io/api/v2/teams/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the team to update
name Yes The new name of the team

Destroy

{
  "success": "Team Name has been destroyed"
}
team = ESP::Team.find(3)
#=> <ESP::Team:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"teams"...}>
team.destroy
team = ESP::Team.find(3)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find Team.

A successful call to this API destroys a single team identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/teams/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the team to update

Time Zones

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
name String Name of the Time Zone No No No

See Searching Lists and Including Objects for more information.

List

[
  {
    "name": "American Samoa"
  },
  {
    "name": "International Date Line West"
  },
  {
    "name": "Midway Island"
  },
  {
    "name": "Samoa"
  },
  {
    "name": "Hawaii"
  },
  {
    "name": "Alaska"
  },
  {
    "name": "Pacific Time (US & Canada)"
  },
  {
    "name": "Tijuana"
  }
]

A successful call to this API returns a list of time zones.

HTTP Request

GET https://api.evident.io/api/v2/time_zones

Users

Attributes

Attribute Type Description Equality Searchable Matching Searchable Sortable
id Integer Unique ID Yes No No
created_at String ISO 8601 timestamp when the resource was created
email String The email of the user Yes Yes Yes
time_zone String The time-zone of the user
first_name String The first name of the user
last_name String The last name of the user
phone Object The phone number associated with the user
mfa_enabled Object
disable_daily_emails Object This option toggles the daily emails option
locked Object
locked_at Object
updated_at String ISO 8601 timestamp when the resource was updated No No Yes

See Searching Lists and Including Objects for more information.

Relationships

Relation Includable n Searchable Note
organization Yes one Yes See Organization Attributes for searchable attributes.
sub_organizations Yes many Yes See Sub Organization Attributes for searchable attributes.
teams Yes many Yes See Team Attributes for searchable attributes.
role Yes one Yes See Role Attributes for searchable attributes.

See Searching on Relationships for more information.

List

{
  "data": [
    {
      "id": "1",
      "type": "users",
      "attributes": {
        "created_at": "2015-08-14T05:03:23.000Z",
        "disable_daily_emails": false,
        "email": "user@email.com",
        "first_name": "John",
        "last_name": "Doe",
        "locked": false,
        "locked_at": null,
        "mfa_enabled": false,
        "phone": "8134040464",
        "time_zone": "Eastern Time (US & Canada)",
        "updated_at": "2015-10-16T00:04:55.000Z"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "https://api.evident.io/api/v2/organizations/1.json"
          }
        },
        "sub_organizations": {
          "links": {
            "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
          }
        },
        "teams": {
          "links": {
            "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
          }
        },
        "role": {
          "links": {
            "related": "https://api.evident.io/api/v2/roles/2.json"
          }
        }
      }
    }
  ],
  "links": {}
}

users = ESP::User.all
#=> #<ActiveResource::PaginatedCollection:0x007fb82b0b54b0 @elements=[#<ESP::User:0x007fb82b0b1fb8 @attributes={"id"=>"1", "type"=>"users"...>
users.count
#=> 6
users.first.email
#=> "someone@somewhere.com"

A successful call to this API returns a paginated list of users available to the caller.

HTTP Request

GET https://api.evident.io/api/v2/users

Show

{
  "data": {
    "id": "1",
    "type": "users",
    "attributes": {
      "created_at": "2015-08-14T05:03:23.000Z",
      "disable_daily_emails": false,
      "email": "user@email.com",
      "first_name": "John",
      "last_name": "Doe",
      "locked": false,
      "locked_at": null,
      "mfa_enabled": false,
      "phone": "8134040464",
      "time_zone": "Eastern Time (US & Canada)",
      "updated_at": "2015-10-16T00:04:55.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organizations": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "role": {
        "links": {
          "related": "https://api.evident.io/api/v2/roles/2.json"
        }
      }
    }
  }
}

user = ESP::User.find 3
#=> <ESP::User:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"users"...}>
user.email
#=> "someone@somewhere.com"

A successful call to this API returns a specific user identified by the id parameter.

HTTP Request

GET https://api.evident.io/api/v2/users/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the user to retrieve

Create

{
  "data": {
    "id": "1",
    "type": "users",
    "attributes": {
      "created_at": "2015-08-14T05:03:23.000Z",
      "disable_daily_emails": false,
      "email": "user@email.com",
      "first_name": "John",
      "last_name": "Doe",
      "locked": false,
      "locked_at": null,
      "mfa_enabled": false,
      "phone": "8134040464",
      "time_zone": "Eastern Time (US & Canada)",
      "updated_at": "2015-10-16T00:04:55.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organizations": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "role": {
        "links": {
          "related": "https://api.evident.io/api/v2/roles/2.json"
        }
      }
    }
  }
}

user = ESP::User.create(first_name: "Bob", last_name: "Belcher", email: "bobsburgers@email.com")
#=> <ESP::User:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"users"...}>
user.id
#=> 3

A successful call to this API creates a new user. The body of the request must contain a json api compliant hash of attributes with type users. See Request Parameters for more information.

HTTP Request

POST https://api.evident.io/api/v2/users

Request Parameters

Parameter Required Description
first_name Yes The first name of the user
last_name Yes The last name of the user
email Yes The email of the user
role_id No The role of the user
sub_organization_ids No A list of sub organization IDs that the user should have access to.
team_ids No A list of team IDs that the user should have access to.
disable_daily_emails No Whether the daily emails should be turned off or not. Valid values are true/false.
phone No The phone number of the user
time_zone No The time zone of the user. See Time Zones for a list of valid time zones.

Update

{
  "data": {
    "id": "1",
    "type": "users",
    "attributes": {
      "created_at": "2015-08-14T05:03:23.000Z",
      "disable_daily_emails": false,
      "email": "user@email.com",
      "first_name": "John",
      "last_name": "Doe",
      "locked": false,
      "locked_at": null,
      "mfa_enabled": false,
      "phone": "8134040464",
      "time_zone": "Eastern Time (US & Canada)",
      "updated_at": "2015-10-16T00:04:55.000Z"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "https://api.evident.io/api/v2/organizations/1.json"
        }
      },
      "sub_organizations": {
        "links": {
          "related": "https://api.evident.io/api/v2/sub_organizations.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "teams": {
        "links": {
          "related": "https://api.evident.io/api/v2/teams.json?filter%5Bq%5D%5Bid_in%5D%5B%5D=1"
        }
      },
      "role": {
        "links": {
          "related": "https://api.evident.io/api/v2/roles/2.json"
        }
      }
    }
  }
}

user = ESP::User.find(3)
#=> <ESP::User:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"users"...}>
user.first_name = "Bob"
user.save
#=> <ESP::User:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"users", first_name=>"Bob"...}>

A successful call to this API updates a specific user identified by the id parameter. The body of the request must contain a json api compliant hash of attributes with type users. See Request Parameters for more information.

HTTP Request

PATCH https://api.evident.io/api/v2/users/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the user to update
first_name No The first name of the user
last_name No The last name of the user
email No The email of the user
role_id No The role of the user
sub_organization_ids No A list of sub organization IDs that the user should have access to.
team_ids No A list of team IDs that the user should have access to.
disable_daily_emails No Whether the daily emails should be turned off or not. Valid values are true/false.
phone No The phone number of the user
time_zone No The time zone of the user. See Time Zones for a list of valid time zones.

Destroy

{
  "success": "test@email.com has been destroyed"
}
user = ESP::User.find(3)
#=> <ESP::User:0x007fb82acd3298 @attributes={"id"=>"3", "type"=>"users"...}>
user.destroy
user = ESP::User.find(3)
#=> ActiveResource::ResourceNotFound: Failed.  Response code = 404.  Response message = Couldn't find User.

A successful call to this API destroys a specific user identified by the id parameter.

HTTP Request

DELETE https://api.evident.io/api/v2/users/<ID>

Request Parameters

Parameter Required Description
id Yes The ID of the user to destroy