security_profiles

Creates, updates, deletes, gets or lists a security_profiles resource.

Overview

Name	security_profiles
Type	Resource
Id	aws.iot.security_profiles

Fields

The following fields are returned by SELECT queries:

describe_security_profile

Name	Datatype	Description
additional_metrics_to_retain	array	Please use DescribeSecurityProfileResponse$additionalMetricsToRetainV2 instead. A list of metrics whose data is retained (stored). By default, data is retained for any metric used in the profile's behaviors, but it is also retained for any metric specified here.
additional_metrics_to_retain_v2	array	A list of metrics whose data is retained (stored). By default, data is retained for any metric used in the profile's behaviors, but it is also retained for any metric specified here.
alert_targets	object	Where the alerts are sent. (Alerts are always sent to the console.)
behaviors	array	Specifies the behaviors that, when violated by a device (thing), cause an alert.
creation_date	string (date-time)	The time the security profile was created.
last_modified_date	string (date-time)	The time the security profile was last modified.
metrics_export_config	object	Set configurations for metrics export.
security_profile_arn	string	The ARN of the security profile.
security_profile_description	string	A description of the security profile (associated with the security profile when it was created or updated). (pattern: <code>[\p{Graph}\x20]*</code>)
security_profile_name	string	The name of the security profile. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
version	integer (int64)	The version of the security profile. A new version is generated whenever the security profile is updated.

list_security_profiles

Name	Datatype	Description
name	string	The name you've given to the security profile. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
arn	string	The ARN of the security profile.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_security_profile	select	security_profile_name, region		Gets information about a Device Defender security profile. Requires permission to access the DescribeSecurityProfile action.
list_security_profiles	select	region	nextToken, maxResults, dimensionName, metricName	Lists the Device Defender security profiles you've created. You can filter security profiles by dimension or custom metric. Requires permission to access the ListSecurityProfiles action. dimensionName and metricName cannot be used in the same request.
create_security_profile	insert	security_profile_name, region		Creates a Device Defender security profile. Requires permission to access the CreateSecurityProfile action.
attach_security_profile	update	security_profile_name, securityProfileTargetArn, region		Associates a Device Defender security profile with a thing group or this account. Each thing group or account can have up to five security profiles associated with it. Requires permission to access the AttachSecurityProfile action.
update_security_profile	update	security_profile_name, region	expectedVersion	Updates a Device Defender security profile. Requires permission to access the UpdateSecurityProfile action.
delete_security_profile	delete	security_profile_name, region	expectedVersion	Deletes a Device Defender security profile. Requires permission to access the DeleteSecurityProfile action.
detach_security_profile	exec	security_profile_name, securityProfileTargetArn, region		Disassociates a Device Defender security profile from a thing group or from this account. Requires permission to access the DetachSecurityProfile action.
validate_security_profile_behaviors	exec	region, behaviors		Validates a Device Defender security profile behaviors specification. Requires permission to access the ValidateSecurityProfileBehaviors action.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)
securityProfileTargetArn	string	The ARN of the thing group from which the security profile is detached.
security_profile_name	string	The security profile that is detached.
dimensionName	string	A filter to limit results to the security profiles that use the defined dimension. Cannot be used with metricName
expectedVersion	integer (int64)	The expected version of the security profile. A new version is generated whenever the security profile is updated. If you specify a value that is different from the actual version, a VersionConflictException is thrown.
maxResults	integer	The maximum number of results to return at one time.
metricName	string	The name of the custom metric. Cannot be used with dimensionName.
nextToken	string	The token for the next set of results.

SELECT examples

describe_security_profile

Gets information about a Device Defender security profile. Requires permission to access the DescribeSecurityProfile action.

SELECT
additional_metrics_to_retain,
additional_metrics_to_retain_v2,
alert_targets,
behaviors,
creation_date,
last_modified_date,
metrics_export_config,
security_profile_arn,
security_profile_description,
security_profile_name,
version
FROM aws.iot.security_profiles
WHERE security_profile_name = '{{ security_profile_name }}' -- required
AND region = '{{ region }}' -- required
;

list_security_profiles

Lists the Device Defender security profiles you've created. You can filter security profiles by dimension or custom metric. Requires permission to access the ListSecurityProfiles action. dimensionName and metricName cannot be used in the same request.

SELECT
name,
arn
FROM aws.iot.security_profiles
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND dimensionName = '{{ dimensionName }}'
AND metricName = '{{ metricName }}'
;

INSERT examples

create_security_profile

Creates a Device Defender security profile. Requires permission to access the CreateSecurityProfile action.

INSERT INTO aws.iot.security_profiles (
securityProfileDescription,
behaviors,
alertTargets,
additionalMetricsToRetain,
additionalMetricsToRetainV2,
tags,
metricsExportConfig,
security_profile_name,
region
)
SELECT 
'{{ securityProfileDescription }}',
'{{ behaviors }}',
'{{ alertTargets }}',
'{{ additionalMetricsToRetain }}',
'{{ additionalMetricsToRetainV2 }}',
'{{ tags }}',
'{{ metricsExportConfig }}',
'{{ security_profile_name }}',
'{{ region }}'
RETURNING
security_profile_arn,
security_profile_name
;

