asff

Submodules

Package Contents

Classes

AmazonSecurityFinding

Provides consistent format for the contents of the Security Hub-aggregated findings. AwsSecurityFinding format enables you to share findings between AWS security services and third-party solutions, and security standards checks. A finding is a potential security issue generated either by AWS services (Amazon GuardDuty, Amazon Inspector, and Amazon Macie) or by the integrated third-party solutions and standards checks.
exception asff.ValidationError(msg)

Bases: ValueError

Inheritance diagram of asff.ValidationError

Inappropriate argument value (of correct type).

class asff.AmazonSecurityFinding(**data)

Bases: asff.generated.AwsSecurityFinding

Inheritance diagram of asff.AmazonSecurityFinding

Provides consistent format for the contents of the Security Hub-aggregated findings. AwsSecurityFinding format enables you to share findings between AWS security services and third-party solutions, and security standards checks. A finding is a potential security issue generated either by AWS services (Amazon GuardDuty, Amazon Inspector, and Amazon Macie) or by the integrated third-party solutions and standards checks.

Parameters

  • schema_version – The schema version that a finding is formatted for.

  • id – The security findings provider-specific identifier for a finding.

  • product_arn – The ARN generated by Security Hub that uniquely identifies a product that generates findings. This can be the ARN for a third-party product that is integrated with Security Hub, or the ARN for a custom integration.

  • generator_id – The identifier for the solution-specific component (a discrete unit of logic) that generated a finding. In various security-findings providers’ solutions, this generator can be called a rule, a check, a detector, a plugin, etc.

  • aws_account_id – The AWS account ID that a finding is generated in.

  • types – One or more finding types in the format of namespace/category/classifier that classify a finding. Valid namespace values are: Software and Configuration Checks | TTPs | Effects | Unusual Behaviors | Sensitive Data Identifications

  • first_observed_at – Indicates when the security-findings provider first observed the potential security issue that a finding captured. Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

  • last_observed_at – Indicates when the security-findings provider most recently observed the potential security issue that a finding captured. Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

  • created_at – Indicates when the security-findings provider created the potential security issue that a finding captured. Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

  • updated_at – Indicates when the security-findings provider last updated the finding record. Uses the date-time format specified in RFC 3339 section 5.6, Internet Date/Time Format. The value cannot contain spaces. For example, 2020-03-22T13:22:13.933Z.

  • severity – A finding’s severity.

  • confidence – A finding’s confidence. Confidence is defined as the likelihood that a finding accurately identifies the behavior or issue that it was intended to identify. Confidence is scored on a 0-100 basis using a ratio scale, where 0 means zero percent confidence and 100 means 100 percent confidence.

  • criticality – The level of importance assigned to the resources associated with the finding. A score of 0 means that the underlying resources have no criticality, and a score of 100 is reserved for the most critical resources.

  • title – A finding’s title. In this release, Title is a required property.

  • description – A finding’s description. In this release, Description is a required property.

  • remediation – A data type that describes the remediation options for a finding.

  • source_url – A URL that links to a page about the current finding in the security-findings provider’s solution.

  • product_fields – A data type where security-findings providers can include additional solution-specific details that aren’t part of the defined AwsSecurityFinding format.

  • user_defined_fields – A list of name/value string pairs associated with the finding. These are custom, user-defined fields added to a finding.

  • malware – A list of malware related to a finding.

  • network – The details of network-related information about a finding.

  • network_path – Provides information about a network path that is relevant to a finding. Each entry under NetworkPath represents a component of that path.

  • process – The details of process-related information about a finding.

  • threat_intel_indicators – Threat intelligence details related to a finding.

  • resources – A set of resource data types that describe the resources that the finding refers to.

  • compliance – This data type is exclusive to findings that are generated as the result of a check run against a specific rule in a supported security standard, such as CIS AWS Foundations. Contains security standard-related finding details.

  • verification_state – Indicates the veracity of a finding.

  • workflow_state – The workflow state of a finding.

  • workflow – Provides information about the status of the investigation into a finding.

  • record_state – The record state of a finding.

  • related_findings – A list of related findings.

  • note – A user-defined note added to a finding.

  • vulnerabilities – Provides a list of vulnerabilities associated with the findings.

  • patch_summary – Provides an overview of the patch compliance status for an instance against a selected compliance standard.

  • action – Provides details about an action that affects or that was taken on a resource.

  • finding_provider_fields – In a BatchImportFindings request, finding providers use FindingProviderFields to provide and update their own values for confidence, criticality, related findings, severity, and types.

Returns

AwsSecurityFinding object

static calculate_finding_id(aws_account_id: str, region: str, product_name: str, title: str) → str

Calculate predictable unique finding ID based on immutable finding attributes. The finding ID is calculated as a SHA256 hash of the string consisting of the following attributes: - aws_account_id - region - product_name - title

finding_id = SHA256(aws_account_id + region + product_name + title)

In the future, the list of attributes used for calculating hashes might be extended, but the primary purpose is to have a set of attributes that are unique, yet easy to remember, so the finding ID could be calculated easily and found by this library.

Parameters

  • aws_account_id – The AWS account ID that the finding applies to.

  • region – AWS region where the finding was found

  • product_name – Product name that generated the finding

  • title – A finding’s title.

Returns

A predictable unique finding ID

classmethod from_dict(cls, data) → asff.finding.AmazonSecurityFinding

Construct the finding from a dictionary.

Parameters

data – Dictionary holding finding data

Returns

A finding object

classmethod from_json(cls, data: str) → asff.finding.AmazonSecurityFinding

Construct the finding from a JSON string.

Parameters

data – JSON string with finding data

Returns

A finding object

classmethod from_kwargs(cls, aws_account_id: str, types: asff.generated.TypeList, title: asff.generated.NonEmptyString, description: asff.generated.NonEmptyString, resources: Optional[List[Any]] = None, id: Optional[str] = None, schema_version: str = DEFAULT_SCHEMA_VERSION, severity: str = DEFAULT_SEVERITY, product_name: Optional[str] = DEFAULT_PRODUCT_NAME, product_version: Optional[str] = DEFAULT_PRODUCT_VERSION, region: str = DEFAULT_REGION, record_state: str = DEFAULT_RECORD_STATE, workflow_status: str = DEFAULT_WORKFLOW_STATUS, generator_id: Optional[str] = None, created_at: Optional[str] = None, updated_at: Optional[str] = None, **kwargs)

Construct the finding from keyword arguments.

Parameters

  • aws_account_id – The AWS account ID that the finding applies to.

  • types – Finding type that classifies the finding

  • title – A finding’s title.

  • description – A finding’s description.

  • resources – A set of resource data types that describe the resources that the finding refers to.

  • id – The product-specific identifier for a finding.

  • schema_version – The schema version that a finding is formatted for

  • severity – A finding’s severity.

  • product_name – Product name that generated the finding

  • product_version – Product version that generated the finding

  • region – AWS region where the finding was found

  • record_state – The record state of a finding.

  • workflow_status – Provides information about the status of the investigation into a finding.

  • generator_id – The identifier for the solution-specific component that generated a finding.

  • created_at – Indicates when the potential security issue captured by a finding was created.

  • updated_at – Indicates when the finding provider last updated the finding record.

  • kwargs – Additional keyword arguments, suitable for passing fields such as notes, user_defined_fields etc

Returns

A finding object

to_dict(self) → Dict[str, Any]

Return a dict representation of the finding.

Returns

A dict representation of the finding

to_json(self) → str

Return a JSON representation of the finding.

Returns

JSON representation of the finding