AWS internal provider functions¶

libcloudforensics.providers.aws.internal.account module¶

Library for incident response operations on AWS EC2.

Library to make forensic images of Amazon Elastic Block Store devices and create analysis virtual machine to be used in incident response.

class libcloudforensics.providers.aws.internal.account.AWSAccount(default_availability_zone, aws_profile=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None)¶

Bases: object

Class representing an AWS account.

default_availability_zone¶

Default zone within the region to create new resources in.

Type: str

default_region¶

The default region to create new resources in.

Type: str

aws_profile¶

The AWS profile defined in the AWS credentials file to use.

Type: str

session¶

A boto3 session object.

Type: boto3.session.Session

_ec2¶

An AWS EC2 client object.

Type: AWSEC2

_ebs¶

An AWS EBS client object.

Type: AWSEBS

_kms¶

An AWS KMS client object.

Type: AWSKMS

_s3¶

An AWS S3 client object.

Type: AWSS3

ClientApi(service, region=None)¶

Create an AWS client object.

Parameters

service (str) – The AWS service to use.
region (str) – Optional. The region in which to create new resources. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

An AWS EC2 client object.

Return type

botocore.client.EC2

ResourceApi(service, region=None)¶

Create an AWS resource object.

Parameters

service (str) – The AWS service to use.
region (str) – Optional. The region in which to create new resources. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

An AWS EC2 resource object.

Return type

boto3.resources.factory.ec2.ServiceResource

property ebs¶

Get an AWS ebs object for the account.

Returns: Object that represents AWS EBS services.
Return type: AWSEBS

property ec2¶

Get an AWS ec2 object for the account.

Returns: Object that represents AWS EC2 services.
Return type: AWSEC2

property kms¶

Get an AWS kms object for the account.

Returns: Object that represents AWS KMS services.
Return type: AWSKMS

property s3¶

Get an AWS S3 object for the account.

Returns: Object that represents AWS S3 services.
Return type: AWSS3

libcloudforensics.providers.aws.internal.common module¶

Common utilities.

libcloudforensics.providers.aws.internal.common.CreateTags(resource, tags)¶

Create AWS Tag Specifications.

Parameters

resource (str) – The type of AWS resource.
tags (Dict[str, str]) – A dictionary of tags to add to the resource.

Returns

A dictionary for AWS Tag Specifications.

Return type

Dict[str, Any]

libcloudforensics.providers.aws.internal.common.ExecuteRequest(client, func, kwargs)¶

Execute a request to the boto3 API.

Parameters

client (boto3.session.Session) – A boto3 client object.
func (str) – A boto3 function to query from the client.
kwargs (Dict) – A dictionary of parameters for the function func. Expected keys are strings, values can be of multiple types. E.g.: {‘InstanceIds’: [‘instance_id’], ‘MaxResults’: 12}.

Returns

A list of dictionaries (responses from the: request), e.g. [{‘Groups’: [{…}], ‘Instances’: [{…}]}, {…}]

Return type

List[Dict]

Raises

RuntimeError – If the request to the boto3 API could not complete.

libcloudforensics.providers.aws.internal.common.GetInstanceTypeByCPU(cpu_cores)¶

Return the instance type for the requested number of CPU cores.

Parameters: cpu_cores (int) – The number of requested cores.
Returns: The type of instance that matches the number of cores.
Return type: str
Raises: ValueError – If the requested amount of cores is unavailable.

libcloudforensics.providers.aws.internal.ebs module¶

Disk functionality.

class libcloudforensics.providers.aws.internal.ebs.AWSElasticBlockStore(aws_account, region, availability_zone, encrypted, name=None)¶

Bases: object

Class representing an AWS EBS resource.

aws_account¶

The account for the resource.

Type: AWSAccount

region¶

The region the EBS is in.

Type: str

availability_zone¶

The zone within the region in which the EBS is.

Type: str

encrypted¶

True if the EBS resource is encrypted, False otherwise.

Type: bool

name¶

The name tag of the EBS resource, if existing.

Type: str

class libcloudforensics.providers.aws.internal.ebs.AWSSnapshot(snapshot_id, aws_account, region, availability_zone, volume, name=None)¶

Bases: libcloudforensics.providers.aws.internal.ebs.AWSElasticBlockStore

Class representing an AWS EBS snapshot.

