NAV

Overview

Evident Security Platform (ESP) is designed to work in tandem with Amazon Web Services (AWS) to help businesses of all sizes detect and manage security risks of their entire AWS infrastructure via automated threat detection, incident response, and compliance through continuous monitoring and analysis of all AWS configuration and usage metadata.

ESP Dashboard

Signature Definition

A signature is an automated validation of best security practices against the resources on your AWS account. Multiple alerts may be generated from a single signature if the validation fails across multiple resources.

Custom Signature Definition

A custom signature is an automated validation against a defined non­standard best practice. An alert is generated when this validation fails or the signature judges that there is a potential security risk. A custom signature is used when the default best practice protocols are insufficient for a specific need. For example, if you wanted to ensure that each of your EC2 instances was tagged with information for your accounting department, you could write a custom signature to do this. For information on creating a custom signature, read our custom signature wiki.

Alert Definition

An alert is a potential risk identified by either a signature or a custom signature and collected in a report. ESP continually scans all of your assigned AWS business resources and collects all alerts into an easy­-to­-read aggregated report. This allows you and your security team to review all available information about your assets and to make an informed decision about the necessary steps to them as needed.

Alert Status

ESP prioritizes every alert generated with a status to quickly convey information about it:

Alert Severity

Every alert generated is placed into a severity level category designed to help you prioritize resources to address identified risks.

Each alert is tagged with a specific severity status indicating:

Requirements

Browser Support

Evident Security Platform supports the following browsers:

We support the latest version of Google Chrome (which automatically updates whenever it detects that a new version of the browser is available). We support the current and previous major releases of Firefox®, Safari®, and Microsoft® Edge™ on a rolling basis. Each time a new version is released, we begin supporting that version and stop supporting the third most recent version.

Security and Compliance

For questions about Evident.io's security and compliance, please send your VRA to security@evident.io.

Updates

Customer Communication: Evident Security Platform Updates


May 17, 2017

The following updates will take effect in the ESP Management Console on 05/17/2017:

Enhancements

Bug Fixes


May 10, 2017

The following updates will take effect in the ESP Management Console on 05/10/2017:

Bug Fixes


April 26, 2017

The following updates will take effect in the ESP Management Console on 04/26/2017:

Enhancements

Bug Fixes


April 20, 2017

The following updates will take effect in the ESP Management Console on 04/20/2017:

Bug Fixes


April 12, 2017

The following updates will take effect in the ESP Management Console on 04/12/2017:

Enhancements

Bug Fixes


April 5, 2017

The following updates will take effect in the ESP Management Console on 04/05/2017:

Enhancements

Bug Fixes


March 22, 2017

The following updates will take effect in the ESP Management Console on 03/22/2017:

Enhancements

Bug Fixes


March 15, 2017

The following updates will take effect in the ESP Management Console on 03/15/2017:

Bug Fixes


March 7, 2017

The following updates will take effect in the ESP Management Console on 03/07/2017:

Enhancements

Bug Fixes


March 1, 2017

The following updates will take effect in the ESP Management Console on 03/01/2017:

Bug Fixes


February 15, 2017

The following updates will take effect in the ESP Management Console on 02/15/2017:

Bug Fixes


February 1, 2017

The following updates will take effect in the ESP Management Console on 02/01/2017:

Enhancements

Bug Fixes


January 11, 2017

The following updates will take effect in the ESP Management Console on 01/11/2017:

Enhancements

Bug Fixes


To view more updates, please visit the Updates Archive.

Onboarding

To onboard with the Evident Security Platform service, complete the following steps.

