Welcome to libcloudforensics’s documentation!¶

Table of contents¶

Getting started¶

Installing from pypi¶

As easy as:

$ pip install libcloudforensics

and you’re done!

Using the CLI¶

A standalone tool called cloudforensics is created during installation.

$ cloudforensics --help
usage: cloudforensics [-h] {aws,az,gcp} ...

CLI tool for AWS, Azure and GCP.

positional arguments:
  {aws,az,gcp}
    aws         Tools for AWS
    az          Tools for Azure
    gcp         Tools for GCP

optional arguments:
  -h, --help    show this help message and exit

The implemented functions for each platform can be listed. For example:

$ cloudforensics gcp -h
usage: cloudforensics gcp [-h] project {listinstances,listdisks,copydisk,startvm,querylogs,listlogs,listservices,creatediskgcs,bucketacls,objectmetadata,listobjects} ...

positional arguments:
  project               GCP project ID.
  {listinstances,listdisks,copydisk,startvm,querylogs,listlogs,listservices,creatediskgcs,bucketacls,objectmetadata,listobjects}
    listinstances       List GCE instances in GCP project.
    listdisks           List GCE disks in GCP project.
    copydisk            Create a GCP disk copy.
    startvm             Start a forensic analysis VM.
    querylogs           Query GCP logs.
    listlogs            List GCP logs for a project.
    listservices        List active services for a project.
    creatediskgcs       Creates GCE persistent disk from image in GCS.
    bucketacls          List ACLs of a GCS bucket.
    objectmetadata      List the details of an object in a GCS bucket.
    listobjects         List the objects in a GCS bucket.

optional arguments:
  -h, --help            show this help message and exit

libcloudforensics capabilities¶

GCP¶

Disk snapshot¶

TODO

GCS to persistent disk¶

TODO

Analysis VM¶

TODO

AWS¶

Prerequisites¶

Your AWS credentials configuration (~/.aws/credentials) should look like this:

# Access credentials to Account A
[src_profile]
aws_access_key_id = xxx
aws_secret_access_key = xxx

# Access credentials to Account B
[dst_profile]
aws_access_key_id = yyy
aws_secret_access_key = yyy

# Access credentials to the default account to use with AWS operations. Note that this can be the same account as one 
# of the accounts above. This is the account that will be used by libcloudforensics for AWSAccount objects that are not 
# instantiated with a particular profile.
[default]
aws_access_key_id = zzz
aws_secret_access_key = zzz

Disk snapshot¶

Use case: you have a volume vol1 in an AWS account (Account A, in zone us-east-2b) which you would like to make a copy of in a different account (Account B).

Using the library and the CLI¶

To make the copy, import the forensics package and use the CreateVolumeCopy method.

from libcloudforensics.providers.aws import forensics

# Create a copy of the volume 'vol1' from one account to another 

copy = forensics.CreateVolumeCopy('us-east-2b',
                                  volume_id='vol1', 
                                  src_profile='src_profile', 
                                  dst_profile='analysis_profile')

The equivalent CLI command is:

# Create a copy of the volume 'vol1' from one account to another 
cloudforensics aws 'us-east-2b' copydisk --volume_id='vol1' --src_profile='src_profile' --dst_profile='dst_profile' 

If you want to make the copy in a different zone, just specify dst_zone in the above method. You can also pass a dictionary of tags to add to the volume copy.

from libcloudforensics.providers.aws import forensics

# Create a copy of the volume 'vol1' from one account to another, in a different zone

copy = forensics.CreateVolumeCopy('us-east-2b',
                                  dst_zone='us-west-2a',
                                  volume_id='vol1', 
                                  src_profile='src_profile', 
                                  dst_profile='analysis_profile',
                                  tags={'customTag': 'customValue'})

The equivalent CLI command is:

# Create a copy of the volume 'vol1' from one account to another, in a different zone
cloudforensics aws 'us-east-2b' copydisk --dst_zone='us-west-2a' --volume_id='vol1' --src_profile='src_profile' --dst_profile='dst_profile' --tags="{'customTag': 'customValue'}" 

Finally, you can opt to pass an instance_id parameter to the method instead of a volume_id. If you do so, then the boot volume of the instance pointed to by instance_id will be copied.

from libcloudforensics.providers.aws import forensics

# Create a copy of the boot volume of instance 'inst1' in the default account.

copy = forensics.CreateVolumeCopy('us-east-2b',
                                  instance_id='inst1')

The equivalent CLI command is:

# Create a copy of the boot volume of instance 'inst1' in the default account
cloudforensics aws 'us-east-2b' copydisk --instance_id='inst1'

EBS encryption¶

Making copies of encrypted resources is a bit more involved. By default, encrypted Elastic Block Store (EBS) resources use the aws/ebs key that is associated with the AWS account. Snapshots that are encrypted with this key cannot be shared directly. Instead, you must first make a copy of the snapshot, and re-encrypt it with a Customer Managed Key (CMK). Both the CMK and the snapshot copy need to then be shared with the destination account.

To reduce key management hassle, libcloudforensics allows you to transfer encrypted EBS resources between accounts by generating a one-time use CMK. This key is deleted once the process completes. The process is depicted below:

ebs-encryption

All of the code snippets and command lines given in the previous section can be applied as-is, regardless of whether the target volume uses EBS encryption or not.

Analysis VMs¶

Use case: you have a volume vol1 in an AWS account (Account A, in zone us-east-2b) which you would like to make a copy of in a different account (Account B). Afterwards, you want to start an analysis VM in Account B, and attach the disk copy that you created to begin your investigation.

Your AWS credentials configuration should be similar to what is described above.

Using the library, you can start an analysis VM as follows:

from libcloudforensics.providers.aws import forensics

# Create a copy of the volume 'vol1' from one account to another 

copy = forensics.CreateVolumeCopy('us-east-2b',
                                  volume_id='vol1', 
                                  src_profile='src_profile', 
                                  dst_profile='dst_profile')

# Start an analysis VM 'vm-forensics' for investigation in the AWS account 
# dst_profile, and attach the copy created in the previous step.

analysis_vm, _ = forensics.StartAnalysisVm('vm-forensics',
                                           'us-east-2b', 
                                            50, 
                                            cpu_cores=4,
                                            attach_volumes=[(copy.volume_id, '/dev/sdf')], 
                                            dst_profile='dst_profile')

The equivalent CLI command is:

# Create a copy of the volume 'vol1' in the dst_account AWS account.
# In this scenario we consider that the final volume copy name is 'vol1-copy' for illustration purpose. 
cloudforensics aws 'us-east-2b' copydisk --volume_id='vol1' --src_profile='src_profile' --dst_profile='dst_profile' 

# Start an analysis VM 'vm-forensics' for investigation in the AWS account 
# dst_profile, and attach a volume to it.
cloudforensics aws 'us-east-2b' startvm 'vm-forensics' --boot_volume_size=50 --cpu_cores=4 --attach_volumes='vol1-copy' --dst_profile='dst_profile'

You’re now ready to go! Log in your AWS account, find the instance (you can search it based on the name tag vm-forensics) and click on Connect.

Important

Pro tip: you can export an environment variable ‘STARTUP_SCRIPT’ that points to a custom bash script.

This script will be shipped to the instance being created and executed during the first boot. You can do any kind of pre-processing you want in this script.

Microsoft Azure¶

Prerequisites¶

Your Azure credentials configuration (~/.azure/credentials.json) should look like this:

{
  # Access credentials to Account A
  'src_profile': {
      'subscriptionId': xxx,
      'tenantId': xxx,
      'clientId': xxx,
      'clientSecret': xxx
  },
  # Access credentials to Account B
  'dst_profile': {
      'subscriptionId': yyy,
      'tenantId': yyy,
      'clientId': yyy,
      'clientSecret': yyy
  },
  ...
}

Alternatively, if you are working on only one account and do not require cross-account disk copies, you can define the following environment variables:

$: export AZURE_SUBSCRIPTION_ID=xxx
$: export AZURE_CLIENT_ID=xxx
$: export AZURE_CLIENT_SECRET=xxx
$: export AZURE_TENANT_ID=xxx

Disk snapshot¶

Scenario 1¶

You have a disk disk1 in an Azure account, in eastus which you would like to make a copy of in the same account and in the same region.

Scenario 2¶

You have a disk disk1 in an Azure account, in eastus which you would like to make a copy of in the same account but in a different region westus.

Scenario 3¶

You have a disk disk1 in an Azure account (Account A) which you would like to make a copy of in a different account (Account B).

Using the library and the CLI¶

To make the copy, import the forensics package and use the CreateDiskCopy method.

from libcloudforensics.providers.azure import forensics

# Scenario 1. Assumes credentials are configured through environment variables
copy = forensics.CreateDiskCopy('resource_group_name',
                                disk_name='disk1')
      
# Scenario 2. Assumes credentials are configured through environment variables                          
copy = forensics.CreateDiskCopy('resource_group_name',
                                disk_name='disk1',
                                region='westus')
                                
# Scenario 3. Assumes credentials are configured through profiles in ~/.azure/credentials.json
copy = forensics.CreateDiskCopy('resource_group_name',
                                disk_name='disk1',
                                src_profile='src_profile',
                                dst_profile='dst_profile')

The equivalent CLI command is:

# Scenario 1. Assumes credentials are configured through environment variables
cloudforensics az 'resource_group_name' copydisk --disk_name='disk1'

# Scenario 2. Assumes credentials are configured through environment variables 
cloudforensics az 'resource_group_name' copydisk --disk_name='disk1' --region='westus'

# Scenario 3. Assumes credentials are configured through profiles in ~/.azure/credentials.json
cloudforensics az 'resource_group_name' copydisk --disk_name='disk1' --src_profile='src_profile' --dst_profile='dst_profile' 

