Managing security agent manually for Amazon EC2 instance - Amazon GuardDuty

Managing security agent manually for Amazon EC2 instance

After you enable Runtime Monitoring, you will need to install the GuardDuty security agent manually. By installing the agent, GuardDuty will receive the runtime events from the Amazon EC2 instances.

To manage the GuardDuty security agent, you must create an Amazon VPC endpoint and then follow the steps to install the security agent manually.

Creating Amazon VPC endpoint manually

Before you can install the GuardDuty security agent, you must create an Amazon Virtual Private Cloud (Amazon VPC) endpoint. This will help GuardDuty receive the runtime events of your Amazon EC2 instances.

Note

There is no additional cost for the usage of the VPC endpoint.

To create a Amazon VPC endpoint
  1. Sign in to the AWS Management Console and open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, under VPC private cloud, choose Endpoints.

  3. Choose Create Endpoint.

  4. On the Create endpoint page, for Service category, choose Other endpoint services.

  5. For Service name, enter com.amazonaws.us-east-1.guardduty-data.

    Make sure to replace us-east-1 with your AWS Region. This must be the same Region as the Amazon EC2 instance that belongs to your AWS account ID.

  6. Choose Verify service.

  7. After the service name is successfully verified, choose the VPC where your instance resides. Add the following policy to restrict Amazon VPC endpoint usage to the specified account only. With the organization Condition provided below this policy, you can update the following policy to restrict access to your endpoint. To provide the Amazon VPC endpoint support to specific account IDs in your organization, see Organization condition to restrict access to your endpoint.

    { "Version": "2012-10-17", "Statement": [ { "Action": "*", "Resource": "*", "Effect": "Allow", "Principal": "*" }, { "Condition": { "StringNotEquals": { "aws:PrincipalAccount": "111122223333" } }, "Action": "*", "Resource": "*", "Effect": "Deny", "Principal": "*" } ] }

    The aws:PrincipalAccount account ID must match the account containing the VPC and VPC endpoint. The following list shows how to share the VPC endpoint with other AWS account IDs:

    • To specify multiple accounts to access the VPC endpoint, replace "aws:PrincipalAccount: "111122223333" with the following block:

      "aws:PrincipalAccount": [ "666666666666", "555555555555" ]

      Make sure to replace the AWS account IDs with the account IDs of those accounts that need to access the VPC endpoint.

    • To allow all the members from an organization to access the VPC endpoint, replace "aws:PrincipalAccount: "111122223333" with the following line:

      "aws:PrincipalOrgID": "o-abcdef0123"

      Make sure to replace the organization o-abcdef0123 with your organization ID.

    • To restrict accessing a resource by an organization ID, add your ResourceOrgID to the policy. For more information, see aws:ResourceOrgID in the IAM User Guide.

      "aws:ResourceOrgID": "o-abcdef0123"
  8. Under Additional settings, choose Enable DNS name.

  9. Under Subnets, choose the subnets in which your instance resides.

  10. Under Security groups, choose a security group that has the in-bound port 443 enabled from your VPC (or your Amazon EC2 instance). If you don't already have a security group that has an in-bound port 443 enabled, see Create a security group in the Amazon EC2 User Guide for Linux Instances.

    If there is an issue while restricting the in-bound permissions to your VPC (or instance), provide the support to in-bound 443 port from any IP address (0.0.0.0/0).

Installing the security agent manually

GuardDuty provides the following two methods to install the GuardDuty security agent on your Amazon EC2 instances:

  • Method 1 - By using AWS Systems Manager – This method requires your Amazon EC2 instance to be AWS Systems Manager managed.

  • Method 2 - By using RPM installation scripts – You can use this method whether or not your Amazon EC2 instances are AWS Systems Manager managed.

Method 1 - By using AWS Systems Manager

To use this method, make sure that your Amazon EC2 instances are AWS Systems Manager managed and then make install the agent.

AWS Systems Manager managed Amazon EC2 instance

