AWS Security Blog

How to Use Amazon Alexa to Get Amazon GuardDuty Statistics and Findings

You can always view and manage your Amazon GuardDuty findings on the Findings page in the GuardDuty console or by using GuardDuty APIs with the AWS CLI or SDK. But there’s a quicker and easier way, you can use Amazon Alexa as a conversational interface to review your GuardDuty findings. With Alexa, you can build natural voice experiences and create a more intuitive way of interacting GuardDuty.

In this post, I show you how to deploy a sample custom Alexa skill and use an Alexa-enabled device, such as Amazon Echo, to get information about GuardDuty findings across your AWS accounts and regions. The information provided by this sample skill gives you a broad overview of GuardDuty finding statistics, severities, and descriptions. When you hear something interesting, you can log in to the GuardDuty console or another analysis tool to investigate the findings data.

Note: Although not covered here, you can also deploy this sample skill using Alexa for Business, which you can use to make skills available to your shared devices and enrolled users without having to publish them to the Alexa skills store.

Prerequisites

To complete the steps in this post, make sure you have:

  • A basic understanding of Alexa Custom Skills, which is helpful for deploying the sample skill described here. If you’re not already familiar with Alexa custom skill concepts and terminology, you might want to review the following documentation resources.
  • An AWS account with GuardDuty enabled in one or more AWS regions.
  • An Alexa-enabled device, such as Amazon Echo.
  • An Amazon Developer Account.

Solution overview

This diagram shows how the CloudFormation template creates the Lambda function for the sample Alexa skill.

CloudFormation template creating the Lambda function

Here’s how the solution works, as shown in the diagram:

  1. The user opens the skill by saying “Alexa, ask GuardDuty” or “Alexa, open GuardDuty.”
  2. After the skill opens, the user states a supported intent, such as “Get flash briefing.”
  3. The Alexa service passes the intent to the custom skill that uses the Lambda function to call the GuardDuty API and request the information.
  4. The GuardDuty service returns the requested information and the Lambda function returns the response to the Alexa service.
  5. The Alexa service delivers the audio response via the Alexa-enabled device.

Solution deployment

This sample solution includes three parts:

  1. Deploy the Lambda function by using the CloudFormation Template.
  2. Create the custom skill in the Alexa developer console.
  3. Test the skill using an Alexa-enabled device.

Deploy the Lambda function with the CloudFormation Template

For this next step, make sure you deploy the template within the AWS account you want to monitor.

  1. To deploy the Lambda function in the N. Virginia region (see the note below), you can use the CloudFormation template provided by clicking the following link: load the supplied template. In the CloudFormation console, on the Select Template page, select Next.

    Note: The following AWS regions support hosting custom Alexa skills: US East (N. Virginia), Asia Pacific (Tokyo), EU (Ireland), West (Oregon). If you want to deploy in a region other than N. Virginia, you will first need to upload the custom skill’s Lambda deployment package (zip file with code) to an S3 bucket in the selected region.

  2. After you load the template, provide the following input parameters:
    Input parameter Input parameter description
    FLASHREGIONS Comma separated list of region Ids with NO spaces to include in flash briefing stats. At least one region is required. Make sure GuardDuty is enabled in regions declared.
    MAXRESP Max number of findings to return in a response.
    ArtifactsBucket S3 Bucket where Lambda deployment package resides. Leave the default for N. Virginia.
    ArtifactsPrefix Path in S3 bucket where Lambda deployment package resides. Leave the default for N. Virginia.
  3. On the Specify Details page, enter the input parameters (see above), and then select Next.
     
    The Specify Details page
     
  4. On the Options page, accept the default values, and then select Next.
  5. On the Review page, confirm the details, and then select Create. The stack will be created in approximately 2 minutes.

Create the custom skill in the Alexa developer console

In the second part of this solution implementation, you will create the skill in the Amazon Developer Console.

  1. Sign in to the Alexa area of the Amazon Developer Console, select Your Alexa Consoles in the top right, and then select Skills.
  2. Select Create Skill.
  3. For the name, enter Ask Amazon GuardDuty, and then select Next.
  4. In the Choose a model to add to your skill page, select Custom, and then select Create skill.
  5. Select the JSON Editor and paste the contents of the alexa_ask_guardduty_skill.json file into the code editor, and overwrite the existing content. This file contains the intent schema which defines the set of intents the service can accept and process.
     
    JSON Editor interface
     
  6. Select Save Model, select Build Model, and then wait for the build to complete.
  7. When the model build is complete, on the left side, select Endpoint.
  8. In the Endpoint page, in the Service Endpoint Type section, select AWS Lambda ARN (Amazon Resource Name).
  9. In the Default Region field, copy and paste the value from the CloudFormation Stack Outputs key named AlexaAskGDSkillArn. Leave the default values for other options, and then select Save Endpoints.
     
    Endpoint interface
     

Because you’re not publishing this skill, you don’t need to complete the Launch section of the configuration. The skill will remain in the “Development” status and will only be available for Alexa devices linked to the Amazon developer account used to create the skill. Anyone with physical access to the linked Alexa-enabled device can use the custom skill. As a best practice, I recommend that you delete the Lambda trigger created by the CloudFormation template and add a new one with Skill ID verification enabled.

Test the skill using an Alexa-enabled device

Now that you’ve deployed the sample solution, the next step is to test the skill. Make sure you’re using an Alexa-enabled device linked to the Amazon developer account used to create the skill. Before testing, if there are no current GuardDuty findings available, you can generate sample findings in the console. When you generate sample findings, GuardDuty populates your current findings list with one sample finding for each supported finding type.

You can test using the following voice commands:

  • “Alexa, Open GuardDuty” — Opens the skill and provides a welcome response. You can also use “Alexa, Ask GuardDuty”.
  • “Get flash briefing” — Provides global and regional counts for low, medium, and high severity findings. The regions declared in the FLASHREGIONS parameter are included. You can also use “Ask GuardDuty to get flash briefing” to bypass the welcome message. You can learn more about GuardDuty severity levels in the documentation.

For the next set of commands, you can specify the region, use region names such as <Virginia>, <Oregon>, <Ireland>, and so on:

  1. “Get statistics for region” — Provides regional counts for low, medium, and high severity findings.
  2. “Get findings for region” — Returns finding information for the requested region. The number of findings returned is configured in the MAXRESP parameter.
  3. “Get <high/medium/low> severity findings for region” – Returns finding information with the minimum severity requested as high, medium, or low. The number of findings returned is configured in the MAXRESP parameter.
  4. “Help” — Provides information about the skill and supported utterances. Also provides current configuration for FLASHREGIONS and MAXRESP.

In addition to the voice response, this skill shows the response text within Home Cards in the Alexa mobile application.

Conclusion

You can use this sample solution to get GuardDuty statistics and findings through the Alexa conversational interface. You’ll be able to identify findings that require further investigation quickly. This solution’s code is available on GitHub.

If you have comments about this blog post, submit them in the Comments section below. If you have questions about using GuardDuty, start a thread in the GuardDuty forum or contact AWS Support. If you questions about Alexa, submit them in the Alexa Developer Forum or the Alexa for Business Forum.