awsenergylabelerlib package

Submodules

awsenergylabelerlib.awsenergylabelerlib module

Main code for awsenergylabelerlib.

class awsenergylabelerlib.awsenergylabelerlib.EnergyLabeler(zone_name, region=None, account_thresholds=[{'critical_high': 0, 'days_open_less_than': 999, 'label': 'A', 'low': 20, 'medium': 10}, {'critical_high': 10, 'days_open_less_than': 999, 'label': 'B', 'low': 40, 'medium': 20}, {'critical_high': 15, 'days_open_less_than': 999, 'label': 'C', 'low': 60, 'medium': 30}, {'critical_high': 20, 'days_open_less_than': 999, 'label': 'D', 'low': 80, 'medium': 40}, {'critical_high': 25, 'days_open_less_than': 999, 'label': 'E', 'low': 100, 'medium': 50}], zone_thresholds=[{'label': 'A', 'percentage': 90}, {'label': 'B', 'percentage': 70}, {'label': 'C', 'percentage': 50}, {'label': 'D', 'percentage': 30}, {'label': 'E', 'percentage': 20}], security_hub_filter={'ComplianceStatus': [{'Comparison': 'EQUALS', 'Value': 'FAILED'}], 'RecordState': [{'Comparison': 'NOT_EQUALS', 'Value': 'ARCHIVED'}], 'UpdatedAt': [{'DateRange': {'Unit': 'DAYS', 'Value': 7}}], 'WorkflowStatus': [{'Comparison': 'NOT_EQUALS', 'Value': 'SUPPRESSED'}]}, frameworks={'aws-foundational-security-best-practices'}, allowed_account_ids=None, denied_account_ids=None, allowed_regions=None, denied_regions=None, zone_type='organizations_zone')[source]

Bases: object

Labeling accounts and zone based on findings and label configurations.

get_zone_energy_label_for_findings(findings)[source]

Calculates an energy label on provided security hub findings.

get_zone_energy_label_for_findings_by_query(findings_query)[source]

Calculates an energy label on an arbitrary security hub findings query.

property initialized_security_hub_query_filter

Calculates and saves the security hub query filter based on the configuration of the zone args.

Returns:

The query filter constructed and cached.

Return type:

query_filter (dict)

property labeled_accounts_energy_label

Energy label of the labeled accounts.

property matching_frameworks

The frameworks provided to match the findings of.

property security_hub

Security Hub.

property security_hub_findings

Security hub findings.

property zone

Zone.

property zone_energy_label

Energy label of the zone.

property zone_labeled_accounts

The zone labeled account objects.

awsenergylabelerlib.awsenergylabelerlibexceptions module

Custom exception code for awsenergylabelerlib.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.AccountsNotPartOfZone[source]

Bases: Exception

If accounts ids are provided but are not part of the zone.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidAccountListProvided[source]

Bases: Exception

The list of accounts provided are not valid AWS accounts.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidFrameworks[source]

Bases: Exception

The frameworks provided are not valid.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidOrNoCredentials[source]

Bases: Exception

Invalid or no credentials were provided from the environment.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidPath[source]

Bases: Exception

The path provided is not valid.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidRegion[source]

Bases: Exception

The region provided is not valid.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.InvalidRegionListProvided[source]

Bases: Exception

The list of regions provided are not valid AWS regions.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.MutuallyExclusiveArguments[source]

Bases: Exception

The arguments provided are mutually exclusive and only one of the should be provided.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.NoAccess[source]

Bases: Exception

The credentials provided do not provide access to the resources.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.NoRegion[source]

Bases: Exception

No region is set on the environment or provided to the library.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.UnableToRetrieveSecurityHubRegions[source]

Bases: Exception

Could not retrieve the regions security hub is active in.

exception awsenergylabelerlib.awsenergylabelerlibexceptions.UnsupportedZoneType[source]

Bases: Exception

The zone type provided is not supported.

awsenergylabelerlib.configuration module

configuration package.

Import all parts from configuration here

awsenergylabelerlib.configuration.get_available_security_hub_regions()[source]

The regions that security hub can be active in.

Returns:

A list of strings of the regions that security hub can be active in.

Return type:

regions (list)

awsenergylabelerlib.datamodels module

Main code for datamodels.

class awsenergylabelerlib.datamodels.LabeledAccountData(filename, labeled_accounts)[source]

Bases: object

Models the data for energy labeling to export.

property data

Data of an account to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.LabeledAccountsData(filename, labeled_accounts)[source]

Bases: object

Models the data for energy labeling to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.Metadata(filename, metadata)[source]

Bases: object

Models the data for execution metadata to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.SecurityHubFindingsData(filename, security_hub_findings)[source]

Bases: object

