awsfindingsmanagerlib package

Submodules

awsfindingsmanagerlib.awsfindingsmanagerlib module

Main code for awsfindingsmanagerlib.

class awsfindingsmanagerlib.awsfindingsmanagerlib.Finding(data: Dict)[source]

Bases: object

Models a finding.

property aws_account_id: str

Account id.

property compliance_frameworks: List[str]

Compliance frameworks.

property compliance_standards: List[str]

Compliance standards.

property compliance_status: str

Compliance status.

property control_id: str | None

Rule ID.

property created_at: datetime | None

Created at.

property days_open: int

Days open.

property description: str

Description.

property first_observed_at: datetime | None

First observed at.

property generator_id: str

Generator id.

property id: str

ID.

is_matching_regions(regions) → bool[source]

Checks the finding region if it matches with any of the regions provided.

Parameters:

regions – A list of regions

Returns:

True if the region matches any of the regions list or if regions list is empty. False otherwise.

is_matching_resource_ids(resource_id_patterns) → bool[source]

Iterates over all finding resource ids and checks if any match with any of the resource ids provided.

Parameters:

resource_id_patterns – A list of resource ids regular expression patterns.

Returns:

True if any resource ID matches any pattern, or if patterns list is empty. False otherwise, like Security Hub filters per resource.

is_matching_rule(rule: Rule) → bool[source]

Checks a rule for a match with the finding.

If any of control_id, security_control_id, rule_id or product_name and title attributes match between the rule and the finding and the rule does not have any filtering attributes like resource_id_regexps or tags then it is considered a match. (Big blast radius) only matching on the control or product.

If the rule has any attributes like resource_id_regexps or tags then a secondary match is searched for any of them with the corresponding finding attributes. If any match is found then the rule is found matching if none are matching then the rule is not considered a matching rule.

Parameters:

rule – The rule object to match with.

Returns:

True if the finding matched the rule, False otherwise.

Raises:

InvalidRuleType if the object provided is not a Rule object. –

is_matching_tags(rule_tags) → bool[source]

Iterates over all finding tags and checks if any match with any of the rule tags provided.

Parameters:

rule_tags – A list of tags coming from a Rule match_on field.

Returns:

True if any finding tag key/value pair matches any rule tag key/value pair, or if the rule_tags is empty. False otherwise, like Security Hub filters per key/value pairs.

property last_observed_at: datetime | None

Last observed at.

static match_if_left_set(left, right)[source]
property matched_rule: Rule

The matched rule that is registered in the finding.

property note_text: str

Note text.

property product_arn: str

Product ARN.

property product_name: str

Product Name.

property record_state: str

Record state.

property region: str

Region.

property remediation_recommendation_text: str | None

Textual recommendation for remediation.

property remediation_recommendation_url: str | None

URL for more information on the remediation.

required_fields = {'AwsAccountId', 'CompanyName', 'CreatedAt', 'Description', 'FindingProviderFields', 'GeneratorId', 'Id', 'ProductArn', 'ProductFields', 'ProductName', 'RecordState', 'Region', 'Resources', 'SchemaVersion', 'Severity', 'Title', 'Types', 'UpdatedAt', 'Workflow', 'WorkflowState'}
property resource_ids: List[str | None]

Resource ids.

property resource_types: List[str | None]

Resource type.

property resources: List[Dict] | None

A list of resource dicts.

property rule_id: str | None

Rule ID.

property security_control_id: str

Security control ID.

property severity: str | None

Severity.

property standards_guide_arn: str | None

Arn of the compliance standard.

property tags: List[Dict | None]

Tags.

property title: str

Title.

property types: str | None

Types.

property updated_at: datetime | None

Updated at.

property workflow_status: str

Workflow status.

class awsfindingsmanagerlib.awsfindingsmanagerlib.FindingsManager(region: str = None, allowed_regions: List[str] | None = None, denied_regions: List[str] | None = None, allowed_account_ids: List[str] | None = None, denied_account_ids: List[str] | None = None, strict_mode: bool = True, suppress_label: str = None, note_text: NoteTextConfig | None = None)[source]

Bases: object

Models security hub and can retrieve findings and suppress them.

property default_query_filter

The default query filter for the instance of FindingManager.

Calculates the filter based on the provided allowed or denied account ids that should always be provided to the remote service.

get_findings() → List[Finding][source]

Retrieves findings from security hub based on the registered rules.

