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

Use case: you have a disk disk1 in a GCP project (project_A) which you would like to make a copy of in a different project (project_B). The disk copy should live in zone us-east1-b.

Using the library and the CLI

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

from libcloudforensics.providers.gcp import forensics

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

copy = forensics.CreateDiskCopy('project_A',
                                'project_B',
                                'us-east1-b',
                                disk_name='disk1')

The equivalent CLI command is:

# Create a copy of the disk 'disk1' from one project to another 
cloudforensics gcp 'project_A' copydisk 'project_B' 'us-east1-b' --disk_name='disk1'

You can opt to pass an instance_name parameter to the method instead of a disk_name. If you do so, then the boot disk of the instance pointed to by instance_name will be copied. You can also create the copy in the same project:

from libcloudforensics.providers.gcp import forensics

# Create a copy of the disk 'disk1' in project_A.

copy = forensics.CreateDiskCopy('project_A',
                                'project_A',
                                'us-east1-b',
                                instance_name='inst1')

The equivalent CLI command is:

# Create a copy of the boot disk of instance 'inst1' in project_A
cloudforensics gcp 'project_A' copydisk 'project_A' 'us-east1-b' --instance_name='inst1'
Analysis VMs

Use case: you have a disk disk1 in a GCP project (project_A) which you would like to make a copy of in a different project (project_B). The disk copy should live in zone us-east1-b. Afterwards, you want to start an analysis VM in project_B, and attach the disk copy that you created to begin your investigation.

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

from libcloudforensics.providers.gcp import forensics

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

copy = forensics.CreateDiskCopy('project_A',
                                'project_B',
                                'us-east1-b',
                                disk_name='disk1')

# Start an analysis VM 'vm-forensics' for investigation in the GCP project
# project_B, and attach the copy created in the previous step.

analysis_vm, _ = forensics.StartAnalysisVm('project_B',
                                           'vm-forensics',
                                           'us-east1-b',
                                           50,
                                           'pd-standard',
                                           4,
                                           attach_disks=['disk1-copy'])

The equivalent CLI command is:

# Create a copy of the disk 'disk1' from one project to another 
# In this scenario we consider that the final disk copy name is 'disk1-copy' for illustration purpose. 
cloudforensics gcp 'project_A' copydisk 'project_B' 'us-east1-b' --disk_name='disk1'

# Start an analysis VM 'vm-forensics' for investigation in the GCP project 
# project_B, and attach a disk to it.
cloudforensics gcp 'project_A' startvm 'vm-forensics' 'us-east1-b' --attach_disks='disk1-copy'

You’re now ready to go! You can connect to your analysis instance.

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.

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:

https://github.com/google/cloud-forensics-utils/blob/master/docs/source/images/ebs.png?raw=trueebs-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'
Cross-account / region sharing

The process for sharing resources across accounts/regions involves the creation (in the destination account/region) of a temporary storage account and container in which the disk’s snapshot is downloaded, prior to creating the disk copy from the storage account. To reduce user hassle, libcloudforensics takes care of all these steps. The process is depicted below:

