Main top-level functionality

Public functions

validate_filters 

validate_filters(
    filters: dict, session_client: BaseClient | None = None
) -> None

Validate AWS SecurityHub filters to get findings.

Parameters:

  • filters
    (dict) –

    The filters to validate

  • session_client
    (BaseClient, default: None ) –

    A boto session BaseClient for AWS SecurityHub Tries to create one if not provided

Raises:

  • ParamValidationError –

    If the filters contain invalid values

validate_updates 

validate_updates(
    updates: dict, session_client: BaseClient | None = None
) -> None

Validate AWS SecurityHub updates to findings.

Parameters:

  • updates
    (dict) –

    The updates to make to (a set of) findings

  • session_client
    (BaseClient, default: None ) –

    A boto session BaseClient for AWS SecurityHub Tries to create one if not provided

Raises:

  • ParamValidationError –

    If the updates contain invalid values

Public classes

Rule dataclass 

Rule(
    Filters: dict[str, list[dict[str, Any]]],
    UpdatesToFilteredFindings: dict[str, Any],
    client: BaseClient,
    ExtraFeatures: dict[str, Any] = dict(),
)

Dataclass representing a SecurityHub management rule.

Returned by: Used by:

Methods:

  • __post_init__ –

    Validate the rule upon initialization.

  • batch_update_findings –

    Batch update findings in AWS SecurityHub.

  • get_and_update –

    Get all the findings matching the rule's filters from AWS SecurityHub and update them according to the rule's updates.

  • match –

    Check if a finding matches the rule's filters.

__post_init__ 
__post_init__() -> None

Validate the rule upon initialization.

batch_update_findings 
batch_update_findings(
    findings: list[dict[str, Any]],
) -> bool

Batch update findings in AWS SecurityHub.

Parameters:

Returns:

  • bool –

    True if there are unprocessed findings, False otherwise.

get_and_update 
get_and_update() -> bool

Get all the findings matching the rule's filters from AWS SecurityHub and update them according to the rule's updates.

Returns:

  • bool –

    True if all findings were processed successfully, False otherwise

match 
match(finding: dict) -> bool

Check if a finding matches the rule's filters.

Parameters:

  • finding
    (dict) –

    The finding to check

Returns:

  • bool –

    True if the finding matches the rule's filters, False otherwise

Manager dataclass 

Manager(
    client: BaseClient,
    DefaultRuleInput: dict[str, Any] = dict(),
    _rules: list[Rule] = list(),
)

Dataclass managing rule creation.

Returned by:

Methods:

  • from_rules_document –

    Build a Manager with its rules registered from a parsed rules document.

  • get_and_update_all –

    Get all the findings matching the rules' filters from AWS SecurityHub and update them according to the rules' updates.

  • match_and_update –

    Match one finding against all configured rules and apply updates for each match.

  • process_finding –

    Match one finding against all configured rules and apply updates for each match.

  • set_rules –

    Create rules based on the provided input and the default rule input.

from_rules_document classmethod 
from_rules_document(
    rules: dict[str, Any], client: BaseClient
) -> Manager

Build a Manager with its rules registered from a parsed rules document.

Parameters:

  • rules
    (dict[str, Any]) –

    The parsed rules document. Must contain a top-level Rules key, and may contain a ManagerConfig key with a DefaultRuleInput sub-key.

  • client
    (BaseClient) –

    The boto3 Security Hub client to use for the manager and its rules.

Returns:

  • Manager –

    A Manager with its rules already registered via Manager.set_rules.

Raises:

  • ValueError –

    If the rules document has no top-level Rules key, or if ManagerConfig contains keys other than DefaultRuleInput (most commonly caused by putting ExtraFeatures next to, rather than inside, DefaultRuleInput).

get_and_update_all 
get_and_update_all() -> bool

Get all the findings matching the rules' filters from AWS SecurityHub and update them according to the rules' updates.

Returns:

  • bool –

    True if all findings were processed successfully, False otherwise

match_and_update 
match_and_update(finding: dict[str, Any]) -> bool

Match one finding against all configured rules and apply updates for each match.

Parameters:

  • finding
    (dict[str, Any]) –

    The finding to match and update.

Returns:

  • bool –

    True if all matching updates were processed, False otherwise.

process_finding 
process_finding(
    finding: dict[str, Any],
) -> MatchAndUpdateResult

Match one finding against all configured rules and apply updates for each match.

Unlike match_and_update, this also reports how many rules matched, so callers can distinguish "nothing matched" from "everything matched and was processed successfully".

Parameters:

  • finding
    (dict[str, Any]) –

    The finding to match and update.

Returns:

  • MatchAndUpdateResult –

    The number of rules that matched and whether all matching updates were processed.

set_rules 
set_rules(rules_input: list[dict[str, Any]]) -> list[Rule]

Create rules based on the provided input and the default rule input.

Parameters:

  • rules_input
    (list[dict[str, Any]]) –

    A list of dictionaries containing the rule input. Each dictionary will be merged with the DefaultRuleInput to create a complete rule input.

Returns:

  • list[Rule] –

    A list of Rule instances created from the input.

MatchAndUpdateResult dataclass 

MatchAndUpdateResult(
    matched_rules: int, all_processed: bool
)

The outcome of matching and updating a single finding against all configured rules.

Attributes:

  • matched_rules (int) –

    The number of rules that matched the finding.

  • all_processed (bool) –

    True if there were no unprocessed findings for any of the matched rules' updates, False otherwise. Vacuously True when no rule matched.

Returned by:

NoteTextConfig dataclass 

NoteTextConfig(Mode: str, Key: str = '')

Configuration for note text handling.

Raises:

  • ValueError –

    If the Mode is not one of the allowed values.

  • ValueError –

    If the Key is not a string when Mode is 'jsonUpdate'.

Methods:

  • __post_init__ –

    Validate the NoteTextConfig upon initialization.

__post_init__ 
__post_init__() -> None

Validate the NoteTextConfig upon initialization.