Analysis VMs¶

Use case: you have a disk disk1 in an Azure account (Account A) which you would like to make a copy of in a different account (Account B). Afterwards, you want to start an analysis VM in Account B, and attach the disk copy that you created to begin your investigation.

Your Azure credentials configuration should be similar to what is described above.

Using the library, you can start an analysis VM as follows:

from libcloudforensics.providers.azure import forensics

# Create a copy of the disk 'disk1' from one account to another 

copy = forensics.CreateDiskCopy('resource_group_name',
                                disk_name='disk1', 
                                src_profile='src_profile', 
                                dst_profile='dst_profile')

# Start an analysis VM 'vm-forensics' for investigation in the Azure account 
# dst_profile, and attach the copy created in the previous step.

analysis_vm, _ = forensics.StartAnalysisVm('resource_group_name',
                                           'vm-forensics',
                                            50, 
                                            'ssh-rsa AAAbbbbFFFF...',
                                            cpu_cores=4,
                                            # In this scenario we consider that the final disk copy name is 'disk1-copy' for illustration purpose.
                                            attach_disks=['disk1-copy'],
                                            dst_profile='dst_profile')

The equivalent CLI command is:

# Create a copy of the disk 'disk1' in the dst_account Azure account.
# In this scenario we consider that the final disk copy name is 'disk1-copy' for illustration purpose. 
cloudforensics az 'resource_group_name' copydisk --disk_name='disk1' --src_profile='src_profile' --dst_profile='dst_profile'

# Start an analysis VM 'vm-forensics' for investigation in the Azure account 
# dst_profile, and attach a volume to it.
# A SSH key pair will be automatically generated and associated to the instance.
cloudforensics az 'resource_group_name' startvm 'vm-forensics' --disk_size=50 --cpu_cores=4 --attach_disks='disk1-copy' --dst_profile='dst_profile'

You’re now ready to go! Log in your Azure account, find the instance’s IP address and SSH to it.

Important

Pro tip: you can export an environment variable ‘STARTUP_SCRIPT’ that points to a custom bash script.

This script will be shipped to the instance being created and executed during the first boot. You can do any kind of pre-processing you want in this script.

Contributing¶

Before you contribute¶

We love contributions! Read this page (including the small print at the end).

Before we can use your code, you must sign the Google Individual Contributor License Agreement (CLA), which you can do online. The CLA is necessary mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things—for instance that you’ll tell us if you know that your code infringes on other people’s patents. You don’t have to sign the CLA until after you’ve submitted your code for review and a member has approved it, but you must do it before we can put your code into our codebase. Before you start working on a larger contribution, you should get in touch with us first through the issue tracker with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on.

We use the github fork and pull review process to review all contributions. First, fork the cloud-forensics-utils repository by following the github instructions. Then check out your personal fork:

$ git clone https://github.com/<username>/cloud-forensics-utils.git

Add an upstream remote so you can easily keep up to date with the main repository:

$ git remote add upstream https://github.com/google/cloud-forensics-utils.git

To update your local repo from the main:

$ git pull upstream master

Please follow the Style Guide when making your changes, and also make sure to use the project’s pylintrc and yapf config file. Once you’re ready for review make sure the tests pass:

$ nosetests -v tests

Commit your changes to your personal fork and then use the GitHub Web UI to create and send the pull request. We’ll review and merge the change.

Code review¶

All submissions, including submissions by project members, require review. To keep the code base maintainable and readable all code is developed using a similar coding style. It ensures:

The code should be easy to maintain and understand. As a developer you’ll sometimes find yourself thinking hmm, what is the code supposed to do here. It is important that you should be able to come back to code 5 months later and still quickly understand what it supposed to be doing. Also for other people that want to contribute it is necessary that they need to be able to quickly understand the code. Be that said, quick-and-dirty solutions might work in the short term, but we’ll ban them from the code base to gain better long term quality. With the code review process we ensure that at least two eyes looked over the code in hopes of finding potential bugs or errors (before they become bugs and errors). This also improves the overall code quality and makes sure that every developer knows to (largely) expect the same coding style.

Style guide¶

We primarily follow the Log2Timeline Python Style Guide.

The small print¶

Contributions made by corporations are covered by a different agreement than the one above, the Software Grant and Corporate Contributor License Agreement.

API documentation¶

Documentation for the library’s functions and classes can be found below:

GCP forensics package¶

Internal provider functions¶

GCP internal provider functions¶

libcloudforensics.providers.gcp.internal.build module¶

Google Cloud Build functionalities.

class libcloudforensics.providers.gcp.internal.build.GoogleCloudBuild(project_id)¶

Bases: object

Class to call Google Cloud Build APIs.

Dictionary objects content can be found in https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds

gcb_api_client¶: Client to interact with GCB APIs.

BlockOperation(response)¶

Block execution until API operation is finished.

Parameters

response (Dict) – Google Cloud Build API response.

Returns

Holding the response of a get operation on an API object of type: operations.

Return type

Dict

Raises

RuntimeError – If the Cloud Build failed or if getting the Cloud Build API operation object failed.

CLOUD_BUILD_API_VERSION = 'v1'¶

CreateBuild(build_body)¶

Create a cloud build.

Parameters

build_body (Dict) – A dictionary that describes how to find the source code and how to build it.

Returns

Represents long-running operation that is the result of a network: API call.

Return type

Dict

GcbApi()¶

Get a Google Cloud Build service object.

Returns: A Google Cloud Build service object.
Return type: googleapiclient.discovery.Resource

libcloudforensics.providers.gcp.internal.cloudsql module¶

Google Cloud SQL functionalities.

class libcloudforensics.providers.gcp.internal.cloudsql.GoogleCloudSQL(project_id=None)¶

Bases: object

Class to call Google CloudSQL APIs.

gcsql_api_client¶: Client to interact with GCSql APIs.

project_id¶: Google Cloud project ID.

GoogleCloudSQLApi()¶

Get a Google CloudSQL service object.

Returns: A Google CloudSQL service object.
Return type: googleapiclient.discovery.Resource

ListCloudSQLInstances()¶

List instances of Google CloudSQL within a project.

Returns: List of instances.
Return type: List[Dict[str, Any]]

SQLADMIN_API_VERSION = 'v1beta4'¶

libcloudforensics.providers.gcp.internal.common module¶

Common utilities.

libcloudforensics.providers.gcp.internal.common.CreateService(service_name, api_version)¶

Creates an GCP API service.

Parameters

service_name (str) – Name of the GCP service to use.
api_version (str) – Version of the GCP service API to use.

Returns

API service resource.

Return type

googleapiclient.discovery.Resource

Raises

CredentialsConfigurationError – If Application Default Credentials could not be obtained
RuntimeError – If service build times out.

libcloudforensics.providers.gcp.internal.common.ExecuteRequest(client, func, kwargs, throttle=False)¶

Execute a request to the GCP API.

Parameters

client (googleapiclient.discovery.Resource) – A GCP client object.
func (str) – A GCP function to query from the client.
kwargs (Dict) – A dictionary of parameters for the function func.
throttle (bool) – A boolean indicating if requests should be throttled. This is necessary for some APIs (e.g. list logs) as there is an API rate limit. Default is False, i.e. requests are not throttled.

Returns

A List of dictionaries (responses from the request).

Return type

List[Dict]

Raises

CredentialsConfigurationError – If the request to the GCP API could not complete.

libcloudforensics.providers.gcp.internal.common.FormatRFC3339(datetime_instance)¶

Formats a datetime per RFC 3339.

Parameters: datetime_instance (datetime) – The datetime group to be formatted.
Returns: A string formatted as per RFC3339 (e.g 2018-05-11T12:34:56.992Z)
Return type: str

libcloudforensics.providers.gcp.internal.common.GenerateDiskName(snapshot, disk_name_prefix=None)¶

Generate a new disk name for the disk to be created from the Snapshot.

The disk name must comply with the following RegEx:

^(?=.{1,63}$)[a-z]([-a-z0-9]*[a-z0-9])?$

i.e., it must be between 1 and 63 chars, the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.

Parameters

snapshot (GoogleComputeSnapshot) – A disk’s Snapshot.
disk_name_prefix (str) – Optional. A prefix for the disk name.

Returns

A name for the disk.

Return type

str

Raises

InvalidNameError – If the disk name does not comply with the RegEx.

libcloudforensics.providers.gcp.internal.common.GenerateSourceRange(exempted_src_ips=None)¶

Generate a list of denied source IP ranges.

The final list is a list of all IPs except the exempted ones.

Parameters: exempted_src_ips (List[str]) – List of IPs exempted from the deny-all ingress firewall rules, ex: analyst IPs.
Returns: Denied source IP ranges specified in CIDR notation.
Return type: List[str]

libcloudforensics.providers.gcp.internal.common.GenerateUniqueInstanceName(prefix, truncate_at=None)¶

Add a timestamp as a suffix to provided name and truncate at max limit.

Parameters

prefix (str) – The name prefix to add the timestamp to and truncate.
truncate_at (int) – Optional. The maximum length of the generated name. Default no limit.

Returns

The name after adding a timestamp.: Ex: [prefix]-[TIMESTAMP(‘%Y%m%d%H%M%S’)]

Return type

str

class libcloudforensics.providers.gcp.internal.common.GoogleCloudComputeClient(project_id=None)¶

Bases: object

Class representing Google Cloud Compute API client.

Request and response dictionary content is described here: https://cloud.google.com/compute/docs/reference/rest/v1

project_id¶

Project name.

Type: str

BlockOperation(response, zone=None)¶

Block until API operation is finished.

Parameters