Returns:

A list of findings from security hub.

Return type:

findings (list)

get_findings_by_matching_rule(rule: Rule) → List[Finding][source]

Retrieves findings by the provided rule.

Parameters:

rule – The rule to match findings on.

Returns:

A list of findings that match the provided rule.

get_findings_by_matching_rule_data(note: str, action: str, match_on: Dict) → List[Finding][source]

Retrieves findings by the provided rule data.

Parameters:

  • note – The note of the rule.

  • action – The action of the rule

  • match_on – The match_on field of the rule.

Returns:

A list of findings that match the provided rule data.

get_unmanaged_suppressed_findings() → List[Finding][source]

Retrieves a list of suppressed findings that are not managed by this library.

Returns:

A list of findings.

Return type:

findings (list)

property regions

Regions.

register_rule(note: str, action: str, match_on: Dict)[source]

Registers a rule by the provided arguments.

Parameters:

  • note – The note of the rule.

  • action – The action of the rule.

  • match_on – The “match_on” payload of the rule

Returns:

True on success, False otherwise

Raises:

InvalidRuleType if strict mode is set and the arguments are not valid for a rule. –

register_rules(rules: List[Dict])[source]

Registers multiple rules by the provided arguments.

If strict mode is enabled on the service in case of any errors the invalid data is registered under the rules_errors attribute.

Parameters:

rules – A list of rule payloads to register.

Returns:

True on success, False otherwise

Raises:

InvalidRuleType if strict mode is set and the arguments are not valid for a rule. –

property rules: List[Rule]

The registered rules of the manager.

property rules_errors

The errors of registered rules if any and strict mode is not set.

suppress_finding_on_matching_rules(finding_data: Dict)[source]

Suppresses a findings based on the provided finding data.

A finding gets constructed with the provided data, and all rules are checked for a match with the finding. If one is found, the finding is suppressed with the data of the matching rule.

Parameters:

finding_data – The data of a finding as provided by Security Hub.

Returns:

A tuple containing a boolean status and the payload. The status is True on success and False otherwise.

Return type:

tuple

Raises:

InvalidFindingData – If the data is not valid finding data.

suppress_findings(findings: List[Finding])[source]

Suppresses findings from security hub based on a provided list.

suppress_findings_on_matching_rules(finding_data: List[Dict] | Dict)[source]

Suppresses a list of findings based on the provided list of finding data.

All findings get constructed with the provided data, and all rules are checked for a match with each finding. If one is found, the finding is suppressed with the data of the matching rule.

Parameters:

finding_data – The data of a finding as provided by Security Hub.

Returns:

A tuple containing a boolean status and the payload. The status is True on success and False otherwise.

Return type:

tuple

Raises:

InvalidFindingData – If any data is not valid finding data.

suppress_matching_findings()[source]

Suppresses findings from security hub based the recorded rules.

unsuppress_unmanaged_findings() → tuple[bool, list][source]

Unsuppresses findings that have not been suppressed by this library.

Returns:

A tuple containing a boolean status and the payload. The status is True on success and False otherwise.

Return type:

tuple

static update_query_for_account_ids(query_filter: Dict = {'WorkflowStatus': [{'Comparison': 'EQUALS', 'Value': 'NEW'}, {'Comparison': 'EQUALS', 'Value': 'NOTIFIED'}]}, allowed_account_ids: List[str] | None = None, denied_account_ids: List[str] | None = None)[source]

Calculates a Security Hub compatible filter for retrieving findings.

Depending on arguments provided for allow list and deny list 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.

Returns:

The query filter calculated based on the provided arguments.

Return type:

query_filter (dict)

validate_finding_on_matching_rules(finding_data: Dict)[source]

Validates that the provided data is correct data for a finding.

Iterates all registered rules and tries to match the finding with any registered rule (first match is used).

Parameters:

finding_data – The data of a finding as provided by Security Hub.

Returns:

A Finding object with a matching rule on success, None if no rule has been matched.

Raises:

InvalidFindingData – The data provided is not valid Finding data.

class awsfindingsmanagerlib.awsfindingsmanagerlib.NoteTextConfig(format: Literal['text', 'json'] = 'text', key: str | None = None)[source]

Bases: object

Immutable configuration for note text handling in findings.

Controls how note text is formatted when suppressing findings. This class is frozen to prevent accidental modification after initialization.