snapshot_id¶

The id of the snapshot.

Type: str

aws_account¶

The account for the snapshot.

Type: AWSAccount

region¶

The region the snapshot is in.

Type: str

availability_zone¶

The zone within the region in which the snapshot is.

Type: str

volume¶

The volume from which the snapshot was taken.

Type: AWSVolume

name¶

The name tag of the snapshot, if existing.

Type: str

Copy(kms_key_id=None, delete=False, deletion_account=None)¶

Copy a snapshot.

Parameters

kms_key_id (str) – Optional. A KMS key id to encrypt the snapshot copy with. If set to None but the source snapshot is encrypted, then the copy will be encrypted too (with the key used by the source snapshot).
delete (bool) – Optional. If set to True, the snapshot being copied will be deleted prior to returning the copy. Default is False.
deletion_account (AWSAccount) – Optional. An AWSAccount object to use to delete the snapshot if ‘delete’ is set to True. Since accounts operate per region, this can be useful when copying snapshots across regions (which requires one AWSAccount object per region as per boto3.session.Session() requirements) and wanting to delete the source snapshot located in a different region than the copy being created.

Returns

A copy of the snapshot.

Return type

AWSSnapshot

Raises

ResourceCreationError – If the snapshot could not be copied.

Delete()¶

Delete a snapshot.

Raises: ResourceDeletionError – If the snapshot could not be deleted.
Return type: None

ShareWithAWSAccount(aws_account_id)¶

Share the snapshot with another AWS account ID.

Parameters: aws_account_id (str) – The AWS Account ID to share the snapshot with.
Return type: None

class libcloudforensics.providers.aws.internal.ebs.AWSVolume(volume_id, aws_account, region, availability_zone, encrypted, name=None, device_name=None)¶

Bases: libcloudforensics.providers.aws.internal.ebs.AWSElasticBlockStore

Class representing an AWS EBS volume.

volume_id¶

The id of the volume.

Type: str

aws_account¶

The account for the volume.

Type: AWSAccount

region¶

The region the volume is in.

Type: str

availability_zone¶

The zone within the region in which the volume is.

Type: str

encrypted¶

True if the volume is encrypted, False otherwise.

Type: bool

name¶

The name tag of the volume, if existing.

Type: str

device_name¶

The device name (e.g. /dev/spf) of the volume when it is attached to an instance, if applicable.

Type: str

Delete()¶

Delete a volume.

Raises: ResourceDeletionError – If the volume could not be deleted.
Return type: None

GetVolumeType()¶

Return the volume type.

Returns: The volume type.
Return type: str

Snapshot(tags=None)¶

Create a snapshot of the volume.

Parameters

tags (Dict[str, str]) – Optional. A dictionary of tags to add to the snapshot, for example {‘Name’: ‘my-snapshot-name’, ‘TicketID’: ‘xxx’}.

Returns

A snapshot object.

Return type

AWSSnapshot

Raises

InvalidNameError – If the snapshot name does not comply with the RegEx.
ResourceCreationError – If the snapshot could not be created.

class libcloudforensics.providers.aws.internal.ebs.EBS(aws_account)¶

Bases: object

Class that represents AWS EBS storage services.

CreateVolumeFromSnapshot(snapshot, volume_name=None, volume_name_prefix=None, volume_type='gp2', kms_key_id=None, tags=None)¶

Create a new volume based on a snapshot.

Parameters

snapshot (AWSSnapshot) – Snapshot to use.
volume_name (str) – Optional. String to use as new volume name.
volume_name_prefix (str) – Optional. String to prefix the volume name with.
volume_type (str) – Optional. The volume type for the volume to create. Can be one of ‘standard’|’io1’|’gp2’|’sc1’|’st1’. The default is ‘gp2’.
kms_key_id (str) – Optional. A KMS key id to encrypt the volume with.
tags (Dict[str, str]) – Optional. A dictionary of tags to add to the volume, for example {‘TicketID’: ‘xxx’}. An entry for the volume name is added by default.

Returns

An AWS EBS Volume.

Return type

AWSVolume

Raises

InvalidNameError – If the volume name does not comply with the RegEx
ValueError – If the volume type is invalid.
ResourceCreationError – If the volume could not be created.

GetAccountInformation()¶

Get information about the AWS account in use.