Models the data for energy labeling to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.SecurityHubFindingsResourcesData(filename, security_hub_findings)[source]

Bases: object

Models the data for energy labeling to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.SecurityHubFindingsTypesData(filename, security_hub_findings)[source]

Bases: object

Models the data for energy labeling to export.

property json

Data to json.

class awsenergylabelerlib.datamodels.ZoneEnergyLabelingData(filename, name, energy_label)[source]

Bases: object

Models the data for energy labeling to export.

property json

Data to json.

awsenergylabelerlib.entities module

entities package.

Import all parts from entities here

class awsenergylabelerlib.entities.AuditZone(name, region, allowed_account_ids=None, denied_account_ids=None, thresholds=[{'label': 'A', 'percentage': 90}, {'label': 'B', 'percentage': 70}, {'label': 'C', 'percentage': 50}, {'label': 'D', 'percentage': 30}, {'label': 'E', 'percentage': 20}], account_thresholds=[{'critical_high': 0, 'days_open_less_than': 999, 'label': 'A', 'low': 20, 'medium': 10}, {'critical_high': 10, 'days_open_less_than': 999, 'label': 'B', 'low': 40, 'medium': 20}, {'critical_high': 15, 'days_open_less_than': 999, 'label': 'C', 'low': 60, 'medium': 30}, {'critical_high': 20, 'days_open_less_than': 999, 'label': 'D', 'low': 80, 'medium': 40}, {'critical_high': 25, 'days_open_less_than': 999, 'label': 'E', 'low': 100, 'medium': 50}])[source]

Bases: Zone

Models the audit zone and retrieves accounts from it.

property accounts

Accounts of the zone.

Returns:

List of accounts retrieved

Raises:

NoAccess – If insufficient access from credentials.

class awsenergylabelerlib.entities.AwsAccount(id_: str, account_thresholds: list, name='NOT_RETRIEVED')[source]

Bases: object

Models the aws account that can label itself.

calculate_energy_label(findings)[source]

Calculates the energy label for the account.

Parameters:

findings – Either a list of security hub findings or a dataframe of security hub findings.

Returns:

The energy label of the account based on the provided configuration.

class awsenergylabelerlib.entities.DataExporter(export_types, name, energy_label, security_hub_findings, labeled_accounts, metadata)[source]

Bases: object

Export AWS security data.

export(path)[source]

Exports the data to the provided path.

class awsenergylabelerlib.entities.DataFileFactory(export_type, name, energy_label, security_hub_findings, labeled_accounts, metadata)[source]

Bases: object

Data export factory to handle the different data types returned.

class awsenergylabelerlib.entities.Finding(data: dict)[source]

Bases: object

Models a finding.

property aws_account_id

Account id.

property compliance_control

Compliance control.

property compliance_frameworks

Compliance frameworks.

property compliance_standards

Compliance standards.

property compliance_status

Compliance status.

property created_at

Created at.

property days_open

Days open.

property description

Description.

property first_observed_at

First observed at.

property generator_id

Generator id.

property id

ID.

property is_aws_foundational_security_best_practices

Is this aws foundational security best practices framework finding.

property is_cis_aws_foundations_benchmark

Is this cis framework finding.

property is_pci_dss

Is this pci dss framework finding.

property last_observed_at

Last observed at.

property measurement_data

Measurement data for computing the energy label.

property original_payload

Original payload.

property record_state

Record status.

property region

Region.

property remediation_recommendation_text

Textual recommendation for remediation.

property remediation_recommendation_url

URL for more information on the remediation.

property resource_ids

Resource ids.

property resource_types

Resource type.

property resources

A list of resource dicts.

property rule_id

Rule id.

property severity

Severity.

property standards_guide_arn

Arn of the compliance standard.

property title

Title.

property types

Types.

property updated_at

Updated at.

property workflow_status

Workflow status.

class awsenergylabelerlib.entities.OrganizationsZone(name, region, allowed_account_ids=None, denied_account_ids=None, thresholds=[{'label': 'A', 'percentage': 90}, {'label': 'B', 'percentage': 70}, {'label': 'C', 'percentage': 50}, {'label': 'D', 'percentage': 30}, {'label': 'E', 'percentage': 20}], account_thresholds=[{'critical_high': 0, 'days_open_less_than': 999, 'label': 'A', 'low': 20, 'medium': 10}, {'critical_high': 10, 'days_open_less_than': 999, 'label': 'B', 'low': 40, 'medium': 20}, {'critical_high': 15, 'days_open_less_than': 999, 'label': 'C', 'low': 60, 'medium': 30}, {'critical_high': 20, 'days_open_less_than': 999, 'label': 'D', 'low': 80, 'medium': 40}, {'critical_high': 25, 'days_open_less_than': 999, 'label': 'E', 'low': 100, 'medium': 50}])[source]

Bases: Zone

Models the organizations zone and retrieves accounts from it.

property accounts

Accounts of the organizations zone.

Returns:

List of accounts retrieved

Raises:

NoAccess – If insufficient access from credentials.

class awsenergylabelerlib.entities.SecurityHub(region=None, allowed_regions=None, denied_regions=None)[source]

Bases: object

Models security hub and can retrieve findings.

static calculate_query_filter(query_filter={'ComplianceStatus': [{'Comparison': 'EQUALS', 'Value': 'FAILED'}], 'RecordState': [{'Comparison': 'NOT_EQUALS', 'Value': 'ARCHIVED'}], 'UpdatedAt': [{'DateRange': {'Unit': 'DAYS', 'Value': 7}}], 'WorkflowStatus': [{'Comparison': 'NOT_EQUALS', 'Value': 'SUPPRESSED'}]}, allowed_account_ids=None, denied_account_ids=None, frameworks={'aws-foundational-security-best-practices'})[source]

Calculates a Security Hub compatible filter for retrieving findings.

Depending on arguments provided for allow list, deny list and frameworks to retrieve a query is constructed to retrieve only appropriate findings, offloading the filter on the back end.

Parameters:

  • query_filter – The default filter if no filter is provided.

  • allowed_account_ids – The allow list of account ids to get the findings for.

  • denied_account_ids – The deny list of account ids to filter out findings for.

  • frameworks – The default frameworks if no frameworks are provided.

Returns:

The query filter calculated based on the provided arguments.

Return type:

query_filter (dict)

property enabled_products

The enabled security hub products.

Returns:

A list of arns for the enabled security hub products.

static filter_findings_by_frameworks(findings, frameworks)[source]

Filters provided findings by the provided frameworks.

Parameters:

  • findings – A list containing security hub findings

  • frameworks – The frameworks to filter for

Returns:

A list of findings matching the provided frameworks

Return type:

findings (list(Findings))

frameworks = {'aws-foundational-security-best-practices', 'cis-aws-foundations-benchmark', 'pci-dss'}
get_findings(query_filter)[source]

Retrieves findings from security hub based on a provided query.

Parameters:

query_filter (dict) – The query filter to execute on security hub to get the findings.

Returns:

A list of findings from security hub.

Return type:

findings (list)

get_findings_resolved_by_day_offset(days_ago=30)[source]

Get findings that have been resolved the last days based on the days_ago provided value.

Parameters:

days_ago – The number of days to filter for resolved findings.

Returns:

A list of findings resolved during the provided time window.

get_suppressed_findings()[source]

Get the suppressed findings.

Returns:

A list of suppressed findings.

property regions

Regions.

static validate_frameworks(frameworks)[source]

Validates provided frameworks.

Parameters:

frameworks – The frameworks to validate according to an accepted list, can be none.

Returns:

A list of supported frameworks or an empty list.

Raises:

InvalidFrameworks – if the frameworks provided are not valid.

class awsenergylabelerlib.entities.Zone(name, region, allowed_account_ids=None, denied_account_ids=None, thresholds=[{'label': 'A', 'percentage': 90}, {'label': 'B', 'percentage': 70}, {'label': 'C', 'percentage': 50}, {'label': 'D', 'percentage': 30}, {'label': 'E', 'percentage': 20}], account_thresholds=[{'critical_high': 0, 'days_open_less_than': 999, 'label': 'A', 'low': 20, 'medium': 10}, {'critical_high': 10, 'days_open_less_than': 999, 'label': 'B', 'low': 40, 'medium': 20}, {'critical_high': 15, 'days_open_less_than': 999, 'label': 'C', 'low': 60, 'medium': 30}, {'critical_high': 20, 'days_open_less_than': 999, 'label': 'D', 'low': 80, 'medium': 40}, {'critical_high': 25, 'days_open_less_than': 999, 'label': 'E', 'low': 100, 'medium': 50}], remote_service_client=None)[source]

Bases: ABC

Models the zone and retrieves accounts from it.

abstract property accounts: []

Accounts.

property accounts_to_be_labeled

Account to be labeled according to the allow or deny list arguments.

Returns:

A list of accounts to be labeled.

Return type:

account (list)

get_allowed_accounts()[source]

Retrieves allowed accounts based on an allow list.

Returns:

The list of accounts based on the allowed list.

get_energy_label(security_hub_findings)[source]

Calculates and returns the energy label of the zone.

Parameters:

security_hub_findings – The measurement data of all the findings for a zone.

Returns:

The labeling object of the zone.

Return type:

energy_label (ZoneEnergyLabel)

get_energy_label_of_targeted_accounts(security_hub_findings)[source]

Get the energy label of the targeted accounts.

Parameters:

security_hub_findings – The findings from security hub.

Returns:

The energy label of the targeted accounts.

Return type:

energy_label (str)

get_labeled_targeted_accounts(security_hub_findings)[source]

Labels the accounts based on the allow and deny list provided.

Parameters:

security_hub_findings – The findings for a zone.

Returns:

A list of AwsAccount objects that have their labels calculated.

Return type:

labeled_accounts (list)

get_not_denied_accounts()[source]

Retrieves allowed accounts based on an deny list.

Returns:

The list of accounts not on the deny list.

awsenergylabelerlib.labels module

schemas package.

Import all parts from schemas here

class awsenergylabelerlib.labels.AccountEnergyLabel(label: str = 'F', number_of_critical_findings: int = 9999, number_of_high_findings: int = 9999, number_of_medium_findings: int = 9999, number_of_low_findings: int = 9999, max_days_open: int = 9999)[source]

Bases: object

Models the account energy label.

label: str = 'F'
max_days_open: int = 9999
number_of_critical_findings: int = 9999
number_of_high_findings: int = 9999
number_of_low_findings: int = 9999
number_of_medium_findings: int = 9999
class awsenergylabelerlib.labels.ZoneEnergyLabel(label: str, best_label: str, worst_label: str, accounts_measured: int, coverage: float)[source]

Bases: object

Models the zone energy label.

accounts_measured: int
best_label: str
coverage: float
label: str
worst_label: str

awsenergylabelerlib.schemas module

schemas package.

Import all parts from schemas here

awsenergylabelerlib.validations module

schemas package.

Import all parts from schemas here

class awsenergylabelerlib.validations.DestinationPath(location)[source]

Bases: object

Models a destination path and identifies if it is valid and it’s type.

is_valid()[source]

Is the path valid.

property type

The type of the path.

awsenergylabelerlib.validations.are_valid_account_ids(account_ids)[source]

Checks whether a provided list of account ids contains all valid AWS account ids.

Parameters:

account_ids (list) – A list of account id strings.

Returns:

True if the provided list contains all valid AWS account ids, false otherwise.

awsenergylabelerlib.validations.get_invalid_regions(regions)[source]

Calculates if regions are not valid for security hub.

Parameters:

regions – The regions to check

Returns:

A set of regions that security hub is not active in

awsenergylabelerlib.validations.is_valid_account_id(account_id)[source]

Checks whether a provided account id is a valid AWS account id.

Parameters:

account_id (str) – An account id string.

Returns:

True if the provided value is a valid AWS account id, false otherwise.

awsenergylabelerlib.validations.is_valid_region(region)[source]

Checks whether a region provided is a valid Security Hub Region.

Parameters:

region – The region to check

Returns:

True if Security Hub is active in that region, False otherwise.

awsenergylabelerlib.validations.validate_account_ids(account_ids)[source]

Validates a provided string or iterable that it contains valid AWS account ids.

Parameters:

account_ids – A string or iterable of strings with AWS account ids.

Returns:

A list of valid AWS account ids.

Return type:

account_ids (list)

Raises:

InvalidAccountListProvided – If any of the provided account ids is not a valid AWS account id.

awsenergylabelerlib.validations.validate_allowed_denied_account_ids(allowed_account_ids=None, denied_account_ids=None)[source]

Validates provided allow and deny account id lists.

Not both arguments can contain values as they are logically mutually exclusive. The validations process also validates that the arguments contain valid account id values if provided.

Parameters:

  • allowed_account_ids (str|iterable) – A single or multiple account id to validate, mutually exclusive with the deny list

  • denied_account_ids (str|iterable) – A single or multiple account id to validate, mutually exclusive with the allow list

Returns:

A tuple of list values with valid account ids

Return type:

allowed_account_ids, denied_account_ids

Raises:
awsenergylabelerlib.validations.validate_allowed_denied_regions(allowed_regions=None, denied_regions=None)[source]

Validates provided allow and deny regions.

Not both arguments can contain values as they are logically mutually exclusive. The validations process also validates that the arguments contain valid regions if provided.

Parameters:

  • allowed_regions (str|iterable) – A single or multiple region to validate, mutually exclusive with the deny

  • denied_regions (str|iterable) – A single or multiple region to validate, mutually exclusive with the allow

Returns:

A tuple of list values with valid regions

Return type:

allowed_regions, denied_regions

Raises:
awsenergylabelerlib.validations.validate_regions(regions)[source]

Validates provided argument of regions for security hub.

Parameters:

regions – A string or iterable of regions that security hub should be active in.

Returns:

A list of valid regions if successful.

Raises:

InvalidRegionListProvided – If the regions provided are not valid for security hub.

Module contents

awsenergylabelerlib package.

Import all parts from awsenergylabelerlib here