https://github.com/google/cloud-forensics-utils/blob/master/docs/source/images/sas.png?raw=trueazure-cross-share

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

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.

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
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]-[rand]-[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
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
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.

CreateInstanceFromArguments(instance_name, machine_type, zone=None, boot_disk=None, boot_disk_type='pd-standard', boot_disk_size=10, boot_image_project='debian-cloud', boot_image_family='debian-10', additional_scopes=None, sa_email='default', metadata=None, data_disks=None, network_name='default', external_ip=True, owner_label=True)

Create a compute instance.

If boot_disk is None then a boot disk need to be created using the ‘boot_disk_size’, ‘cpu_cores’, ‘image_project’ and ‘image_family parameters’.

Parameters

  • instance_name (str) – Name of the compute instance

  • machine_type (str) – A string, name of the machine type.

  • zone (Optional[str]) – Compute zone to start the instance in, default is self.default_zone.

  • boot_disk (Optional[GoogleComputeDisk]) – Boot disk name.

  • boot_disk_type (str) – represents persistent disk types, default “pd-standard”.

  • boot_disk_size (int) – boot disk size in base-2 GB. If you specify a sourceImage, which is required for boot disks, the default size is the size of the sourceImage, else default is 10 GB.

  • boot_image_project (str) – Name of the project where the boot disk image is stored.

  • boot_image_family (str) – Name of the image to use to create the boot disk.

  • additional_scopes (Optional[List[str]]) – additional scopes to be provided to the instance. Default scopes https://cloud.google.com/compute/docs/access/service-accounts#associating_a_service_account_to_an_instance # pylint: disable=line-too-long

  • sa_email (Optional[str]) – Service account email in case default service account is not used.

  • metadata (Optional[Dict[str, str]]) – A dictionary mapping metadata keys and values.

  • data_disks (Optional[List[Union[GoogleComputeDisk, GoogleRegionComputeDisk]]]) – List of disks to attach to the instance, default mode is READ_ONLY.

  • network_name (str) – Name of the VPC network to use, “default” network is default.

  • external_ip (bool) – True if the instance should have an external IP.

  • owner_label (bool) – True if the instance should have an owner label.

Return type

GoogleComputeInstance

Returns

Compute instance object.

Raises
CreateInstanceFromRequest(request_body, zone=None)

Creates an instance from an instance.insert request body.

Parameters
Return type

GoogleComputeInstance

Returns

Compute instance object.

Raises
Disks(refresh=True)

Get all disks in the project.

Parameters

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

Returns

Dictionary mapping disk IDs (str) to

their respective GoogleComputeDisk object.

Return type

Dict[str, GoogleComputeDisk]

GetDisk(disk_name, zone=None)

Get a GCP disk object.

Parameters

  • disk_name (str) – The disk identifier, can be either a disk name or ID.

  • zone (Optional[str]) – Compute zone.

Returns

Disk object.

Return type

GoogleComputeDisk

Raises

ResourceNotFoundError – When the specified disk cannot be found in project.

GetDiskTypes(disk_type, zone=None)

Get selected diskTypes API object in specified zone/project.

Parameters

  • disk_type (str) – Name of the disk type.

  • zone (Optional[str]) – Compute zone to get available disk types.

Returns

https://cloud.google.com/compute/docs/reference/rest/v1/diskTypes#resource # pylint: disable=line-too-long

Return type

The selected diskTypes API resource

Raises

HttpError if getting diskType object for the given disk-type name fails. –

GetImageFamily(image_family, project=None)

Get image family API object in specified project.

Parameters

  • image_family (str) – Name of the image famiky.

  • project (Optional[str]) – Project to get the image family API object from.

Returns

https://cloud.google.com/compute/docs/reference/rest/v1/images/getFromFamily # pylint: disable=line-too-long

Return type

The selected image family API resource

Raises

HttpError if getting image object for the given image family name fails. –

GetInstance(instance_name, zone=None)

Get instance from project.

Parameters

  • instance_name (str) – The instance identifier, can be either an instance name or ID.

  • zone (Optional[str]) – Compute zone.

Returns

A Google Compute Instance object.

Return type

GoogleComputeInstance

Raises

ResourceNotFoundError – If instance does not exist.

GetMachineTypes(machine_type, zone=None)

Get selected machineTypes API object in specified zone/project.

Parameters

  • machine_type (str) – Name of the machine type.

  • zone (Optional[str]) – Compute zone to get available machine types.

Returns

https://cloud.google.com/compute/docs/reference/latest/machineTypes#resource # pylint: disable=line-too-long

Return type

The selected machineTypes API resource

Raises

HttpError if getting machineType object for the given machine-type name fails. –

GetNetwork(network_name)

Get selected network API object in specified project.

Parameters

network_name (str) – Name of the network.

Returns

https://cloud.google.com/compute/docs/reference/rest/v1/networks # pylint: disable=line-too-long

Return type

The selected network API resource

Raises

HttpError if getting network object for the given machine-type name fails. –

GetOrCreateAnalysisVm(vm_name, boot_disk_size=10, disk_type='pd-standard', cpu_cores=4, image_project='ubuntu-os-cloud', image_family='ubuntu-1804-lts', packages=None, zone=None, data_disks=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) – boot disk size in base-2 GB. If you specify a sourceImage, which is required for boot disks, the default size is the size of the sourceImage, else default is 10 GB.

  • disk_type (str) – 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) – Number of CPU cores for the virtual machine.

  • image_project (str) – Name of the project where the analysis VM image is hosted.

  • image_family (str) – Name of the image to use to create the analysis VM.

  • packages (Optional[List[str]]) – List of packages to install in the VM.

  • zone (Optional[str]) – Compute zone to start the instance in, default is self.default_zone.

  • data_disks (Optional[List[Union[GoogleComputeDisk, GoogleRegionComputeDisk]]]) – List of disks to attach to the instance, default mode is READ_ONLY. If the VM already exists, disks will be attached to the existing VM.