Step 1: Create an Account with Evident Security Platform

  1. Go to the Evident Security Platform (https://esp.evident.io).
  2. Click Sign up.

    Set Up Your Evident.io Account

  3. Enter the appropriate information into the appropriate fields.
  4. Click Sign Up.

Step 2: Create Role and Cross-Account Access (AWS Identity / ARN):

To sync your accounts:

  1. Log into your Amazon Management Console (https://console.aws.amazon.com/ ).
  2. On the AWS Services page, select the IAM service.
  3. Select Roles on the left menu.
  4. Click Create New Role.
  5. Select the radio button Role for Cross-Account Access.
  6. Select Allows IAM users from a 3rd party AWS account to access this account.
  7. Enter the Account ID of our service.  This number will be provided by ESP.
  8. Enter the External ID field of the AWS dialog box. The External ID is dynamically generated just for you. Refreshing this page will generate a new External ID.
  9. Verify that Require MFA is not enabled. Click Next Step.
  10. Select the SecurityAudit policy from Amazon's pre-configured policies. Click Next Step.
  11. ESP recommends that you name the role Evident-Service-Role. Click Create Role.
  12. Click the Role. Copy the Role ARN string.
  13. Return to ESP and paste the Role ARN into the ARN field.
  14. Enter the appropriate information into the remaining fields.
  15. Click Submit.

Step 3: Connect Your AWS Account to ESP

Connect Your AWS Account to ESP

  1. Enter the Amazon Resource Name (ARN) for your Amazon Web Service into the appropriate field.
  2. Enter the External ID into the appropriate field.
  3. Enter a name for this resource into the appropriate field.
  4. Click Submit to continue. You will receive a notification that ESP is building your account and populating it with data.


PSaaS

Welcome to the PSaaS Documentation Library.

The Evident Security Platform (ESP) Private SaaS 100 enables organizations to continuously monitor both security and compliance across their entire AWS infrastructure (up to 100 accounts) from within their own VPC. ESP combines the detection and analysis of misconfigurations, vulnerabilities, and risk with user attribution, guided remediation, and audit capabilities to meet compliance requirements. The highly customizable solution enables DevOps and SecOps to implement and manage security policies, create custom signatures, and build auto-remediation into their workflows, making response near real-time. The Private SaaS Edition is for organizations that want to guarantee data privacy and sovereignty by running in their own dedicated environment.

PSaaS CFN Template Upload

  1. Upload the template through the CloudFormation console.
  2. Under the Instance Configuration section, select an existing EC2 KeyPair from the dropdown menu and enter a cidr block to SSHLocation with the format x.x.x.x/xx.

  3. Under the Instance Type section, select your prefered instance size for each stack. If you are unsure of your requirements, choose the default options.

  4. Under the ELB Configuration section, enter the arn of an existing ssl certificate and a cird block to the WebLocation with the format x.x.x.x/xx.

  5. Under the Network Configuration section, select two different availability zones from the dropdown menus. The VPC and subnet cidr blocks can be altered if desired or you already have an existing VPC with the same ip range. Ensure subnet cidr blocks are within the range of the VCP cidr block.

  6. Under the Default Database Credentials section, edit the default mysql database name and superuser if you desire and enter a password. Note: The password must be at least 8 characters long as required by RDS.

  7. Click Next.
  8. On the next screen, Options, there is no need to add any tags, permissions, or advanced data. Click Next to progress to the Review screen.
  9. On the Review page, confirm your options are set as intended.
    Before clicking Create, you MUST select the checkbox [ ] I acknowledge that AWS CloudFormation might create IAM resources., under the Capabilities section.

  10. Click Create to launch the stack. Please ensure that your setup is complete before clicking Create. This process may take up to 30 minutes.

Accessing ESP PSaaS Admin

ESP PSaaS Admin

ESP PSaaS Admin is the hub that allows you to edit information about your individual PSaaS services. You may always find this panel by clicking the Overview Tab.

To access the PSaas Admin panel:

  1. Log into the CloudFormation console.
  2. Select the evident-saas template.
  3. Select the Outputs tab and click the link for the AdminAppELBDNSName.

  4. Login into the ESP PSaaS Admin page using the user name admin and then enter the password based on your instance ID as explained below:
    • If your admin app's instance ID is still using the short AWS instance id, append x before and after the instance id. For example: if your instance id is i-abcde123 then your password is xi-abcde123x.
    • If your admin app's instance ID uses the new AWS instance ID (16 digit ID), the initial password is your instance id.


  5. The URL at the bottom noted at the bottom is your personalized ESP Web URL.


To Create a Backup of Your Settings

Click Backup to create a backup all of your settings.

For more information on creating a snapshot of your database, see AWS: Creating a DB Snapshot

Restarting ESP

When settings are changed, they won’t be applied to the ESP Admin until after ESP is restarted. Click Restart ESP to terminate the web and worker instances. Autoscaling will create new instances with the changes applied.
Note: There is no need to restart during the initial setup process.

ESP PSaaS Settings

The available settings for ESP PSaaS are:

The following PSaaS Settings may be edited on the Admin page or via the ESP Setting pulldown menu.


From Email

From Email is the sender's email. It will appear as the from email address sent from the ESP application. These emails include any automated emails like daily alerts just as one example.

The domain portion of From Email should be the same as your SMTP domain or emails will be blocked by certain email services providers like Gmail.

To edit this setting:

  1. Enter your designated email into the From Email field.
  2. Click Save.
  3. You will need to restart your ESP for this change to take effect.


MySQL

This page allows you to edit your SQL settings.

To edit this setting:

  1. Enter the appropriate information into the following fields:
    1. Pool size is the number of immediately available database connections ready for connecting without initial handshake overheard. They include persistent, framework and standalone types. We recommend this value be 15.
    2. Select a new username that will be used for the ESP Web application will use to connect to the DB. his is the password for ESP web username.
    3. Select a new password for the ESP Web app. This will be used to log into the MySQL database. When updating, leaving this field blank will not remove the password, but entering a value will change the password.
    4. Select a new Super User Password for the newly created MySQL super user. This account is used to create the application user and set its privileges. When updating, leaving this field blank will not remove the password, but entering a value will change the password.
  2. Click Save.


SMTP Email Settings

This page allows you to edit your SMTP Email settings.

To edit this setting:

  1. Enter the appropriate information into the following fields:
    1. SMTP address is the hostname of your mail server that sends out emails. It would be localhost if you have a locally running mail server.
    2. SMTP port is the port number that mail clients like Outlook connect to. The default port is 25.
    3. SMTP authentication is the type of authentication for logging into SMTP on the mail server. It can be plain, login or cram_md5.
    4. SMTP domain is the domain name that emails will be sent from.
    5. SMTP user name is the username for logging into the user's mail account.
    6. SMTP password is the user's password for logging into the mail account.
  2. Click Save.


ESP URL Settings

This page allows you to edit your ESP URL settings.

URL is used internally by ESP Web, among other things, to create proper links in emails. If setting up a DNS endpoint, update this to reflect that. It is important that this is a correct URL. If incorrect, some functionality will be lost.

To edit this setting:

  1. Enter the URL into the ESP URL field.
  2. Click Save.


SNS Region Settings

This page allows you to edit your SNS Region settings.

SNS Region is the region where new Amazon SNS Integrations will be created.

To edit this setting:

  1. Enter the appropriate region into the SNS Region.
  2. Click Save.


SSL Cert

This page allows you to upload your SSL Cert files.

To upload your SSL Certs:

  1. SSL Cert is the actual certificate that your SSL provider issues to you after you've gone through the process. Click Choose File and browse to your SSL Cert.
  2. Key should be the public key generated when you generated your key pair for the SSL signing request. Click Choose File and browse to your Key.
  3. Click Import.

Evident.io Dashboards

Evident.io - Overview

Evident.io - Detailed Risks

ESP SSO Integration

Single Sign-On (SSO) is a session and user authentication service that permits a user to use one set of login credentials (e.g., name and password) to access multiple applications.

Evident.io uses PingOne as our Identity Provider (IdP). You can download our PingOne metadata  and will need you to generate a corresponding SAML 2.0 metadata.xml file or provide similar information about your setup.  We use the user's email address as the common authentication component.

You will need the following information to integrate with Evident via PingOne:

Assertion Consumer Service (ACS) URL (The URL used by PingOne to receive the AuthnResponse from the IdP indicating whether a user has been successfully authenticated for single sign-on.)

https://sso.connect.pingidentity.com/sso/sp/ACS.saml2

PingOne Entity ID / Audience URI (A globally unique name identifying PingOne as a SAML entity. If we are going to set up more than one SSO/SAML, please contact us as we will need to configure unique URIs for you.)

PingConnect

TargetResource / Default Relay State (To do IdP-initiated SSO, the IdP needs to provide a TargetResource value for the single connection.)

https://pingone.com/1.0/a004e86a-202c-46e7-96e7-39d1ca13f453

Verification Certificate (If your IdP doesn’t support uploading the PingOne metadata, you can use our certificate independently.)

pingone-signing-07-21-2017.crt

Name ID Format

EmailAddress

Application Username

Email

Once you have your side configured, please send us your metadata. It may be contained in a SAML 2.0 metadata.xml similar to ours. We need the following information from you:

Entity ID

Uniquely identifies the your IdP to PingOne. This identifier is used in the SAML assertion sent to PingOne by the IdP.

SSO Endpoint

Your endpoint URL IdP to which PingOne sends SAML AuthnRequests.

Verification Certificate

Your IdP public signing certificate used to sign SAML assertions.

Once we receive this information, we will configure our side and reach out to schedule a time to test and confirm that SSO is working properly for you.

User Attribution

The signal to noise can be overwhelming when scanning through a flood of alert data. User Attribution allows you to correlate ESP security alerts directly to AWS CloudTrail events, helping you find the needle in the haystack of data. User Attribution analyzes your events, reduces datasets to that relevant to the specific ESP alert, and summarizes the relevant CloudTrail event fields in ESP alerts.

User attribution identifies the following information for every alert:

User Attribution Workflow

  1. Click Control Panel and then select External Account.
  2. Click User Attribution.
  3. Once User Attribution has been properly turned on, it can take thirty minutes before you start seeing data from Evident.io. Attribution data allows you to quickly identify bad actors and insider threats quickly.
  4. Simply click on the desired alert to access more information.


  5. Review the attribution data to learn everything you need to know to resolve this alert.


  6. Next, you click View Event to study the Event Details, as shown below.

Setup CloudTrail

The first step is to setup a global trail in CloudTrail. This will record changes made by users that we will use to attribute alerts. Follow the steps on the right to setup a new trail.

To setup a new CloudTrail:

  1. Log into your Amazon Management Console (https://console.aws.amazon.com/).
  2. On the AWS Services page, select the Cloudtrail service.
  3. Select Trails on the left menu.
  4. Select Add new trail.
  5. Use the following options below to setup the trail. The names are suggested values.
    • Trail name: Evident-User-Attribution
    • Apply trail to all regions: Yes
    • Create a new S3 bucket: Yes
    • S3 bucket: test1 spaces-u-d.p -- .-evident-user-attribution
  6. Select Advanced to expand the advanced options. Use the following settings.
    • Leave Log file prefix blank.
    • Encrypt log files: Yes
    • Enable log file validation: Yes
    • Send SNS notification for every log file delivery: Yes
    • Create a new SNS topic: Yes
    • SNS topic: Evident-User-Attribution
  7. Click Create.
  8. Select the newly created trail from the trail list.
  9. Make a note of the S3 bucket name.
  10. Find the Management events section and click edit.
  11. Find Read/Write events and ensure it is set to Write-only. Then click Save.

Add Policy to External Account

Next we need to update this external account with the appropriate permissions. This will allow us to verify the cloudtrail is setup properly, as well as read the log files from the S3 bucket.

  1. On the AWS Services page, select the IAM service.
  2. Select Policies on the left menu.
  3. Click Create Policy.
  4. Select Create Your Own Policy.
  5. Name the policy EvidentUserAttribution.
  6. Copy the S3 bucket and SNS Topic ARN from the previous section into the forms below.

  7. image

  8. Next, copy the policy below into the Policy Document field.
  9. {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:Get*",
                    "s3:List*"
                ],
                "Resource": [
                    "arn:aws:s3:::<S3 BUCKET NAME>",
                    "arn:aws:s3:::<S3 BUCKET NAME>/*"
                ]
            },
            {
                "Effect": "Allow",
                "Action": [
                    "cloudtrail:GetEventSelectors"
                ],
                "Resource": [
                     "*"
                ]
             }
        ]
    }
    
  10. When you are finished click Create Policy.
  11. Select Roles on the left menu.
  12. Filter for role Evident-Test-QA-02062017 and select it.
  13. On the Permissions tab, select Attach Policy.
  14. Select the policy you created in Steps 5 to 8. Click Attach Policy.
  15. Click Submit.

Create SNS Subscription

Then we need to create a subscription from your SNS topic to our service.

  1. On the AWS Services page, select the SNS service.
  2. Select Topics on the left menu.
  3. Select the checkbox next to the Evident-User-Attribution topic.
  4. Select the Actions menu near the top of the screen.
  5. Click Subscribe to topic.
  6. Set Protocol to HTTPS.
  7. Click Get URL in ESP to generate a HTTPS endpoint.
  8. Add the generated URL in the Endpoint box.
  9. Click Create Subscription.
  10. Click Submit. (If you have previously created a subscription, you will need to click Submit again.)

Add CloudTrail Name

At this point everything should be set up properly for you to turn on User Attribution. Enter the cloudtrail name on the right and click Submit. We will finish setting up user attribution by subscribing the SNS topic to our Lambda function.

  1. Enter the CloudTrail Name into the field below.
  2. Click Submit.


    image

Optional: Add Optional Lifecycle Bucket Policy

To prevent logs from filling up in your S3 bucket and incurring a charge from AWS, you may wish to add this optional lifecycle bucket policy.  ESP only searches for the logs from an hour before and an hour after an alert is generated to populate the User Attribution details.

  1. Select the S3 bucket: demolicious accountageous-evident-user-attribution (or whatever you named the bucket previously).
  2. In the right-window, select Lifecycle.
  3. Click Add Rule and then apply to the whole bucket.
  4. Click Configure Rule.
  5. Click Permanently Delete.
  6. Enter 1 in the Days field.
  7. Click Review.
  8. Change the policy name. (We recommend ESP CloudTrail Bucket Policy).
  9. Click Create and Activate.

Compliance

The dynamic nature of the cloud creates challenges for risk and compliance professionals tasked with measuring and demonstrating adherence to security and privacy controls. The tools they used for traditional systems don’t work. Despite the fact that manual interrogation of the cloud is slow and arduous, many organizations want to increase the frequency of their audits to ensure and demonstrate they are doing their best to remain secure.

ESP Compliance ensures that all of your company’s cloud computing meets all applicable regulations.

Using the continuous security monitoring data collected in the Evident Security Platform and the compliance report views, you eliminate the manual drudgery of compliance assessment. With one button simplicity, you can access the needed compliance report and then spend more time mitigating risks and addressing the gaps that were found.

The following features are included in Compliance Views:

Compliance View

The Compliance View dashboard shows all of the current compliance rules, divided by the standards you are working within, that ESP is currently monitoring across all of your AWS resources.

Note: For the moment, ESP automatically enrolls all assets for the CIS AWS Foundations Benchmark. In the future, customers will be able to purchase additional standards.

ESP Compliance View

To review all of the alerts generated by a specific set of standards, click on the desired standards. In the example above, click the CIS AWS Foundations Benchmark standard.

ESP Compliance View

ESP reveals a complete list of all of the rules under the selected standard. The example above is the CIS AWS Foundations Benchmark standard.

To drill-down into the AWS resources monitored under these rules, simply select one of the rules, as shown below, to reveal all of the monitored assets.

ESP Compliance View

To look at all alerts, generated because of one of these rules, click on the resource.

ESP Compliance View

To examine the details for the alerts for your AWS asset generated by one of these rules, click on Details to the right of it.

ESP Compliance View

