AWS forensics package

Internal provider functions

libcloudforensics.providers.aws.forensics module

Forensics on AWS.

libcloudforensics.providers.aws.forensics.CreateVolumeCopy(zone, dst_zone=None, instance_id=None, volume_id=None, volume_type=None, src_profile=None, dst_profile=None, tags=None)

Create a copy of an AWS EBS Volume.

By default, the volume copy will be created in the same AWS account where the source volume sits. If you want the volume copy to be created in a different AWS account, you can specify one in the dst_profile parameter. The following example illustrates how you should configure your AWS credentials file for such a use case.

# AWS credentials file [default] # default account to use with AWS aws_access_key_id=foo aws_secret_access_key=bar

[investigation] # source account for a particular volume to be copied from aws_access_key_id=foo1 aws_secret_access_key=bar1

[forensics] # destination account to create the volume copy in aws_access_key_id=foo2 aws_secret_access_key=bar2

# Copies the boot volume from instance “instance_id” from the default AWS # account to the default AWS account. volume_copy = CreateVolumeCopy(zone, instance_id=’instance_id’)

# Copies the boot volume from instance “instance_id” from the default AWS # account to the ‘forensics’ AWS account. volume_copy = CreateVolumeCopy(

zone, instance_id=’instance_id’, dst_profile=’forensics’)

# Copies the boot volume from instance “instance_id” from the # ‘investigation’ AWS account to the ‘forensics’ AWS account. volume_copy = CreateVolumeCopy(

zone, instance_id=’instance_id’, src_profile=’investigation’, dst_profile=’forensics’)

Parameters

  • zone (str) – The AWS zone in which the volume is located, e.g. ‘us-east-2b’.

  • dst_zone (str) – Optional. The AWS zone in which to create the volume copy. By default, this is the same as ‘zone’.

  • instance_id (str) – Optional. Instance ID of the instance using the volume to be copied. If specified, the boot volume of the instance will be copied. If volume_id is also specified, then the volume pointed by that volume_id will be copied.

  • volume_id (str) – Optional. ID of the volume to copy. If not set, then instance_id needs to be set and the boot volume will be copied.

  • volume_type (str) – Optional. The volume type for the volume to be created. Can be one of ‘standard’|’io1’|’gp2’|’sc1’|’st1’. The default behavior is to use the same volume type as the source volume.

  • src_profile (str) – Optional. If the AWS account containing the volume that needs to be copied is different from the default account specified in the AWS credentials file then you can specify a different profile name here (see example above).

  • dst_profile (str) – Optional. If the volume copy needs to be created in a different AWS account, you can specify a different profile name here (see example above).

  • tags (Dict[str, str]) – Optional. A dictionary of tags to add to the volume copy, for example {‘TicketID’: ‘xxx’}.

Returns

An AWS EBS Volume object.

Return type

AWSVolume

Raises

  • ResourceCreationError – If there are errors copying the volume, or errors during KMS key creation/sharing if the target volume is encrypted.

  • ValueError – If both instance_id and volume_id are missing, or if AWS account information could not be retrieved.

libcloudforensics.providers.aws.forensics.StartAnalysisVm(vm_name, default_availability_zone, boot_volume_size, boot_volume_type='gp2', ami=None, cpu_cores=4, attach_volumes=None, dst_profile=None, ssh_key_name=None, tags=None, subnet_id=None, security_group_id=None, userdata_file=None)

Start a virtual machine for analysis purposes.

Look for an existing AWS instance with tag name vm_name. If found, this instance will be started and used as analysis VM. If not found, then a new vm with that name will be created, started and returned.

Parameters

  • vm_name (str) – The name for the virtual machine.

  • default_availability_zone (str) – Default zone within the region to create new resources in.

  • boot_volume_size (int) – The size of the analysis VM boot volume (in GB).

  • boot_volume_type (str) – Optional. The volume type for the boot volume of the VM. Can be one of ‘standard’|’io1’|’gp2’|’sc1’|’st1’. The default is ‘gp2’.

  • ami (str) – Optional. The Amazon Machine Image ID to use to create the VM. Default is a version of Ubuntu 18.04.

  • cpu_cores (int) – Optional. The number of CPU cores to create the machine with. Default is 4.

  • attach_volumes (List[Tuple[str, str]]) – Optional. List of tuples containing the volume IDs (str) to attach and their respective device name (str, e.g. /dev/sdf). Note that it is mandatory to provide a unique device name per volume to attach.

  • dst_profile (str) – Optional. The AWS account in which to create the analysis VM. This is the profile name that is defined in your AWS credentials file.

  • ssh_key_name (str) – Optional. A SSH key pair name linked to the AWS account to associate with the VM. If none provided, the VM can only be accessed through in-browser SSH from the AWS management console with the EC2 client connection package (ec2-instance-connect). Note that if this package fails to install on the target VM, then the VM will not be accessible. It is therefore recommended to fill in this parameter.

  • tags (Dict[str, str]) – Optional. A dictionary of tags to add to the instance, for example {‘TicketID’: ‘xxx’}. An entry for the instance name is added by default.

  • subnet_id (str) – Optional. The subnet to launch the instance in.

  • security_group_id (str) – Optional. Security group ID to attach.

  • userdata_file (str) – Optional. Filename to be read in as the userdata launch script.

Returns

a tuple with a virtual machine object

and a boolean indicating if the virtual machine was created or not.

Return type

Tuple[AWSInstance, bool]

Raises

RuntimeError – When multiple AMI images are returned.