If the call succeeds, then the response from the STS API is expected to have the following entries:

UserId

Account

Arn

See https://boto3.amazonaws.com/v1/documentation/api/1.9.42/reference/services/sts.html#STS.Client.get_caller_identity for more details. # pylint: disable=line-too-long

Returns: The AWS account information.
Return type: Dict[str, str]

GetVolumeById(volume_id, region=None)¶

Get a volume from an AWS account by its ID.

Parameters

volume_id (str) – The volume id.
region (str) – Optional. The region to look the volume in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

An Amazon EC2 Volume object.

Return type

AWSVolume

Raises

ResourceNotFoundError – If the volume does not exist.

GetVolumesByName(volume_name, region=None)¶

Get all volumes from an AWS account with matching name tag.

Parameters

volume_name (str) – The volume name tag.
region (str) – Optional. The region to look the volume in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

A list of EC2 Volume objects. If no volume with: matching name tag is found, the method returns an empty list.

Return type

List[AWSVolume]

GetVolumesByNameOrId(volume_name=None, volume_id=None, region=None)¶

Get a volume from an AWS account by its name tag or its ID.

Exactly one of [volume_name, volume_id] must be specified. If looking up a volume by its ID, the method returns a list with exactly one element. If looking up volumes by their name tag (which are not unique across volumes), then the method will return a list of all volumes with that name tag, or an empty list if no volumes with matching name tag could be found.

Parameters

volume_name (str) – Optional. The volume name tag of the volume to get.
volume_id (str) – Optional. The volume id of the volume to get.
region (str) – Optional. The region to look the volume in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

A list of Amazon EC2 Volume objects.

Return type

List[AWSVolume]

Raises

ValueError – If both volume_name and volume_id are None or if both are set.

ListVolumes(region=None, filters=None)¶

List volumes of an AWS account.

Example usage:: # List volumes attached to the instance ‘some-instance-id’ ListVolumes(filters=[

{‘Name’:’attachment.instance-id’, ‘Values’:[‘some-instance-id’]}])

Parameters

region (str) – Optional. The region from which to list the volumes. If none provided, the default_region associated to the AWSAccount object will be used.
filters (List[Dict]) – Optional. Filters for the query. Filters are given as a list of dictionaries, e.g.: {‘Name’: ‘someFilter’, ‘Values’: [‘value1’, ‘value2’]}.

Returns

Dictionary mapping volume IDs (str) to their: respective AWSVolume object.

Return type

Dict[str, AWSVolume]

Raises

RuntimeError – If volumes can’t be listed.

libcloudforensics.providers.aws.internal.ec2 module¶

Instance functionality.

class libcloudforensics.providers.aws.internal.ec2.AWSInstance(aws_account, instance_id, region, availability_zone, name=None)¶

Bases: object

Class representing an AWS EC2 instance.

aws_account¶

The account for the instance.

Type: AWSAccount

instance_id¶

The id of the instance.

Type: str

region¶

The region the instance is in.

Type: str

availability_zone¶

The zone within the region in which the instance is.

Type: str

name¶

The name tag of the instance, if existing.

Type: str

AttachVolume(volume, device_name)¶

Attach a volume to the AWS instance.

Parameters

volume (AWSVolume) – The AWSVolume object to attach to the instance.
device_name (str) – The device name for the volume (e.g. /dev/sdf).

Raises

RuntimeError – If the volume could not be attached.

Return type

None

GetBootVolume()¶

Get the instance’s boot volume.

Returns: Volume object if the volume is found.
Return type: AWSVolume
Raises: ResourceNotFoundError – If no boot volume could be found.

GetVolume(volume_id)¶

Get a volume attached to the instance by ID.

Parameters: volume_id (str) – The ID of the volume to get.
Returns: The AWSVolume object.
Return type: AWSVolume
Raises: ResourceNotFoundError – If volume_id is not found amongst the volumes attached to the instance.

ListVolumes()¶

List all volumes for the instance.

Returns

Dictionary mapping volume IDs to their respective: AWSVolume object.

Return type

Dict[str, AWSVolume]

class libcloudforensics.providers.aws.internal.ec2.EC2(aws_account)¶

Bases: object

Class that represents AWS EC2 instance services.

GenerateSSHKeyPair(vm_name)¶

Generate a SSH key pair and returns its name and private key.

Parameters

vm_name (str) – The VM name for which to generate the key pair.

Returns

A tuple containing the key name and the private key for: the generated SSH key pair.

Return type

Tuple[str, str]

Raises

ValueError – If vm_name is None.
ResourceCreationError – If the key could not be created.

GetInstanceById(instance_id, region=None)¶

Get an instance from an AWS account by its ID.

Parameters

instance_id (str) – The instance id.
region (str) – Optional. The region to look the instance in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

An Amazon EC2 Instance object.

Return type

AWSInstance

Raises

ResourceNotFoundError – If instance does not exist.

GetInstancesByName(instance_name, region=None)¶

Get all instances from an AWS account with matching name tag.

Parameters

instance_name (str) – The instance name tag.
region (str) – Optional. The region to look the instance in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

A list of EC2 Instance objects. If no instance with: matching name tag is found, the method returns an empty list.

Return type

List[AWSInstance]

GetInstancesByNameOrId(instance_name=None, instance_id=None, region=None)¶

Get instances from an AWS account by their name tag or an ID.

Exactly one of [instance_name, instance_id] must be specified. If looking up an instance by its ID, the method returns a list with exactly one element. If looking up instances by their name tag (which are not unique across instances), then the method will return a list of all instances with that name tag, or an empty list if no instances with matching name tag could be found.

Parameters

instance_name (str) – Optional. The instance name tag of the instance to get.
instance_id (str) – Optional. The instance id of the instance to get.
region (str) – Optional. The region to look the instance in. If none provided, the default_region associated to the AWSAccount object will be used.

Returns

A list of Amazon EC2 Instance objects.

Return type

List[AWSInstance]

Raises

ValueError – If both instance_name and instance_id are None or if both are set.

GetOrCreateAnalysisVm(vm_name, boot_volume_size, ami, cpu_cores, boot_volume_type='gp2', ssh_key_name=None, tags=None, subnet_id=None, security_group_id=None, userdata=None)¶

Get or create a new virtual machine for analysis purposes.

Parameters

vm_name (str) – The instance name tag of the virtual machine.
boot_volume_size (int) – The size of the analysis VM boot volume (in GB).
ami (str) – The Amazon Machine Image ID to use to create the VM.
cpu_cores (int) – Number of CPU cores for the analysis VM.
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’.
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. Subnet to launch the instance in.
security_group_id (str) – Optional. Security group id to attach.
userdata (str) – Optional. String passed to the instance as a userdata launch script.

Returns

A tuple with an AWSInstance object and a: boolean indicating if the virtual machine was created (True) or reused (False).

Return type

Tuple[AWSInstance, bool]

Raises

ResourceCreationError – If the virtual machine cannot be created.

ListImages(qfilter=None)¶

List AMI images.

Parameters

qfilter (List[Dict]) – The filter expression.
https (See) – //boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.describe_images # pylint: disable=line-too-long

Returns

The list of images with their properties.

Return type

List[Dict[str, Any]]

Raises

RuntimeError – If the images could not be listed.

ListInstances(region=None, filters=None, show_terminated=False)¶

List instances of an AWS account.

Example usage:

ListInstances(region=’us-east-1’, filters=[: {‘Name’:’instance-id’, ‘Values’:[‘some-instance-id’]}])

Parameters

region (str) – Optional. The region from which to list instances. If none provided, the default_region associated to the AWSAccount object will be used.
filters (List[Dict]) – Optional. Filters for the query. Filters are given as a list of dictionaries, e.g.: {‘Name’: ‘someFilter’, ‘Values’: [‘value1’, ‘value2’]}.
show_terminated (bool) – Optional. Include terminated instances in the list.

Returns

Dictionary mapping instance IDs (str) to their: respective AWSInstance object.

Return type

Dict[str, AWInstance]

Raises

RuntimeError – If instances can’t be listed.

libcloudforensics.providers.aws.internal.kms module¶

KMS functionality.

class libcloudforensics.providers.aws.internal.kms.KMS(aws_account)¶

Bases: object

Class that represents AWS KMS services.

CreateKMSKey()¶

Create a KMS key.

Returns: The KMS key ID for the key that was created.
Return type: str
Raises: ResourceCreationError – If the key could not be created.

DeleteKMSKey(kms_key_id=None)¶

Delete a KMS key.