Generate Compliance Reports


  1. Click Control Panel.
  2. Click Reports.


  3. Select Run Reports and then your specific team. In this example, Contract AWS Billing.


  4. A report will be queued for the external account selected: Contract AWS Billing.


  5. Once the report has been generated, click View Report.


  6. Select the Compliance tab.


  7. This report will allow you to drill down to look at individual rules and alerts generated just like any other report (see Reports).

Compliance View — Enabling Compliance

This document details step-by-step instructions on how to set up the compliance reports for Evident Security Platform and review the reports.

To Enable Compliance Reports on Evident Security Platform:


  1. Click Control Panel.
  2. Click External Accounts.


  3. Compliance standards must be applied to each External Account separately. In this example, we will select the Compliance button from Contract AWS Billing.


  4. All of the Compliance Standards available for this External Account will be listed on the screen. For the purpose of this demo, NIST 800-53r4 - Moderate and PCI DSS 3.2 are available.
    Click Enable to the right of the desired compliance (PCI DSS 3.2) to activate it for your account.


  5. Once a standard has been activated, ESP will populate your reports with compliance data at the next scheduled report interval.
  6. The Disable button will appear to the right of the standard, allowing you to deactivate it for the future.


Viewing Compliance Reports on Evident Security Platform:


  1. Click Control Panel.
  2. Click Reports.


  3. [Optional] If you have not run a report since enabling compliance, then select Run Reports > Contract AWS Billing.


  4. [Optional] A report will be queued for the external account selected: Contract AWS Billing.


  5. Once the report has been generated, click View Report.


  6. Select the Compliance tab.


  7. Scroll down until you locate the PCI DSS 3.2 Compliance information that lists the controls and number of alerts are shown next to a red X if the control inspection fails or a check if the control passes.  The numbers represent the actual alerts.


  8. To drill down further, click on one of the rules. For this example, select Do not allow unauthorized outbound traffic.


  9. You now have the opportunity to review all alerts generated by this rule.  If you see a failed alert, you may drill down further by clicking Details.


  10. This page details information about the alert, what resources it effected, and how to address the problem.
  11. To export this report to a PDF, return to the reports page and click Export to File > PDF.

Export Team-Specific Compliance Report

To Export a Compliance Report specific to a team:

  1. Open ESP Dashboard.
  2. On the top-left panel, select the team(s) you want to view.
  3. Select the Compliance Report that you want to view. This will open the Compliance Report for the selected team(s).
  4. To export, click on the Export to File > PDF button on the bottom-right.

Export Compliance Report to PDF

  1. Generate a Compliance Report.
  2. View the Compliance Report.
  3. Select the Compliance tab.
  4. Click Export to File > PDF.

Alerts

The Evident Security Platform Dashboard is the prism to receive the big picture of all incoming alerts and how to process them.

Alerts are tagged by color according to severity and may be found along the dashboard or within data bubbles.

Color Tag

Meaning

RED

High Risk

ORANGE

Medium Risk

YELLOW

Low Risk

GREEN

Pass

BLUE

Total number of alerts aggregated together.

Your EC2 instances are categorized according to the data bubbles that represent AWS Availability Regions of EC2 Assets. The size of the bubble reflects the number of alerts generated within that AWS Region These points have the following properties:

Alert Severity
Every alert generated is placed into a severity level category designed to help you prioritize resources to address identified risks. Each alert is tagged with a specific severity status indicating:

Type

Meaning

HIGH

This alert has been judged to be a great potential risk to your business assets and should be examined as soon as possible.

MEDIUM

This alert has been weighed as an issue that should be scheduled and tracked.

LOW

This alert may not be applicable or local business rules have determined that it is not a threat.



Filtering Alerts via the Alert Severity Key

Investigating Alerts via Availability Region Data Bubbles

To investigate all alerts within a specific available region:

  1. Locate the Availability Region you wish to investigate and click on it.

  2. All of the alerts of the selected severity for the last report will be displayed in the security report. Alerts may be filtered via the follow categories:

    1. Severity: The severity of this specific alert.
    2. Status: The status of the alert can be: Pass, Fail, Warn, Error, and Info.
    3. Team: The user can belong to different teams which can belong to a sub organization or organization.
    4. Region: The Amazon AWS Region.
    5. Signature Name: This is the name of the security offense that the alert is for ( e.g. Cloud Trails Bucket IAM Delete).
    6. Signature Identifier: The specific code for the signature. (e.g. AWS:SSS­003)
    7. First Seen: The date/time when the alert was first reported.
    8. Services: The services associated with the alert generated. Resources: The resources associated with the alert generated.
  1. The affected resource report will detail information about the alert including a description, suggested remediation steps, all of the available alert details.

  2. Scroll down to see a code snippet from the signature identifying the exact problem.

  3. Once you have examined the alert and addressed the core issue, you have the option to suppress the alert, the signature causing the alert, or the region that has generated the alert.

  1. Triage individual alerts via Alert Severity and Availability Region. You’ll want to examine High Severities in your most valuable regions first.

  2. Drill­down to the Details on the individual reports.

Toggling the Presentation

The Evident Security Platform dashboard is an interactive application that aggregates statistics across all of your accounts, giving you one-click access to a complicated set of filters that will shape your data to best serve your needs.

Our goal is to optimize your experience so that critical details about your alerts are one click away.

Graph Customization

The best presentation of data depends upon the volume and complexity of the source material and the data. The Evident Security Platform now has the ability to toggle between different graph templates that refactors and represents your data in the manner that best showcases the details you consider most important.

To refactor your report data, simply select one of the available graphs from the dashboard. ESP will instantly reorder your data in the selected format.

Do you have a suggestion for a better graph template that would improve your experience? Evident.io is actively soliciting feedback. If you have a graph view you would like our engineers to add to the dashboard, please contact Support .

Multiple Team Lock

The previous version of the ESP dashboard could only filter by one team at a time. The latest dashboard allows the selection of multiple teams, which brings you much more flexibility when drilling down.

24hr Only Toggle

If you want to only see alerts from the previous 24 hours on the dashboard, select this option to see every element in the dashboard can be replaced by the stats for only the new alerts. This is great for spotting changes at a glance. Would you notice the total alerts in us_east_1 went from 111 to 114 overnight? If you had "24hr only" active you would more likely notice the change in the count growing from 0 yesterday to 3 today.

Graph Pass Toggle

Not all reports are bad news. Every passing alert is an indication that your organization doing a great job at implementing best practices. However, this can drown out problems. By toggling the Graph Pass status, you can now view your alerts via the context of their status.

Additional Status Types

Your security landscape is more than just pass and fail. Our signatures create alerts that are just warnings, purely informational, or ones that exist in an error state because of an AWS outage or other undefined behavior. Toggle the different statuses to see the counts reflected. When you click on an element with that status active, the alerts with that status will be in the report, not just the failing alerts.

Set Custom Risk Levels

Customers may now create custom risk levels for signatures to match their best security practices.

To set a custom risk level for a signature:

  1. Click Control Panel > External Accounts.


    Set Custom Risk Levels

  2. Click Custom Risk Levels.


    Set Custom Risk Levels

  3. Locate the signature you wish to modify and then click the Set button under the Set Risk Level column.


    Set Custom Risk Levels

  4. Select the new risk level for the Signature from the pull-down menu.
  5. Click Submit.

Reports

A report is a record of all of the alerts generated for a specific organization, sub-organization, or team. Click on Reports on the ESP dashboard to locate the Reports page.

ESP Reports

The ESP Reports page has three different filters to help you find the exact data you need:

ESP Reports

Generating and Viewing Reports

Evident Security Platform runs a scan every hour and compiles alert data into reports. If you need more recent data, you can trigger an immediate scan and report generation.

To generate and view a report:

  1. Click Reports on the dashboard.

    ESP Reports

  2. Select the Run Report pull-down menu and select the specific organization, sub-organization, or team you wish to review. Or alternatively, you could select All Teams.

    ESP Reports

    ESP will run the scans through the selected team assets to build new reports. It will also list the external accounts it was unable to scan.

  3. Click History next to the report you wish view to see a visual snaphot of the generated security report.

    ESP Reports

  4. Click View Report next to the security report you wish to view. This will take you to a detailed page that is divided by Alerts, Signatures, Custom Signatures, and Compliance.

    ESP Reports

  5. Click View Affected Resources next to the item you wish to view further.

    ESP Reports

Searching Reports


ESP Reports

To search for a specific report:

  1. Click Search (Open).

  2. Enter the appropriate search parameters into the fields. Parameters include:

    1. Organization Name
    2. Sub Organization Name
    3. Team Name
    4. Created after
    5. Created before

  3. Click Search.

  4. Select the report you wish to examine.

The Affected Resource page related to the specific alert opens. You may press further into this information or turn your attention to other alerts in the report.

Exporting Reports to File

To export a report to file:

  1. You must first generate a report.
  2. Select the specific organization, sub-organization, or team you wish to examine.

  3. ESP Reports

  4. Select the Alerts tab.

  5. ESP Reports

  6. Click the Export to File pull-down menu and select the file type for the report. You may choose between CSV, JSON, and PDF.
  7. Evident.io will then email you the exported file.

Exporting Reports to an Integration

To export a report to an Integration:

  1. You must first generate a report.

  2. Select the Alerts tab.

    ESP Reports

  3. If you have an available Integration, then you will see the Export to Integrations pull-down menu. If this option isn’t available, you need to add an Integration. Select the Integration you desire to send the report to. ESP will then begin exporting all of the alerts to the selected to integration, not just the alerts from filtered results.

Disable Signatures

To disable a Signature, your user account must be assigned the Manager role.

  1. Go to Control Panel > Disabled Signatures.

    Disable Signature
  2. You have the option to view all available Signatures via alphabetical order or via accounts.
  3. Select the Signature you want to disable and click Show Accounts.

    Disable Signature
  4. All associated accounts are displayed under the Signature outlined in a field of green. To toggle a Signature off for a select account, simply click on the field.

    Disable Signature
  5. Disabled Signatures are outlined in pink. You may click Disable All to disable all Signatures for every account. Or you may click Enable All to enable a Signature for all accounts.

