AWS Incident Response

In this post, we will be talking about the ways one can set up and automate a set of functions that need to be carried out in a sequence in case an attack happens in AWS,  Yes! AWS Incident response. Having the whole infrastructure on the cloud can be both good and bad in terms of Security. Many cloud services such as the Amazon AWS have a shared responsibility model, which means, both the client and Amazon’s security team share the responsibilities of securing the system. Here is a chart that would help us understand the same,

This shows that there is a considerable amount of items which are under the responsibility of the user.  That makes cloud security, a matter of interest and being prepared is an absolute necessity.

In this post, we will be discussing a tool which will help us with automating the Incident response in case an attack happens. The tools we are going to use are AWS IR, an incident response tool for Instance and Key compromise, and Margarita Shotgun, a memory capture tool.


AWS-IR is a python module and standalone command line tool that can be used to collect evidence and mitigate compromises. The command line tool has two sub-commands: instance-compromise and key-compromise.

AWS-IR is built on top of boto3, an AWS SDK for the python language. In order to use AWS-IR, a user should have installed amazon cli (check here)  and their environment for use with the AWS SDK and have the appropriate AWS credentials configured with the account.

When using one of the compromise commands, AWS-IR collects evidence and tags instances according to a case number. The case number can be provided with the -n flag, and if one isn’t provided, a case number will be randomly assigned. The case is the basic organization of evidence and logging for a particular incident. All evidence collected by AWS-IR is stored in an S3 bucket for that specific case. Additionally, every action performed by AWS-IR is logged and stored with the case.

Installing the AWS IR

AWS-IR is recommended to be used with python3. The default interpreter in your distribution can be python2. So it is recommended to use a virtualenv while working with the AWS-IR.

We will first clone the contents of aws-ir from the GitHub and then create a virtualenv with the python3 interpreter to install the aws-ir.

git clone
cd aws_ir
virtualenv Python3Env -p python3
source Python3Env/bin/activate

We are now ready to install the aws-ir, use the following commands to install the aws-ir

pip3 -r requirements.txt
python3 install
aws_ir -h

--case-number The aws -ir can be run by providing a case number (useful for maintaining logs) using this option.

--bucket-name We can also provide an S3 bucket name which would be used to store the incident artifacts.

--examiner-cidr-range We can use this option to provide the responder’s/examiner’s IP/CIDR range. This will create a security group for the compromised instance and enforce the inbound and outbound rules to only allow communication to this IP range.

--dry-runLets you run the commands without modifying resources. This can be used for verifying API calls.

We have two functions that the aws-ir can performinstance-compromisekey-compromise.

Key compromise

The key-compromise function can be used during the incident response phase when an access key is identified as compromised or just to remove the obsolete keys. When the key-compromise subcommand is used, the user must provide the AWS access key id of the compromised key. AWS-IR will locate the IAM account associated with the key and disable the key.

The key-compromise has two plugins,

  • disableaccess_key  – Used to disable the access key
  • revokests_key – Used to revoke STS tokens for the particular access id

By default, both the plugins are executed. But selective plugins can be run by specifying the plugin names after --plugin.

To demonstrate the function of key-compromise , we will first create a test user ‘compromised_user’ in AWS IAM.

We will use the access key id of the ‘compromised_user’ to disable its access using aws_ir.

aws_ir key-compromise --access-key-id AKIAINXHXCB6235NKBEA

Let’s check the IAM console for the status of the user with that access key

We could see that the user account with the compromised access key was automatically disabled and the artifacts(if any) would be stored in the S3 bucket specified  --bucket-name

Instance Compromise

The instance compromise can be used to safely stop a compromised instance without losing its forensic value during an Incident Response phase. When the instance-compromise sub-command, AWS-IR first starts collecting evidence and then mitigates the affected host. To use the instance-compromise command, the user only needs to provide an IP address. An SSH username with root privileges and SSH key should also be provided if that information is available. AWS-IR will then start mitigating the compromised host by attaching a new, highly restrictive security group to the instance. This is designed to sever any existing session an attacker may have and stop the exfiltration of data. AWS-IR will then snapshot all attached volumes, attempt to capture memory, collect metadata about the instance, grab console output and save a console screenshot. After the evidence has been collected, AWS-IR will shut down the instance and provide the case number.

The instance-compromise has the following plugins,

  • examineracl_host
  • gather_host
  • isolate_host
  • snapshotdisks_host
  • stop_host
  • tag_host
  • get_memory

By default, both the plugins are executed. But selective plugins can be run by specifying the plugin names after --plugin.

To demonstrate the instance-compromise function, We will set up an instance in EC2 which will act as the compromised system.

We will then run the following command in aws_ir

aws_ir --bucket-name memorydmp instance-compromise --target --user ec2-user --ssh-key EC2_IAM_demo.pem

We used the instance compromise on the target server specifying the following parameters,

--target The public IP address of the target compromised EC2 server instance.

--user The user account name of a root user of the compromised system.

--ssh-key The ssh key file for the root user on the target system.

After executing the command, this is the output we receive

The instance compromise first searches for the instance in all the available regions,

The host is first isolated from other resources and dependencies, the instance is tagged with the aws_ir case number (which can be specified manually using –case-number).

A full snapshot of the system is created which can be used to recreate the running state of the instance, which would help in forensics. The snapshot is also tagged with the case number.

An examiner security group is added to the instance which would restrict the inbound and outbound rules of the system to the IP/CIDR range provided with the option--examiner-cidr-range.

The get_memory plugin would just invoke the margarita shotgun to create memory dump if the --examiner-cidr-range is provided. Finally, the instance is stopped by the stop_host plugin. Any artifacts created will be stored in an S3 bucket other than the snapshot.

Margarita Shotgun

The margarita shotgun a tool that creates a memory dump from a running Linux instance.

Margarita Shotgun is a python module and a standalone command line tool that automates the process of acquiring memory from remote systems, both on-premise and in Amazon Web Services since this is a very important part of the Incident response phase. Margarita Shotgun makes heavy use of paramiko to securely connect to remote systems and secure memory in transit between the compromised server and the incident responder workstation.

Margarita Shotgun makes use of the LiME Project to capture the memory. A configurable repository of pre-built LiME kernel modules is available to streamline the memory acquisition process.

After determining the remote system’s kernel version and architecture the appropriate LiME kernel module is loaded and system memory is streamed over an ssh tunnel to the incident responder’s workstation. Memory can be saved to disk or streamed directly to an s3 bucket.

We will now run the margarita shotgun to extract the memory from our compromised instance and store it locally or in an S3 bucket.

margaritashotgun --server --username ec2-user --key EC2_IAM_demo.pem --bucket memorydmp --repository

--server The target instance’s IP address whose memory has to be captured.

--username A user account with root access on the target system

--key SSH key which will be used to connect to the target system

--bucket S3 bucket for the captured memory. This can be replaced with --output-dir to store the file locally.

--repository This will point to the public ThreatResponse repository which will have the Lime kernel module build for the kernel running on the instance.

The output of the command we executed is below,

Margarita shotgun can also be used to capture multiple instances at once. Please read here to find more information about margarita shotgun and its functions.


Thus, We can automate the procedure during an Incident response using AWS IR and Margarita Shotgun from ThreatResponse. These tools are constantly being developed and they might have to get additional functions in the future.

Thank you for reading! – Setu Parimi, Steve George & Indranil Roy

Sign up for the blog directly here.

Check out our professional services here.

Feedback is welcome! For professional services, fan mail, hate mail, or whatever else, contact [email protected]


Leave a Reply

%d bloggers like this: