awsfindingsmanagerlib 2.0.0__py3-none-any.whl

awsfindingsmanagerlib/__init__.py

@@ -0,0 +1,37 @@
+"""The main package of awsfindingsmanagerlib."""
+
+from .awsfindingsmanagerlib import validate_filters, validate_updates
+from .boto_utils import (
+    BotoStubCall,
+    get_values_by_boto_argument,
+    stub_boto_client,
+    validate_call_params,
+)
+from .manager import Manager, MatchAndUpdateResult
+from .note_text_config import NoteTextConfig
+from .rule import Rule
+from .utils import (
+    TimeRange,
+    are_keys_in_collection,
+    are_keys_in_dataclass_fields,
+    is_valid_against_reference,
+    parse_timestamp_str_if_set,
+)
+
+__all__ = [
+    "BotoStubCall",
+    "Manager",
+    "MatchAndUpdateResult",
+    "NoteTextConfig",
+    "Rule",
+    "TimeRange",
+    "are_keys_in_collection",
+    "are_keys_in_dataclass_fields",
+    "get_values_by_boto_argument",
+    "is_valid_against_reference",
+    "parse_timestamp_str_if_set",
+    "stub_boto_client",
+    "validate_call_params",
+    "validate_filters",
+    "validate_updates",
+]

awsfindingsmanagerlib/aws_lambda/__init__.py

@@ -0,0 +1 @@
+"""AWS Lambda entry points for running awsfindingsmanagerlib as part of an event-driven pipeline."""

awsfindingsmanagerlib/aws_lambda/clients.py

@@ -0,0 +1,28 @@
+"""Lazily-created, cached boto3 clients shared across Lambda handlers.
+
+Creating these lazily (rather than as module-level constants) means importing a handler module
+never requires AWS credentials or network access, which keeps the handlers unit-testable.
+"""
+
+from functools import cache
+
+import boto3
+from botocore.client import BaseClient
+
+
+@cache
+def get_securityhub_client() -> BaseClient:
+    """Return a cached boto3 Security Hub client, created on first use."""
+    return boto3.client("securityhub")
+
+
+@cache
+def get_s3_client() -> BaseClient:
+    """Return a cached boto3 S3 client, created on first use."""
+    return boto3.client("s3")
+
+
+@cache
+def get_sqs_client() -> BaseClient:
+    """Return a cached boto3 SQS client, created on first use."""
+    return boto3.client("sqs")

awsfindingsmanagerlib/aws_lambda/events.py

@@ -0,0 +1,74 @@
+"""EventBridge-triggered Lambda handler.
+
+Suppresses findings carried by a "Security Hub Findings - Imported" EventBridge event.
+
+Returns `{"finding_state": "suppressed"}` or `{"finding_state": "skipped"}` and never raises, so
+that a Step Function orchestrating this handler ahead of a ticketing integration can branch on
+the result: `terraform-aws-mcaf-securityhub-findings-manager` relies on exactly this contract to
+decide whether a finding still needs a Jira ticket after this handler has run.
+"""
+
+from typing import Any
+
+from awsfindingsmanagerlib import Manager
+from awsfindingsmanagerlib.aws_lambda.clients import (
+    get_s3_client,
+    get_securityhub_client,
+)
+from awsfindingsmanagerlib.aws_lambda.logging import get_logger
+from awsfindingsmanagerlib.aws_lambda.rules_backend import load_rules
+
+LOGGER = get_logger()
+
+
+@LOGGER.inject_lambda_context()
+def lambda_handler(event: dict[str, Any], _context: object) -> dict[str, str]:
+    """Suppress the findings carried by an EventBridge "Security Hub Findings - Imported" event.
+
+    Parameters
+    ----------
+    event : dict[str, Any]
+        The EventBridge event. `event["detail"]["findings"]` is expected to be a list of Security
+        Hub finding dicts.
+    _context : object
+        The Lambda context object (unused).
+
+    Returns
+    -------
+    dict[str, str]
+        `{"finding_state": "suppressed"}` if at least one finding matched a rule and all matching
+        updates were processed successfully, `{"finding_state": "skipped"}` otherwise (no rule
+        matched, the manager could not be initialized, or an update failed).
+    """
+    findings = event.get("detail", {}).get("findings", [])
+
+    try:
+        manager = Manager.from_rules_document(
+            load_rules(s3_client=get_s3_client()), get_securityhub_client()
+        )
+    except Exception:
+        LOGGER.exception("Failed to initialize the findings manager; skipping.")
+        return {"finding_state": "skipped"}
+
+    matched_any = False
+    processed_all = True
+
+    for finding in findings:
+        try:
+            result = manager.process_finding(finding)
+        except Exception:
+            LOGGER.exception("Failed to process a finding; skipping it.")
+            processed_all = False
+            continue
+
+        matched_any = matched_any or result.matched_rules > 0
+        processed_all = processed_all and result.all_processed
+
+    if matched_any and processed_all:
+        LOGGER.info("Successfully suppressed matching finding(s).")
+        return {"finding_state": "suppressed"}
+
+    LOGGER.info(
+        "No finding(s) were suppressed (no rule matched, or an update could not be processed)."
+    )
+    return {"finding_state": "skipped"}

awsfindingsmanagerlib/aws_lambda/logging.py

@@ -0,0 +1,36 @@
+"""Shared Lambda logging setup, built on aws-lambda-powertools.
+
+aws-lambda-powertools is an optional dependency (the 'lambda' extra), so importing this module
+without it installed raises a clear, actionable error instead of a bare ModuleNotFoundError.
+"""
+
+try:
+    from aws_lambda_powertools import Logger
+    from aws_lambda_powertools.logging import utils
+except ImportError as error:
+    msg = (
+        "aws-lambda-powertools is required to use awsfindingsmanagerlib.aws_lambda handlers. "
+        "Install it with the 'lambda' extra, e.g. `uv add 'awsfindingsmanagerlib[lambda]'` "
+        "or `pip install 'awsfindingsmanagerlib[lambda]'`."
+    )
+    raise ImportError(msg) from error
+
+
+def get_logger() -> Logger:
+    """Create a powertools Logger and propagate its configuration to other registered loggers.
+
+    The service name is taken from the `POWERTOOLS_SERVICE_NAME` environment variable, as usual
+    for aws-lambda-powertools. Handlers built on this logger call `inject_lambda_context()`
+    without an explicit `log_event` argument, so whether the incoming event is logged (which can
+    include full Security Hub finding payloads) is controlled entirely by the
+    `POWERTOOLS_LOGGER_LOG_EVENT` environment variable (defaults to `false`); passing
+    `log_event=True`/`False` explicitly at the call site would silently override that setting.
+
+    Returns
+    -------
+    Logger
+        A ready-to-use powertools Logger.
+    """
+    logger = Logger()
+    utils.copy_config_to_registered_loggers(source_logger=logger)
+    return logger

awsfindingsmanagerlib/aws_lambda/rules_backend.py

@@ -0,0 +1,61 @@
+"""Load suppression rules for AWS Lambda use."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from botocore.client import BaseClient
+
+try:
+    from yaml import safe_load
+except ImportError as error:
+    msg = (
+        "pyyaml is required to use awsfindingsmanagerlib.aws_lambda handlers. "
+        "Install it with the 'lambda' extra, e.g. `uv add 'awsfindingsmanagerlib[lambda]'` "
+        "or `pip install 'awsfindingsmanagerlib[lambda]'`."
+    )
+    raise ImportError(msg) from error
+
+
+def load_rules(s3_client: BaseClient | None = None) -> dict[str, Any]:
+    """Load the rules document, from S3 if configured, otherwise from a local file.
+
+    If both the `S3_BUCKET_NAME` and `S3_OBJECT_NAME` environment variables are set, the rules
+    document is loaded from that S3 object. Otherwise, it is loaded from the local file at
+    `RULES_PATH` (defaults to `rules.yaml`).
+
+    Parameters
+    ----------
+    s3_client : BaseClient, optional
+        The boto3 S3 client to use when loading rules from S3. Only used (and required) when
+        `S3_BUCKET_NAME` and `S3_OBJECT_NAME` are both set. Accepting it as a parameter, rather
+        than creating one internally, keeps this function free of AWS calls in unit tests.
+
+    Returns
+    -------
+    dict[str, Any]
+        The parsed rules document, expected to contain a top-level `Rules` key and optionally a
+        `ManagerConfig` key. See `awsfindingsmanagerlib.Manager.from_rules_document` for turning this into a
+        ready-to-use `Manager`.
+
+    Raises
+    ------
+    ValueError
+        If S3 loading is configured but no `s3_client` was provided.
+    """
+    bucket_name = os.environ.get("S3_BUCKET_NAME")
+    object_name = os.environ.get("S3_OBJECT_NAME")
+
+    if bucket_name and object_name:
+        if s3_client is None:
+            msg = (
+                "S3_BUCKET_NAME and S3_OBJECT_NAME are set, but no s3_client was provided "
+                "to load_rules()."
+            )
+            raise ValueError(msg)
+        response = s3_client.get_object(Bucket=bucket_name, Key=object_name)
+        return safe_load(response["Body"].read())
+
+    rules_path = os.environ.get("RULES_PATH", "rules.yaml")
+    with Path(rules_path).open() as file:
+        return safe_load(file)

awsfindingsmanagerlib/aws_lambda/scheduled.py

@@ -0,0 +1,42 @@
+"""Standalone scheduled Lambda handler.
+
+Loads the configured rules (from S3, or a local file bundled in the deployment package) and
+applies all of them against every currently matching Security Hub finding. Intended to be run on
+a schedule (e.g. via an EventBridge rule) rather than triggered by individual finding or rules
+events; see `awsfindingsmanagerlib.aws_lambda.events`, `.trigger` and `.worker` for the event-driven pipeline
+used by `terraform-aws-mcaf-securityhub-findings-manager`.
+"""
+
+from typing import Any
+
+from awsfindingsmanagerlib import Manager
+from awsfindingsmanagerlib.aws_lambda.clients import (
+    get_s3_client,
+    get_securityhub_client,
+)
+from awsfindingsmanagerlib.aws_lambda.logging import get_logger
+from awsfindingsmanagerlib.aws_lambda.rules_backend import load_rules
+
+LOGGER = get_logger()
+
+
+@LOGGER.inject_lambda_context()
+def lambda_handler(_event: dict[str, Any], _context: object) -> None:
+    """Apply all configured suppression rules to every currently matching Security Hub finding.
+
+    Raises
+    ------
+    RuntimeError
+        If not all matched findings could be successfully processed. Check the logged warnings
+        above the raised error for which finding(s)/rule(s) were affected.
+    """
+    manager = Manager.from_rules_document(
+        load_rules(s3_client=get_s3_client()), get_securityhub_client()
+    )
+
+    if not manager.get_and_update_all():
+        msg = (
+            "Not all findings were processed successfully; "
+            "see the warnings logged above for details."
+        )
+        raise RuntimeError(msg)

awsfindingsmanagerlib/aws_lambda/trigger.py

@@ -0,0 +1,48 @@
+"""S3-triggered Lambda handler.
+
+Fired when the rules document is uploaded to S3. Loads the rules and fans each one out as its
+own message on SQS, carrying the shared `ManagerConfig` alongside it, so that the worker Lambda
+(`awsfindingsmanagerlib.aws_lambda.worker`) can build an equivalent single-rule Manager for it.
+
+Unlike `events.lambda_handler`, failures here are raised rather than swallowed: there is no
+downstream Step Function branching on this handler's result, and a failure to queue rules should
+be visible (e.g. via a Lambda error metric alarm) rather than silently skipped.
+"""
+
+import json
+import os
+from typing import Any
+
+from awsfindingsmanagerlib.aws_lambda.clients import get_s3_client, get_sqs_client
+from awsfindingsmanagerlib.aws_lambda.logging import get_logger
+from awsfindingsmanagerlib.aws_lambda.rules_backend import load_rules
+
+LOGGER = get_logger()
+
+
+@LOGGER.inject_lambda_context()
+def lambda_handler(_event: dict[str, Any], _context: object) -> None:
+    """Load the configured rules and place each one on SQS for the worker Lambda to apply.
+
+    Reads the destination queue URL from the `SQS_QUEUE_URL` environment variable.
+
+    Raises
+    ------
+    Exception
+        Re-raises any failure to load the rules or send a message to SQS, after logging it.
+    """
+    try:
+        rules = load_rules(s3_client=get_s3_client())
+        manager_config = rules.get("ManagerConfig", {})
+        queue_url = os.environ.get("SQS_QUEUE_URL")
+        sqs = get_sqs_client()
+
+        for rule in rules.get("Rules", []):
+            message_body = json.dumps(
+                {"ManagerConfig": manager_config, "Rules": [rule]}
+            )
+            LOGGER.info("Putting rule on SQS. Rule details: %s", message_body)
+            sqs.send_message(QueueUrl=queue_url, MessageBody=message_body)
+    except Exception:
+        LOGGER.exception("Failed putting rule(s) on SQS.")
+        raise

awsfindingsmanagerlib/aws_lambda/worker.py

@@ -0,0 +1,60 @@
+"""SQS-triggered Lambda handler.
+
+Each SQS record carries a single-rule rules document (as produced by
+`awsfindingsmanagerlib.aws_lambda.trigger`): applies that rule against all currently matching Security Hub
+findings.
+
+Failures are reported per record via SQS's partial batch response contract
+(`{"batchItemFailures": [...]}`), not by raising: a failed record becomes visible again after the
+queue's visibility timeout and is retried (and eventually sent to the dead-letter queue per the
+queue's redrive policy) without the whole batch, including already-successful records, being
+reprocessed. This requires `function_response_types = ["ReportBatchItemFailures"]` to be set on
+the event source mapping; without it, Lambda ignores this return value and deletes the entire
+batch regardless of these results.
+"""
+
+import json
+from typing import Any
+
+from awsfindingsmanagerlib import Manager
+from awsfindingsmanagerlib.aws_lambda.clients import get_securityhub_client
+from awsfindingsmanagerlib.aws_lambda.logging import get_logger
+
+LOGGER = get_logger()
+
+
+@LOGGER.inject_lambda_context()
+def lambda_handler(
+    event: dict[str, Any], _context: object
+) -> dict[str, list[dict[str, str]]]:
+    """Apply the suppression rule carried by each SQS record to matching Security Hub findings.
+
+    Parameters
+    ----------
+    event : dict[str, Any]
+        The SQS event. Each `event["Records"]` entry's `body` is expected to be a JSON-encoded
+        rules document with exactly one rule in its `Rules` list.
+    _context : object
+        The Lambda context object (unused).
+
+    Returns
+    -------
+    dict[str, list[dict[str, str]]]
+        `{"batchItemFailures": [{"itemIdentifier": <messageId>}, ...]}`, naming only the records
+        that failed to process. Requires `function_response_types = ["ReportBatchItemFailures"]`
+        on the SQS event source mapping to take effect.
+    """
+    batch_item_failures: list[dict[str, str]] = []
+
+    for record in event.get("Records", []):
+        try:
+            rule = json.loads(record["body"])
+            manager = Manager.from_rules_document(rule, get_securityhub_client())
+            manager.get_and_update_all()
+        except Exception:
+            LOGGER.exception(
+                "Failed to process rule from SQS record %s.", record.get("messageId")
+            )
+            batch_item_failures.append({"itemIdentifier": record["messageId"]})
+
+    return {"batchItemFailures": batch_item_failures}

awsfindingsmanagerlib/awsfindingsmanagerlib.py

@@ -0,0 +1,75 @@
+"""The main module of awsfindingsmanagerlib."""
+
+import botocore.session
+from botocore.client import BaseClient
+
+from .boto_utils import (
+    BotoStubCall,
+    validate_call_params,
+)
+
+
+def _validate_call_params(
+    stub_responses: list[BotoStubCall],
+    session_client: BaseClient | None = None,
+) -> None:
+    if not session_client:
+        session_client = botocore.session.get_session().create_client("securityhub")
+
+    validate_call_params(stub_responses, session_client)
+
+
+def 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, optional
+        A boto session BaseClient for AWS SecurityHub
+        Tries to create one if not provided
+
+    Raises
+    ------
+    botocore.exceptions.ParamValidationError
+        If the filters contain invalid values
+    """
+    _validate_call_params(
+        [
+            BotoStubCall(
+                method="get_findings",
+                service_response={"Findings": []},
+                expected_params={"Filters": filters},
+            )
+        ],
+        session_client,
+    )
+
+
+def 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, optional
+        A boto session BaseClient for AWS SecurityHub
+        Tries to create one if not provided
+
+    Raises
+    ------
+    botocore.exceptions.ParamValidationError
+        If the updates contain invalid values
+    """
+    _validate_call_params(
+        [
+            BotoStubCall(
+                method="batch_update_findings",
+                service_response={"ProcessedFindings": [], "UnprocessedFindings": []},
+                expected_params=updates,
+            )
+        ],
+        session_client,
+    )