Return type

Tuple[GoogleComputeInstance, bool]

Returns

A tuple with a virtual machine object and a boolean indicating

if the virtual machine was created or re-used.

Raises

  • ResourceCreationError – If virtual machine cannot be found after creation.

  • ValueError – If the requested CPU cores is not available for the specified machine type.

GetRegionDisk(disk_name, region=None)

Get regional disk in project.

Regional disks API resource: https://cloud.google.com/compute/docs/reference/rest/v1/regionDisks#resource:-disk # pylint: disable=line-too-long

Parameters

  • disk_name (str) – Name or ID of the regional disk to get.

  • region (Optional[str]) – Compute region.

Return type

GoogleRegionComputeDisk

Returns

Regional disk object.

Raises

ResourceNotFoundError – When the specified disk cannot be found in project.

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
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 IDs

(str) to their respective GoogleComputeInstance object.

Return type

Dict[str, GoogleComputeInstance]

ListComputeRegions()

List Compute regions in the project

Return type

List[str]

Returns

List of all regions.

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 IDs (str)

to their respective GoogleComputeInstance object.

Return type

Dict[str, GoogleComputeInstance]

ListMIGS(zone)

Gets the managed instance groups in a particular zone.

Returns a dictionary, with as keys the managed instance groups, and as values a list of instances belonging to the group.

Parameters

zone (str) – The zone in which to list managed instance groups.

Returns

A mapping from managed instance

groups to their managed GCE instances.

Return type

Dict[str, List[GoogleComputeInstance]]

ListMIGSByInstanceName(zone)

Gets a mapping from instance names to their managed instance group.

Parameters

zone (str) – The zone in which to list managed instance groups.

Returns

A mapping from instance names to their managed instance

group.

Return type

Dict[str, str]

Raises

RuntimeError – If multiple managed instance groups are found for a single instance.

ListRegionDisks()

List regional disks in project.

Return type

Dict[str, GoogleRegionComputeDisk]

Returns

Dictionary mapping disk names (str) to

their respective GoogleRegionComputeDisk object.

ListReservedExternalIps(zone)

Lists all static external IP addresses that are available to a zone.

The method first converts the zone to a region, and then queries the GCE addresses resource.

Parameters

zone (str) – The zone in which the returned IPs would be available.

Returns

The list of available IPs in the specified zone.

Return type

List[str]

Raises
RegionDisks(refresh=True)

Get all regional disks in the project.

Parameters

refresh (Optional[bool]) – Returns refreshed result if True.

Return type

Dict[str, GoogleRegionComputeDisk]

Returns

Dictionary mapping disk IDs (str) to their respective

GoogleRegionComputeDisk object.

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeDisk(project_id, zone, name, resource_id=None, labels=None, deletion_protection=False, region=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. created: False if the resource existed already.

Return type

GoogleComputeSnapshot

Raises

  • InvalidNameError – If the name of the snapshot does not comply with the RegEx.

  • RuntimeError – If the snapshot operation fails.

class libcloudforensics.providers.gcp.internal.compute.GoogleComputeImage(project_id, zone, name, resource_id=None, labels=None, deletion_protection=False, region=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, resource_id=None, labels=None, deletion_protection=False, region=None)

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

Class representing a Google Compute Engine virtual machine.

AbandonFromMIG(instance_group)

Abandons the instance from the managed instance group.

Parameters

instance_group (str) – The instance group that this instance should be abandoned from.

Raises

errors.OperationFailedError – If the request did not succeed.

Return type

None

AssignExternalIp(net_if, ip_addr=None)

Assigns an external IP to an instance’s network interface.

The instance must not have an IP assigned to the network interface when calling this method. If the IP address is specified, it must be one that is available to the project.

Parameters

  • net_if (str) – The instance’s network interface to which the IP address must be assigned.

  • ip_addr (str) – Optional. The static IP address that exposes the network interface. If None, the assigned IP address will be ephemeral.

Raises

errors.ResourceCreationError – If the assignment did not succeed.

Return type

None

AttachDisk(disk, read_write=False)

Attach a disk to the virtual machine.

Parameters
Return type

None

Delete(delete_disks=False, force_delete=False)

Delete an Instance.

Parameters

  • delete_disks (bool) – force delete all attached disks (ignores the ‘Keep when instance is deleted’ bit).

  • force_delete (bool) – force delete the instance, even if deletionProtection is set to true.

Raises

ResourceDeletionError – If deleteProtection could not be toggled on the instance

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.

GetEffectiveFirewalls()

Get the raw effective firewalls for every interface: https://cloud.google.com/compute/docs/reference/rest/v1/instances/getEffectiveFirewalls

Returns

The effective firewall rules per interface.

Return type

List[Dict[str, Any]]

GetNatIps()

Get the NAT external IPv4 addresses attached to an instance.

Returns

a list of IP addresses.

Return type

List[str]

GetNormalisedFirewalls()

Get normalised effective firewalls for every interface with firewall policies and normal VPC firewalls collapsed into a single list.

Returns

The normalised firewalls per interface.

Return type

List[Dict[str, Any]]

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]

RemoveExternalIps()

Removes any external IP of the instance, breaking ongoing connections.

Note that if the instance’s IP address was static, that the IP will still belong to the project.

Returns

A mapping from an instance’s network

interfaces to the corresponding removed external IP.

Return type

Dict[str, str]

Raises

errors.ResourceDeletionError – If the removal did not succeed.

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

class libcloudforensics.providers.gcp.internal.compute.GoogleRegionComputeDisk(project_id, region, name, **kwargs)

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

Class representing a regional compute disk.

project_id

Project ID.

region

Compute region in which the disk resides.

name

name of the regional compute disk.

GetOperation()

Get API operation object for the regional disk.

Return type

Dict[str, Any]

Returns

An API operation object for a Google Regional Compute Engine disk.

https://cloud.google.com/compute/docs/reference/rest/v1/regionDisks/get#response-body # pylint: disable=line-too-long

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, resource_id=None, labels=None, deletion_protection=False, region=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

resource_id

The ID number of the resource.

Type

str

labels

Dictionary of labels for the resource, if existing.

Type

Dict

deletion_protection

True if the resource has deletionProtection enabled.

Type

bool

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.

CLOUD_FUNCTIONS_API_VERSION = 'v1'
ExecuteFunction(function_name, region, args)

Executes a Google Cloud Function.

Parameters
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.GkeCluster(project_id, zone, cluster_id)