response (Dict) – GCE API response.
zone (str) – Optional. GCP zone to execute the operation in. None means GlobalZone.

Returns

Holding the response of a get operation on an API object of type: zoneOperations or globalOperations.

Return type

Dict

Raises

RuntimeError – If API call failed.

COMPUTE_ENGINE_API_VERSION = 'v1'¶

GceApi()¶

Get a Google Compute Engine service object.

Returns

A Google Compute Engine service: object.

Return type

googleapiclient.discovery.Resource

libcloudforensics.providers.gcp.internal.compute module¶

Google Compute Engine functionalities.

class libcloudforensics.providers.gcp.internal.compute.GoogleCloudCompute(project_id, default_zone=None)¶

Bases: libcloudforensics.providers.gcp.internal.common.GoogleCloudComputeClient

Class representing all Google Cloud Compute objects in a project.

project_id¶: Project name.

default_zone¶: Default zone to create new resources in.

CreateDiskFromImage(src_image, zone, name=None)¶

Creates a GCE persistent disk from a GCE image.

Parameters

src_image (GoogleComputeImage) – Source image for the disk.
zone (str) – Zone to create the new disk in.
name (str) – Optional. Name of the disk to create. Default is [src_image.name]-[TIMESTAMP(‘%Y%m%d%H%M%S’)].

Returns

A Google Compute Disk object.

Return type

GoogleComputeDisk

Raises

InvalidNameError – If GCE disk name is invalid.

CreateDiskFromSnapshot(snapshot, disk_name=None, disk_name_prefix=None, disk_type='pd-standard')¶

Create a new disk based on a Snapshot.

Parameters

snapshot (GoogleComputeSnapshot) – Snapshot to use.
disk_name (str) – Optional. String to use as new disk name.
disk_name_prefix (str) – Optional. String to prefix the disk name with.
disk_type (str) – Optional. URL of the disk type resource describing which disk type to use to create the disk. Default is pd-standard. Use pd-ssd to have a SSD disk. You can list all available disk types by running the following command: gcloud compute disk-types list

Returns

Google Compute Disk.

Return type

GoogleComputeDisk

Raises

ResourceCreationError – If the disk could not be created.

CreateImageFromDisk(src_disk, name=None)¶

Creates an image from a persistent disk.

Parameters

src_disk (GoogleComputeDisk) – Source disk for the image.
name (str) – Optional. Name of the image to create. Default is [src_disk.name]-[TIMESTAMP(‘%Y%m%d%H%M%S’)].

Returns

A Google Compute Image object.

Return type

GoogleComputeImage

Raises

InvalidNameError – If the GCE Image name is invalid.

CreateImageFromGcsTarGz(gcs_uri, name=None)¶

Creates a GCE image from a Gzip compressed Tar archive in GCS.

Parameters

gcs_uri (str) – Path to the compressed image archive (image.tar.gz) in Cloud Storage. It must be a gzip compressed tar archive with the extension .tar.gz. ex: ‘https://storage.cloud.google.com/foo/bar.tar.gz’ ‘gs://foo/bar.tar.gz’ ‘foo/bar.tar.gz’
name (str) – Optional. Name of the image to create. Default is [src_disk.name]-[TIMESTAMP(‘%Y%m%d%H%M%S’)].

Returns

A Google Compute Image object.

Return type

GoogleComputeImage

Raises

InvalidNameError – If the GCE Image name is invalid.
ValueError – If the extension of the archived image is invalid.

Disks(refresh=True)¶

Get all disks in the project.

Parameters

refresh (boolean) – Optional. Returns refreshed result if True.

Returns

Dictionary mapping disk names (str) to: their respective GoogleComputeDisk object.

Return type

Dict[str, GoogleComputeDisk]

GetDisk(disk_name)¶

Get a GCP disk object.

Parameters: disk_name (str) – Name of the disk.
Returns: Disk object.
Return type: GoogleComputeDisk
Raises: ResourceNotFoundError – When the specified disk cannot be found in project.

GetInstance(instance_name)¶

Get instance from project.

Parameters: instance_name (str) – The instance name.
Returns: A Google Compute Instance object.
Return type: GoogleComputeInstance
Raises: ResourceNotFoundError – If instance does not exist.

GetOrCreateAnalysisVm(vm_name, boot_disk_size, disk_type='pd-standard', cpu_cores=4, image_project='ubuntu-os-cloud', image_family='ubuntu-1804-lts', packages=None)¶

Get or create a new virtual machine for analysis purposes.

If none of the optional parameters are specified, then by default the analysis VM that will be created will run Ubuntu 18.04 LTS. A default set of forensic tools is also installed (a custom one may be provided using the ‘packages’ argument).

Parameters

vm_name (str) – Name of the virtual machine.
boot_disk_size (int) – The size of the analysis VM boot disk (in GB).
disk_type (str) – Optional. URL of the disk type resource describing which disk type to use to create the disk. Default is pd-standard. Use pd-ssd to have a SSD disk.
cpu_cores (int) – Optional. Number of CPU cores for the virtual machine.
image_project (str) – Optional. Name of the project where the analysis VM image is hosted.
image_family (str) – Optional. Name of the image to use to create the analysis VM.
packages (List[str]) – Optional. List of packages to install in the VM.

Returns

A tuple with a virtual machine object: and a boolean indicating if the virtual machine was created or not.

Return type

Tuple(GoogleComputeInstance, bool)

Raises

RuntimeError – If virtual machine cannot be created.

ImportImageFromStorage(storage_image_path, image_name=None, bootable=False, os_name=None, guest_environment=True)¶

Import GCE image from Cloud storage.

The import tool supports raw disk images and most virtual disk file formats, valid import formats are: [raw (dd), qcow2, qcow , vmdk, vdi, vhd, vhdx, qed, vpc].

Parameters

storage_image_path (str) – Path to the source image in Cloud Storage.
image_name (str) – Optional. Name of the imported image, default is “imported-image-” appended with a timestamp in “%Y%m%d%H%M%S” format.
bootable (bool) – Optional. True if the imported image is bootable. Default is False. If True the os_name must be specified.
os_name (str) – Optional. Name of the operating system on the bootable image. For supported versions please see: https://cloud.google.com/sdk/gcloud/reference/compute/images/import#–os # pylint: disable=line-too-long For known limitations please see: https://googlecloudplatform.github.io/compute-image-tools/image-import.html#compatibility-and-known-limitations # pylint: disable=line-too-long
guest_environment (bool) – Optional. Install Google Guest Environment on a bootable image. Relevant only if image is bootable. Default True.

Returns

A Google Compute Image object.

Return type

GoogleComputeImage

Raises

ValueError – If bootable is True and os_name not specified.
InvalidNameError – If imported image name is invalid.

InsertFirewallRule(body)¶

Insert a firewall rule to the project.

Parameters: body (Dict) – The request body. https://googleapis.github.io/google-api-python-client/docs/dyn/compute_v1.firewalls.html#insert # pylint: disable=line-too-long
Return type: None

Instances(refresh=True)¶

Get all instances in the project.

Parameters

refresh (boolean) – Optional. Returns refreshed result if True.

Returns

Dictionary mapping instance names: (str) to their respective GoogleComputeInstance object.

Return type

Dict[str, GoogleComputeInstance]

ListDiskByLabels(labels_filter, filter_union=True)¶

List Disks in a project with one/all of the provided labels.

This will call the _ListByLabel function on a disks() API object with the proper labels filter and return a Dict with name and metadata for each disk, e.g.:

{‘disk-1’: {‘zone’: ‘us-central1-a’, ‘labels’: {‘id’: ‘123’}}

Parameters

labels_filter (Dict[str, str]) – A Dict of labels to find e.g. {‘id’: ‘123’}.
filter_union (bool) – Optional. A Boolean; True to get the union of all filters, False to get the intersection.

Returns

Dictionary mapping disks to their: respective GoogleComputeDisk object.

Return type

Dict[str, GoogleComputeDisk]

ListDisks()¶

List disks in project.

Returns

Dictionary mapping disk names (str) to: their respective GoogleComputeDisk object.

Return type

Dict[str, GoogleComputeDisk]

ListInstanceByLabels(labels_filter, filter_union=True)¶

List VMs in a project with one/all of the provided labels.

This will call the _ListByLabel function on an instances() API object with the proper labels filter and return a Dict with name and metadata for each instance, e.g.:

{‘instance-1’: {‘zone’: ‘us-central1-a’, ‘labels’: {‘id’: ‘123’}}

Parameters

labels_filter (Dict[str, str]) – A Dict of labels to find e.g. {‘id’: ‘123’}.
filter_union (bool) – Optional. A Boolean; True to get the union of all filters, False to get the intersection.

Returns

Dictionary mapping instances to their: respective GoogleComputeInstance object.

Return type

Dict[str, GoogleComputeInstance]

ListInstances()¶

List instances in project.

Returns

Dictionary mapping instance names (str): to their respective GoogleComputeInstance object.

Return type

Dict[str, GoogleComputeInstance]

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeDisk(project_id, zone, name, labels=None)¶

Bases: libcloudforensics.providers.gcp.internal.compute_base_resource.GoogleComputeBaseResource

Class representing a Compute Engine disk.

Delete()¶

Delete a Disk.

Return type: None

GetDiskType()¶

Return the disk type.

Returns: The disk type.
Return type: str

GetOperation()¶

Get API operation object for the disk.

Returns

An API operation object for a Google Compute Engine disk.: https://cloud.google.com/compute/docs/reference/rest/v1/disks/get#response-body

Return type

Dict

Snapshot(snapshot_name=None)¶

Create Snapshot of the disk.

The Snapshot name must comply with the following RegEx:

^(?=.{1,63}$)[a-z]([-a-z0-9]*[a-z0-9])?$

i.e., it must be between 1 and 63 chars, the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.

Parameters: snapshot_name (str) – Optional. Name of the Snapshot.
Returns: A Snapshot object.
Return type: GoogleComputeSnapshot
Raises: InvalidNameError – If the name of the snapshot does not comply with the RegEx.

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeImage(project_id, zone, name, labels=None)¶

Bases: libcloudforensics.providers.gcp.internal.compute_base_resource.GoogleComputeBaseResource

Class representing a Compute Engine Image.

Delete()¶

Delete Compute Disk Image from a project.

Return type: None

ExportImage(gcs_output_folder, output_name=None)¶

Export compute image to Google Cloud storage.

Exported image is compressed and stored in .tar.gz format.

Parameters

gcs_output_folder (str) – Folder path of the exported image.
output_name (str) – Optional. Name of the output file. Name will be appended with .tar.gz. Default is [image_name].tar.gz.

Raises

InvalidNameError – If exported image name is invalid.

Return type

None

GetOperation()¶

Get API operation object for the image.

Returns

Holding an API operation object for a Google Compute Engine Image.: https://cloud.google.com/compute/docs/reference/rest/v1/images/get#response-body

Return type

Dict

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeInstance(project_id, zone, name, labels=None)¶

Bases: libcloudforensics.providers.gcp.internal.compute_base_resource.GoogleComputeBaseResource

Class representing a Google Compute Engine virtual machine.

AttachDisk(disk, read_write=False)¶

Attach a disk to the virtual machine.

Parameters

disk (GoogleComputeDisk) – Disk to attach.
read_write (bool) – Optional. Boolean indicating whether the disk should be attached in RW mode. Default is False (read-only).

Return type

None

Delete(delete_disks=False)¶

Delete an Instance.

Parameters: delete_disks (bool) – force delete all attached disks (ignores the ‘Keep when instance is deleted’ bit).
Return type: None

DetachDisk(disk)¶

Detach a disk from the virtual machine.

Parameters: disk (GoogleComputeDisk) – Disk to detach.
Return type: None

DetachServiceAccount()¶

Detach a service account from the instance

Raises: errors.ServiceAccountRemovalError – if en error occurs while detaching the service account
Return type: None

GetBootDisk()¶

Get the virtual machine boot disk.

Returns: Disk object.
Return type: GoogleComputeDisk
Raises: ResourceNotFoundError – If no boot disk could be found.

GetDisk(disk_name)¶

Gets a disk attached to this virtual machine disk by name.

Parameters: disk_name (str) – The name of the disk to get.
Returns: Disk object.
Return type: GoogleComputeDisk
Raises: ResourceNotFoundError – If disk name is not found among those attached to the instance.

GetOperation()¶

Get API operation object for the virtual machine.

Returns

An API operation object for a Google Compute Engine: virtual machine. https://cloud.google.com/compute/docs/reference/rest/v1/instances/get#response-body

Return type

Dict

GetPowerState()¶

Gets the current power state of the instance.

As per https://cloud.google.com/compute/docs/reference/rest/v1/instances/get this can return one of the following possible values: PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING, and TERMINATED

Return type: str

ListDisks()¶

List all disks for the virtual machine.

Returns

Dictionary mapping disk names to their: respective GoogleComputeDisk object.

Return type

Dict[str, GoogleComputeDisk]

SetTags(new_tags)¶

Sets tags for the compute instance.

Tags are used to configure firewall rules and network routes.

Parameters: new_tags (List[str]) – A list of tags. Each tag must be 1-63 characters long, and comply with RFC1035.
Raises: InvalidNameError – If the name of the tags does not comply with RFC1035.
Return type: None

Ssh()¶

Connect to the virtual machine over SSH.

Return type: None

Start()¶

Starts the instance.

Raises: errors.InstanceStateChangeError – If the Start operation is unsuccessful
Return type: None

Stop()¶

Stops the instance.

Raises: errors.InstanceStateChangeError – If the Stop operation is unsuccessful
Return type: None

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeSnapshot(disk, name)¶

Bases: libcloudforensics.providers.gcp.internal.compute_base_resource.GoogleComputeBaseResource

Class representing a Compute Engine Snapshot.

disk¶

Disk used for the Snapshot.

Type: GoogleComputeDisk

Delete()¶

Delete a Snapshot.

Return type: None

GetOperation()¶

Get API operation object for the Snapshot.

Returns

An API operation object for a Google Compute Engine Snapshot.: https://cloud.google.com/compute/docs/reference/rest/v1/snapshots/get#response-body

Return type

Dict

libcloudforensics.providers.gcp.internal.compute_base_resource module¶

Google Compute Engine resources.

class libcloudforensics.providers.gcp.internal.compute_base_resource.GoogleComputeBaseResource(project_id, zone, name, labels=None)¶

Bases: libcloudforensics.providers.gcp.internal.common.GoogleCloudComputeClient

Base class representing a Computer Engine resource.

project_id¶

Google Cloud project ID.

Type: str

zone¶

What zone the resource is in.

Type: str

name¶

Name of the resource.

Type: str

labels¶

Dictionary of labels for the resource, if existing.

Type: Dict

AddLabels(new_labels_dict, blocking_call=False)¶

Add or update labels of a compute resource.

Parameters

new_labels_dict (Dict) – A dictionary containing the labels to be added, ex:{“incident_id”: “1234abcd”}.
blocking_call (bool) – Optional. A boolean to decide whether the API call should be blocking or not, default is False.

Returns

The response of the API operation (a Dict if the call is: successful).

Return type

Optional[Any]

Raises

RuntimeError – If the Compute resource Type is not one of instance, disk or snapshot.

FormOperation(operation_name)¶

Form an API operation object for the compute resource.

Example:[RESOURCE].FormOperation(‘setLabels’)(**kwargs) [RESOURCE] can be type “instance”, disk or “Snapshot”.

Parameters

operation_name (str) – The name of the API operation you need to perform.

Returns

An API operation object for the: referenced compute resource.

Return type

googleapiclient.discovery.Resource

Raises

RuntimeError – If resource type is not defined as a type which extends the GoogleComputeBaseResource class.

FormatLogMessage(message)¶

Format log messages with project specific information.

Parameters: message (str) – Message string to log.
Returns: Formatted log message string.
Return type: str

GetLabels()¶

Get all labels of a compute resource.

Returns: A dictionary of all labels.
Return type: Dict

GetOperation()¶

Abstract method to be implemented by child classes.

Raises: NotImplementedError – If the child class doesn’t implement GetOperation.
Return type: Dict[str, Any]

GetResourceType()¶

Get the resource type from the resource key-value store.

Returns

Resource Type which is a string with one of the following values:: compute#instance compute#disk compute#Snapshot

Return type

str

GetSourceString()¶

API URL to the resource.

Returns: The full API URL to the resource.
Return type: str

GetValue(key)¶

Get specific value from the resource key value store.

Parameters: key (str) – A key of type String to get key’s corresponding value.
Returns: Value of key/dictionary or None if key is missing.
Return type: str|Dict

libcloudforensics.providers.gcp.internal.function module¶

Google Cloud Functions functionalities.

class libcloudforensics.providers.gcp.internal.function.GoogleCloudFunction(project_id)¶

Bases: object

Class to call Google Cloud Functions.

project_id¶: Google Cloud project ID.

gcf_api_client¶: Client to interact with GCF APIs.

CLOUD_FUNCTIONS_API_VERSION = 'v1'¶

ExecuteFunction(function_name, region, args)¶

Executes a Google Cloud Function.

Parameters

function_name (str) – The name of the function to call.
region (str) – Region to execute functions in.
args (Dict) – Arguments to pass to the function. Dictionary content details can be found in https://cloud.google.com/functions/docs/reference/rest/v1/projects.locations.functions # pylint: disable=line-too-long

Returns

Return value from function call.

Return type

Dict[str, str]

Raises

RuntimeError – When cloud function arguments cannot be serialized or when an HttpError is encountered.

GcfApi()¶

Get a Google Cloud Function service object.

Returns

A Google Cloud Function service: object.

Return type

googleapiclient.discovery.Resource

libcloudforensics.providers.gcp.internal.gke module¶

Google Kubernetes Engine functionalities.

class libcloudforensics.providers.gcp.internal.gke.GoogleKubernetesEngine¶

Bases: object

Class to call Google Kubernetes Engine (GKE) APIs.

https://cloud.google.com/kubernetes-engine/docs/reference/rest

gke_api_client¶

Client to interact with GKE APIs.

Type: googleapiclient.discovery.Resource

GKE_API_VERSION = 'v1'¶

GetCluster(name)¶

Gets the details of a specific cluster.

Parameters

name (str) – The name (project, location, cluster) of the cluster to retrieve. Specified in the format projects/*/locations/*/clusters/*. For regional cluster: /locations/[GCP_REGION]. For zonal cluster: /locations/[GCP_ZONE].

Returns

A Google Kubernetes Engine cluster object:: https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster # pylint: disable=line-too-long

Return type

Dict

GkeApi()¶

Gets a Google Container service object.

https://container.googleapis.com/$discovery/rest?version=v1

Returns: A Google Container service object.
Return type: googleapiclient.discovery.Resource

libcloudforensics.providers.gcp.internal.log module¶

Google Cloud Logging functionalities.

class libcloudforensics.providers.gcp.internal.log.GoogleCloudLog(project_id)¶

Bases: object

Class representing a Google Cloud Logs interface.

project_id¶: Google Cloud project ID.

gcl_api_client¶: Client to interact with GCP logging API.

Example use:: # pylint: disable=line-too-long gcp = GoogleCloudLog(project_id=’your_project_name’) gcp.ListLogs() gcp.ExecuteQuery(filter=’resource.type=”gce_instance” labels.”compute.googleapis.com/resource_name”=”instance-1”’) See https://cloud.google.com/logging/docs/view/advanced-queries for filter details.

ExecuteQuery(qfilter)¶

Query logs in GCP project.

Parameters

qfilter (str) – The query filter to use.

Returns

Log entries returned by the query, e.g. [{‘projectIds’:: […], ‘resourceNames’: […]}, {…}]

Return type

List[Dict]

Raises

RuntimeError – If API call failed.

GclApi()¶

Get a Google Compute Logging service object.

Returns

A Google Compute Logging service: object.

Return type

googleapiclient.discovery.Resource

LOGGING_API_VERSION = 'v2'¶

ListLogs()¶

List logs in project.

Returns: The project logs available.
Return type: List[str]
Raises: RuntimeError – If API call failed.

libcloudforensics.providers.gcp.internal.monitoring module¶

Google Cloud Monitoring functionality.

class libcloudforensics.providers.gcp.internal.monitoring.GoogleCloudMonitoring(project_id)¶

Bases: object

Class to call Google Monitoring APIs.

https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries

project_id¶: Project name.

gcm_api_client¶: Client to interact with Monitoring APIs.

ActiveServices(timeframe=30)¶

List active services in the project (default: last 30 days).

Parameters: timeframe (int) – Optional. The number (in days) for which to measure activity.
Returns: Dictionary mapping service name to number of uses.
Return type: Dict[str, int]

CLOUD_MONITORING_API_VERSION = 'v3'¶

GcmApi()¶

Get a Google Cloud Monitoring service object.

Returns

A Google Cloud Monitoring: service object.

Return type

googleapiclient.discovery.Resource

libcloudforensics.providers.gcp.internal.project module¶

Google Cloud Project resources and services.

class libcloudforensics.providers.gcp.internal.project.GoogleCloudProject(project_id, default_zone='us-central1-f')¶

Bases: object

Class representing a Google Cloud Project.

project_id¶: Google Cloud project ID.

default_zone¶: Default zone to create new resources in.

Example use:: gcp = GoogleCloudProject(“your_project_name”, “us-east1-b”) gcp.compute.ListInstances()

property build¶

Get a GoogleCloudBuild object for the project.

Returns: Object that represents Google Cloud Build.
Return type: GoogleCloudBuild

property cloudsql¶

Get a GoogleCloudSql object for the project.

Returns: Object that represents Google SQL.
Return type: GoogleCloudSql

property compute¶

Get a GoogleCloudCompute object for the project.

Returns: Object that represents Google Cloud Compute Engine.
Return type: GoogleCloudCompute

property function¶

Get a GoogleCloudFunction object for the project.

Returns: Object that represents Google Cloud Function.
Return type: GoogleCloudFunction

property gke¶

Get a GoogleKubernetesEngine object for the project.

Returns: Object that represents Google Kubernetes Engine.
Return type: GoogleKubernetesEngine

property log¶

Get a GoogleCloudLog object for the project.

Returns: Object that represents Google Cloud Logging.
Return type: GoogleCloudLog

property monitoring¶

Get a GoogleCloudMonitoring object for the project.

Returns: Object that represents Google Monitoring.
Return type: GoogleCloudMonitoring

property storage¶

Get a GoogleCloudStorage object for the project.

Returns: Object that represents Google Cloud Logging.
Return type: GoogleCloudLog

libcloudforensics.providers.gcp.internal.storage module¶

Google Cloud Storage functionalities.

class libcloudforensics.providers.gcp.internal.storage.GoogleCloudStorage(project_id=None)¶

Bases: object

Class to call Google Cloud Storage APIs.

gcs_api_client¶: Client to interact with GCS APIs.

project_id¶: Google Cloud project ID.

CLOUD_STORAGE_API_VERSION = 'v1'¶

CreateBucket(bucket, labels=None, predefined_acl='private', predefined_default_object_acl='private')¶

Creates a Google Cloud Storage bucket in the current project.

Parameters

bucket (str) – Name of the desired bucket.
labels (Dict[str, str]) – Mapping of key/value strings to be applied as a label to the bucket. Rules for acceptable label values are located at https://cloud.google.com/storage/docs/key-terms#bucket-labels
predefined_acl (str) – A predefined set of Access Controls to apply to the bucket.
predefined_default_object_acl (str) – A predefined set of Access Controls to apply to the objects in the bucket.
listed in https (Values) – //cloud.google.com/storage/docs/json_api/v1/buckets/insert#parameters # pylint: disable=line-too-long

Returns

An API operation object for a Google Cloud Storage bucket.: https://cloud.google.com/storage/docs/json_api/v1/buckets#resource

Return type

Dict[str, Any]

DeleteObject(gcs_path)¶

Deletes an object in a Google Cloud Storage bucket.

Parameters: gcs_path (str) – Full path to the object (ie: gs://bucket/dir1/dir2/obj)
Return type: None

GcsApi()¶

Get a Google Cloud Storage service object.

Returns: A Google Cloud Storage service object.
Return type: googleapiclient.discovery.Resource

GetBucketACLs(bucket, user_project=None)¶

Get ACLs for a Google Cloud Storage bucket.

This includes both ACL entries and IAM policies.

Parameters

bucket (str) – Name of a bucket in GCS. Ex: logs_bucket_1
user_project (str) – The project ID to be billed for this request. Required for Requester Pays buckets.

Returns

A mapping of role to members of that role.

Return type

Dict

GetBucketSize(bucket, timeframe=1)¶

List the size of a Google Storage Bucket in a project (default: last 1 day).

Note: This will list the _maximum size_: (in bytes) the bucket had in the timeframe.

Ref: https://cloud.google.com/monitoring/api/metrics_gcp#gcp-storage

Parameters

bucket (str) – Name of a bucket in GCS.
timeframe (int) – Optional. The number (in days) for which to measure activity. Default: 1 day.

Returns

Dictionary mapping bucket name to its size (in bytes).

Return type

Dict[str, int]

GetObject(gcs_path, out_file=None)¶

Gets the contents of an object in a Google Cloud Storage bucket.

Parameters

gcs_path (str) – Full path to the object (ie: gs://bucket/dir1/dir2/obj)
out_file (str) – Path to the local file that will be written. If not provided, will create a temporary file.

Returns

The filename of the written object.

Return type

str

Raises

ResourceCreationError – If the file couldn’t be downloaded.

GetObjectMetadata(gcs_path, user_project=None)¶

Get API operation object metadata for Google Cloud Storage object.

Parameters

gcs_path (str) – File path to a resource in GCS. Ex: gs://bucket/folder/obj
user_project (str) – The project ID to be billed for this request. Required for Requester Pays buckets.

Returns

An API operation object for a Google Cloud Storage object.: https://cloud.google.com/storage/docs/json_api/v1/objects#resource

Return type

Dict

ListBucketObjects(bucket)¶

List objects (with metadata) in a Google Cloud Storage bucket.

Parameters: bucket (str) – Name of a bucket in GCS.
Return type: List[Dict[str, Any]]
Returns: List of Object Dicts (see GetObjectMetadata)

ListBuckets()¶

List buckets in a Google Cloud project.

Returns: List of object dicts. (https://cloud.google.com/storage/docs/json_api/v1/buckets#resource)
Return type: List[Dict[str, Any]]

libcloudforensics.providers.gcp.internal.storage.SplitStoragePath(path)¶

Split a path to bucket name and object URI.

Parameters: path (str) – File path to a resource in GCS. Ex: gs://bucket/folder/obj
Returns: Bucket name. Object URI.
Return type: Tuple[str, str]

libcloudforensics.providers.gcp.forensics module¶

Forensics on GCP.

libcloudforensics.providers.gcp.forensics.AddDenyAllFirewallRules(project_id, network, deny_ingress_tag, deny_egress_tag, exempted_src_ips=None, enable_logging=False)¶

Add deny-all firewall rules, of highest priority.

Parameters

project_id (str) – Google Cloud Project ID.
network (str) – URL of the network resource for thesee firewall rules.
deny_ingress_tag (str) – Target tag name to apply deny ingress rule, also used as a deny ingress firewall rule name.
deny_egress_tag (str) – Target tag name to apply deny egress rule, also used as a deny egress firewall rule name.
exempted_src_ips (List[str]) – List of IPs exempted from the deny-all ingress firewall rules, ex: analyst IPs.
enable_logging (bool) – Optional. Enable firewall logging. Default is False.

Raises

InvalidNameError – If Tag names are invalid.

Return type

None

libcloudforensics.providers.gcp.forensics.CreateDiskCopy(src_proj, dst_proj, zone, instance_name=None, disk_name=None, disk_type=None)¶

Creates a copy of a Google Compute Disk.

Parameters

src_proj (str) – Name of project that holds the disk to be copied.
dst_proj (str) – Name of project to put the copied disk in.
zone (str) – Zone where the new disk is to be created.
instance_name (str) – Optional. Instance using the disk to be copied.
disk_name (str) – Optional. Name of the disk to copy. If None, instance_name must be specified and the boot disk will be copied.
disk_type (str) – Optional. URL of the disk type resource describing which disk type to use to create the disk. The default behavior is to use the same disk type as the source disk.

Returns

A Google Compute Disk object.

Return type

GoogleComputeDisk

Raises

ResourceNotFoundError – If the GCP resource is not found.
CredentialsConfigurationError – If the library could not authenticate to GCP.
RuntimeError – If an unknown HttpError is thrown.
ResourceCreationError – If there are errors copying the disk.
ValueError – If both instance_name and disk_name are missing.

libcloudforensics.providers.gcp.forensics.CreateDiskFromGCSImage(project_id, storage_image_path, zone, name=None)¶

Creates a GCE persistent disk from a image in GCS.

The method supports raw disk images and most virtual disk file formats. Valid import formats are: [raw (dd), qcow2, qcow , vmdk, vdi, vhd, vhdx, qed, vpc].

The created GCE disk might be larger than the original raw (dd) image stored in GCS to satisfy GCE capacity requirements: https://cloud.google.com/compute/docs/disks/#introduction However the bytes_count and the md5_hash values of the source image are returned with the newly created disk. The md5_hash can be used to verify the integrity of the created GCE disk, it must be compared with the hash of the created GCE disk from byte 0 to bytes_count. i.e: result[‘md5Hash’] = hash(created_gce_disk,

start_byte=0, end_byte=result[‘bytes_count’])

Parameters

project_id (str) – Google Cloud Project ID.
storage_image_path (str) – Path to the source image in GCS.
zone (str) – Zone to create the new disk in.
name (str) – Optional. Name of the disk to create. Default is imported-disk-[TIMESTAMP(‘%Y%m%d%H%M%S’)].

Returns

A key value describing the imported GCE disk.

Ex: {: ‘project_id’: ‘fake-project’, ‘disk_name’: ‘fake-imported-disk’, ‘zone’: ‘fake-zone’, ‘bytes_count’: ‘1234’ # Content-Length of source image in bytes. ‘md5Hash’: ‘Source Image MD5 hash string in hex’

}

Return type

Dict

Raises

InvalidNameError – If the GCE disk name is invalid.

libcloudforensics.providers.gcp.forensics.InstanceNetworkQuarantine(project_id, instance_name, exempted_src_ips=None, enable_logging=False)¶

Put a Google Cloud instance in network quarantine.

Network quarantine is imposed via applying deny-all ingress/egress firewall rules on each network interface.

Parameters

project_id (str) – Google Cloud Project ID.
instance_name (str) – : The name of the virtual machine.
exempted_src_ips (List[str]) – List of IPs exempted from the deny-all ingress firewall rules, ex: analyst IPs.
enable_logging (bool) – Optional. Enable firewall logging. Default is False.

Return type

None

libcloudforensics.providers.gcp.forensics.StartAnalysisVm(project, vm_name, zone, boot_disk_size, boot_disk_type, cpu_cores, attach_disks=None, image_project='ubuntu-os-cloud', image_family='ubuntu-1804-lts')¶

Start a virtual machine for analysis purposes.

Parameters

project (str) – Project id for virtual machine.
vm_name (str) – The name of the virtual machine.
zone (str) – Zone for the virtual machine.
boot_disk_size (int) – The size of the analysis VM boot disk (in GB).
boot_disk_type (str) – URL of the disk type resource describing which disk type to use to create the disk. Use pd-standard for a standard disk and pd-ssd for a SSD disk.
cpu_cores (int) – The number of CPU cores to create the machine with.
attach_disks (List[str]) – Optional. List of disk names to attach.
image_project (str) – Optional. Name of the project where the analysis VM image is hosted.
image_family (str) – Optional. Name of the image to use to create the analysis VM.

Returns

A tuple with a virtual machine object: and a boolean indicating if the virtual machine was created or not.

Return type

Tuple(GoogleComputeInstance, bool)

libcloudforensics.providers.gcp.forensics.VMRemoveServiceAccount(project_id, instance_name, leave_stopped=False)¶

Remove a service account attachment from a GCP VM.

Service account attachments to VMs allow the VM to obtain credentials via the instance metadata service to perform API actions. Removing the service account attachment will prevent credentials being issued.

Note that the instance will be powered down, if it isn’t already for this action.

Parameters

project_id (str) – Google Cloud Project ID.
instance_name (str) – The name of the virtual machine.
leave_stopped (bool) – Optional. True to leave the machine powered off.

Returns

True if the service account was successfully removed, False otherwise.

Return type

bool

AWS forensics package¶

Internal provider functions¶

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

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.

Azure forensics package¶

Internal provider functions¶

Azure internal provider functions¶

libcloudforensics.providers.azure.internal.account module¶

Represents an Azure account.

class libcloudforensics.providers.azure.internal.account.AZAccount(default_resource_group_name, default_region='eastus', profile_name=None)¶

Bases: object

Class that represents an Azure Account.

subscription_id¶

The Azure subscription ID to use.

Type: str

credentials¶

An Azure credentials object.

Type: ServicePrincipalCredentials

default_region¶

The default region to create new resources in.

Type: str

default_resource_group_name¶

The default resource group in which to create new resources in.

Type: str

property compute¶

Get an Azure compute object for the account.

Returns: An Azure compute object.
Return type: AZCompute

property monitoring¶

Get an Azure monitoring object for the account.

Returns: An Azure monitoring object.
Return type: AZMonitoring

property network¶

Get an Azure network object for the account.

Returns: An Azure network object.
Return type: AZNetwork

property resource¶

Get an Azure resource object for the account.

Returns: An Azure resource object.
Return type: AZResource

property storage¶

Get an Azure storage object for the account.

Returns: An Azure storage object.
Return type: AZStorage

libcloudforensics.providers.azure.internal.common module¶

Common utilities.

libcloudforensics.providers.azure.internal.common.ExecuteRequest(client, func, kwargs=None)¶

Execute a request to the Azure API.

Parameters

client (Any) – An Azure operation client object.
func (str) – An Azure function to query from the client.
kwargs (Dict) – Optional. A dictionary of parameters for the function func.

Returns

A List of Azure response objects (VirtualMachines, Disks, etc).

Return type

List[Any]

Raises

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

libcloudforensics.providers.azure.internal.common.GenerateDiskName(snapshot, disk_name_prefix=None)¶

Generate a new disk name for the disk to be created from the Snapshot.

The disk name must comply with the following RegEx:

^[w]{1-80}$

i.e., it must be between 1 and 80 chars, and can only contain alphanumeric characters and underscores.

Parameters

snapshot (AZComputeSnapshot) – A disk’s Snapshot.
disk_name_prefix (str) – Optional. A prefix for the disk name.

Returns

A name for the disk.

Return type

str

Raises

InvalidNameError – If the disk name does not comply with the RegEx.

libcloudforensics.providers.azure.internal.common.GetCredentials(profile_name=None)¶

Get Azure credentials.

Parameters

profile_name (str) –

A name for the Azure account information to retrieve. If not provided, the default behavior is to look for Azure credential information in environment variables as explained in https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-authenticate If provided, then the library will look into ~/.azure/credentials.json for the account information linked to profile_name. The .json file should have the following format:

{

‘profile_name’: {: ‘subscriptionId’: xxx, ‘tenantId’: xxx, ‘clientId’: xxx, ‘clientSecret’: xxx

}, ‘other_profile_name’: {

’subscriptionId’: yyy, ‘tenantId’: yyy, ‘clientId’: yyy, ‘clientSecret’: yyy

}

Note that you can specify several profiles that use the same tenantId, clientId and clientSecret but a different subscriptionId. If you set the environment variable AZURE_CREDENTIALS_PATH to an absolute path to the credentials file, then the library will look there instead of in ~/.azure/credentials.json.

Returns

Subscription ID and: corresponding Azure credentials.

Return type

Tuple[str, DefaultAzureCredential]

Raises

CredentialsConfigurationError – If there are environment variables that are not set or if the credentials file has missing entries/profiles.
FileNotFoundError – If the credentials file is not found.
InvalidFileFormatError – If the credentials file couldn’t be parsed.

libcloudforensics.providers.azure.internal.compute module¶

Azure Compute functionality.

class libcloudforensics.providers.azure.internal.compute.AZCompute(az_account)¶

Bases: object

Class representing all Azure Compute objects in an account.

az_account¶: An Azure account object.

compute_client¶

An Azure compute client object.

Type: ComputeManagementClient

CreateDiskFromSnapshot(snapshot, region=None, disk_name=None, disk_name_prefix=None, disk_type='Standard_LRS')¶

Create a new disk based on a Snapshot.

Parameters

snapshot (AZComputeSnapshot) – Snapshot to use.
region (str) – Optional. The region in which to create the disk. If not provided, the disk will be created in the default_region associated to the AZAccount object.
disk_name (str) – Optional. String to use as new disk name.
disk_name_prefix (str) – Optional. String to prefix the disk name with.
disk_type (str) – Optional. The sku name for the disk to create. Can be Standard_LRS, Premium_LRS, StandardSSD_LRS, or UltraSSD_LRS. The default value is Standard_LRS.

Returns

Azure Compute Disk.

Return type

AZComputeDisk

Raises

ResourceCreationError – If the disk could not be created.

CreateDiskFromSnapshotURI(snapshot, snapshot_uri, region=None, disk_name=None, disk_name_prefix=None, disk_type='Standard_LRS')¶

Create a new disk based on a SAS snapshot URI.

This is useful if e.g. one wants to make a copy of a disk in a separate Azure account. This method will create a temporary Azure Storage account within the destination account, import the snapshot from a downloadable link (the source account needs to share the snapshot through a SAS link) and then create a disk from the VHD file saved in storage. The Azure storage account is then deleted.

Parameters

snapshot (AZComputeSnapshot) – Source snapshot to use.
snapshot_uri (str) – The URI of the snapshot to copy.
region (str) – Optional. The region in which to create the disk. If not provided, the disk will be created in the default_region associated to the AZAccount object.
disk_name (str) – Optional. String to use as new disk name.
disk_name_prefix (str) – Optional. String to prefix the disk name with.
disk_type (str) – Optional. The sku name for the disk to create. Can be Standard_LRS, Premium_LRS, StandardSSD_LRS, or UltraSSD_LRS. Default is Standard_LRS.

Returns

Azure Compute Disk.

Return type

AZComputeDisk

Raises

ResourceCreationError – If the disk could not be created.

GetDisk(disk_name, resource_group_name=None)¶

Get disk from AZ subscription / resource group.

Parameters

disk_name (str) – The disk name.
resource_group_name (str) – Optional. The resource group name to look the disk in. If none specified, then the disk will be fetched from the AZ subscription.

Returns

An Azure Compute Disk object.

Return type

AZComputeDisk

Raises

ResourceNotFoundError – If the disk was not found in the subscription/ resource group.

GetInstance(instance_name, resource_group_name=None)¶

Get instance from AZ subscription / resource group.

Parameters

instance_name (str) – The instance name.
resource_group_name (str) – Optional. The resource group name to look the instance in. If none specified, then the instance will be fetched from the AZ subscription.

Returns

An Azure virtual machine object.

Return type

AZComputeVirtualMachine

Raises

ResourceNotFoundError – If the instance was not found in the subscription/ resource group.

GetOrCreateAnalysisVm(vm_name, boot_disk_size, cpu_cores, memory_in_mb, ssh_public_key, region=None, packages=None, tags=None)¶

Get or create a new virtual machine for analysis purposes.

Parameters

vm_name (str) – The instance name tag of the virtual machine.
boot_disk_size (int) – The size of the analysis VM boot volume (in GB).
cpu_cores (int) – Number of CPU cores for the analysis VM.
memory_in_mb (int) – The memory size (in MB) for the analysis VM.
ssh_public_key (str) – A SSH public key data to associate with the VM. This must be provided as otherwise the VM will not be accessible.
region (str) – Optional. The region in which to create the vm. If not provided, the vm will be created in the default_region associated to the AZAccount object.
packages (List[str]) – Optional. List of packages to install in the VM.
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.

Returns

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

Return type

Tuple[AZComputeVirtualMachine, bool]

Raises

RuntimeError – If the provided SSH key is invalid.
ResourceCreationError – If the virtual machine cannot be found or created.

ListDisks(resource_group_name=None)¶

List disks in an Azure subscription / resource group.

Parameters

resource_group_name (str) – Optional. The resource group name to list disks from. If none specified, then all disks in the AZ subscription will be listed.

Returns

Dictionary mapping disk names (str) to their: respective AZComputeDisk object.

Return type

Dict[str, AZComputeDisk]

ListInstanceTypes(region=None)¶

Returns a list of available VM sizes for a given region.

Parameters

region (str) – Optional. The region in which to look the instance types. By default, look in the default_region associated to the AZAccount object.

Returns

A list of available vm size. Each size is a: dictionary containing the name of the configuration, the number of CPU cores, and the amount of available memory (in MB). E.g.: {‘Name’: ‘Standard_B1ls’, ‘CPU’: 1, ‘Memory’: 512}

Return type

List[Dict[str, str]]

ListInstances(resource_group_name=None)¶

List instances in an Azure subscription / resource group.

Parameters

resource_group_name (str) – Optional. The resource group name to list instances from. If none specified, then all instances in the Azure subscription will be listed.

Returns

Dictionary mapping instance names: (str) to their respective AZComputeVirtualMachine object.

Return type

Dict[str, AZComputeVirtualMachine]

class libcloudforensics.providers.azure.internal.compute.AZComputeDisk(az_account, resource_id, name, region, zones=None)¶

Bases: libcloudforensics.providers.azure.internal.compute_base_resource.AZComputeResource

Class that represents Azure disks.

GetDiskType()¶

Return the SKU disk type.

Returns: The SKU disk type.
Return type: str

Snapshot(snapshot_name=None, tags=None)¶

Create a snapshot of the disk.

Parameters

snapshot_name (str) – Optional. A name for the snapshot. If none provided, one will be generated based on the disk’s name.
tags (Dict[str, str]) – Optional. A dictionary of tags to add to the snapshot, for example {‘TicketID’: ‘xxx’}.

Returns

A snapshot object.

Return type

AZComputeSnapshot

Raises

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

class libcloudforensics.providers.azure.internal.compute.AZComputeSnapshot(az_account, resource_id, name, region, source_disk)¶

Bases: libcloudforensics.providers.azure.internal.compute_base_resource.AZComputeResource

Class that represents Azure snapshots.

disk¶

The disk from which the snapshot was taken.

Type: AZComputeDisk

Delete()¶

Delete a snapshot.

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

GrantAccessAndGetURI()¶

Grant access to a snapshot and return its access URI.

Returns: The access URI for the snapshot.
Return type: str

RevokeAccessURI()¶

Revoke access to a snapshot.

Return type: None

class libcloudforensics.providers.azure.internal.compute.AZComputeVirtualMachine(az_account, resource_id, name, region, zones=None)¶

Bases: libcloudforensics.providers.azure.internal.compute_base_resource.AZComputeResource

Class that represents Azure virtual machines.

AttachDisk(disk)¶

Attach a disk to the virtual machine.

Parameters: disk (AZComputeDisk) – Disk to attach.
Raises: RuntimeError – If the disk could not be attached.
Return type: None

GetBootDisk()¶

Get the instance’s boot disk.

Returns: Disk object if the disk is found.
Return type: AZComputeDisk
Raises: ResourceNotFoundError – If no boot disk could be found.

GetDisk(disk_name)¶

Get a disk attached to the instance by ID.

Parameters: disk_name (str) – The ID of the disk to get.
Returns: The disk object.
Return type: AZComputeDisk
Raises: ResourceNotFoundError – If disk_name is not found amongst the disks attached to the instance.

ListDisks()¶

List all disks for the instance.

Returns

Dictionary mapping disk names to their: respective AZComputeDisk object.

Return type

Dict[str, AZComputeDisk]

libcloudforensics.providers.azure.internal.compute_base_resource module¶

Azure Compute Base Resource.

class libcloudforensics.providers.azure.internal.compute_base_resource.AZComputeResource(az_account, resource_id, name, region, zones=None)¶

Bases: object

Class that represent an Azure compute resource.

az_account¶

An Azure account object.

Type: AZAccount

resource_group_name¶

The Azure resource group name for the resource.

Type: str

resource_id¶

The Azure resource ID.

Type: str

name¶

The resource’s name.

Type: str

region¶

The region in which the resource is located.

Type: str

zones¶

Optional. Availability zones within the region where the resource is located.

Type: List[str]

property compute_client¶

Return the Azure compute client object associated to the Azure: account.

Returns: An Azure compute client object.
Return type: ComputeManagementClient

libcloudforensics.providers.azure.internal.monitoring module¶

Azure Monitoring functionality.

class libcloudforensics.providers.azure.internal.monitoring.AZMonitoring(az_account)¶

Bases: object

Azure Monitoring.

monitoring_client¶

An Azure monitoring client object.

Type: MonitorManagementClient

GetMetricsForResource(resource_id, metrics, from_date=None, to_date=None, interval=None, aggregation='Total', qfilter=None)¶

Retrieve metrics for a given resource.

Parameters

resource_id (str) – The resource ID for which to lookup the metric.
metrics (str) – A comma separated list of metrics to retrieve. E.g. ‘Percentage CPU,Network In’.
from_date (datetime.datetime) – Optional. A start date from which to get the metric. If passed, to_date is also required.
to_date (datetime.datetime) – Optional. An end date until which to get the metric. If passed, from_date is also required.
interval (str) – An interval for the metrics, e.g. ‘PT1H’ will output metric’s values with one hour granularity.
aggregation (str) – Optional. The type of aggregation for the metric’s values. Default is ‘Total’. Possible values: ‘Total’, ‘Average’. Both can be retrieved if passed as a single string, separated by a comma.
qfilter (str) – Optional. A filter for the query. See https://docs.microsoft.com/en-us/rest/api/monitor/metrics/list for details about filtering.

Returns

A dictionary mapping the metric to a dict of: the metric’s values, per timestamp.

Return type

Dict[str, Dict[str, str]]

Raises

RuntimeError – If the resource could not be found.

ListAvailableMetricsForResource(resource_id)¶

List the available metrics for a given resource.

Parameters: resource_id (str) – The resource ID from which to list available metrics.
Returns: A list of metrics that can be queried for the resource ID.
Return type: List[str]
Raises: RuntimeError – If the resource could not be found.

libcloudforensics.providers.azure.internal.network module¶

Azure Networking functionality.

class libcloudforensics.providers.azure.internal.network.AZNetwork(az_account)¶

Bases: object

Azure Networking functionality.

az_account¶

An Azure account object.

Type: AZAccount

network_client¶

An Azure network client object.

Type: NetworkManagementClient

CreateNetworkInterface(name, region=None)¶

Create a network interface and returns its ID.

Parameters

name (str) – The name of the network interface.
region (str) – Optional. The region in which to create the network interface. Default uses default_region of the AZAccount object.

Returns

The id of the created network interface.

Return type

str

Raises

ValueError – if name is not provided.
ResourceCreationError – If no network interface could be created.

libcloudforensics.providers.azure.internal.resource module¶

Azure Resource functionality.

class libcloudforensics.providers.azure.internal.resource.AZResource(az_account)¶

Bases: object

Azure resource functionality.

az_account¶

An Azure account object.

Type: AZAccount

resource_client¶

An Azure resource client object.

Type: ResourceManagementClient

subscription_client¶

An Azure subscription client object.

Type: SubscriptionClient

GetOrCreateResourceGroup(resource_group_name)¶

Check if a resource group exists, and create it otherwise.

Parameters: resource_group_name (str) – existence for. If it does not exist, create it.
Returns: The resource group name.
Return type: str

ListSubscriptionIDs()¶

List subscription ids from an Azure account.

Returns: A list of all subscription IDs from the Azure account.
Return type: List[str]

libcloudforensics.providers.azure.internal.storage module¶

Azure Storage functionality.

class libcloudforensics.providers.azure.internal.storage.AZStorage(az_account)¶

Bases: object

Azure Storage functionality.

az_account¶

An Azure account object.

Type: AZAccount

storage_client¶

An Azure storage client object.

Type: StorageManagementClient

CreateStorageAccount(storage_account_name, region=None)¶

Create a storage account and returns its ID and access key.

Parameters

storage_account_name (str) – The name for the storage account.
region (str) – Optional. The region in which to create the storage account. If not provided, it will be created in the default_region associated to the AZAccount object.

Returns

The storage account ID and its access key.

Return type

Tuple[str, str]

Raises

InvalidNameError – If the storage account name is invalid.

DeleteStorageAccount(storage_account_name)¶

Delete an account storage.

Raises: ResourceDeletionError – if the storage account could not be deleted.
Return type: None

libcloudforensics.providers.azure.forensics module¶

Forensics on Azure.

libcloudforensics.providers.azure.forensics.CreateDiskCopy(resource_group_name, instance_name=None, disk_name=None, disk_type=None, region='eastus', src_profile=None, dst_profile=None)¶

Creates a copy of an Azure Compute Disk.

Parameters

resource_group_name (str) – The resource group in which to create the disk copy.
instance_name (str) – Optional. Instance name of the instance using the disk to be copied. If specified, the boot disk of the instance will be copied. If disk_name is also specified, then the disk pointed to by disk_name will be copied.
disk_name (str) – Optional. Name of the disk to copy. If not set, then instance_name needs to be set and the boot disk will be copied.
disk_type (str) – Optional. The sku name for the disk to create. Can be Standard_LRS, Premium_LRS, StandardSSD_LRS, or UltraSSD_LRS. The default behavior is to use the same disk type as the source disk.
region (str) – Optional. The region in which to create the disk copy. Default is eastus.
src_profile (str) – Optional. The name of the source profile to use for the disk copy, i.e. the account information of the Azure account that holds the disk. For more information on profiles, see GetCredentials() in libcloudforensics.providers.azure.internal.common.py. If not provided, credentials will be gathered from environment variables.
dst_profile (str) – Optional. The name of the destination profile to use for the disk copy. The disk will be copied into the account linked to this profile. If not provided, the default behavior is that the destination profile is the same as the source profile. For more information on profiles, see GetCredentials() in libcloudforensics.providers.azure.internal.common.py

Returns

An Azure Compute Disk object.

Return type

AZComputeDisk

Raises

ResourceCreationError – If there are errors copying the disk.
ValueError – If both instance_name and disk_name are missing.

libcloudforensics.providers.azure.forensics.StartAnalysisVm(resource_group_name, vm_name, boot_disk_size, ssh_public_key, cpu_cores=4, memory_in_mb=8192, region='eastus', attach_disks=None, tags=None, dst_profile=None)¶

Start a virtual machine for analysis purposes.

Look for an existing Azure virtual machine with 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. Note that if a new vm is created, you should provide the ssh_public_key parameter.

Parameters

resource_group_name (str) – The resource group in which to create the analysis vm.
vm_name (str) – The name for the virtual machine.
boot_disk_size (int) – The size of the analysis VM boot disk (in GB).
ssh_public_key (str) – A SSH public key data (OpenSSH format) to associate with the VM, e.g. ssh-rsa AAAAB3NzaC1y… This must be provided as otherwise the VM will not be accessible.
cpu_cores (int) – Number of CPU cores for the analysis VM.
memory_in_mb (int) – The memory size (in MB) for the analysis VM.
region (str) – Optional. The region in which to create the VM. Default is eastus.
attach_disks (List[str]) – Optional. List of disk names to attach to the VM.
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.
dst_profile (str) – The name of the destination profile to use for the vm creation, i.e. the account information of the Azure account in which to create the vm. For more information on profiles, see GetCredentials() in libcloudforensics.providers.azure.internal.common.py

Returns

a tuple with a virtual machine object: and a boolean indicating if the virtual machine was created or not.

Return type

Tuple[AZComputeVirtualMachine, bool]

Helper classes¶

libcloudforensics.scripts.utils module¶

Utils method for cloud providers

libcloudforensics.scripts.utils.ReadStartupScript(filename='')¶

Read and return the startup script that is to be run on the forensics VM.

Users can either write their own script to install custom packages, or use one of the provided ones. To use your own script, export a STARTUP_SCRIPT environment variable with the absolute path to it: “user@terminal:~$ export STARTUP_SCRIPT=’absolute/path/script.sh’”

Parameters: filename (str) – the name of the script in the scripts directory to read Defaults to ‘forensics_packages_startup.sh’ if none specified.
Returns: The script to run.
Return type: str
Raises: OSError – If the script cannot be opened, read or closed.

libcloudforensics.errors module¶

Generic error wrapper

exception libcloudforensics.errors.CredentialsConfigurationError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with the credentials configuration is encountered.

exception libcloudforensics.errors.InstanceStateChangeError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with changing an instance state is encountered.

exception libcloudforensics.errors.InvalidFileFormatError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with file format is encountered.

exception libcloudforensics.errors.InvalidNameError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with resource name is encountered.

exception libcloudforensics.errors.LCFError(message, name)¶

Bases: Exception

Class to represent a cloud-forensics-utils (CFU) error.

message¶

The error message.

Type: str

name¶

Name of the module that generated the error.

Type: str

exception libcloudforensics.errors.ResourceCreationError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with creating a new resource is encountered.

exception libcloudforensics.errors.ResourceDeletionError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with deleting a resource is encountered.

exception libcloudforensics.errors.ResourceNotFoundError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with non-existent resource is encountered.

exception libcloudforensics.errors.ServiceAccountRemovalError(message, name)¶

Bases: libcloudforensics.errors.LCFError

Error when an issue with removing a service account is encountered.

libcloudforensics.logging_utils module¶

Module providing custom logging formatters and colorization for ANSI compatible terminals.

class libcloudforensics.logging_utils.Formatter(colorize=True, random_color=False, **kwargs)¶

Bases: logging.Formatter

Helper class used to add color to log messages depending on their level.

format(record)¶

Hooks the native format method and colorizes messages if needed.

Parameters: record (logging.LogRecord) – Native log record.
Returns: The formatted message string.
Return type: str

libcloudforensics.logging_utils.GetLogger(name)¶

Return a logger.

This is a wrapper around logging.getLogger that is intended to be used by the other modules so that they don’t have to import the logging module + this module.

Parameters: name (str) –
Returns: The logger.
Return type: logging.Logger

libcloudforensics.logging_utils.SetUpLogger(name)¶

Setup a logger.

Parameters: name (str) – The name for the logger.
Return type: None

Welcome to libcloudforensics’s documentation!¶

Table of contents¶

Getting started¶

Installing from pypi¶

Using the CLI¶

libcloudforensics capabilities¶

GCP¶

Disk snapshot¶

GCS to persistent disk¶

Analysis VM¶

AWS¶

Prerequisites¶

Disk snapshot¶

Using the library and the CLI¶

EBS encryption¶

Analysis VMs¶

Microsoft Azure¶

Prerequisites¶

Disk snapshot¶

Scenario 1¶

Scenario 2¶

Scenario 3¶

Using the library and the CLI¶

Cross-account / region sharing¶

Analysis VMs¶

Contributing¶

Before you contribute¶

Code review¶

Style guide¶

The small print¶

API documentation¶

GCP forensics package¶

Internal provider functions¶

GCP internal provider functions¶

libcloudforensics.providers.gcp.internal.build module¶

libcloudforensics.providers.gcp.internal.cloudsql module¶

libcloudforensics.providers.gcp.internal.common module¶

libcloudforensics.providers.gcp.internal.compute module¶

libcloudforensics.providers.gcp.internal.compute_base_resource module¶

libcloudforensics.providers.gcp.internal.function module¶

libcloudforensics.providers.gcp.internal.gke module¶

libcloudforensics.providers.gcp.internal.log module¶

libcloudforensics.providers.gcp.internal.monitoring module¶

libcloudforensics.providers.gcp.internal.project module¶

libcloudforensics.providers.gcp.internal.storage module¶

libcloudforensics.providers.gcp.forensics module¶

AWS forensics package¶

Internal provider functions¶

AWS internal provider functions¶

libcloudforensics.providers.aws.internal.account module¶

libcloudforensics.providers.aws.internal.common module¶

libcloudforensics.providers.aws.internal.ebs module¶

libcloudforensics.providers.aws.internal.ec2 module¶

libcloudforensics.providers.aws.internal.kms module¶

libcloudforensics.providers.aws.internal.log module¶

libcloudforensics.providers.aws.internal.s3 module¶

libcloudforensics.providers.aws.forensics module¶

Azure forensics package¶

Internal provider functions¶

Azure internal provider functions¶

libcloudforensics.providers.azure.internal.account module¶

libcloudforensics.providers.azure.internal.common module¶

libcloudforensics.providers.azure.internal.compute module¶

libcloudforensics.providers.azure.internal.compute_base_resource module¶

libcloudforensics.providers.azure.internal.monitoring module¶

libcloudforensics.providers.azure.internal.network module¶

libcloudforensics.providers.azure.internal.resource module¶

libcloudforensics.providers.azure.internal.storage module¶

libcloudforensics.providers.azure.forensics module¶

Helper classes¶

libcloudforensics.scripts.utils module¶

libcloudforensics.errors module¶

libcloudforensics.logging_utils module¶