CreateInsightCommand

Suggest an Edit

Creates a custom insight in Security Hub. An insight is a consolidation of findings that relate to a security issue that requires attention or remediation.

To group the related findings in the insight, use the GroupByAttribute.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { SecurityHubClient, CreateInsightCommand } from "@aws-sdk/client-securityhub"; // ES Modules import
// const { SecurityHubClient, CreateInsightCommand } = require("@aws-sdk/client-securityhub"); // CommonJS import
const client = new SecurityHubClient(config);
const input = { // CreateInsightRequest
  Name: "STRING_VALUE", // required
  Filters: { // AwsSecurityFindingFilters
    ProductArn: [ // StringFilterList
      { // StringFilter
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "PREFIX" || "NOT_EQUALS" || "PREFIX_NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    AwsAccountId: [
      {
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "PREFIX" || "NOT_EQUALS" || "PREFIX_NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    Id: [
      {
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "PREFIX" || "NOT_EQUALS" || "PREFIX_NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    GeneratorId: [
      {
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "PREFIX" || "NOT_EQUALS" || "PREFIX_NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    Region: [
      {
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "PREFIX" || "NOT_EQUALS" || "PREFIX_NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    Type: "<StringFilterList>",
    FirstObservedAt: [ // DateFilterList
      { // DateFilter
        Start: "STRING_VALUE",
        End: "STRING_VALUE",
        DateRange: { // DateRange
          Value: Number("int"),
          Unit: "DAYS",
        },
      },
    ],
    LastObservedAt: [
      {
        Start: "STRING_VALUE",
        End: "STRING_VALUE",
        DateRange: {
          Value: Number("int"),
          Unit: "DAYS",
        },
      },
    ],
    CreatedAt: [
      {
        Start: "STRING_VALUE",
        End: "STRING_VALUE",
        DateRange: {
          Value: Number("int"),
          Unit: "DAYS",
        },
      },
    ],
    UpdatedAt: [
      {
        Start: "STRING_VALUE",
        End: "STRING_VALUE",
        DateRange: {
          Value: Number("int"),
          Unit: "DAYS",
        },
      },
    ],
    SeverityProduct: [ // NumberFilterList
      { // NumberFilter
        Gte: Number("double"),
        Lte: Number("double"),
        Eq: Number("double"),
        Gt: Number("double"),
        Lt: Number("double"),
      },
    ],
    SeverityNormalized: [
      {
        Gte: Number("double"),
        Lte: Number("double"),
        Eq: Number("double"),
        Gt: Number("double"),
        Lt: Number("double"),
      },
    ],
    SeverityLabel: "<StringFilterList>",
    Confidence: [
      {
        Gte: Number("double"),
        Lte: Number("double"),
        Eq: Number("double"),
        Gt: Number("double"),
        Lt: Number("double"),
      },
    ],
    Criticality: [
      {
        Gte: Number("double"),
        Lte: Number("double"),
        Eq: Number("double"),
        Gt: Number("double"),
        Lt: Number("double"),
      },
    ],
    Title: "<StringFilterList>",
    Description: "<StringFilterList>",
    RecommendationText: "<StringFilterList>",
    SourceUrl: "<StringFilterList>",
    ProductFields: [ // MapFilterList
      { // MapFilter
        Key: "STRING_VALUE",
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    ProductName: "<StringFilterList>",
    CompanyName: "<StringFilterList>",
    UserDefinedFields: [
      {
        Key: "STRING_VALUE",
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    MalwareName: "<StringFilterList>",
    MalwareType: "<StringFilterList>",
    MalwarePath: "<StringFilterList>",
    MalwareState: "<StringFilterList>",
    NetworkDirection: "<StringFilterList>",
    NetworkProtocol: "<StringFilterList>",
    NetworkSourceIpV4: [ // IpFilterList
      { // IpFilter
        Cidr: "STRING_VALUE",
      },
    ],
    NetworkSourceIpV6: [
      {
        Cidr: "STRING_VALUE",
      },
    ],
    NetworkSourcePort: [
      {
        Gte: Number("double"),
        Lte: Number("double"),
        Eq: Number("double"),
        Gt: Number("double"),
        Lt: Number("double"),
      },
    ],
    NetworkSourceDomain: "<StringFilterList>",
    NetworkSourceMac: "<StringFilterList>",
    NetworkDestinationIpV4: [
      {
        Cidr: "STRING_VALUE",
      },
    ],
    NetworkDestinationIpV6: [
      {
        Cidr: "STRING_VALUE",
      },
    ],
    NetworkDestinationPort: "<NumberFilterList>",
    NetworkDestinationDomain: "<StringFilterList>",
    ProcessName: "<StringFilterList>",
    ProcessPath: "<StringFilterList>",
    ProcessPid: "<NumberFilterList>",
    ProcessParentPid: "<NumberFilterList>",
    ProcessLaunchedAt: [
      {
        Start: "STRING_VALUE",
        End: "STRING_VALUE",
        DateRange: {
          Value: Number("int"),
          Unit: "DAYS",
        },
      },
    ],
    ProcessTerminatedAt: "<DateFilterList>",
    ThreatIntelIndicatorType: "<StringFilterList>",
    ThreatIntelIndicatorValue: "<StringFilterList>",
    ThreatIntelIndicatorCategory: "<StringFilterList>",
    ThreatIntelIndicatorLastObservedAt: "<DateFilterList>",
    ThreatIntelIndicatorSource: "<StringFilterList>",
    ThreatIntelIndicatorSourceUrl: "<StringFilterList>",
    ResourceType: "<StringFilterList>",
    ResourceId: "<StringFilterList>",
    ResourcePartition: "<StringFilterList>",
    ResourceRegion: "<StringFilterList>",
    ResourceTags: [
      {
        Key: "STRING_VALUE",
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    ResourceAwsEc2InstanceType: "<StringFilterList>",
    ResourceAwsEc2InstanceImageId: "<StringFilterList>",
    ResourceAwsEc2InstanceIpV4Addresses: [
      {
        Cidr: "STRING_VALUE",
      },
    ],
    ResourceAwsEc2InstanceIpV6Addresses: "<IpFilterList>",
    ResourceAwsEc2InstanceKeyName: "<StringFilterList>",
    ResourceAwsEc2InstanceIamInstanceProfileArn: "<StringFilterList>",
    ResourceAwsEc2InstanceVpcId: "<StringFilterList>",
    ResourceAwsEc2InstanceSubnetId: "<StringFilterList>",
    ResourceAwsEc2InstanceLaunchedAt: "<DateFilterList>",
    ResourceAwsS3BucketOwnerId: "<StringFilterList>",
    ResourceAwsS3BucketOwnerName: "<StringFilterList>",
    ResourceAwsIamAccessKeyUserName: "<StringFilterList>",
    ResourceAwsIamAccessKeyPrincipalName: "<StringFilterList>",
    ResourceAwsIamAccessKeyStatus: "<StringFilterList>",
    ResourceAwsIamAccessKeyCreatedAt: "<DateFilterList>",
    ResourceAwsIamUserUserName: "<StringFilterList>",
    ResourceContainerName: "<StringFilterList>",
    ResourceContainerImageId: "<StringFilterList>",
    ResourceContainerImageName: "<StringFilterList>",
    ResourceContainerLaunchedAt: "<DateFilterList>",
    ResourceDetailsOther: [
      {
        Key: "STRING_VALUE",
        Value: "STRING_VALUE",
        Comparison: "EQUALS" || "NOT_EQUALS" || "CONTAINS" || "NOT_CONTAINS",
      },
    ],
    ComplianceStatus: "<StringFilterList>",
    VerificationState: "<StringFilterList>",
    WorkflowState: "<StringFilterList>",
    WorkflowStatus: "<StringFilterList>",
    RecordState: "<StringFilterList>",
    RelatedFindingsProductArn: "<StringFilterList>",
    RelatedFindingsId: "<StringFilterList>",
    NoteText: "<StringFilterList>",
    NoteUpdatedAt: "<DateFilterList>",
    NoteUpdatedBy: "<StringFilterList>",
    Keyword: [ // KeywordFilterList
      { // KeywordFilter
        Value: "STRING_VALUE",
      },
    ],
    FindingProviderFieldsConfidence: "<NumberFilterList>",
    FindingProviderFieldsCriticality: "<NumberFilterList>",
    FindingProviderFieldsRelatedFindingsId: "<StringFilterList>",
    FindingProviderFieldsRelatedFindingsProductArn: "<StringFilterList>",
    FindingProviderFieldsSeverityLabel: "<StringFilterList>",
    FindingProviderFieldsSeverityOriginal: "<StringFilterList>",
    FindingProviderFieldsTypes: "<StringFilterList>",
    Sample: [ // BooleanFilterList
      { // BooleanFilter
        Value: true || false,
      },
    ],
    ComplianceSecurityControlId: "<StringFilterList>",
    ComplianceAssociatedStandardsId: "<StringFilterList>",
    VulnerabilitiesExploitAvailable: "<StringFilterList>",
    VulnerabilitiesFixAvailable: "<StringFilterList>",
    ComplianceSecurityControlParametersName: "<StringFilterList>",
    ComplianceSecurityControlParametersValue: "<StringFilterList>",
    AwsAccountName: "<StringFilterList>",
    ResourceApplicationName: "<StringFilterList>",
    ResourceApplicationArn: "<StringFilterList>",
  },
  GroupByAttribute: "STRING_VALUE", // required
};
const command = new CreateInsightCommand(input);
const response = await client.send(command);
// { // CreateInsightResponse
//   InsightArn: "STRING_VALUE", // required
// };

Example Usage

 Loading code editorLoading code editor

CreateInsightCommand Input

See CreateInsightCommandInput for more details

Parameter
Type
Description
Filters
Required
AwsSecurityFindingFilters | undefined

One or more attributes used to filter the findings included in the insight. The insight only includes findings that match the criteria defined in the filters.

GroupByAttribute
Required
string | undefined

The attribute used to group the findings for the insight. The grouping attribute identifies the type of item that the insight applies to. For example, if an insight is grouped by resource identifier, then the insight produces a list of resource identifiers.

Name
Required
string | undefined

The name of the custom insight to create.

CreateInsightCommand Output

See CreateInsightCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
InsightArn
Required
string | undefined

The ARN of the insight created.

Throws

Name
Fault
Details
InternalException
server

Internal server error.

InvalidAccessException
client

The account doesn't have permission to perform this action.

InvalidInputException
client

The request was rejected because you supplied an invalid or out-of-range value for an input parameter.

LimitExceededException
client

The request was rejected because it attempted to create resources beyond the current Amazon Web Services account or throttling limits. The error code describes the limit exceeded.

ResourceConflictException
client

The resource specified in the request conflicts with an existing resource.

SecurityHubServiceException
Base exception class for all service exceptions from SecurityHub service.