Custom Signatures

A custom signature is an automated validation against a defined non-standard best practice. An alert is generated when this validation fails or the signature judges that there is a potential security risk. A custom signature is used when the default best practice protocols are insufficient for a specific need. For example, if you wanted to ensure that each of your EC2 instances was tagged with information for your accounting department, you could write a custom signature to do this.

For information on coding a custom signature, read our Custom Signatures Guide.

Definitions

A definition is the archival system that keeps a snapshot of the code for the custom signature. There may be multiple definitions for a single custom signature, each with a unique version version number, language, and code.

All definitions possess a status designed to quickly convey information about it:

Lifecycle of a Definition

A definition is created when a user creates a custom signature in the Evident Security Platform. Once the user has inserted the code of the signature into the definition, it is validated by the custom signatures engine. Evident will vet the new code of the custom signature to ensure that everything is working as intended and once validated, the status of this definition will be set to active. The new custom signature will then be included in future report intervals.

If a definition fails validation, Evident.io pushes it back into the editable status. Once a new definition is activated, the previous definition will be archived (only one active at a time). Once archived, a definition cannot be changed and is just there for visibility.

Results

Results are a record used for the tracking of tracking the manual runs of a definition. Whenever a definition is tested, a result is created. A definition may have multiple results.

All results possess a status designed to quickly convey information about it:

When a result is generated, ESP runs a test of the definition and saves all alerts generated. If the result generates errors, then ESP sets it to the failed state. Evident.io saves the first 100 alerts generated per resul using the same checks that’s performed in the validating phase of definitions. A failed result may or may not have alerts, but there will be some kind of error along with them.

Creating a Custom Signature

To create a custom signature within ESP:

  1. Click Control Panel.

  2. Click Custom Signatures.

  3. Click New.

  4. Enter the information for the custom signature.

  5. Click Submit.

  6. Select the Region and External Account you wish to associate with this custom signature.

  7. Click Run to validate this custom signature.

  8. Once you have inserted the code for custom signature, click Save.

The code is saved as Definition Version 1 as seen above.

The maximum run time for a definition is five minutes. If you later create a new version of the code after this definition has been activated, it will archive the old definition.

Viewing Custom Signature

To view the custom signatures:

  1. Click Control Panel.

  2. Click Custom Signatures.

This page displays all of the relevant information about the custom signature and the status of the definition.


Last updated on July 11, 2016 by Jason Andrew

Integrations

An integration is a notification service that tells Evident.io to send your alerts for desired signatures to the teams that need them.

To Add an Integration:

  1. Under Control Panel, click Integrations.

  2. Add Integration
  3. Select the service you wish to engage as an Integration.
  4. Follow the instructions for the individual service.

Amazon SNS

Amazon Simple Notification Service (Amazon SNS) is a fast, flexible, fully managed push notification service that lets you send individual messages or to fan-out messages to large numbers of recipients. Amazon SNS makes it simple and cost effective to send push notifications to mobile device users, email recipients or even send messages to other distributed services. For more information, see https://aws.amazon.com/sns/

To create a topic in the AWS Management Console:

  1. On the SNS page, select Create Topic.
  2. When the new-topic modal shows, enter a topic name and click Create Topic.
  3. You will be redirected to the topic page.
  4. Select the text for Topic ARN and copy it. Paste that ARN into the box to the left of this page.

The following steps will give us the ability to publish messages about alerts to a SNS topic by creating a role in IAM.

  1. Enable Raw Message Delivery by following the instructions here: http://docs.aws.amazon.com/sns/latest/dg/large-payload-raw-message.html
  2. On the AWS Services page, select the IAM service.
  3. Select Policies on the left menu.
  4. Click Create Policy.
  5. Select Create Your Own Policy.
  6. Name the policy EvidentSNSIntegrationPublish.
  7. Next, copy the policy below into the Policy Document field.
  8. {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": [
                        "sns:Publish"
                    ],
                    "Effect": "Allow",
                    "Resource": "<SNS TOPIC ARN>"
                }
            ]
        }
        

  9. When you are finished click Create Policy.
  10. Select Roles on the left menu.
  11. Select Create New Role.
  12. ESP recommends that you name the role Evident-Service-Role-SNS-Integration. Click Next Step.
  13. Select the radio button Role for Cross-Account Access.
  14. Select Allows IAM users from a 3rd party AWS account to access this account.
  15. Enter the Account ID of our service. Account ID: 613698206329.
  16. Enter the External ID field of the AWS dialog box. The External ID is dynamically generated just for you. Refreshing this page will generate a new External ID. External ID: 1f43070d-55b5-426a-8b62-4d9f710f8b87
  17. Verify that Require MFA is not enabled.
  18. Click Next Step.
  19. AWS will open a window with a list of policies. Select the policy you created in Steps 5 to 8. Click Next Step.
  20. In the Review step, copy the Role ARN string to paste in the last step.
  21. Click Create Role.
  22. Return to ESP and paste the Role ARN into the ARN field and click Save.
  23. Enter the appropriate information into the Name, Sub Organization, and Team fields.
  24. Click Submit.

HipChat

HipChat is hosted group chat and video chat built for teams. Supercharge real-time collaboration with persistent chat rooms, file sharing, and screen sharing. This integration will send new alerts to a HipChat room. We only support API v2. For more information, see the HipChat integration documentation.

  1. From the admin panel, go to the Rooms tab.
  2. Pick the room you would like alerts to be sent to and then choose Tokens from the left hand menu.
  3. Enter Evident in the label and create the token.
  4. Paste the token that is provided by HipChat on the left and also enter the room name or room id in the room field.

JIRA

JIRA is a workflow management system that lets you track your work in any scenario.

Integrating JIRA with ESP will automatically create new issues for new alerts that you subscribe to. For example, if you subscribe to failing status and the alert starts as fail, changes to pass on a later run, and then fails again, two issues will be created for each fail status.

The Evident to JIRA integration requires 5 pieces of JIRA specific information:

URL

The JIRA REST API is enabled by default and has the following format:

For the ESP integration, you only need the host and port portion of the URL. If you are using a standard port (80|443), you do not need to include the port number.

For more information about the JIRA REST API, please follow this link.

Project Key

The JIRA integration needs to be associated with a specific JIRA Project. When you create a JIRA Project, you are required to designate Key. Include this Key when you configure the JIRA integration.

For detailed information on how to manage a JIRA Project, please refer to the JIRA documentation.

Issue Type

The JIRA integration needs to be associated with a specific JIRA Issue Type. Examples of the default Issue Types are Task, Bug, Improvement. You will need to decide which Issue Type to include when configuring the JIRA integration.

Given ESP’s Compliance and Security use case, consider creating a unique Issue Type for the ESP alerts such as “SecurityFinding”. For information on how to add an issue, please refer to the JIRA documentation on creating a new Issue Type.

For more detailed information on Issue Types, please refer to the JIRA documentation.

Username/Password

The ESP to JIRA integration uses Basic Auth so you will need to create a user with access to the Project designated in the previous step. For specifics on how to create a JIRA user and assign access, please refer to the JIRA documentation.

Test JIRA Configuration

Before configuring the ESP integration you may want to test your JIRA configuration by following these instructions. This particular example uses curl so you will need access to bash shell.

  1. Create a text file (example test.txt) with the following:
    {
            	    "fields": {
            	        "project":
                        	{
                         	"key": "Your_Project_Key"
        	              },
                   	"summary": "JIRA configuration test",
                   	"description": "Creating an issue via REST API",
                   	"issuetype": {
                      	"name": "SecurityFinding"
                    	}
            	    }
    }
    

  2. Use curl to create an issue:
    curl -D- -u USERNAME:PASSWORD -X POST --data-binary "@FILENAME" -H "Content-Type: application/json" https://jirahost.example.com/rest/api/latest/issue/
    

  3. If the command was successful it will return similar output to the following:
    HTTP/1.1 201 Created
    Server: nginx
    Date: Wed, 22 Feb 2017 15:22:14 GMT
    Content-Type: application/json;charset=UTF-8
    Transfer-Encoding: chunked
    Connection: keep-alive
    X-AREQUESTID: 622x1128x1
    X-AUSERNAME: USERNAME
    X-ATENANT-ID: jirahost.example.com
    Cache-Control: no-cache, no-store, no-transform
    X-Content-Type-Options: nosniff
    Set-Cookie: JSESSIONID=974A7D7832157FEB89DF7EFA90EA8691; Path=/; Secure; HttpOnly
    Set-Cookie: atlassian.xsrf.token=BE2J-9QGD-DHYI-2L1Q|95d23adf9a7127427b08570d0955caf2b408daca|lin; Path=/; Secure
    Strict-Transport-Security: max-age=315360000;includeSubDomains
    

Create JIRA Integration in ESP

  1. Log into ESP.
  2. Navigate to Control Panel > Integrations.
  3. Click the JIRA icon.

    JIRA Icon

  4. Enter the information in the following fields, based on the information from the previous sections:
    1. URL
    2. Project Key
    3. Issue Type
    4. Username
    5. Password

    6. JIRA Integration
  5. Click Save.

PagerDuty

PagerDuty provides alerting, on-call scheduling, escalation policies and incident tracking to increase uptime of your apps, servers, websites and databases. Check the PagerDuty guide for help.

Provide a PagerDuty API Key below and we will create incidents for the signatures you choose. If you subscribe to Fail/Warn/Error alert statuses then we will create incidents for those alerts. We will resolve those incidents if the alerts later pass and you subscribed to pass.

Note: We only create incidents for new alerts. If you set your incidents to autoresolve after a certain amount time, a new incident will not be created.

  1. From your PagerDuty dashboard, click Services at the top.
  2. Click the Add New Service button on the services page.
  3. Name the service and set the escalation policy to your preferences.
  4. Under Integration Type, choose Select a Tool then select Evident.io from the list.
  5. Enter the Service API Key that is listed on the left.

