AWS iot documentation change
Summary
Added documentation for retrieving socket-level connection details (IP/port/VPC endpoint) with new IAM permission controls, restructured examples, and introduced security-focused IAM condition keys for granular access control.
Security assessment
The changes introduce documentation for sensitive socket information (IP/port/VPC endpoints) and emphasize IAM controls via the new 'iot:IncludeSocketInformation' condition key. While this enables security monitoring of device connections, there's no evidence of addressing a specific vulnerability. The changes primarily document security features for controlling access to network-level data.
Diff
diff --git a/iot/latest/developerguide/device-connectivity-status.md b/iot/latest/developerguide/device-connectivity-status.md index 4fbbe4296..97f3a9fad 100644 --- a//iot/latest/developerguide/device-connectivity-status.md +++ b//iot/latest/developerguide/device-connectivity-status.md @@ -7 +7 @@ -How it worksFeaturesBenefitsPrerequisitesExamples +How it worksFeaturesBenefitsPrerequisitesExample @@ -28,0 +29,8 @@ With device connectivity query support, you can: + 3. Session information including the keep-alive duration + + 4. Socket level session information including IP address, port, and VPC endpoint ID. This information is available only when the following conditions are met: + + 1. You enable this option in fleet indexing configuration settings. + + 2. You have the corresponding permission in the IAM policy when invoking the API. + @@ -34 +42 @@ With device connectivity query support, you can: -Fleet indexing indexes the connectivity status for a device whose connection `clientId` is the same as the `thingName` of a registered thing in [Registry.](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) +Fleet indexing indexes the connectivity status for a device whose connection `clientId` is the same as the `thingName` of a registered thing in [Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html). @@ -59 +67 @@ To use device connectivity query support: - 3. [Enable Fleet Indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) with Connectivity indexing + 3. [Enable Fleet Indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) with Connectivity indexing. Optional: Opt-in to receive socket level information by enabling the `includeSocketInformation` option. @@ -66 +74 @@ To use device connectivity query support: -No additional setup is required if you already have connectivity indexing enabled +No additional setup is required if you already have connectivity indexing enabled. @@ -70 +78,4 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// -## Examples +## Example + +**CLI Command:** + @@ -71,0 +83 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + aws iot get-thing-connectivity-data --include-socket-information --thing-name myThingName @@ -73 +85 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - aws iot get-thing-connectivity-data --thing-name myThingName +**Response:** @@ -76,0 +89 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + "thingName": "myThingName", @@ -77,0 +91 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + "timestamp": "2024-12-19T10:00:00.000000-08:00", @@ -79,2 +93,8 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - "thingName": "myThingName", - "timestamp": "2024-12-19T10:00:00.000000-08:00" + "sourceIp": "192.0.2.1", + "sourcePort": 52123, + "targetIp": "198.51.100.1", + "targetPort": 8883, + "vpcEndpointId": "vpce-1234567890abcdef0", + "keepAliveDuration": 60, + "cleanSession": true, + "clientId": "myThingName" @@ -83 +103 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `thingName`: The name of the device as indicated by the request. This also matches the clientId used to connect to AWS IoT Core. +**API Parameters** @@ -85 +105 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `disconnectReason`: Reason for disconnect. Will be NONE for a connected device. + * `thingName`: The name of the device registered in AWS IoT Registry. This must match the `clientId` used to connect to AWS IoT Core. @@ -87 +107 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `connected`: The boolean value true indicating this device is currently connected. + * `includeSocketInformation`: The `includeSocketInformation` parameter controls whether socket-level network information is included in the API response. When set to true, the response includes the following fields: `sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId`. When `includeSocketInformation` is not specified or set to false, these socket fields are excluded from the response. To restrict specific IAM users from accessing socket information you will need to specify this in their IAM policy by setting the `includeSocketInformation` condition key to be false @@ -89 +108,0 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `timestamp`: The timestamp representing the device’s most recent disconnect in milliseconds. @@ -92,0 +112 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// +**Response Fields** @@ -93,0 +114 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `thingName`: The name of the device registered in AWS IoT Registry. This must match the `clientId` used to connect to AWS IoT Core. @@ -95 +116 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - aws iot get-thing-connectivity-data --thing-name myThingName + * `connected`: The boolean value true indicating this device is currently connected. @@ -96,0 +118 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `disconnectReason`: Reason for disconnect. Will be `NONE` for a connected device and `UNKNOWN` for a device which has never been connected. For a disconnected device, this will indicate if the disconnection was client initiated, server initiated, due to authentication/authorization issues or due to network issues. For disconnect reason codes, see [LifeCycleEvents ](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html) @@ -98,6 +120 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - { - "connected": false, - "disconnectReason": "CLIENT_INITIATED_DISCONNECT", - "thingName": "myThingName", - "timestamp": "2024-12-19T10:30:00.000000-08:00" - } + * `timestamp`: The timestamp representing the device’s most recent connect or disconnect event. @@ -105 +122 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `thingName`: The name of the device as indicated by the request. This also matches the clientId used to connect to AWS IoT Core. + * `clientId`: The clientId of the MQTT client. @@ -107 +124 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `disconnectReason`: Reason for disconnect is CLIENT_INITIATED_DISCONNECT indicating the client indicated to AWS IoT Core that it would disconnect. + * `keepAliveDuration`: The keep-alive interval in seconds that the client specified when establishing the connection. This determines how frequently the client sends keep-alive messages to maintain the connection. @@ -109 +126 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `connected`: The boolean value false indicating this device is currently disconnected. + * `cleanSession`: Indicates whether the client is using a clean session. @@ -111 +128 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `timestamp`: The timestamp representing the device’s most recent disconnect in milliseconds. + * `sessionExpiry`: The persistent session expiry configuration the client specified when establishing the connection. This determines how long a session will remain active after the client disconnects. @@ -112,0 +130 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `sourceIp`: The IP address of the client that initiated the connection. Only returned if `includeSocketInformation` is set to be true and user is authorized to retrieve this information. @@ -113,0 +132 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `sourcePort`: The port number used by the client for the connection. Only returned if `includeSocketInformation` is set to be true and user is authorized to retrieve this information. @@ -114,0 +134 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `targetIp`: The IP address where the connection request was made to. Only returned if `includeSocketInformation` is set to be true and user is authorized to retrieve this information @@ -115,0 +136 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + * `targetPort`: The port number of the AWS IoT Core endpoint that the client connected to. Only returned if `includeSocketInformation` is set to be true and user is authorized to retrieve this information. @@ -117 +138 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - aws iot get-thing-connectivity-data --thing-name neverConnectedThing + * `vpcEndpointId`: The ID of the VPC endpoint that the client connected through, if applicable. Only returned if `includeSocketInformation` is set to be true and user is authorized to retrieve this information. @@ -120,5 +140,0 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - { - "connected": false, - "disconnectReason": "UNKNOWN", - "thingName": "neverConnectedThing" - } @@ -126 +141,0 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `thingName`: The name of the device as indicated by the request. This also matches the clientId used to connect to AWS IoT Core. @@ -128 +143,5 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `disconnectReason`: Reason for disconnect. Will be “UNKNOWN” for a device which has never been connected or for which Fleet Indexing does not have the last disconnect reason stored. +**Required Permissions** + +To use the GetThingConnectivityData API, you need the following IAM permission + +`iot:GetThingConnectivityData` @@ -130 +149 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `connected`: The boolean value false indicating this device is currently disconnected. +You can scope this permission to specific things using resource based policies. Use the `iot:IncludeSocketInformation` condition to implement granular access control on socket information. The policy example below demonstrates a scenario where you deny the user access to socket information. Please note that this example works when it is the sole policy granting access to the action GetThingConnectivityData. @@ -132 +151 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// - * `timestamp`: The timestamp is not returned for a device which has never been connected or for which Fleet Indexing does not have the last timestamp stored. +**Authorization Policy Examples** @@ -134,0 +154,14 @@ For detailed setup instructions, refer to the [AWS IoT Developer Guide](https:// + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ "iot:GetThingConnectivityData" ], + "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*"], + "Condition": { + "Bool": { + "iot:IncludeSocketInformation": "false" + } + } + }] + } @@ -143 +176 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Manage thing group indexing +Managing thing group indexing