Bases: libcloudforensics.providers.kubernetes.cluster.K8sCluster, libcloudforensics.providers.gcp.internal.gke.GoogleKubernetesEngine

Class to call GKE and Kubernetes APIs on a GKE resource.

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

project_id

The GCP project name.

Type

str

zone

The GCP zone for this project.

Type

str

cluster_id

The name of the GKE cluster.

Type

str

ClusterLogsQuery(workload=None)

Creates the GCP k8s_cluster logs query string for this cluster.

A workload may optionally be specified, in which case the returned query string will be more specific to only cover that workload.

Parameters

workload (base.K8sWorkload) – Optional. A workload to specify in the query string.

Returns

The k8s_cluster logs query string.

Return type

str

ContainerLogsQuery(workload=None)

Returns the GCP k8s_container logs query string for this cluster.

A workload may optionally be specified, in which case the returned query string will be more specific to only cover that workload.

Parameters

workload (base.K8sWorkload) – Optional. A workload to specify in the query string.

Returns

The k8s_container logs query string.

Return type

str

GetOperation()

Get GKE API operation object for the GKE resource.

Returns

GKE API response to ‘get’ operation for this cluster.

Return type

Dict[str, Any]

IsLegacyEndpointsDisabled()

Returns whether legacy endpoints are enabled.

Returns

True if legacy endpoints are disabled, False otherwise.

Return type

bool

IsNetworkPolicyEnabled()

Override of abstract method.

Return type

bool

IsWorkloadIdentityEnabled()

Returns whether the workload identity is enabled.

Returns

True if workload identity is enabled, False otherwise.

Return type

bool

property name

Name of the GKE cluster resource, for use in API calls.

Returns

Full name of the cluster resource.

Return type

str

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

Bases: object

Base class for calling GKE APIs.

GKE_API_VERSION = 'v1'
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_ids)

Bases: object

Class representing a Google Cloud Logs interface.

project_ids

List of Google Cloud project IDs.

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=None)

Query logs in GCP project.

Parameters

qfilter (List[str]) – Optional. A list of query filters to use.

Returns

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

[…], ‘resourceNames’: […]}, {…}]

Return type

List[Dict]

Raises

  • RuntimeError – If API call failed.

  • ValueError – If the number of project IDs being queried doesn’t match the number of provided filters.

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.

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

GetCpuUsage(instance_ids=None, days=7, aggregation_minutes=60)

Returns CPU usage metrics for compute instances.

By default returns hourly usage for the last seven days for all instances within a project.

Parameters

  • list[str] (instance_ids) – Optional. A list of instance IDs to collect metrics for. When not provided will collect metrics for all instances in the project.

  • days (int) – Optional. The number of days to collect metrics for.

  • aggregation_minutes (int) – Optional. The minutes to aggregate on.

Returns

a list of CPU usage for each instance in the format
[
{

‘instance_name’: str, ‘instance_id’: str, ‘cpu_usage’: [

{

‘timestamp’: str, ‘cpu_usage’: float

},

]

},

]

Return type

List[Dict[str, Any]]

libcloudforensics.providers.gcp.internal.project module

Google Cloud Project resources and services.

class libcloudforensics.providers.gcp.internal.project.GoogleCloudProject(project_id=None, 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()

Delete()

Delete a GCP project.

Returns

The operation’s result details.

Return type

Dict[str, Any]

property bigquery

Get a GoogleBigQuery object for the project.

Returns

Object that represents Google BigQuery.

Return type

GoogleBigQuery

property build

Get a GoogleCloudBuild object for the project.

Returns

Object that represents Google Cloud Build.

Return type

GoogleCloudBuild

property cloudresourcemanager

Get a GoogleCloudResourceManager object for the project.

Returns

Object that represents Google cloud resource

manager.

Return type

GoogleCloudResourceManager

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 serviceusage

Get a GoogleServiceUsage object for the project.

Returns

Object that represents Google service usage.

Return type

GoogleServiceUsage

property storage

Get a GoogleCloudStorage object for the project.

Returns

Object that represents Google Cloud Storage.

Return type

GoogleCloudStorage

property storagetransfer

Get a GoogleCloudStorageTransfer object for the project.

Returns

Object that represents Google Cloud Storage Transfer.

Return type

GoogleCloudStorageTransfer

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.

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]