ServiceNow

ServiceNow is a software platform that supports IT service management and automates common business processes.

This integration will use the ServiceNow API to create new incidents for alerts. For more information, see the Service Now integration documentation.

From your instance Home page, click User Administration.

  1. Click Users and select the user you want to make API calls with.
  2. Scroll down to the Roles section and click Edit.
  3. From the Collection box, find rest_service and move it to Roles List and Save.
  4. Enter the Instance URLcthat is provided by ServiceNow on the left.
  5. Authentication is handled with BasicAuth, so your username and password is required to access the ServiceNow API. We encrypt this information.

Slack

Slack brings all your communication together in one place. It’s real-time messaging, archiving and search for modern teams. For more information, see the Slack integration documentation.

This integration will send new alerts to a Slack channel.

  1. From the Integration page on Slack, choose Incoming Webhooks.
  2. Pick the channel you would like messages to be posted to and choose Add Incoming Webhooks Integration.
  3. Enter the Webhook URL that is provided by Slack on the left.

Webhook

Webhooks are user-assigned URLs to which Evident.io will POST alerts. This integration will send new alerts to a user-assigned URL. For more information, see the Webhook integration documentation.

  1. In the field to the left, enter the URL you would like to designate to receive alerts POSTed from Evident.io.
  2. NOTE: Only HTTPS URLs are allowed. This endpoint must return a 200 status code or delivery is considered a failure. In the event of a failure, the message will be retried.

Splunk

Splunk Enterprise is the leading platform for real-time operational intelligence. It's the easy, fast and secure way to search, analyze and visualize the massive streams of machine data generated by your IT systems and technology infrastructure—physical, virtual and in the cloud.

To setup your Splunk Integration:

  1. Install and configure the Splunk App for Evident.io from Splunkbase:
    1. Log into Splunk Web and navigate to Apps > Manage Apps.
    2. Click “Install App from File.”
    3. “Choose file” downloaded and then click Upload.
    4. Restart your Splunk Web, (Settings > Server Controls > Restart Splunk.)
    5. A new Evident.io application will be listed in the Splunk Console.
    6. Add a Field Alias (Settings -> Fields -> Field Aliases) with the following parameters:
      1. Destination app = splunk_app_evidentio
      2. Apply to, sourcetype = aws-evidentio
      3. Field alias, "Records{}.Sns.Message" to "Message"
    7. Update Splunk Evident.io App
      1. Go to Splunk Evident.io App
      2. Click Edit.
      3. Click Source.
      4. Copy and Paste the following into the editor and save:
        <form>
          <label>Evident.io Overview Dashboard</label>
          <fieldset submitButton="true">
            <input type="time" token="time">
              <label>Time</label>
              <default>
                <earliest>-24h@h</earliest>
                <latest>now</latest>
              </default>
            </input>
            <input type="dropdown" token="resource_type" searchWhenChanged="true">
              <label>Resource Type</label>
              <choice value="*">All</choice>
              <choice value="vol*">Volume</choice>
              <choice value="vpc*">VPC</choice>
              <choice value="i*">Instance</choice>
              <choice value="acl*">ACL</choice>
              <choice value="subnet*">Subnet</choice>
              <choice value="sg*">Security Group</choice>
              <default>*</default>
            </input>
          </fieldset>
          <row>
            <panel>
              <title>Severity Breakdown</title>
              <chart>
                <title>By Resource</title>
                <search>
                  <query>index=main sourcetype=aws-evidentio Message &gt; 1  | spath input=Message|  search data.attributes.resource = "$resource_type$*" |  rename "included{}.attributes.risk_level" as "Severity" | stats count by Severity</query>
                  <earliest>$time.earliest$</earliest>
                  <latest>$time.latest$</latest>
                </search>
                <option name="charting.axisLabelsX.majorLabelStyle.overflowMode">ellipsisNone</option>
                <option name="charting.axisLabelsX.majorLabelStyle.rotation">0</option>
                <option name="charting.axisTitleX.visibility">visible</option>
                <option name="charting.axisTitleY.visibility">visible</option>
                <option name="charting.axisTitleY2.visibility">visible</option>
                <option name="charting.axisX.scale">linear</option>
                <option name="charting.axisY.scale">linear</option>
                <option name="charting.axisY2.enabled">0</option>
                <option name="charting.axisY2.scale">inherit</option>
                <option name="charting.chart">pie</option>
                <option name="charting.chart.bubbleMaximumSize">50</option>
                <option name="charting.chart.bubbleMinimumSize">10</option>
                <option name="charting.chart.bubbleSizeBy">area</option>
                <option name="charting.chart.nullValueMode">gaps</option>
                <option name="charting.chart.showDataLabels">none</option>
                <option name="charting.chart.sliceCollapsingThreshold">0.01</option>
                <option name="charting.chart.stackMode">default</option>
                <option name="charting.chart.style">shiny</option>
                <option name="charting.drilldown">all</option>
                <option name="charting.layout.splitSeries">0</option>
                <option name="charting.layout.splitSeries.allowIndependentYRanges">0</option>
                <option name="charting.legend.labelStyle.overflowMode">ellipsisMiddle</option>
                <option name="charting.legend.placement">right</option>
              </chart>
            </panel>
            <panel>
              <title>Resource Breakdown</title>
              <table>
                <search>
                  <query>index=main sourcetype=aws-evidentio Message &gt; 1   | spath input=Message  | rename data.attributes.resource as resource | search resource = "$resource_type$*" | rename included{}.attributes.data.details.attachedEC2Instances{} as Instance | rename included{}.attributes.resolution as Resolution| rename included{}.attributes.data.details.securityGroup.vpcId as VPC | rename included{}.attributes.risk_level as Severity | stats count as "Number of Alerts",values(Instance) as "Associated EC2 Instances" by Severity, resource | sort + Severity</query>
                  <earliest>$time.earliest$</earliest>
                  <latest>$time.latest$</latest>
                </search>
                <option name="charting.chart">bar</option>
                <option name="wrap">true</option>
                <option name="rowNumbers">false</option>
                <option name="dataOverlayMode">none</option>
                <option name="drilldown">cell</option>
                <option name="count">10</option>
              </table>
            </panel>
          </row>
          <row>
            <panel>
              <title>Resolution</title>
              <table>
                <search>
                  <query>index=main sourcetype=aws-evidentio Message &gt; 1    | spath input=Message   | rename data.attributes.resource as resource | search resource = $resource_type$ | rename included{}.attributes.resolution as Resolution | table  Resolution</query>
                  <earliest>$time.earliest$</earliest>
                  <latest>$time.latest$</latest>
                </search>
                <option name="wrap">true</option>
                <option name="rowNumbers">false</option>
                <option name="dataOverlayMode">none</option>
                <option name="drilldown">cell</option>
                <option name="count">10</option>
              </table>
            </panel>
          </row>
        </form>
        
  2. Create HTTP Event Collector (HEC) Token Creation.
    1. From the Settings menu, select Add Data.
    2. Select Monitor, and then in the left pane, select HTTP Event Collector. The right pane populates with fields for HEC end point.
    3. In the Name field, enter a name for the token that describes its purpose and that you will remember.
    4. Click Next. The Input Settings page displays.
    5. For Source Type, choose "Select" and input "aws-evidentio"
    6. For Index, choose "main"
    7. Click Review. Confirm that all settings for the endpoint are what you want. If you need to change settings, click the gray < button at the top of the page.
    8. If all settings are what you want, click Next. The success page loads and displays the token value that Event Collector generated. You can copy this token value from the displayed field and paste it into another document for reference later. See "About Event Collector tokens."
  3. Create the AWS Lambda Function.
    1. Log into your AWS Console and navigate to the Lambda Function service.
    2. Click Create a Lambda Function.
    3. In the Filter box, type in "splunk-logging" Click on the result.
    4. Give your Lambda function a name; suggest using "GetDataFromEvidentio"
    5. Encrypt your Splunk HEC token using the AWS CLI tools and the KMS key generated per the video reference link in #3 (aws kms encrypt.)
    6. By default, the function will generate 5 Splunk events per invocation.  It is recommended to modify the function to fit your needs.
    7. Note: You can use the unencrypted HEC token with the curl command to make sure this works outside of Lambda.  Following that, you can run the test function in Lambda per the video to make sure this works before populating it with the SNS topic. The video link in #3 is a guide to setting this up.
  4. Configure the Evident SNS Integration.
    1. Create a topic in the AWS Management Console per the instructions in the integration reference.
    2. Create a cross-account policy that allows ESP to publish SNS notifications to that topic per reference.
  5. Go to your AWS SNS topics and subscribe your Lambda function to the topic collecting data from Evident.io.
    Note: If this is a new SNS topic, you may wish to subscribe an email address to it first to make sure the path from ESP to the SNS topic is working correctly before adding the Lambda function.

Sumo Logic App for ESP

The Evident.io Evident Security Platform (ESP) streamlines and optimizes vulnerability and risk management. It continuously monitors the AWS cloud, automatically identifies security misconfigurations, enables rapid mitigation of risk through guided remediation and provides visibility to their service through integrations with a central security analytics platform like Sumo Logic.

By combining the vulnerability and identified security misconfigurations from Evident and other data sources, you can reduce your security risk and improve your overall security posture.

Use the preconfigured searches and Dashboards in the Sumo Logic App for Evident.io ESP to investigate Evident-specific events and provide operational visibility to team members without logging into Evident.io.

Log Types

The Sumo Logic App for Evident.io ESP uses monitoring alerts. For details on the log format and definitions, refer to Evident.io documentation at http://docs.evident.io/.

Collect Logs for Evident.io

To collect logs for Evident.io, you will perform the following steps, detailed in the sections below:

  1. Configure an Evident.IO Integration with AWS SNS
  2. Add a Sumo Logic Hosted Collector and HTTP Source.
  3. Subscribe to SNS Notifications.

Configure an Evident.io Integration with AWS SNS

