Agent installation guide
Overview
This guide offers examples for using Contrast Security’s Java agent within an AWS EC2 environment. Amazon Elastic Compute Cloud (Amazon EC2) provides scalable computing capacity in the Amazon Web Services (AWS) Cloud. Using Amazon EC2 eliminates your need to invest in hardware up front, so you can develop and deploy applications faster.
We encourage you to take this guide, make it your own, and distribute it to teams who need to instrument applications this way.
The main portion of the guide details some of the popular methods customers use to instrument a Java application running on an Amazon AWS EC2 linux based environment.
Main steps
There are 2 different approaches provided to install the Contrast Agent into the EC2 instance
Method 1: Install Contrast agent via Contrast API:
- Launch an EC2 instance
- Create a userdata script to download/install the Contrast Agent on instance launch
- Configure the EC2 instance to leverage the Contrast agent
- Instrument your application
Method 2: Install Contrast agent via yum repository:
- Launch an EC2 instance
- Create a userdata script to add the contrast yum repository to the EC2 instance
- Install the Contrast Agent via the yum repository
- Configure the EC2 instance to leverage the Contrast agent
- Instrument your application
Supported technologies
Before you begin, please be sure Contrast supports your preferred tools and environments for Java:
https://docs.contrastsecurity.com/en/java-supported-technologies.html
This guide assumes you have
- Some familiarity with how EC2 and Java works
- Some familiarity with AWS Secret Manager
- API Credentials available to download the agent via the Contrast API
- The information needed to connect the Contrast Java agent to the Contrast dashboard
- You have followed the EC2 getting started tutorial here:
- You have installed and configured the AWS CLI for access to your AWS instance
Instructions
Preliminary setup
Using the AWS CLI add the required API credentials to the AWS Secret Manager
In your command line terminal issue the following 2 commands:
aws secretsmanager create-secret --region <AWS_REGION> --name <SECRET_NAME_API> --secret-string <YOUR_API_KEY>
|
aws secretsmanager create-secret --region <AWS_REGION> --name <SECRET_NAME_AUTH> --secret-string <YOUR_AUTHORIZATION_HEADER>
|
Where:
<SECRET_NAME_API>
= The name of the secret in the AWS Secret Manager you wish to create to store the user api key<SECRET_NAME_AUTH>
= The name of the secret in the AWS Secret Manager you wish to create to store the user api authorization header<YOUR_API_KEY>
= The api key of the user that will be used to access the Contrast API<YOUR_AUTHORIZATION_HEADER>
= The authorization header of the user that will be used to access the Contrast API
This document lists how to find your user api keys:
https://docs.contrastsecurity.com/en/personal-keys.html
Note:
It is recommended to create a specific api user for programmatic access to the Contrast API.
Create an IAM role to allow access to the AWS Secret Manager
In the AWS console select IAM and then Roles in the subsequent screen:
- Click on the “Create Role” button
- Select AWS Service and EC2
- Click on the “Next: Permissions” button
- Search For SecretsManagerReadWrite
- Select the checkbox next to the SecretsManagerReadWrite entry
- Click on “Next: Tags” and create any appropriate tags for the role
- Click on “Next: Review”
- Name Your IAM Role as appropriate (referenced in this document as <IAM_ROLE>)
Install Contrast Java agent via EC2 UserData
These instructions will guide you through installing the Contrast Java agent on an EC2 instance
Create the EC2 instance
In the AWS EC2 console select the “Launch Instance” option to begin the EC2 launch wizard
Within the Launch Instance Wizard
- Select “Amazon Linux 2 AMI (64-bit x86)” as the Amazon Machine Image
- Select “t2.micro” as the Instance Type or as appropriate for your application
- Select “Next: Configure Instance Details”
- Within the Configure Instance Details screen
- Select the IAM role <IAM_ROLE> created in the Preliminary step
- In the User data section paste the following script:
#!/bin/bash |
Where:
<SECRET_NAME_API>
= The name of the secret storing the api key in the AWS Secret Manager created in the preliminary step<SECRET_NAME_AUTH>
= The name of the secret storing the authorization header in the AWS Secret Manager created in the preliminary step<ORGANIZATION_ID>
= The Organization ID of your Organization within Contrast TeamServer
- Click on “Review and Launch”
- Click on “Launch” to launch the EC2 instance
Install Contrast Java agent via yum repository
These instructions will guide you through installing the Contrast Java agent on an EC2 instance
Create the EC2 instance
In the AWS EC2 console select the “Launch Instance” option to begin the EC2 launch wizard
Within the Launch Instance Wizard
- Select “Amazon Linux 2 AMI (64-bit x86)” as the Amazon Machine Image
- Select “t2.micro” as the Instance Type or as appropriate for your application
- Select “Next: Configure Instance Details”
- Within the Configure Instance Details screen
- Select the IAM role <IAM_ROLE> created in the Preliminary step
- In the User data section paste the following script:
#!/bin/bash |
Where:
<SECRET_NAME_API>
= The name of the secret storing the api key in the AWS Secret Manager created in the preliminary step<SECRET_NAME_AUTH>
= The name of the secret storing the authorization header in the AWS Secret Manager created in the preliminary step<ORGANIZATION_ID>
= The Organization ID of your Organization within Contrast TeamServer
- Click on “Review and Launch”
- Click on “Launch” to launch the EC2 instance