Raises

ResourceCreationError – If the resource could not be created.

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.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.CheckInstanceSSHAuth(project_id, instance_name)

Check enabled SSH authentication methods for an instance.

Uses SSH with the verbose flag to check enabled SSH authentication methods. Note this Will generate a log line on the target host:

“Connection closed by authenticating user root <your_ip> port <port> [preauth]”

Parameters

  • project_id (str) – the project id for the instance.

  • instance_name (str) – the instance name to check.

Returns

The SSH authentication methods supported by the instance or

None if SSH wasn’t accessible.

Return type

List[str]

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
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.QuarantineGKEWorkload(project_id, zone, cluster_id, namespace, workload_id, exempted_src_ips=None)

Guides the analyst through quarantining a GKE workload.

Parameters

  • project_id (str) – The GCP project ID.

  • zone (str) – The zone in which the cluster resides.

  • cluster_id (str) – The name of the Kubernetes cluster holding the workload.

  • namespace (str) – The Kubernetes namespace of the workload (e.g. ‘default’).

  • workload_id (str) – The name of the workload.

  • exempted_src_ips (List[str]) – Optional. The list of source IPs to exempt in the GCP firewall rules when isolating the nodes. If not specified, no IPs are exempted.

Raises

ResourceNotFoundError – If the workload isn’t found.

Return type

None

libcloudforensics.providers.gcp.forensics.StartAnalysisVm(project, vm_name, zone, boot_disk_size=10, boot_disk_type='pd-standard', cpu_cores=4, 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 (Optional[List[str]]) – List of disk names to attach. Default behaviour is to search in zonal disks then regional disks, when using regional disks CreateInstanceFromArguments from GoogleCloudCompute is recommended to avoid name colisions with zonal disks.

  • image_project (str) – Name of the project where the analysis VM image is hosted.

  • image_family (str) – Name of the image to use to create the analysis VM.

Return type

Tuple[GoogleComputeInstance, bool]

Returns

A tuple with a virtual machine object

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

libcloudforensics.providers.gcp.forensics.TriageInstance(project_id, instance_name)

Gather triage information for an instance.

Parameters

  • project_id (str) – the project id for the instance.

  • instance_name (str) – the instance name to check.

Returns

The instance triage information.

Return type

Dict[str, Any]

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 iam

Get an AWS IAM object for the account.

Returns

Object that represents AWS IAM services.

Return type

AWSIAM

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
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
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, vpc, 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

Delete(force_delete=False)

Delete an instance.

Parameters

force_delete (bool) – Optional. True if the instance should be deleted despite disableApiTermination being set to True on the instance.

Raises

ResourceDeletionError – If the instance could not be deleted.

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.

CreateIsolationSecurityGroup(vpc, ingress_subnets=None)

Creates an isolation security group.

Parameters

  • vpc (str) – VPC ID for the security group.

  • ingress_subnets (List[str]) – Optional. Subnets to allow ingress from.

Returns

The ID of the newly created security group.

Return type

str

Raises
DisassociateInstanceProfile(assoc_id)

Remove an instance profile attachment from an instance.

Parameters

assoc_id (str) – The instance profile association ID. Can be retrieved via ec2.GetInstanceProfileAttachment.

Raises

ResourceNotFoundError – If the assoc_id cannot be found.

Return type

None

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
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.

GetInstanceProfileAttachment(instance_id)

Get the instance profile attached to the instance, if any.

Parameters

instance_id (str) – The instance ID (i-xxxxxx)

Returns

A tuple containing the association id of the profile

attachment, and the Arn of the Instance profile attached. Both are None if no profile is attached, or the instance cannot be found.

Return type

Tuple[str, str]

Raises

ResourceNotFoundError – If the 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.

GetOrCreateVm(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, instance_profile=None, terminate_on_shutdown=False, wait_for_health_checks=True)

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.

  • instance_profile (str) – Optional. Instance role to be attached.

  • terminate_on_shutdown (bool) – Optional. Terminate the instance when the instance initiates shutdown.

  • wait_for_health_checks (bool) – Optional. Wait for health checks on the instance before returning

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.

GetSnapshotInfo(snapshot_id)

Get information about the snapshot.

Parameters

snapshot_id (str) – the snapshot id to fetch info for (snap-xxxxxx).

Raises

ResourceNotFoundError – If the snapshot ID cannot be found.

Return type

Dict[str, Any]

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.

SetInstanceSecurityGroup(instance_id, sg_id)

Attach a security group to an instance, removing all others.

Parameters

  • instance_id (str) – The instance ID (i-xxxxxx)

  • sg_id (str) – The Security Group ID (sg-xxxxxx)

Raises

ResourceCreationError – If the instance or security group cannot be found.

Return type

None

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

CheckForObject(bucket, key)

Check if an object exists in S3.

Parameters

  • bucket (str) – S3 bucket name.

  • key (str) – object path and name.

Returns

True if the object exists and you have permissions to GetObject.

False otherwise.

Return type

bool

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”}

