= AWS Security Hub Component
:doctitle: AWS Security Hub
:shortname: aws-security-hub
:artifactid: camel-aws-security-hub
:description: Manage and interact with AWS Security Hub for security findings.
:since: 4.18
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only producer is supported
//Manually maintained attributes
:group: AWS
:camel-spring-boot-name: aws-security-hub

*Since Camel {since}*

*{component-header}*

The AWS Security Hub component allows you to interact with
https://aws.amazon.com/security-hub/[AWS Security Hub] to manage security findings.

AWS Security Hub provides a comprehensive view of your security state in AWS and helps you check your environment against security industry standards and best practices.

Prerequisites

You must have a valid Amazon Web Services developer account, and be
signed up to use Amazon Security Hub. More information is available at
https://aws.amazon.com/security-hub/[Amazon Security Hub].

== URI Format

-------------------------
aws-security-hub://label[?options]
-------------------------

You can append query options to the URI in the following format:

`?options=value&option2=value&...`


// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END

== Usage

=== Static credentials, Default Credential Provider and Profile Credentials Provider

You have the possibility of avoiding the usage of explicit static credentials by specifying the useDefaultCredentialsProvider option and set it to true.

The order of evaluation for Default Credentials Provider is the following:

 - Java system properties - `aws.accessKeyId` and `aws.secretKey`.
 - Environment variables - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
 - Web Identity Token from AWS STS.
 - The shared credentials and config files.
 - Amazon ECS container credentials - loaded from the Amazon ECS if the environment variable `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set.
 - Amazon EC2 Instance profile credentials.

You have also the possibility of using Profile Credentials Provider, by specifying the useProfileCredentialsProvider option to true and profileCredentialsName to the profile name.

Only one of static, default and profile credentials could be used at the same time.

For more information about this you can look at https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html[AWS credentials documentation]

=== AWS Security Hub Producer operations

Camel-AWS Security Hub component provides the following operation on the producer side:

- batchImportFindings
- getFindings
- batchUpdateFindings
- getFindingHistory
- describeHub
- listEnabledProductsForImport

==== BatchImportFindings

Import security findings into Security Hub. This is the primary way to send findings from custom integrations.

[source,java]
--------------------------------------------------------------------------------
from("direct:importFindings")
    .process(exchange -> {
        AwsSecurityFinding finding = AwsSecurityFinding.builder()
            .schemaVersion("2018-10-08")
            .id("my-finding-id")
            .productArn("arn:aws:securityhub:us-east-1:123456789012:product/123456789012/default")
            .generatorId("my-generator")
            .awsAccountId("123456789012")
            .types("Software and Configuration Checks/Vulnerabilities/CVE")
            .createdAt("2024-01-15T00:00:00.000Z")
            .updatedAt("2024-01-15T00:00:00.000Z")
            .severity(Severity.builder().label(SeverityLabel.HIGH).build())
            .title("Critical vulnerability found")
            .description("A critical vulnerability was detected")
            .resources(Resource.builder()
                .type("AwsEc2Instance")
                .id("arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0")
                .build())
            .build();
        exchange.getIn().setBody(List.of(finding));
    })
    .to("aws-security-hub://findings?operation=batchImportFindings")
    .to("mock:result");
--------------------------------------------------------------------------------

==== GetFindings

Retrieve security findings from Security Hub with optional filtering.

[source,java]
--------------------------------------------------------------------------------
from("direct:getFindings")
    .process(exchange -> {
        AwsSecurityFindingFilters filters = AwsSecurityFindingFilters.builder()
            .severityLabel(StringFilter.builder()
                .comparison(StringFilterComparison.EQUALS)
                .value("CRITICAL")
                .build())
            .build();
        exchange.getIn().setHeader(SecurityHubConstants.FILTERS, filters);
        exchange.getIn().setHeader(SecurityHubConstants.MAX_RESULTS, 10);
    })
    .to("aws-security-hub://findings?operation=getFindings")
    .to("mock:result");
--------------------------------------------------------------------------------

==== BatchUpdateFindings

Update security findings with notes, severity changes, workflow status, etc.

[source,java]
--------------------------------------------------------------------------------
from("direct:updateFindings")
    .process(exchange -> {
        List<AwsSecurityFindingIdentifier> identifiers = List.of(
            AwsSecurityFindingIdentifier.builder()
                .id("my-finding-id")
                .productArn("arn:aws:securityhub:us-east-1:123456789012:product/123456789012/default")
                .build()
        );
        exchange.getIn().setHeader(SecurityHubConstants.FINDING_IDENTIFIERS, identifiers);

        NoteUpdate note = NoteUpdate.builder()
            .text("Reviewed and confirmed as false positive")
            .updatedBy("security-team")
            .build();
        exchange.getIn().setHeader(SecurityHubConstants.NOTE, note);

        WorkflowUpdate workflow = WorkflowUpdate.builder()
            .status(WorkflowStatus.RESOLVED)
            .build();
        exchange.getIn().setHeader(SecurityHubConstants.WORKFLOW, workflow);
    })
    .to("aws-security-hub://findings?operation=batchUpdateFindings")
    .to("mock:result");
--------------------------------------------------------------------------------

==== DescribeHub

Get information about the Security Hub configuration in your account.

[source,java]
--------------------------------------------------------------------------------
from("direct:describeHub")
    .to("aws-security-hub://hub?operation=describeHub")
    .to("mock:result");
--------------------------------------------------------------------------------

=== OCSF Integration

AWS Security Hub uses the https://schema.ocsf.io/[Open Cybersecurity Schema Framework (OCSF)] for findings. You can use the Camel OCSF DataFormat to work with security events in a vendor-neutral format, then convert them for import into Security Hub.

[source,java]
--------------------------------------------------------------------------------
from("direct:ocsfToSecurityHub")
    .unmarshal().ocsf(DetectionFinding.class)
    .process(exchange -> {
        DetectionFinding ocsf = exchange.getIn().getBody(DetectionFinding.class);
        // Convert OCSF finding to AWS Security Finding format
        AwsSecurityFinding finding = convertToAwsFinding(ocsf);
        exchange.getIn().setBody(List.of(finding));
    })
    .to("aws-security-hub://findings?operation=batchImportFindings");
--------------------------------------------------------------------------------

== Dependencies

Maven users will need to add the following dependency to their pom.xml.

*pom.xml*

[source,xml]
---------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws-security-hub</artifactId>
    <version>${camel-version}</version>
</dependency>
---------------------------------------

where `$\{camel-version}` must be replaced by the actual version of Camel.