Parameters:

  • format – Format for note text - “text” for plain text (default) or “json” for structured JSON.

  • key – JSON key to store suppression note when format is “json”. Automatically defaults to “Note”.

Behavior:

  • When format=”json” and key is None: key is set to “Note”

  • When format=”json” and key is provided: uses the provided key

  • When format=”text”: key is forced to None (any provided value is ignored)

Examples

>>> NoteTextConfig()  # Default: text format
NoteTextConfig(format='text', key=None)

>>> NoteTextConfig(format="json")  # JSON format with default key
NoteTextConfig(format='json', key='Note')

>>> NoteTextConfig(format="json", key="SuppressionReason")
NoteTextConfig(format='json', key='SuppressionReason')
DEFAULT_KEY = 'Note'
format: Literal['text', 'json'] = 'text'
key: str | None = None
class awsfindingsmanagerlib.awsfindingsmanagerlib.Rule(note: str, action: str, match_on: Dict)[source]

Bases: object

Models a suppression rule.

property action: str
property data: Dict
property match_on: Dict

The match_on data of the rule.

property note: str
property product_name: str

The product name if any, empty string otherwise.

property query_filter: Dict

The query filter of the Rule based on all set attributes.

Returns:

The Security Hub compatible query filter for all attributes set on the Rule.

property regions: List[str | None]

The regions specified under the match_on attribute, empty list otherwise.

property resource_id_regexps: List[str | None]

The resource ids specified under the match_on attribute.

property rule_or_control_id: str

The control ID if any, empty string otherwise.

property security_control_id: str

The security control ID if any, empty string otherwise.

property tags: List[str | None]

The tags specified under the match_on attribute.

property title: str

The title if any, empty string otherwise.

awsfindingsmanagerlib.awsfindingsmanagerlibexceptions module

Custom exception code for awsfindingsmanagerlib.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.FailedToBatchUpdate[source]

Bases: Exception

Failed to batch update security hub findings.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidAccountListProvided[source]

Bases: Exception

The list of accounts provided are not valid AWS accounts.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidFindingData[source]

Bases: Exception

The data provided for a finding is invalid.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidOrNoCredentials[source]

Bases: Exception

Invalid or no credentials were provided from the environment.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidRegion[source]

Bases: Exception

The region provided is not valid.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidRegionListProvided[source]

Bases: Exception

The list of regions provided are not valid AWS regions.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidRuleAction[source]

Bases: Exception

The rule action is not in the accepted rules.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.InvalidRuleType[source]

Bases: Exception

The rule type is not in the accepted rules.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.MutuallyExclusiveArguments[source]

Bases: Exception

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

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.MutuallyExclusiveKeys[source]

Bases: Exception

Entries on match_on field are provided that are mutually exclusive.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.NoRegion[source]

Bases: Exception

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

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.NoRuleFindings[source]

Bases: Exception

Findings with no rules matched are provided to suppress.

Depending on the strictness set it might be an error or a warning.

exception awsfindingsmanagerlib.awsfindingsmanagerlibexceptions.UnableToRetrieveSecurityHubRegions[source]

Bases: Exception

Could not retrieve the regions security hub is active in.

awsfindingsmanagerlib.backends module

Main code for backends.

class awsfindingsmanagerlib.backends.Backend[source]

Bases: ABC

get_rules()[source]
class awsfindingsmanagerlib.backends.DynamoDB(dynamodb_table_name)[source]

Bases: Backend

class awsfindingsmanagerlib.backends.Http(url)[source]

Bases: Backend

class awsfindingsmanagerlib.backends.Local(path)[source]

Bases: Backend

class awsfindingsmanagerlib.backends.S3(bucket_name, file_name)[source]

Bases: Backend

awsfindingsmanagerlib.configuration module

Main code for configuration.

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

awsfindingsmanagerlib.validations module

Main code for validations.

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

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

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

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

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

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

awsfindingsmanagerlib.validations.validate_rule_data(rule_data) → Dict[source]

Validate that the provided match_on data is valid.

Currently only checks the schema and for the mutually exclusive attributes.

Parameters:

rule_data – The data to validate.

Returns:

The match_on data if valid.

Raises:

  • MutuallyExclusiveKeys – if mutually exclusive keys are set.

  • SchemaError – If any of the data does not conform to the match_on schema defined under validations.

Module contents

awsfindingsmanagerlib package.

Import all parts from awsfindingsmanagerlib here