Install the agent on an AMI or WorkSpace bundle

Read this page if you want to launch new Amazon EC2 instances and Amazon WorkSpaces with the agent 'baked in'.

If instead you want to:

'Baking the agent' is the process of launching an EC2 instance based on a public AMI, installing the agent on it, and then saving this custom EC2 image as an AMI. This AMI (with the agent 'baked in') can then be selected when launching new Amazon EC2 instances.

Similarly, if you want to deploy the Deep Security Agent on multiple Amazon WorkSpaces, you can create a custom 'WorkSpace bundle' that includes the agent. The custom bundle can then be selected when launching new Amazon WorkSpaces.

To bake an AMI and create a custom WorkSpace bundle with a pre-installed and pre-activated agent, follow these steps:

  1. Add your AWS account to Deep Security Manager
  2. Set the communication direction
  3. Configure the activation type
  4. Launch a 'master' Amazon EC2 instance or Amazon WorkSpace
  5. Deploy an agent on the master
  6. Verify that the agent was installed and activated properly
  7. (Recommended) Set up policy auto-assignment
  8. Create an AMI or custom WorkSpace bundle based on the master
  9. Use the AMI

Add your AWS account to Deep Security Manager

You'll need to add your AWS accounts to Deep Security Manager. These are the AWS accounts that will contain the Amazon EC2 instances and Amazon WorkSpaces that you want to protect.

See About adding AWS accounts for details.

Set the communication direction

You'll need to set the communication direction: either agent-initiated, manager-initiated, or bidirectional.

See Install the agent on Amazon EC2 and WorkSpaces > Set the communication direction for instructions.

Configure the activation type

You'll need to indicate whether you'll allow agent-initiated activation.

See Install the agent on Amazon EC2 and WorkSpaces > Configure the activation type for instructions.

Launch a 'master' Amazon EC2 instance or Amazon WorkSpace

You'll need to launch a 'master' Amazon EC2 instance or Amazon WorkSpace. The master instance is the basis for the EC2 AMI or WorkSpace bundle that you will create later.

  1. In AWS, launch an Amazon EC2 instance or Amazon WorkSpace. See the Amazon EC2 documentation and Amazon WorkSpaces documentation for details.
  2. Call the instance 'master'.

Deploy an agent on the master

You'll need to install and activate the agent on the master. During this process, you can optionally install a policy.

See Install the agent on Amazon EC2 and WorkSpaces > Deploy agents to your Amazon EC2 instances and WorkSpaces for instructions.

Ideally, if you bake the agent into your AMI or workspace bundle and then want to use a newer agent later on, you should update the bundle to include the new agent. However, if that's not possible, you can use the Automatically upgrade agents on activation setting so when the agent in the AMI or bundle activates itself, Deep Security Manager can automatically upgrade the agent to the latest version. For details, see Automatically upgrade agents on activation.

Verify that the agent was installed and activated properly

You should verify that the agent was installed and activated properly on the master before proceeding.

See Install the agent on Amazon EC2 and WorkSpaces > Verify that the agent was installed and activated properly for instructions.

(Recommended) Set up policy auto-assignment

You may need to set up policy auto-assignment depending on how you deployed the agent on the master:

  • If you used a deployment script, then a policy has already been assigned, and no further action is required.
  • If you manually installed and activated the agent, no policy was assigned to the agent, and one should be assigned now so that the master is protected. The Amazon EC2 instances and Amazon WorkSpaces that are launched based on the master will also be protected.

If you want to assign a policy to the master, as well as auto-assign a policy to future EC2 instances and WorkSpaces that are launched using the master, follow these instructions:

  1. In Deep Security Manager, create an event-based task with these parameters: 
    • Set the Event to Agent-Initiated Activation.
    • Set Assign Policy to the policy you want to assign.
    • (Optional) Set a condition to Cloud Instance Metadata, with
      • a tagKey of EC2 and a tagValue.* of True (for an EC2 instance)
        OR
      • a tagKey of WorkSpaces and a tagValue.* of True (for WorkSpaces)

      The above event-based task says:
      When an agent is activated, assign the specified policy, on condition that EC2=true or WorkSpaces=true exists in the Amazon EC2 instance or WorkSpace.
      If that key/value pair does not exist in the EC2 instance or WorkSpace, then the policy is not assigned (but the agent is still activated). If you do not specify a condition, then the policy is assigned on activation unconditionally.
      For details on creating event-based tasks, see Automatically assign policies by AWS instance tags.

  2. If you added a key/value pair in Deep Security Manager in the previous step, do the following:
    1. Go to AWS.
    2. Find your master EC2 instance or WorkSpace.
    3. Add tags to the master with a Key of EC2 or WorkSpaces and a Value of True.
      For details, see this Amazon EC2 documentation on tagging, and this Amazon WorkSpace documentation on tagging.
      You have now set up policy auto-assignment. New Amazon EC2 instances and Amazon WorkSpaces that are launched using the master are activated automatically (since the agent is pre-activated on the master), and then auto-assigned a policy through the event-based task.
  3. On the master EC2 instance or WorkSpace, reactivate the agent by re-running the activation command on the agent, or by clicking the Reactivate button in Deep Security Manager. For details, see Activate the agent
    The re-activation causes the event-based task to assign the policy to the master. The master is now protected.

You are now ready to bake your AMI or create a custom WorkSpace bundle.

Create an AMI or custom WorkSpace bundle based on the master

You now have an AMI or WorkSpace bundle that includes a pre-installed and pre-activated agent.

Use the AMI

Now that you have a custom AMI or WorkSpace bundle, you can use it as the basis for future Amazon EC2 instances and Amazon WorkSpaces. With the custom AMI or bundle, Deep Security Agent starts up automatically, activates itself, and applies the protection policy assigned to it. It appears in Deep Security Manager with a Status of Managed and a green dot next to it.