- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
CreateInsightCommand
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
CreateInsightCommand Input
Parameter | Type | Description |
---|
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
Parameter | Type | Description |
---|
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 |
---|
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. |