To configure an Evident.io Integration with AWS SNS:

  1. In Evident.io, add an Integration.
  2. Enable an AWS SNS integration.
  3. In the AWS SNS Topic you created, enable Raw Message Delivery:
    1. Select the AWS Topic.
    2. Click Other subscription actions.
    3. Click Edit subscription attributes.
    4. evident_app_edit_subscription.png

  1. Select the Raw message delivery check box.
  2. Click Set subscription attributes.
  3. evident_app_set_subscription.png

Add a Sumo Logic Collector and Source

  1. In Sumo Logic, configure a Hosted Collector.
  2. Configure an HTTP Source.
    1. Name.
      1. Enter Evident.io SNS Integration.
    2. Source Category.
      1. Enter security_evident.
  3. In the Advanced section, configure the following:
    1. Enable Timestamp Parsing.
      1. Activate the check box Extract timestamp information from log files.
    2. Time Zone.
      1. Select Ignore time zone from log file, and select (UTC) Etc/UTC
  4. Processing Rules. Create the following Mask Rule
    1. Name.
      1. Enable proper timestamp parsing
    2. Filter.
      1. \"(?:created_at|updated_at|ended_at)\":\"\d+-\d+-\d+(T)\d+:\d+:\d+.\d+Z\"
    3. Type.
      1. Mask messages that match
    4. Mask String.
      1. t

      2. evident_app_processing_rules.png
  5. Click Apply.
  6. Click Save.
  7. Copy the HTTP Source Address URL and use it in the following section.

Subscribe to SNS Notifications

Once the Hosted Collector and HTTP Source are configured, subscribe to Evident.io SNS Notifications:

  1. In the AWS Management Console, go to SNS > Topics, and find the topic you created in Configure an Evident.IO Integration with AWS SNS.
  2. Select the checkbox for the topic.
  3. Under Amazon SNS, in the Actions menu, select Subscribe to Topic.
  4. Under Protocol, select HTTPS, and paste the Sumo Logic HTTP Source URL into the Endpoint field.
  5. Click Create Subscription.
  6. In a few minutes, a confirmation message is sent to Sumo Logic.
  7. In Sumo Logic, search for the new message from your HTTP Source. For example, use the query _sourceCategory="security_evident".
  8. Then, in the Messages tab, parse the message for the JSON field SubscribeURL, and copy it to your clipboard, as shown.
  9. aws_config_app_example_700x317.png

  10. In the AWS Management Console, select SNS >Topics.
  11. Under Amazon SNS > Actions, select Confirm a subscription.
  12. Paste the SubscribeURL into the field Subscription confirmation URL, and click Confirm subscription.

Install the Evident.io App

To install the App:

  1. In the Library, click the Preview tab.
  2. Select Evident.io.
  3. Click Install.
  4. In the Install Application dialog box, select Select from _sourceCategory values and choose security_evident.
  5. Click Install.
  6. When the Confirm dialog displays, click Go to navigate to the installed app.

Intervals

To avoid rate limits, Evident.io has added two features that help you control how often your External Account sends API calls to Amazon Web Services.

Report Intervals

The report interval is a setting of a number of minutes between report runs.

Report Intervals

  1. Go to Control Panel > Teams
  2. Select the interval period for Evident.io to run reports for this team. You can choose intervals of 1 (default), 3, 6, 12, and 24 hours.

Scan Intervals

The scan interval is the number of minutes between each service scan. Evident.io recommends using this feature only if you have a large AWS account with a large number of resources or you are experiencing rate limiting from AWS. The default time for each service will be 15.

  1. Select Control Panel > External Accounts > Scan Intervals


    Scan Intervals

  2. Click Set or Edit on the Service you wish to modify.
  3. Select the interval period for Evident.io to run reports for this team on the pull-down menu. The interval options (in minutes) are IAM: 15, 30, 45, 60, 120 and all other services: 5, 15, 30, 45, 60, 120.
  4. Click Submit.

Organization

The Evident Security Platform (ESP) provides visibility into the security state of the shared security responsibilities customers have in AWS.

ESP also has the ability to control access to security reports based on a hierarchical organization structure. You can design the structure to match your company’s organizational structure, or one that makes sense with your security remediation workflow. This is also an important requirement for Segregation of Duties (SOD) controls in the various compliance frameworks, such as HIPAA, ISO 27001, SOC 2, etc.

The structure in ESP is, in precedence from overall to fine grained visibility:

An ESP Organization has the ability to silo AWS accounts and ESP users within specific Sub-Organizations and Teams.

Consider a ‘Customer’ role user, bob@example.com, that is assigned to Team Red that is under Sub-Organization B in Organization Example. Bob would be able to view reports for AWS accounts that are under Team Red. Sub-Organization B also has a Team Blue, but this would not show up in the dashboard at all for Bob since he is not apart of Team Blue. Bob would not be able to change any configuration settings for accounts he can view.

Consider also a ‘Manager’ role user, jeff@example.com, that is assigned to the same Sub-Organization B that was described in the previous scenario. Jeff is assigned specifically to the Sub-Organization B, so he can view reports for both Team Blue and Team Red. He can also modify integration settings, or scan intervals since he is a ‘Manager’ role user.

Jeff has access to both Team Blue and Team Red since he was assigned to the Sub-Organization and not a specific team. Bob only has access to Team Blue because was assigned specifically to Team Blue, and not Team Red.

You must make the decision where to place the Users and External accounts. Visibility of ESP security reports is completely controlled in the Users window in the ESP Control Panel.

The following is an example of how complex the reporting structure can be:

ESP Organization Structure

As far as security assessments are concerned, someone with broad security responsibilities throughout a company should have visibility for every sub organization and team, while a software developer would only need to view reports for his particular team. Visibility into organizations/sub organizations/teams is explicit. If a user should be seeing a particular team’s report (or all reports), that user must be added every time a new team and external account is created.

In the example below, we take a fictitious user, evidentdemo@xxxxx.com and give him access to all teams.

We can easily remove access by unchecking the sub organization or team in the list and clicking save.

ESP User Access to Teams and Organizations

This would generate a report (and dashboard) view such as the following:

ESP Dashboard

As you can see, ESP can help you satisfy SOD controls for compliance and your organization, while giving flexibility in the constant changing world of DevOps and AWS account security management.

Custom Signatures Guide

This is the Developer's Guide to Custom Signatures.

Custom Signature Overview

A custom signature is an automated validation against a defined nonstandard best practice. An alert is generated when this validation fails or the signature judges that there is a potential security risk. If the default best practice protocols and recommendations are insufficient for a specific business need or practice, a custom signature may be created to meet that need.

When the default best practice protocols are insufficient for a specific business need, a custom signature may be generated. If you wanted to ensure that each of your EC2 instances was tagged with information for your accounting department, you could write a custom signature that monitors this.

Custom signatures limit properties access to defined group of users or a company account or a defined group of users within one company account.

An alert from a custom signature will have the follow attributes:

Warning: ESP API Javascript custom signatures follows the AWS Ruby SDK instead of AWS Javascript SDK.

Anatomy of a Custom Signature

A custom signature is a function that reads AWS SDK data from Amazon, and creates one or more alerts based on that data and conditionals you describe.

A custom signature will always have two sections — config and perform.

In order for an API client to function, the service must be listed and allowed implicitly or explicitly in the attached IAM policy on the IAM role you assign to ESP. The AWS-managed policy allows a lot of services, but is not inclusive of all of the AWS services we have client methods for.

Note: the AWS Ruby SDK is utilized regardless of custom signature script language.

Config

dsl.configure is a function that is passed an anonymous callback function that receives a configuration object (here c) as the first argument. Inside the anonymous function you have access the configuration settings for the signature.

Config Example

dsl.configure(function(c) {
        c.valid_regions = ['us_east_1'];
        c.identifier = ['AWS:EC2-909'];
        c.deep_inspection = ['volume_id'];
        c.unique_identifier = ['volume_id'];
        });
        

Configuration Metadata

valid_regions

identifier

deep_inspection

unique_identifier

perform

The perform section is a function that is passed the AWS SDK as an object. You use this aws object to make calls to AWS.

Perform Example

// Required perform function
function perform(aws) {
  try {
    var region = aws.region;

    // these are AWS SDK calls to get a list of resources to check
    var volumes = aws.ec2.describe_volumes().volumes;

    // this is our condition we are searching for in this signature
    // we want to enforce a specific volume type in this region
    // if you change the variable below to 'gp2' it will use that
    var type_to_check_for = 'standard';

    // for each volume returned from the AWS SDK call
    volumes.map(function(volume) {
      // our condition check
      // is the volume.volume_type not the same as our desired type?
      if (volume.volume_type !== type_to_check_for) {
        // in this block the volume.volume_type !== type_to_check_for
        // You will create a failed alert with any extra information you would like.
        // In this case we are adding a message with the expected type.
        // The message is a string, and the failed alert is created by calling
        // dsl.fail({ message: 'some message indicating why'})
        // You then push that object on to the alerts array and the next
        // volume is checked

        var fail_message = 'volume with id ';
        fail_message += ' is of type ' + report[volume_type]
        fail_message += ' and not of type '
        fail_message += type_to_check_for;

        // Create the passing alert. The resource ID must be unique among all alerts created.
        dsl.fail({
          resource_id: volume.volume_id,
          volume_type: volume.volume_type,
          message: fail_message
        });
      } else {
        // in this block the volume.volume_type === type_to_check_for
        // You will create a pass alert with a message.
        var pass_message = 'volume with id ' + volume.volume_id;
        pass_message += 'is of type ' + volume.volume_type;

        // Create the passing alert. The resource ID must be unique among all alerts created.        
        dsl.pass({
          resource_id: volume.volume_id,
          volume_type: volume.volume_type,
          message: pass_message
        });
      }
    })
  } catch (err) {
    return dsl.error({
      errors: err.message
    });
  }
}

Supported Services