Raises

ResourceCreationError – If the object couldn’t be uploaded.

Return type

None

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
Return type

None

RmBucket(bucket)

Delete an S3 bucket.

Parameters

bucket (str) – The bucket name.

Return type

None

RmObject(bucket, key)

Remove an object from S3.

Parameters

  • bucket (str) – The S3 bucket.

  • key (str) – The object key (path).

Return type

None

RmObjectByPath(s3_path)

Remove an object from S3.

Parameters

s3_path (str) – The path of the object to remove.

Return type

None

libcloudforensics.providers.aws.forensics module

Forensics on AWS.

libcloudforensics.providers.aws.forensics.CopyEBSSnapshotToS3(s3_destination, snapshot_id, instance_profile_name, zone, subnet_id=None, security_group_id=None, cleanup_iam=False)

Copy an EBS snapshot into S3.

Unfortunately, this action is not natively supported in AWS, so it requires creating a volume and attaching it to an instance. This instance, using a userdata script then performs a dd operation to send the disk image to S3.

Uses the components methods of SetUp, Process and TearDown. If you want to copy multiple snapshots, consider using those methods directly.

Parameters

  • s3_destination (str) – S3 directory in the form of s3://bucket/path/folder

  • snapshot_id (str) – EBS snapshot ID.

  • instance_profile_name (str) – The name of an existing instance profile to attach to the instance, or to create if it does not yet exist.

  • zone (str) – AWS Availability Zone the instance will be launched in.

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

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

  • cleanup_iam (bool) – If we created IAM components, remove them afterwards

Raises
Return type

Dict[str, Any]

libcloudforensics.providers.aws.forensics.CopyEBSSnapshotToS3Process(aws_account, s3_destination, snapshot_id, instance_profile_arn, subnet_id=None, security_group_id=None)

Copy an EBS snapshot into S3.

Unfortunately, this action is not natively supported in AWS, so it requires creating a volume and attaching it to an instance. This instance, using a userdata script then performs a dd operation to send the disk image to S3.

Parameters

  • aws_account (account.AWSAccount) – An AWS account to use for the operation.

  • s3_destination (str) – S3 directory in the form of s3://bucket/path/folder

  • snapshot_id (str) – EBS snapshot ID.

  • instance_profile_arn (str) – The name of an existing instance profile to attach to the instance, or to create if it does not yet exist.

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

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