Manifest

# Description fields are for documentation purposes
- name: security_profiles
props:
  - name: security_profile_name
    value: "{{ security_profile_name }}"
    description: Required parameter for the security_profiles resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the security_profiles resource.
  - name: securityProfileDescription
    value: "{{ securityProfileDescription }}"
  - name: behaviors
    value:
      - name: "{{ name }}"
        metric: "{{ metric }}"
        metricDimension:
          dimensionName: "{{ dimensionName }}"
          operator: "{{ operator }}"
        criteria:
          comparisonOperator: "{{ comparisonOperator }}"
          value:
            count: {{ count }}
            cidrs:
              - "{{ cidrs }}"
            ports:
              - {{ ports }}
            number: {{ number }}
            numbers:
              - {{ numbers }}
            strings:
              - "{{ strings }}"
          durationSeconds: {{ durationSeconds }}
          consecutiveDatapointsToAlarm: {{ consecutiveDatapointsToAlarm }}
          consecutiveDatapointsToClear: {{ consecutiveDatapointsToClear }}
          statisticalThreshold:
            statistic: "{{ statistic }}"
          mlDetectionConfig:
            confidenceLevel: "{{ confidenceLevel }}"
        suppressAlerts: {{ suppressAlerts }}
        exportMetric: {{ exportMetric }}
  - name: alertTargets
    value: "{{ alertTargets }}"
  - name: additionalMetricsToRetain
    value:
      - "{{ additionalMetricsToRetain }}"
  - name: additionalMetricsToRetainV2
    value:
      - metric: "{{ metric }}"
        metricDimension:
          dimensionName: "{{ dimensionName }}"
          operator: "{{ operator }}"
        exportMetric: {{ exportMetric }}
  - name: tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: metricsExportConfig
    description: |
      Set configurations for metrics export.
    value:
      mqttTopic: "{{ mqttTopic }}"
      roleArn: "{{ roleArn }}"

UPDATE examples

attach_security_profile

Associates a Device Defender security profile with a thing group or this account. Each thing group or account can have up to five security profiles associated with it. Requires permission to access the AttachSecurityProfile action.

UPDATE aws.iot.security_profiles
SET 
-- No updatable properties
WHERE 
security_profile_name = '{{ security_profile_name }}' --required
AND securityProfileTargetArn = '{{ securityProfileTargetArn }}' --required
AND region = '{{ region }}' --required;

update_security_profile

Updates a Device Defender security profile. Requires permission to access the UpdateSecurityProfile action.

UPDATE aws.iot.security_profiles
SET 
securityProfileDescription = '{{ securityProfileDescription }}',
behaviors = '{{ behaviors }}',
alertTargets = '{{ alertTargets }}',
additionalMetricsToRetain = '{{ additionalMetricsToRetain }}',
additionalMetricsToRetainV2 = '{{ additionalMetricsToRetainV2 }}',
deleteBehaviors = {{ deleteBehaviors }},
deleteAlertTargets = {{ deleteAlertTargets }},
deleteAdditionalMetricsToRetain = {{ deleteAdditionalMetricsToRetain }},
metricsExportConfig = '{{ metricsExportConfig }}',
deleteMetricsExportConfig = {{ deleteMetricsExportConfig }}
WHERE 
security_profile_name = '{{ security_profile_name }}' --required
AND region = '{{ region }}' --required
AND expectedVersion = '{{ expectedVersion}}'
RETURNING
additional_metrics_to_retain,
additional_metrics_to_retain_v2,
alert_targets,
behaviors,
creation_date,
last_modified_date,
metrics_export_config,
security_profile_arn,
security_profile_description,
security_profile_name,
version;

DELETE examples

delete_security_profile

Deletes a Device Defender security profile. Requires permission to access the DeleteSecurityProfile action.

DELETE FROM aws.iot.security_profiles
WHERE security_profile_name = '{{ security_profile_name }}' --required
AND region = '{{ region }}' --required
AND expectedVersion = '{{ expectedVersion }}'
;

Lifecycle Methods

detach_security_profile

Disassociates a Device Defender security profile from a thing group or from this account. Requires permission to access the DetachSecurityProfile action.

EXEC aws.iot.security_profiles.detach_security_profile 
@security_profile_name='{{ security_profile_name }}' --required, 
@securityProfileTargetArn='{{ securityProfileTargetArn }}' --required, 
@region='{{ region }}' --required
;

validate_security_profile_behaviors

Validates a Device Defender security profile behaviors specification. Requires permission to access the ValidateSecurityProfileBehaviors action.

EXEC aws.iot.security_profiles.validate_security_profile_behaviors 
@region='{{ region }}' --required 
@@json=
'{
"behaviors": "{{ behaviors }}"
}'
;