AWS IoT Device Defender - AWS IoT Greengrass
VersionsTypeOperating systemRequirementsDependenciesConfigurationInput dataOutput dataLocal log fileLicensesChangelog

AWS IoT Device Defender

The AWS IoT Device Defender component (aws.greengrass.DeviceDefender) notifies administrators about changes in the state of Greengrass core devices. This can help identify unusual behavior that might indicate a compromised device. For more information, see AWS IoT Device Defender in the AWS IoT Core Developer Guide.

This component reads system metrics on the core device. Then, it publishes the metrics to AWS IoT Device Defender. For more information about how to read and interpret the metrics that this component reports, see Device metrics document specification in the AWS IoT Core Developer Guide.

Note

This component provides similar functionality to the Device Defender connector in AWS IoT Greengrass V1. For more information, see Device Defender connector in the AWS IoT Greengrass V1 Developer Guide.

Versions

This component has the following versions:

  • 3.1.x

  • 3.0.x

  • 2.0.x

For information about changes in each version of the component, see the changelog.

Type

v3.x

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

v2.x

This component is a Lambda component (aws.greengrass.lambda). The Greengrass nucleus runs this component's Lambda function using the Lambda launcher component.

For more information, see Component types.

Operating system

v3.x

This component can be installed on core devices that run the following operating systems:

  • Linux

  • Windows

v2.x

This component can be installed on Linux core devices only.

Requirements

This component has the following requirements:

v3.x

  • Python version 3.7 installed on the core device and added to the PATH environment variable.

  • AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more information, see Detect in the AWS IoT Core Developer Guide.

v2.x

  • Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see Lambda function requirements.

  • Python version 3.7 installed on the core device and added to the PATH environment variable.

  • AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more information, see Detect in the AWS IoT Core Developer Guide.

  • The psutil library installed on the core device. Version 5.7.0 is the latest version that is verified to work with the component.

  • The cbor library installed on the core device. Version 1.0.0 is the latest version that is verified to work with the component.

  • To receive output data from this component, you must merge the following configuration update for the legacy subscription router component (aws.greengrass.LegacySubscriptionRouter) when you deploy this component. This configuration specifies the topic where this component publishes responses.

    Legacy subscription router v2.1.xLegacy subscription router v2.0.x
    Legacy subscription router v2.1.x
    {
  "subscriptions": {
    "aws-greengrass-device-defender": {
      "id": "aws-greengrass-device-defender",
      "source": "component:aws.greengrass.DeviceDefender",
      "subject": "$aws/things/+/defender/metrics/json",
      "target": "cloud"
    }
  }
}
    Legacy subscription router v2.0.x
    {
  "subscriptions": {
    "aws-greengrass-device-defender": {
      "id": "aws-greengrass-device-defender",
      "source": "arn:aws:lambda:region:aws:function:aws-greengrass-device-defender:version",
      "subject": "$aws/things/+/defender/metrics/json",
      "target": "cloud"
    }
  }
}

    • Replace region with the AWS Region that you use.

    • Replace version with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the AWS IoT Greengrass console, and look for the Lambda function key-value pair. This key-value pair contains the name and version of the Lambda function.

    Important

    You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

    For more information, see Create deployments.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

3.1.1

The following table lists the dependencies for version 3.1.1 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <3.0.0 Soft
Token exchange service >=0.0.0 Hard
3.0.0 - 3.0.2

The following table lists the dependencies for versions 3.0.0 to 3.0.2 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <3.0.0 Soft
Token exchange service >=0.0.0 Hard
2.0.10 and 2.0.11

The following table lists the dependencies for version 2.0.10 and 2.0.11 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.8.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.9

The following table lists the dependencies for version 2.0.9 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.7.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.8

The following table lists the dependencies for version 2.0.8 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.6.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.7

The following table lists the dependencies for version 2.0.7 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.5.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.6

The following table lists the dependencies for version 2.0.6 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.4.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.5

The following table lists the dependencies for version 2.0.5 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.3.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.4

The following table lists the dependencies for version 2.0.4 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.2.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.3

The following table lists the dependencies for version 2.0.3 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.3 <2.1.0 Hard
Lambda launcher >=1.0.0 Hard
Lambda runtimes >=1.0.0 Soft
Token exchange service >=1.0.0 Hard

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

v3.x
PublishRetryCount

The amount of times the publish will be retried. This feature is available in version 3.1.1.

The minimum is 0.

The maximum is 72.

Default: 5

SampleIntervalSeconds

(Optional) The amount of time in seconds between each cycle where the component gathers and reports metrics.

The minimum value is 300 seconds (5 minutes).

Default: 300 seconds

UseInstaller