When calling AWS methods and classes within custom signatures, please use the list below as a reference.

Class Name

Method Name

AutoScaling

as

CloudFormation

cfm

CloudFront

cf

CloudSearch

cs

CloudTrail

ct

CloudWatch

cw

CloudWatchLogs

cwl

CodeDeploy

cd

CognitoIdentity

cognito

CognitoSync

cognito_sync

ConfigService

config

DataPipeline

dp

DirectConnect

dc

DynamoDB

dynamodb

EC2

ec2

EMR

emr

ElastiCache

ec

ElasticBeanstalk

elbs

ElasticLoadBalancing

elb

ElasticTranscoder

elt

Glacier

glacier

IAM

iam

ImportExport

ie

KMS

kms

Kinesis

ks

Lambda

lambda

OpsWorks

ops

RDS

rds

Redshift

rs

Route53

route53

Route53Domains

route53_domains

S3

s3

SES

ses

SNS

sns

SQS

sqs

STS

sts

SWF

swf

SimpleDB

sdb

StorageGateway

sg

Support

support

Actions

The following are the available actions that may leveraged by the ESP API to control/run/use custom signatures.

List

List a pageable response of 25 records per page.

List Example

api.custom_signatures.list
> [
    {
                     "id" => 4,
        "organization_id" => 1,
              "signature" => "<raw code would be here>",
            "description" => "test",
             "resolution" => "test",
                   "name" => "Testing",
                 "active" => true,
             "created_at" => "2014-07-21T20:09:24.809Z",
             "updated_at" => "2014-08-04T14:15:28.326Z",
             "risk_level" => "High",
             "identifier" => nil,
             "service_id" => nil,
             "deleted_at" => nil
    }
  ]

Show

Show a specific custom signature

Note: Teams are only retrieved if it is explicitly included. If you are going to update the custom signature, make sure to include teams like so: ESP::CustomSignature.find(544, include: "teams")

Show Example

api.custom_signatures.show(id: 4)
> {
                     "id" => 4,
        "organization_id" => 1,
              "signature" => "<raw code would be here>",
            "description" => "test",
             "resolution" => "test",
                   "name" => "Testing",
                 "active" => true,
             "created_at" => "2014-07-21T20:09:24.809Z",
             "updated_at" => "2014-08-04T14:15:28.326Z",
             "risk_level" => "High",
             "identifier" => nil,
             "service_id" => 11,
             "deleted_at" => nil
  }

Update

Update a specific custom signature

Update Parameters

Name

Type

Description

id

integer

Required. The ID of the custom signature.

name

string

Name of this signature.

signature

string

Raw code to run

risk_level

string

Severity level of this signature. Possible values are: High, Medium,Low

description

string

Describe the issue this signature checks for.

resolution

string

Steps to resolve this issue.

active

boolean

Flag used to determine if this signature should be run.

Update Example

api.custom_signatures.update(id: 4, active: false, name: 'Updated Name')
> {
                 "id" => 4,
    "organization_id" => 1,
          "signature" => "<raw code would be here>",
        "description" => "test",
         "resolution" => "test",
               "name" => "Updated Name",
             "active" => false,
         "created_at" => "2014-07-21T20:09:24.809Z",
         "updated_at" => "2014-09-24T20:48:21.822Z",
         "risk_level" => "High",
         "identifier" => nil,
         "service_id" => 11,
         "deleted_at" => nil
  }

Create

Create a specific custom signature

Create Parameters

Name

Type

Description

name

string

Required. Name of this signature.

signature

string

Required. Raw code to run

risk_level

string

Required. Severity level of this signature. Possible values are:High, Medium, Low

description

string

Describe the issue this signature checks for.

resolution

string

Steps to resolve this issue.

active

boolean

Flag used to determine if this signature should be run.

Create Example

javascript = "<javascript code>"
api.custom_signatures.create(signature: javascript, name: 'Demo Signature', risk_level: 'High')
> {
                 "id" => 97,
    "organization_id" => 1,
          "signature" => "<raw code would be here>",
        "description" => nil,
         "resolution" => nil,
               "name" => "Demo Signature",
             "active" => nil,
         "created_at" => "2014-09-24T20:51:08.901Z",
         "updated_at" => "2014-09-24T20:51:08.901Z",
         "risk_level" => "High",
         "identifier" => nil,
         "service_id" => 11,
         "deleted_at" => nil
  }

Destroy

Destroy a custom signature

Destroy Parameters

Name

Type

Description

id

integer

Required. The ID of the custom signature.

Destroy Example

api.custom_signatures.destroy(id: 97)
> {
    "success" => "Demo Signature has been destroyed"
  }

Run

Run a custom signature directly.

Run Parameters

Name

Type

Description

signature

integer

Required. The ID of the custom signature.

external_account_id

integer

Required. The ID of the external account to run this signature against.

regions

array

Required. Array of strings representing the regions to run the signature in.

Run Example

api.custom_signatures.run(id: 1, external_account_id: 1, regions: [:us_east_1])
> {
    "alerts" => [
      {
                       "info" => {
                   "user_count" => 1,
                    "condition" => "count >= 1",
              "deep_inspection" => [
                  {
                      "users" => [
                         {
                                     "path" => "/",
                                "user_name" => "demouser",
                                  "user_id" => "AIDAHJFKDHGFHFGKHKGFH",
                                      "arn" => "arn:aws:iam::00000000:user/demouser",
                              "create_date" => "2014-01-16T19:05:36.000Z"
                          }
                      ]
                  }
              ]
          },
                     "status" => "pass",
                     "config" => {
                          "module" => "check_user_count_javascript",
                     "description" => "Check IAM user count",
                   "valid_regions" => [
                     "us_east_1"
              ],
                      "identifier" => "AWS:GLO-001",
                 "deep_inspection" => [
                    "users"
              ],
               "unique_identifier" => [
                  {
                      "user_name" => "user_id"
                  }
              ],
                      "display_as" => "global",
              "validation_context" => nil,
                          "errors" => {}
          },
                     "region" => "us_east_1",
          "unique_identifier" => {
                    "demouser"  => "AIDAHJFKDHGFHFGKHKGFH",
          }
      }
    ]
  }
             "identifier" => nil,
             "service_id" => nil,
             "deleted_at" => nil
    }
  ]

Run Raw

This signature runs a specific custom signature without creating it first and returns the alerts generated by it.

Run Raw Parameters

Name

Type

Description

signature

integer

Required. The ID of the custom signature.

external_account_id

integer

Required. The ID of the external account to run this signature against.

regions

array

Required. Array of strings representing the regions to run the signature in.

Run Raw Example

javascript = "<javascript code>"
api.custom_signatures.run_raw(signature: javascript, regions: [:us_east_1], external_account_id: 1)
> {
    "alerts" => [
        {
                         "info" => {
                     "user_count" => 1,
                      "condition" => "count >= 1",
                "deep_inspection" => [
                    {
                        "users" => [
                            {
                                       "path" => "/",
                                  "user_name" => "demouser",
                                    "user_id" => "AIDAHJFKDHGFHFGKHKGFH",
                                        "arn" => "arn:aws:iam::00000000:user/demouser",
                                "create_date" => "2014-01-16T19:05:36.000Z"
                            }
                        ]
                    }
                ]
            },
                       "status" => "pass",
                       "config" => {
                            "module" => "check_user_count_javascript",
                       "description" => "Check IAM user count",
                     "valid_regions" => [
                       "us_east_1"
                ],
                        "identifier" => "AWS:GLO-001",
                   "deep_inspection" => [
                     "users"
                ],
                 "unique_identifier" => [
                     {
                        "user_name" => "user_id"
                    }
                ],
                        "display_as" => "global",
                "validation_context" => nil,
                            "errors" => {}
            },
                       "region" => "us_east_1",
            "unique_identifier" => {
                      "demouser"  => "AIDAHJFKDHGFHFGKHKGFH",
            }
        }
    ]
  }

Last updated on September 12, 2016 by Jason Andrew

New Customer Walkthrough

The Evident Security Platform (ESP) is designed to work in tandem with Amazon Web Services (AWS) to help your business detect and manage security risks for your entire AWS infrastructure. Our application is configurable to allow for automated vulnerability detection, incident response, and compliance through continuous monitoring and analysis of AWS configuration and usage metadata.

This walkthrough is designed to help you maximize the value of your ESP trial membership by helping you focus on the most actionable alerts, to accurately evaluate security risks to the business.

The goal for this walkthrough is to make your security data organized, relevant, and actionable.

Step 1: Segregation of Duties with ESP Organizational Structures

The Evident Security Platform (ESP) has the ability to control access to security reports based on a hierarchical organization structure. You can design the structure to match your company’s organizational structure, or one that makes sense with your security remediation workflow.

Here’s the overall access structure for ESP:

You must make the decision where to place the Users and External accounts. Visibility of ESP security reports is completely controlled in the Users window in the ESP Control Panel. The following is an example of how complex the reporting structure can be:

As far as security assessments are concerned, someone with broad security responsibilities throughout a company should have visibility into every sub organization and team, while a software developer should only have visibility into reports for his particular team. Visibility into organizations/sub organizations/teams is explicit. If it is required that a user should see a particular team’s report (or all reports), that user must be added every time a new team and external account is created.

In the example below, we take a fictitious user, user@xxxxx.com and give him access to all teams. We can easily remove access by unchecking the sub organization or team in the list and clicking save.

This would generate a report (and dashboard) view as follows:

Step 2: Adding User Accounts

The next step is to add user accounts to the appropriate sections of your organization.

  1. Click Control Panel.

  2. Click Users.

    Addingusers2.PNG
  3. Click New.

  4. Enter the relevant information about your new user and assign him to the appropriate sub-organizations and teams as you desire.

  5. When finished, click Save.

The new user will be able to examine data only through the lense of the organization's levels you assigned to him (from the options you created in Step 1).

Step 3: Examining the Data