Raises
Return type

Dict[str, Any]

libcloudforensics.providers.aws.forensics.CopyEBSSnapshotToS3SetUp(aws_account, instance_profile_name)

Set up for CopyEBSSnapshotToS3. Creates the IAM components required, or returns the existing ones if they exist already.

Parameters

  • aws_account (account.AWSAccount) – An AWS account object.

  • instance_profile_name (str) – name of the instance profile to create.

Returns: A Dict containing:
‘profile’:

‘arn’: The ARN of the profile. ‘created’: True if the profile was created; False if it existed already.

‘policy’:

‘arn’: The ARN of the policy. ‘created’: True if the policy was created; False if it existed already.

‘role’:

‘name’: The name of the role. ‘created’: True if the role was created; False if it existed already.

Raises

ResourceCreationError – If any IAM resource could not be created.

Return type

Dict[str, Dict[str, Any]]

libcloudforensics.providers.aws.forensics.CopyEBSSnapshotToS3TearDown(aws_account, instance_profile_name, iam_details)

Removes the IAM components created by CopyEBSSnapshotToS3SetUp, if any were created anew.

Parameters

  • aws_account (account.AWSAccount) – An AWS account object.

  • instance_profile_name (str) – The name of the instance profile.

  • iam_details (Dict[str, Dict[str, Any]]) – The Dict returned by the SetUp method.

Return type

None

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.InstanceNetworkQuarantine(zone, instance_id, exempted_src_subnets=None)

Put an AWS EC2 instance in network quarantine.

Network quarantine is imposed via applying empty security groups to the instance.

Parameters

  • zone (str) – AWS Availability Zone the instance is in.

  • instance_id (str) – The id (i-xxxxxx) of the virtual machine.

  • exempted_src_subnets (List[str]) – List of subnets that will be permitted

Raises
Return type

None

libcloudforensics.providers.aws.forensics.InstanceProfileMitigator(zone, instance_id, revoke_existing=False)

Remove an instance profile attachment from an instance.

Also, optionally revoke existing issued tokens for the profile.

Parameters

  • zone (str) – AWS Availability Zone the instance is in.

  • instance_id (str) – The id (i-xxxxxx) of the virtual machine.

  • revoke_existing (bool) – True to revoke existing tokens for the profile’s role. False otherwise.

Raises

ResourceNotFoundError – If the instance cannot be found, or does not have a profile attachment.

Return type

None

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, trying three different methods:

  1. If profile_name is provided it will attempt to parse credentials from a credentials.json file, failing if this raises an exception.

  2. Environment variables as per https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-authenticate

  3. Azure CLI credentials.

Parameters

profile_name (str) – A name for the Azure account information to retrieve. If provided, then the library will look into ~/.azure/credentials.json for the account information linked to profile_name.

Returns

Subscription ID and

corresponding Azure credentials.

Return type

Tuple[str, DefaultAzureCredential]

Raises

CredentialsConfigurationError – If none of the credential methods work.

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
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.AmbiguousIdentifierError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when an identifier could refer to more than one resource.

exception libcloudforensics.errors.CredentialsConfigurationError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when an issue with the credentials configuration is encountered.

exception libcloudforensics.errors.InstanceProfileCreationError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when there is an issue creating an instance profile.

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.OperationFailedError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when an operation did not succeed.

exception libcloudforensics.errors.ResourceAlreadyExistsError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when trying to create a resource with existing name.

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.

exception libcloudforensics.errors.TransferCreationError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when an issue with creating a new transfer job is encountered.

exception libcloudforensics.errors.TransferExecutionError(message, name)

Bases: libcloudforensics.errors.LCFError

Error when an issue with running a transfer job 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, no_newline=False)

Setup a logger.

Parameters

  • name (str) – The name for the logger.

  • no_newline (bool) – Optional. Whether or not to disable new lines in the logger’s output. Defaults to False.

Return type

None