Use the following steps to make your Amazon EC2 instances AWS Systems Manager managed.

  • AWS Systems Manager helps you manage your AWS applications and resources end-to-end and enable secure operations at scale.

    To manage your Amazon EC2 instances with AWS Systems Manager, see Setting up Systems Manager for Amazon EC2 instances in the AWS Systems Manager User Guide.

  • The following table shows the new GuardDuty managed AWS Systems Manager documents:

    Document name Document type Purpose

    AmazonGuardDuty-RuntimeMonitoringSsmPlugin

    Distributor

    To package the GuardDuty security agent.

    AmazonGuardDuty-ConfigureRuntimeMonitoringSsmPlugin

    Command

    To run installation/un-installation script to install the GuardDuty security agent.

    For more information about AWS Systems Manager, see Amazon EC2 Systems Manager Documents in the AWS Systems Manager User Guide.

To install the GuardDuty agent for Amazon EC2 instance by using AWS Systems Manager
  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Documents

  3. In Owned by Amazon, choose AmazonGuardDuty-ConfigureRuntimeMonitoringSsmPlugin.

  4. Choose Run Command.

  5. Enter the following Run Command parameters

    • Action: Choose Install.

    • Installation Type: Choose Install or Uninstall.

    • Name: AmazonGuardDuty-RuntimeMonitoringSsmPlugin

    • Version: If this remains empty, you'll get latest version of the GuardDuty security agent. For more information about the release versions, GuardDuty security agent for Amazon EC2 instances.

  6. Select the targeted Amazon EC2 instance. You can select one or more Amazon EC2 instances. For more information, see AWS Systems Manager Running commands from the console in the AWS Systems Manager User Guide

  7. Validate if the GuardDuty agent installation is healthy. For more information, see Validating GuardDuty security agent installation status.

Method 2 - By using RPM installation scripts

Important

