AWS iot high security documentation change
Summary
Added support for including socket information (source/target IP/port, VPC endpoint ID) in GetThingConnectivityData responses. Updated connectivity indexing configuration, added IAM policy requirements for socket information access, expanded connectivity data fields in examples, and clarified device registration requirements.
Security assessment
The change explicitly documents security-sensitive socket information exposure and adds mandatory IAM policy requirements (iot:IncludeSocketInformation condition key) to control access to this data. This directly addresses potential information disclosure risks by providing explicit security controls.
Diff
diff --git a/iot/latest/developerguide/managing-index.md b/iot/latest/developerguide/managing-index.md index 1b407a00b..b97477c40 100644 --- a//iot/latest/developerguide/managing-index.md +++ b//iot/latest/developerguide/managing-index.md @@ -9 +9 @@ Enabling thing indexingDescribing a thing indexQuerying a thing indexRestriction -# Manage thing indexing +# Managing thing indexing @@ -60,0 +61,4 @@ The `--thing-indexing-configuration` parameter takes a string with the following + ], + "connectivity": { + "includeSocketInformation": [ + "GET_THING_CONNECTIVITY_DATA" @@ -63,0 +68 @@ The `--thing-indexing-configuration` parameter takes a string with the following + } @@ -74 +79 @@ You can specify different thing indexing modes in your indexing configuration, d - * `thingConnectivityIndexingMode`: Specifies if thing connectivity data is indexed. + * `thingConnectivityIndexingMode`: Specifies if thing connectivity data is indexed. This needs to be enabled to get connectivity status information in [ SearchIndex queries](https://docs.aws.amazon.com//iot/latest/developerguide/managing-index.html#search-index) or to use the GetThingConnectivityData API. The [ GetThingConnectivityData](https://docs.aws.amazon.com//iot/latest/developerguide/device-connectivity-status.html) API response will also include socket information if this is enabled in the [ filter](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) and the `includeSocketInformation` flag is `true` in the GetThingConnectivityData API request. @@ -115 +120 @@ You can aggregate attributes, Device Shadow data, and Device Defender violations -Indexing filter provides additional selections for named shadows and geolocation data. +Indexing filter provides additional selections for named shadows, geolocation, and connectivity data. @@ -165 +170,34 @@ The example filter below specifies a geoLocation object in a named shadow (`name -For more information, see [ IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html) from _AWS IoT_ _API Reference_. +`**connectivity**` + + * To include socket information (source IP address, target IP address, source port, target port, and VPC endpoint ID) in the `GetThingConnectivityData` response, use the `includeSocketInformation` option within the connectivity filter as shown in the following example. You must also set the `includeSocketInformation` parameter to `true` when invoking the `GetThingConnectivityData` API. To restrict specific callers from accessing socket information, you must explicitly specify this in their IAM policy by setting the `iot:IncludeSocketInformation` condition context key to `false`. + +###### Note + +The option to include socket information is only supported for the `GetThingConnectivityData` response and not for `SearchIndex` or other fleet indexing APIs. + + "filter": { + "connectivity": { + "includeSocketInformation": [ + "GET_THING_CONNECTIVITY_DATA" + ] + } + } + +To disable socket information indexing, you must set `includeSocketInformation` in the connectivity filter to an empty array as shown in the example below. + +###### Note + +In an `UpdateIndexingConfiguration` request, if connectivity indexing is enabled and a connectivity filter is not configured or `includeSocketInformation` is not specified or null, the previous value of the connectivity filter is preserved while updating the indexing configuration. + +Example to disable socket information indexing + + "filter": { + "connectivity": { + "includeSocketInformation": [ ] + } + } + + + + +For more information, see [ IndexingFilter](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) from _AWS IoT_ _API Reference_. @@ -176 +214,2 @@ Short syntax: - namedShadowIndexingMode=ON,filter={namedShadowNames=[thing1shadow]}, thingConnectivityIndexingMode=STATUS, + namedShadowIndexingMode=ON,thingConnectivityIndexingMode=STATUS, + filter={namedShadowNames=[namedShadow1],geoLocations=[{name=shadow.name.namedShadow1.reported.location,order=LonLat}],connectivity={includeSocketInformation=[GET_THING_CONNECTIVITY_DATA]}}, @@ -178 +217 @@ Short syntax: - {name=shadow.name.thing1shadow.desired.DefaultDesired, type=String}, {name=shadow.desired.power, type=Boolean}, + {name=shadow.name.namedShadow1.desired.DefaultDesired, type=String}, {name=shadow.desired.power, type=Boolean}, @@ -189 +228 @@ JSON syntax: - "filter": { "namedShadowNames": ["thing1shadow"]}, + "filter": { "namedShadowNames": ["namedShadow1"], "geoLocations": [{"name": "shadow.name.namedShadow1.reported.location", "order": "LonLat"}], "connectivity": {"includeSocketInformation": ["GET_THING_CONNECTIVITY_DATA"]}}, @@ -192,2 +231,2 @@ JSON syntax: - {"name": "shadow.name.thing1shadow.desired.DefaultDesired", "type": "String"}, - {"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": Number} ] } }' + {"name": "shadow.name.namedShadow1.desired.DefaultDesired", "type": "String"}, + {"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": "Number"} ] } }' @@ -197 +236 @@ This command doesn't produce any output. -To check the thing index status, run the `describe-index` CLI command: +To check the thing index status, run the **describe-index** CLI command: @@ -202 +241 @@ To check the thing index status, run the `describe-index` CLI command: -The output of the `describe-index` command looks like the following: +The output of the **describe-index** command looks like the following: @@ -215 +254 @@ It can take a moment for fleet indexing to update the fleet index. We recommend -To get your thing indexing configuration details, run the `get-indexing-configuration` CLI command: +To get your thing indexing configuration details, run the **get-indexing-configuration** CLI command: @@ -220 +259 @@ To get your thing indexing configuration details, run the `get-indexing-configur -The output of the `get-indexing-configuration` command looks like the following: +The output of the **get-indexing-configuration** command looks like the following: @@ -231,2 +270,2 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "connectivity.disconnectReason", - "type": "String" + "name": "connectivity.keepAliveDuration", + "type": "Number" @@ -235 +274 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "registry.version", + "name": "connectivity.version", @@ -239 +278 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "thingName", + "name": "deviceDefender.*.*.metricName", @@ -243 +282,5 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "deviceDefender.violationCount", + "name": "connectivity.connected", + "type": "Boolean" + }, + { + "name": "shadow.version", @@ -247 +290,5 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "shadow.hasDelta", + "name": "deviceDefender.*.*.lastViolationTime", + "type": "Number" + }, + { + "name": "deviceDefender.*.*.inViolation", @@ -249,0 +297,8 @@ The output of the `get-indexing-configuration` command looks like the following: + { + "name": "thingName", + "type": "String" + }, + { + "name": "deviceDefender.version", + "type": "Number" + }, @@ -255 +310 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "shadow.version", + "name": "registry.version", @@ -259 +314 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "connectivity.version", + "name": "connectivity.sessionExpiry", @@ -263 +318,5 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "connectivity.timestamp", + "name": "registry.thingTypeName", + "type": "String" + }, + { + "name": "deviceDefender.violationCount", @@ -267,2 +326,2 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "shadow.name.*.hasDelta", - "type": "Boolean" + "name": "connectivity.timestamp", + "type": "Number" @@ -271 +330 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "registry.thingTypeName", + "name": "connectivity.clientId", @@ -279 +338 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "connectivity.connected", + "name": "shadow.name.*.hasDelta", @@ -284,0 +344,12 @@ The output of the `get-indexing-configuration` command looks like the following: + }, + { + "name": "shadow.hasDelta", + "type": "Boolean" + }, + { + "name": "connectivity.cleanSession", + "type": "Boolean" + }, + { + "name": "connectivity.disconnectReason", + "type": "String" @@ -289,6 +360 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "shadow.name.thing1shadow.desired.DefaultDesired", - "type": "String" - }, - - { - "name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", + "name": "attributes.version", @@ -302 +368,5 @@ The output of the `get-indexing-configuration` command looks like the following: - "name": "attributes.version", + "name": "shadow.name.namedShadow1.desired.DefaultDesired", + "type": "String" + }, + { + "name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", @@ -308 +378,11 @@ The output of the `get-indexing-configuration` command looks like the following: - "thing1shadow" + "namedShadow1" + ], + "geoLocations": [ + { + "name": "shadow.name.namedShadow1.reported.location", + "order": "LonLat" + } + ], + "connectivity": { + "includeSocketInformation": [ + "GET_THING_CONNECTIVITY_DATA" @@ -310,0 +391 @@ The output of the `get-indexing-configuration` command looks like the following: + } @@ -317 +398 @@ The output of the `get-indexing-configuration` command looks like the following: -To update the custom fields, you can run the `update-indexing-configuration` command. An example is as follows: +To update the custom fields, you can run the **update-indexing-configuration** command. An example is as follows: @@ -374 +455,2 @@ Use the **search-index** CLI command to query data in the index. - "things":[{ + "things": [ + { @@ -376,3 +458 @@ Use the **search-index** CLI command to query data in the index. - "thingGroupNames":[ - "mygroup1" - ], + "thingGroupNames": ["mygroup1"], @@ -386 +466,5 @@ Use the **search-index** CLI command to query data in the index. - "disconnectReason": "CONNECTION_LOST" + "disconnectReason": "CONNECTION_LOST", + "clientId": "mything1",