Schedule the KMS key for deletion. By default, users have a 30 days: window before the key gets deleted.

Parameters: kms_key_id (str) – The ID of the KMS key to delete.
Raises: ResourceDeletionError – If the key could not be scheduled for deletion.
Return type: None

ShareKMSKeyWithAWSAccount(kms_key_id, aws_account_id)¶

Share a KMS key.

Parameters

kms_key_id (str) – The KMS key ID of the key to share.
aws_account_id (str) – The AWS Account ID to share the KMS key with.

Raises

RuntimeError – If the key could not be shared.

Return type

None

libcloudforensics.providers.aws.internal.log module¶

Log functionality.

class libcloudforensics.providers.aws.internal.log.AWSCloudTrail(aws_account)¶

Bases: object

Class representing an AWS CloudTrail service.

aws_account¶

The AWS account to use.

Type: AWSAccount

LookupEvents(qfilter=None, starttime=None, endtime=None)¶

Lookup events in the CloudTrail logs of this account.

Example usage:: # pylint: disable=line-too-long # qfilter = ‘key,value’ # starttime = datetime(2020,5,5,17,33,00) # LookupEvents(qfilter=qfilter, starttime=starttime) # Check documentation for qfilter details # https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudtrail.html#CloudTrail.Client.lookup_events

Parameters

qfilter (string) – Optional. Filter for the query including 1 key and value.
starttime (datetime) – Optional. Start datetime to add to query filter.
endtime (datetime) – Optional. End datetime to add to query filter.

Returns

A list of events. E.g. [{‘EventId’: ‘id’, …},: {‘EventId’: …}]

Return type

List[Dict]

libcloudforensics.providers.aws.internal.s3 module¶

Bucket functionality.

class libcloudforensics.providers.aws.internal.s3.S3(aws_account)¶

Bases: object

Class that represents AWS S3 storage services.

aws_account¶

The account for the resource.

Type: AWSAccount

name¶

The name of the bucket.

Type: str

region¶

The region in which the bucket resides.

Type: str

CreateBucket(name, region=None, acl='private', tags=None, policy=None)¶

Create an S3 storage bucket.

Parameters

name (str) – The name of the bucket.
region (str) – Optional. The region in which the bucket resides.
acl (str) – Optional. The canned ACL with which to create the bucket. Default is ‘private’.
tags (Dict[str, str]) – Optional. A dictionary of tags to add to the bucket, for example {‘TagName’: ‘TagValue’}.
policy (str) – Optional. A bucket policy to be applied after creation. It must be a valid JSON document.

Appropriate values for the Canned ACLs are here: https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl # pylint: disable=line-too-long

New tags will not be set if the bucket already exists.

Returns

An API operation object for a S3 bucket.: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Bucket.create # pylint: disable=line-too-long

Return type

Dict

Raises

ResourceCreationError – If the bucket couldn’t be created or already exists. # pylint: disable=line-too-long

GCSToS3(project_id, gcs_path, s3_path, s3_args=None)¶

Copy an object in GCS to an S3 bucket.

(Creates a local copy of the file in a temporary directory)

Parameters

project_id (str) – Google Cloud project ID.
gcs_path (str) – File path to the source GCS object. Ex: gs://bucket/folder/obj
s3_path (str) – Path to the target S3 bucket. Ex: s3://test/bucket
s3_args (Dict[str, str]) –
Optional. A dictionary of extra arguments to be supplied to the S3 Put call. Useful for specifying encryption parameters.

Ex: {‘ServerSideEncryption’: “AES256”}

Returns

An API operation object for an S3 Put request.: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.put_object # pylint: disable=line-too-long

Return type

Dict

Raises

ResourceCreationError – If the object couldn’t be uploaded.

Put(s3_path, filepath, extra_args=None)¶

Upload a local file to an S3 bucket.

Keeps the local filename intact.

Parameters

s3_path (str) – Path to the target S3 bucket. Ex: s3://test/bucket
filepath (str) – Path to the file to be uploaded. Ex: /tmp/myfile
extra_args (Dict[str, str]) –
Optional. A dictionary of extra arguments that will be directly supplied to the upload_file call. Useful for specifying encryption parameters.

Ex: {‘ServerSideEncryption’: “AES256”}

Raises

ResourceCreationError – If the object couldn’t be uploaded.

Return type

None