We strongly recommend verifying the GuardDuty security agent RPM signature before installing it on your machine.

  1. Verify the GuardDuty security agent RPM signature

    1. Download the appropriate public key, signature of x86_64 RPM, signature of arm64 RPM, and the corresponding access link to the RPM scripts hosted in Amazon S3 buckets

      You can use the following templates to form the public key, signature of x86_64 RPM, signature of arm64 RPM, and the corresponding access link to the RPM scripts. Replace the value of the AWS Region, AWS account ID, and the GuardDuty agent version to access the RPM scripts.

      • Public key:

        s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/publickey.pem
      • GuardDuty security agent RPM signature:

        Signature of x86_64 RPM
        s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/x86_64/amazon-guardduty-agent-1.1.0.x86_64.sig
        Signature of arm64 RPM
        s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/arm64/amazon-guardduty-agent-1.1.0.arm64.sig
      • Access links to the RPM scripts in Amazon S3 bucket:

        Access link for x86_64 RPM
        s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/x86_64/amazon-guardduty-agent-1.1.0.x86_64.rpm
        Access link for arm64 RPM
        s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/arm64/amazon-guardduty-agent-1.1.0.arm64.rpm

      In the following command to download appropriate public key, signature of x86_64 RPM, signature of arm64 RPM, and the corresponding access link to the RPM scripts hosted in Amazon S3 buckets, make sure to replace the account ID with the appropriate AWS account ID and the Region with your current Region.

      aws s3 cp s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/x86_64/amazon-guardduty-agent-1.1.0.x86_64.rpm ./amazon-guardduty-agent-1.1.0.x86_64.rpm aws s3 cp s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/x86_64/amazon-guardduty-agent-1.1.0.x86_64.sig ./amazon-guardduty-agent-1.1.0.x86_64.sig aws s3 cp s3://694911143906-eu-west-1-guardduty-agent-rpm-artifacts/1.1.0/publickey.pem ./publickey.pem
      AWS Region Region name AWS account ID
      eu-west-1 Europe (Ireland) 694911143906
      us-east-1 US East (N. Virginia) 593207742271
      us-west-2 US West (Oregon) 733349766148
      eu-west-3 Europe (Paris) 665651866788
      us-east-2 US East (Ohio) 307168627858
      eu-central-1 Europe (Frankfurt) 323658145986
      ap-northeast-2 Asia Pacific (Seoul) 914738172881
      eu-north-1 Europe (Stockholm) 591436053604
      ap-east-1 Asia Pacific (Hong Kong) 258348409381
      me-south-1 Middle East (Bahrain) 536382113932
      eu-west-2 Europe (London) 892757235363
      ap-northeast-1 Asia Pacific (Tokyo) 533107202818
      ap-southeast-1 Asia Pacific (Singapore) 174946120834
      ap-south-1 Asia Pacific (Mumbai) 251508486986
      ap-southeast-3 Asia Pacific (Jakarta) 510637619217
      sa-east-1 South America (São Paulo) 758426053663
      ap-northeast-3 Asia Pacific (Osaka) 273192626886
      eu-south-1 Europe (Milan) 266869475730
      af-south-1 Africa (Cape Town) 197869348890
      ap-southeast-2 Asia Pacific (Sydney) 005257825471
      me-central-1 Middle East (UAE) 000014521398
      us-west-1 US West (N. California) 684579721401
      ca-central-1 Canada (Central) 354763396469
      ap-south-2 Asia Pacific (Hyderabad) 950823858135
      eu-south-2 Europe (Spain) 919611009337
      eu-central-2 Europe (Zurich) 529164026651
      ap-southeast-4 Asia Pacific (Melbourne) 251357961535
      il-central-1 Israel (Tel Aviv) 870907303882
    2. Import the public key to the database

      gpg --import publickey.pem

      gpg shows import successfully

      gpg: key 093FF49D: public key "AwsGuardDuty" imported gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1)
    3. Verify the signature

      gpg --verify amazon-guardduty-agent-1.1.0.x86_64.sig amazon-guardduty-agent-1.1.0.x86_64.rpm

      If verification passes, you will see a message similar to the result below. You can now proceed to install the GuardDuty security agent using RPM.

      Example output:

      gpg: Signature made Fri 17 Nov 2023 07:58:11 PM UTC using ? key ID 093FF49D gpg: Good signature from "AwsGuardDuty" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 7478 91EF 5378 1334 4456 7603 06C9 06A7 093F F49D

      If verification fails, it means the signature on RPM has been potentially tampered. You must remove the public key from the database and retry the verification process.

      Example:

      gpg: Signature made Fri 17 Nov 2023 07:58:11 PM UTC using ? key ID 093FF49D gpg: BAD signature from "AwsGuardDuty"
    4. Remove the public key from the database.

      gpg --delete-keys AwsGuardDuty
  2. Connect with SSH from Linux or macOS.

  3. Install the GuardDuty security agent by using the following command:

    sudo rpm -ivh amazon-guardduty-agent-1.1.0.x86_64.rpm
  4. Validate if the GuardDuty agent installation is healthy. For more information about the steps, see Validating GuardDuty security agent installation status.

  5. (Optional) remove the GuardDuty security agent by using the following command:

    sudo rpm -ev amazon-guardduty-agent

Out of memory error

If you experience an out-of-memory error while installing or updating the GuardDuty security agent for Amazon EC2 manually, see Troubleshooting out of memory error.

Validating GuardDuty security agent installation status

To validate if the GuardDuty security agent is healthy
  1. Connect with SSH from Linux or macOS.

  2. Run the following command to check the status of the GuardDuty security agent:

    sudo systemctl status amazon-guardduty-agent

If you want to view the security agent installation logs, they are available under /var/log/amzn-guardduty-agent/.

To view the logs, do sudo journalctl -u amazon-guardduty-agent.

Updating the GuardDuty security agent manually

You can update the GuardDuty security agent by using the Run command. You can follow the same steps that you used to install the GuardDuty security agent.