Azure internal provider functions

libcloudforensics.providers.azure.internal.account module

Represents an Azure account.

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

Bases: object

Class that represents an Azure Account.

subscription_id

The Azure subscription ID to use.

Type

str

credentials

An Azure credentials object.

Type

ServicePrincipalCredentials

default_region

The default region to create new resources in.

Type

str

default_resource_group_name

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

Type

str

property compute

Get an Azure compute object for the account.

Returns

An Azure compute object.

Return type

AZCompute

property monitoring

Get an Azure monitoring object for the account.

Returns

An Azure monitoring object.

Return type

AZMonitoring

property network

Get an Azure network object for the account.

Returns

An Azure network object.

Return type

AZNetwork

property resource

Get an Azure resource object for the account.

Returns

An Azure resource object.

Return type

AZResource

property storage

Get an Azure storage object for the account.

Returns

An Azure storage object.

Return type

AZStorage

libcloudforensics.providers.azure.internal.common module

Common utilities.

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

Execute a request to the Azure API.

Parameters

  • client (Any) – An Azure operation client object.

  • func (str) – An Azure function to query from the client.

  • kwargs (Dict) – Optional. A dictionary of parameters for the function func.

Returns

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

Return type

List[Any]

Raises

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

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

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

The disk name must comply with the following RegEx:

  • ^[w]{1-80}$

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

Parameters

  • snapshot (AZComputeSnapshot) – A disk’s Snapshot.

  • disk_name_prefix (str) – Optional. A prefix for the disk name.

Returns

A name for the disk.

Return type

str

Raises

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

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

Get Azure credentials.

Parameters

profile_name (str) –

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

{
‘profile_name’: {

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

}, ‘other_profile_name’: {

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

}

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

Returns

Subscription ID and

corresponding Azure credentials.

Return type

Tuple[str, DefaultAzureCredential]

Raises

  • CredentialsConfigurationError – If there are environment variables that are not set or if the credentials file has missing entries/profiles.

  • FileNotFoundError – If the credentials file is not found.

  • InvalidFileFormatError – If the credentials file couldn’t be parsed.

libcloudforensics.providers.azure.internal.compute module

Azure Compute functionality.

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

Bases: object

Class representing all Azure Compute objects in an account.

az_account

An Azure account object.

compute_client

An Azure compute client object.

Type

ComputeManagementClient

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

Create a new disk based on a Snapshot.

Parameters

  • snapshot (AZComputeSnapshot) – Snapshot to use.

  • region (str) – Optional. The region in which to create the disk. If not provided, the disk will be created in the default_region associated to the AZAccount object.

  • disk_name (str) – Optional. String to use as new disk name.

  • disk_name_prefix (str) – Optional. String to prefix the disk name with.

  • disk_type (str) – Optional. The sku name for the disk to create. Can be Standard_LRS, Premium_LRS, StandardSSD_LRS, or UltraSSD_LRS. The default value is Standard_LRS.

Returns

Azure Compute Disk.

Return type

AZComputeDisk

Raises

ResourceCreationError – If the disk could not be created.

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

Create a new disk based on a SAS snapshot URI.

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

Parameters

  • snapshot (AZComputeSnapshot) – Source snapshot to use.

  • snapshot_uri (str) – The URI of the snapshot to copy.

  • region (str) – Optional. The region in which to create the disk. If not provided, the disk will be created in the default_region associated to the AZAccount object.

  • disk_name (str) – Optional. String to use as new disk name.

  • disk_name_prefix (str) – Optional. String to prefix the disk name with.

  • disk_type (str) – Optional. The sku name for the disk to create. Can be Standard_LRS, Premium_LRS, StandardSSD_LRS, or UltraSSD_LRS. Default is Standard_LRS.

Returns

Azure Compute Disk.

Return type

AZComputeDisk

Raises

ResourceCreationError – If the disk could not be created.

GetDisk(disk_name, resource_group_name=None)

Get disk from AZ subscription / resource group.

Parameters

  • disk_name (str) – The disk name.

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

Returns

An Azure Compute Disk object.

Return type

AZComputeDisk

Raises

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

GetInstance(instance_name, resource_group_name=None)

Get instance from AZ subscription / resource group.

Parameters

  • instance_name (str) – The instance name.

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

Returns

An Azure virtual machine object.

Return type

AZComputeVirtualMachine

Raises

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

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

Get or create a new virtual machine for analysis purposes.

Parameters

  • vm_name (str) – The instance name tag of the virtual machine.

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

  • cpu_cores (int) – Number of CPU cores for the analysis VM.

  • memory_in_mb (int) – The memory size (in MB) for the analysis VM.

  • ssh_public_key (str) – A SSH public key data to associate with the VM. This must be provided as otherwise the VM will not be accessible.

  • region (str) – Optional. The region in which to create the vm. If not provided, the vm will be created in the default_region associated to the AZAccount object.

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

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

Returns

A tuple with an

AZComputeVirtualMachine object and a boolean indicating if the virtual machine was created (True) or reused (False).

Return type

Tuple[AZComputeVirtualMachine, bool]

Raises

  • RuntimeError – If the provided SSH key is invalid.

  • ResourceCreationError – If the virtual machine cannot be found or created.

ListDisks(resource_group_name=None)

List disks in an Azure subscription / resource group.

Parameters

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

Returns

Dictionary mapping disk names (str) to their

respective AZComputeDisk object.

Return type

Dict[str, AZComputeDisk]

ListInstanceTypes(region=None)

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

Parameters

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

Returns

A list of available vm size. Each size is a

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

Return type

List[Dict[str, str]]

ListInstances(resource_group_name=None)

List instances in an Azure subscription / resource group.

Parameters

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

Returns

Dictionary mapping instance names

(str) to their respective AZComputeVirtualMachine object.

Return type

Dict[str, AZComputeVirtualMachine]

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

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

Class that represents Azure disks.

GetDiskType()

Return the SKU disk type.

Returns

The SKU disk type.

Return type

str

Snapshot(snapshot_name=None, tags=None)

Create a snapshot of the disk.

Parameters

  • snapshot_name (str) – Optional. A name for the snapshot. If none provided, one will be generated based on the disk’s name.

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

Returns

A snapshot object.

Return type

AZComputeSnapshot

Raises
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