(Optional) Boolean value that defines whether to use the installer script in this component to install this component's dependencies.

Set this value to false if you want to use a custom script to install dependencies, or if you want to include runtime dependencies in a pre-built Linux image. To use this component, you must install the following libraries, including any dependencies, and make them available to the default Greengrass system user.

  • AWS IoT Device SDK v2 for Python

  • cbor library. Version 1.0.0 is the latest version that is verified to work with the component.

  • psutil library. Version 5.7.0 is the latest version that is verified to work with the component.

Note

If you use version 3.0.0 or 3.0.1 of this component on core devices that you configure to use an HTTPS proxy, you must set this value to false. The installer script doesn't support operation behind an HTTPS proxy in these versions of this component.

Default: true

v2.x
Note

This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

lambdaParams

An object that contains the parameters for this component's Lambda function. This object contains the following information:

EnvironmentVariables

An object that contains the Lambda function's parameters. This object contains the following information:

PROCFS_PATH

(Optional) The path to the /proc folder.

  • To run this component in a container, use the default value, /host-proc. The component runs in a container by default.

  • To run this component in no container mode, specify /proc for this parameter.

Default: /host-proc. This is the default path where this component mounts the /proc folder in the container.

Note

This component has read-only access to this folder.

SAMPLE_INTERVAL_SECONDS

(Optional) The amount of time in seconds between each cycle where the component gathers and reports metrics.

The minimum value is 300 seconds (5 minutes).

Default: 300 seconds

containerMode

(Optional) The containerization mode for this component. Choose from the following options:

  • GreengrassContainer – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.

  • NoContainer – The component doesn't run in an isolated runtime environment.

    If you specify this option, you must specify /proc for the PROCFS_PATH environment variable parameter.

Default: GreengrassContainer

containerParams

(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify GreengrassContainer for containerMode.

This object contains the following information:

memorySize

(Optional) The amount of memory (in kilobytes) to allocate to the component.

Defaults to 50,000 KB.

pubsubTopics

(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.

This object contains the following information:

0 – This is an array index as a string.

An object that contains the following information:

type

(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:

  • PUB_SUB – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see Publish/subscribe local messages.

  • IOT_CORE – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see Publish/subscribe AWS IoT Core MQTT messages.

Default: PUB_SUB

topic

(Optional) The topic to which the component subscribes to receive messages. If you specify IotCore for type, you can use MQTT wildcards (+ and #) in this topic.

Example: Configuration merge update (container mode)
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "PROCFS_PATH": "/host_proc"
    }
  },
  "containerMode": "GreengrassContainer"
}
Example: Configuration merge update (no container mode)
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "PROCFS_PATH": "/proc"
    }
  },
  "containerMode": "NoContainer"
}

Input data

This component doesn't accept messages as input data.

Output data

This component publishes security metrics to the following reserved topic for AWS IoT Device Defender. This component replaces coreDeviceName with the name of the core device when it publishes the metrics.

Topic (AWS IoT Core MQTT): $aws/things/coreDeviceName/defender/metrics/json

Example output
{
  "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
      }
    }
  }
}

For more information about the metrics that this component reports, see Device metrics document specification in the AWS IoT Core Developer Guide.

Local log file

This component uses the following log file.

Linux
/greengrass/v2/logs/aws.greengrass.DeviceDefender.log
Windows
C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log
To view this component's logs

  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.

    Linux
    sudo tail -f /greengrass/v2/logs/aws.greengrass.DeviceDefender.log
    Windows (PowerShell)
    Get-Content C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log -Tail 10 -Wait

Licenses

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

Changelog

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

v3.x

Version

Changes

3.1.1
Bug fixes and improvements

  • Adds retries for client connection when the connection fails to recover after a network outage.

  • Adds a configurable retry for publishing metrics.

3.1.0
Bug fixes and improvements

3.0.1

Fixes an issue with how the component calculates delta values for metrics.

3.0.0
Warning

This version is no longer available. The improvements in this version are available in later versions of this component.

Initial version.
v2.x

Version

Changes

2.0.11

Version updated for Greengrass nucleus version 2.11.0 release.

2.0.10

Version updated for Greengrass nucleus version 2.7.0 release.

2.0.9

Version updated for Greengrass nucleus version 2.6.0 release.

2.0.8

Version updated for Greengrass nucleus version 2.5.0 release.

2.0.7

Version updated for Greengrass nucleus version 2.4.0 release.

2.0.6

Version updated for Greengrass nucleus version 2.3.0 release.

2.0.5

Version updated for Greengrass nucleus version 2.2.0 release.

2.0.4

Version updated for Greengrass nucleus version 2.1.0 release.

2.0.3

Initial version.