Requirements Parameters Input data Output data Licenses Changelog See also

Device Defender connector

The Device Defender connector notifies administrators of changes in the state of a Greengrass core device. This can help identify unusual behavior that might indicate a compromised device.

This connector reads system metrics from the /proc directory on the core device, and then publishes the metrics to AWS IoT Device Defender. For metrics reporting details, see Device metrics document specification in the AWS IoT Developer Guide.

This connector has the following versions.

Version	ARN
3	`arn:aws:greengrass:region::/connectors/DeviceDefender/versions/3`
2	`arn:aws:greengrass:region::/connectors/DeviceDefender/versions/2`
1	`arn:aws:greengrass:region::/connectors/DeviceDefender/versions/1`

For information about version changes, see the Changelog.

Requirements

This connector has the following requirements:

Version 3

AWS IoT Greengrass Core software v1.9.3 or later.
Python version 3.7 or 3.8 installed on the core device and added to the PATH environment variable.
Note
To use Python 3.8, run the following command to create a symbolic link from the the default Python 3.7 installation folder to the installed Python 3.8 binaries.
```
sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7
```
This configures your device to meet the Python requirement for AWS IoT Greengrass.
AWS IoT Device Defender configured to use the Detect feature to keep track of violations. For more information, see Detect in the AWS IoT Developer Guide.
A local volume resource in the Greengrass group that points to the /proc directory. The resource must use the following properties:
- Source path: /proc
- Destination path: /host_proc (or a value that matches the valid pattern)
- AutoAddGroupOwner: true
The psutil library installed on the Greengrass core. Version 5.7.0 is the latest version that is verified to work with the connector.
The cbor library installed on the Greengrass core. Version 1.0.0 is the latest version that is verified to work with the connector.

Versions 1 - 2

AWS IoT Greengrass Core software v1.7 or later.
Python version 2.7 installed on the core device and added to the PATH environment variable.
AWS IoT Device Defender configured to use the Detect feature to keep track of violations. For more information, see Detect in the AWS IoT Developer Guide.
A local volume resource in the Greengrass group that points to the /proc directory. The resource must use the following properties:
- Source path: /proc
- Destination path: /host_proc (or a value that matches the valid pattern)
- AutoAddGroupOwner: true
The psutil library installed on the Greengrass core.
The cbor library installed on the Greengrass core.

Connector Parameters

This connector provides the following parameters:

SampleIntervalSeconds

The number of seconds between each cycle of gathering and reporting metrics. The minimum value is 300 seconds (5 minutes).

Display name in the AWS IoT console: Metrics reporting interval

Required: true

Type: string

Valid pattern: ^[0-9]*(?:3[0-9][0-9]|[4-9][0-9]{2}|[1-9][0-9]{3,})$

ProcDestinationPath-ResourceId

The ID of the /proc volume resource.

Note

This connector is granted read-only access to the resource.

Display name in the AWS IoT console: Resource for /proc directory

Required: true

Type: string

Valid pattern: [a-zA-Z0-9_-]+

ProcDestinationPath

The destination path of the /proc volume resource.

Display name in the AWS IoT console: Destination path of /proc resource

Required: true

Type: string

Valid pattern: \/[a-zA-Z0-9_-]+

Create Connector Example (AWS CLI)

The following CLI command creates a ConnectorDefinition with an initial version that contains the Device Defender connector.


aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyDeviceDefenderConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/DeviceDefender/versions/3",
            "Parameters": {
                "SampleIntervalSeconds": "600",
                "ProcDestinationPath": "/host_proc",
                "ProcDestinationPath-ResourceId": "my-proc-resource"
            }
        }
    ]
}'

Note

The Lambda function in this connector has a long-lived lifecycle.

In the AWS IoT Greengrass console, you can add a connector from the group's Connectors page. For more information, see Getting started with Greengrass connectors (console).

Input data

This connector doesn't accept MQTT messages as input data.

Output data

This connector publishes security metrics to AWS IoT Device Defender as output data.

Topic filter in subscription

$aws/things/+/defender/metrics/json

Note

This is the topic syntax that AWS IoT Device Defender expects. The connector replaces the + wildcard with the device name (for example, $aws/things/thing-name/defender/metrics/json).

Example output

For metrics reporting details, see Device metrics document specification in the AWS IoT Developer Guide.


{
    "header": {
        "report_id": 1529963534,
        "version": "1.0"
    },
    "metrics": {
        "listening_tcp_ports": {
            "ports": [
                {
                    "interface": "eth0",
                    "port": 24800
                },
                {
                    "interface": "eth0",
                    "port": 22
                },
                {
                    "interface": "eth0",
                    "port": 53
                }
            ],
            "total": 3
        },
        "listening_udp_ports": {
            "ports": [
                {
                    "interface": "eth0",
                    "port": 5353
                },
                {
                    "interface": "eth0",
                    "port": 67
                }
            ],
            "total": 2
        },
        "network_stats": {
            "bytes_in": 1157864729406,
            "bytes_out": 1170821865,
            "packets_in": 693092175031,
            "packets_out": 738917180
        },
        "tcp_connections": {
            "established_connections":{
                "connections": [
                    {
                    "local_interface": "eth0",
                    "local_port": 80,
                    "remote_addr": "192.168.0.1:8000"
                    },
                    {
                    "local_interface": "eth0",
                    "local_port": 80,
                    "remote_addr": "192.168.0.1:8000"
                    }
                ],
                "total": 2
            }
        }
    }
}

Licenses

This connector is released under the Greengrass Core Software License Agreement.

Changelog

The following table describes the changes in each version of the connector.

Version	Changes
3	Upgraded the Lambda runtime to Python 3.7, which changes the runtime requirement.
2	Fix to reduce excessive logging.
1	Initial release.

A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.