An alert is a potential risk identified by either a signature or a custom signature and collected in a report. ESP continually scans all of your assigned AWS business resources and collects all alerts into an easy­-to­-read aggregated report. This allows you and your security team to review all available information about your assets and to make an informed decision about the necessary steps to them as needed.

Initially, Evident Security Platform will be set to the Security Best Practices as recommended by Amazon Web Services. The next step will be to ensure that the signatures return alerts that contain actionable intelligence to meet your business needs.

Alert Status

Alerts are generated according to the following classifications:

Alert Severity

Every alert generated is placed into a severity level category designed to help you prioritize resources to address identified risks.

Each alert is tagged with a specific severity status indicating:

Step 4: Relevant Data Configuration

The next step is to examine the alerts from Step 3 and compare the triggered alerts with your specific business rules to determine if there are some signatures that should be configured differently to meet your business needs.

If a signature isn’t configured to exactly your needs, it can be suppressed or in some cases modified. This step will walk you through suppressing alerts.

  1. Take a look at the alerts generated. Click on the low risk category to further drill down into these alerts. This will allow you to review and evaluate the Evident.io defaults and best practices.

  2. The Security Report details all of the Low Risk alerts generated for your account.
  3. The EBS Snapshot Alerts are a good example of how your business rules may differ from the best practices recommended by Evident.io. The EBS Snapshot signature generates these alerts if you do not take a snapshot of your volumes every fifteen days.
    There are a number of logical business reasons why your policies might be different.
    1. You might not take snapshots from your development account and in this case, you might want to suppress all of this type of alerts for this account.
    2. Your volume might be part of a RAID array of disks and therefore you will want to suppress this alert for a few, specific volumes
    3. You might take snapshots at a different frequency and therefore you will want to customize the signature to match your business rules.
  4. Click Suppression Options at the bottom of the EBS Snapshot alert.

  5. There are three different options you might take:
    1. If you want to suppress this alert for a few, specific volumes, then select Suppress this Alert. This alert will be suppressed for this individual volume. This signature will generate alerts for all other volumes, in all other regions.
    2. If you might want to suppress all of this type of alerts for this account, then select Suppress this Signature. Evident will suppress this alert across all volumes, in all regions, by default. (This may be customized as needed.)
    3. You might take snapshots at a different frequency and therefore you will want to customize the signature to match your business rules. This requires you to modify an existing signature. For more information, see Step 5: Modifying an Existing Signature.
    4. We recommend avoiding suppressing entire regions because you become blind to any alerts that might be generated from this region. This is important because an alert might hint to unauthorized usage in that region, if for example, someone begins to run new services in that region. If a region isn’t being used, we recommend that instead of suppressing alerts, you simply eliminate the VPCs in that region.
  6. For the purpose of this example, we’re going to suppress this alert to meet your business needs. Select Suppress Alert.

  7. Enter the business reason for this alert suppression.
  8. Click Customize Configuration.

  9. The Suppression Configuration wizard allows you to select the accounts and regions from which you wish to suppress these alerts. If you wanted to ensure that development accounts did not receive this alerts, you could suppress this alerts only for those accounts. You will need to create a suppression for each volume you do not want Evident to generate an alert for.

Step 5: Modifying an Existing Signature

Sometimes you want to modify an existing signature to create a custom signature that meets your business needs. For the purpose of this example, we’re going to presume that you want to customize the signature AWS:EC2-001 to alert you if you haven’t taken a snapshot of your volumes within the last 45 days, rather than 30 days.

  1. Click Control Panel.
  2. Click Signatures.
  3. Click Search.

    cs1.PNG

  4. Enter AWS:EC2-001 in the Identifier field and click Search.

  5. Click Copy.

    cs3.PNG

  6. Enter the appropriate information in the above fields. This allows you to name your custom signature, alter the risk level, and create your own Identifier. In this case, we changed the Identifier, by adding the letter A at the end.

    cs4.PNG

  7. Assign the region and External account you want associated with your custom signature.
  8. The next step is to alter the code so that this signature generates an alert every 45 days instead of the standard 30.

    cs5.PNG

  9. Change 30.days.ago to 45.days.ago. Review the error messages and modify all references to 30 days old to 45 days old.

    cs8.PNG

  10. Once you are finished, click Run.
  11. You have now created a new custom signature that will generate an alert for you if your snapshot for your volume is older than 45 days.

Step 6: Cleaning Up Unused Regions

Now that you have configured your alerts to better suit your needs, the next step is to clean up your unused regions for better security.

If you are receiving alerts from a region where you have no resources, then you should remove those VPCs. If needed at a later time, you can always re-add the VPC by calling AWS Support. By removing the VPC, you help prevent unexpected resources from being launched into a region. The alternative is to suppress an entire region, but then you lose visibility into the activity within that region.

You can see that there are alerts coming from ap_southeast_2, but for the purpose of this example we know that your company has no resources there.

To Clean Up Unused Regions:

  1. Log into your AWS account and access VPC Dashboard for the region you do not use.

    clean3

  2. Verify that you have no instances in the specified region.

    clean4

  3. Select the VPC you wish to delete.

    clean5

  4. From the Actions pulldown menu, select Delete VPC.

    clean6

  5. Click the appropriate radio buttons and click Yes, Delete.

    clean7

  6. It will take a few moments for AWS to delete the VPC, but once it has, those alerts will no longer be triggered.

Step 7: Setting Your Daily Email Report

Evident.io generates a single email report every twenty-four hours at 9 AM your local time.

To change this default time:

  1. Click Control Panel.
  2. Click Users.

  3. Find your account and click Edit.

  4. Alter the timezone so that your daily email is sent at 9 AM.
  5. Click Save.

Step 8: Retrieving Your New Data

Now that you have configured the signatures to generate alerts that better meet your needs, you should look at your reports to view your new alerts.

  1. Click Reports.
  2. Click Run Reports and select your desired team.

Step 9: Conclusion

Now that you’ve completed this process, your alerts have been customized to give you the best information when you need it. You will receive a daily 24-hour email report that gives a general overview of your alerts. (You may adjust the delivery of this report at any time by repeating Step 7: Setting Your Daily Email Report.)


Last updated on July 07, 2016 by Jason Andrew

Auto-Remediation via Lambda Walkthrough

The goal of this walkthrough is to help you setup, create, and then test a Lambda function for your AWS service. For more information, please see AWS Lambda.

A core design goal and philosophy at Evident.io is to provide our customers the most robust configuration security alerting platform on AWS and the remediation guidance to make those alerts actionable. Using our SNS integration, customers can extend that philosophy to make sure alerts are automatically remediated before you, or malicious actors, even know there’s an issue. Imagine revoking an EC2 security group rule that allows ingress traffic from the world minutes after it’s been detected by ESP.

This document will walk you through the steps to configure our SNS integration to send Evident.io alerts as events for Lambda to remediate on your behalf.

We recommend that you select ESP alerts to remediate based one of the following criteria:

Step 1: ESP SNS Integration

  1. Follow the instructions for setting up the ESP SNS Integration. When configuring, make sure you configure for only one Team and one signature. Note: If there is more than one AWS account assigned to a Team, this will not work for more than one account until a future integrations enhancement is released.
  2. In the SNS topic you’ve set up, subscribe your email address, if only on a temporary basis, for troubleshooting purposes.

Step 2: Create IAM Policy and Role

The next step is to create the IAM Policy and Role that will give the Lambda function execution privileges.

  1. In the IAM Console under Policies, click Create Policy.
  2. Select Policy Generator.
  3. Select EC2 for service.
    1. Actions are DescribeSecurityGroups and RevokeSecurityGroupsIngress
    2. Resource name is *
    3. Add Statement.
    4. Name your policy and click Create Policy.
  4. In the IAM Console under Roles, click Create New Role.
    1. Name your role.
    2. Role type is AWS Lambda.
    3. Attach the policy created above.
    4. Additionally, attach the AWSLambdaBasicExecutionRole policy, to allow the Lambda function to send execution logs to CloudWatch Logs.

Step 3: Create the Lambda function in the AWS Console

The next step is to create the Lambda function in the AWS Console.

  1. Select the sns-message-python blueprint.
  2. Event source type is SNS.
  3. Select the SNS topic you created for the integration.
  4. In the next screen, name your function, give it a description and leave the Python runtime version as is.
  5. Copy and paste the Lambda code from the following link: https://github.com/EvidentSecurity/aws-lambda/blob/master/autoremediate/autoremediate-EC2-002.py
  1. This sample code works across regions, so you can create the Lambda function in whichever region makes sense for your scenario.
  2. Leave the Lambda function handler as is, but select the IAM Role you created above in the drop-down menu.
  3. Under Advanced Settings, set the timeout value to 1 minute, 30 seconds. This is due to the fact that when multiple ESP alerts are sent to Lambda, it will take Lambda longer than the default 30 seconds to execute each lambda function.
  4. Select No VPC access is required.
  5. In the next screen, you can select the SNS topic above for Event Source, or leave as is and configure later once you are comfortable with the Lambda function code. If you click on Enable event source, the Lambda function will be subscribed to the SNS topic above.

Step 4: Testing and Verifying the Lambda Function

After the Lambda function is created, you will need to configure a test event to test your function.

  1. It is recommended to generate one SNS alert message to your email address per the subscription above, and copy the entire body of the message for your test event.
    1. To generate an alert, create a FAIL condition for the Global SSH signature.
    2. Create an EC2 security group, and add a rule that allows TCP port 22 to the entire internet, or “0.0.0.0/0”.
    3. Make sure no instances are associated with that security group
    4. This will be your test security group.
  2. In the Lambda function console, click on Actions -> Configure test event.
  3. Select the SNS sample test event.
  4. Replace the entire Section that begins with "Sns:", but inclusive only of the beginning and ending curly braces that will come from the email message generated via SNS.
  5. Execution logs are sent to a CloudWatch Logs log group by the same name as your Lambda function.

Last updated on June 14, 2016 by Jason Andrew