connectivity-test

contest

Assesses the connectivity between a host, Internet, and AWS services.

Current version: 1.0.9

Lead Maintainer: Halim Qarroum

Table of contents

• Installation
• Features
• Metrics
• Description
• Usage
• Supported Services
• See also

Install

npm install --global @aws-blocks/contest

Features

• Checks for Internet availability on the current host.
• Detects potential captive portals blocking access to the Internet network.
• Assess the connectivity and the access to different AWS service APIs and to the AWS IoT Core message broker.
• Corporate proxy support for HTTPS and MQTTS connections.
• Integrated with Speedtest to measure the current Internet throughput.

Metrics

The below metrics displays approximate values associated with deploying and using this block.

Metric	Value
Type	Tool
Installation Time	Less than 1 minute
Requirements	aws-cli, npm
Audience	Any individual using AWS services

Description

The contest (or connectivity-tester) command-line tool is a Node.js application that creates a connectivity and access report of the local host to remote AWS services. It comes in handy if you are connected to an unfamiliar network you do not control, and want to assess the connectivity options you have to the Internet and AWS services as well. This tool also supports the use of corporate proxy servers to gain access to AWS services or the IoT Core MQTT service as well.

It also implements a captive portal detection which are common on public networks.

Usage

Once the contest package has been installed, you can run it using the following command in your terminal :

contest

This will start the test plan associated with the different network connectivity tests which contest has been developed to assess.

Note that the MQTT test will fail since you did not yet configured contest to take AWS IoT certificates into consideration (see the Configuring MQTT access section).

Provisionning AWS credentials

If you happen to have the aws-cli installed and configured with valid credentials on your local machine, contest will use these credentials to authenticate against the AWS services it is assessing the connectivity to.

If you do not have the aws-cli installed or configured, you can pass your AWS_ACCESS_KEY_ID and your AWS_SECRET_ACCESS_KEY as environment variables of contest such as in the following example :

$ AWS_ACCESS_KEY_ID=<access-key-id> AWS_SECRET_ACCESS_KEY=<secret-access-key> contest

Configuring MQTT access

In order to allow contest to test an MQTT connection to the AWS IoT Core message broker, you need to generate a valid device certificate chain using the AWS Console. As such, you need to have the following files at your disposal for the MQTT test to succeed :

• The device certificate (.cert.pem extension).
• The device private key (.key extension).
• The AWS Root CA .pem file.

Make sure that you associate to your certificate(s) the rights to iot:Connect to the MQTT broker, iot:Receive and iot:Publish on the connectivity/tester topic.

Once you have downloaded these files on your filesystem, you need to ensure that you know the AWS IoT endpoint (ATS) associated with your account and desired region.

To do so, you can run the following command which will invoke the aws-cli and retrive your ATS AWS IoT endpoint :

aws iot describe-endpoint --endpoint-type iot:Data-ATS

To retrieve your AWS IoT endpoint, you can also open the AWS IoT console in your browser, and click on the Settings option on the bottom left-hand corner of the side-menu.

At this point, you have all the elements to provide contest with all the information required to establish a connection to AWS IoT. To pass all these information to the command-line tool, you can use the following example :

contest \
  --aws:iot:keyPath=path/to/private.key \
  --aws:iot:certPath=path/to/certificate.pem \
  --aws:iot:caPath=path/to/root-ca.pem \
  --aws:iot:host=aws-iot-endpoint

Connecting to AWS IoT Core using ALPN extensions

AWS has recently announced support for the ALPN TLS extension on its IoT service which allows MQTT clients to connect to the AWS IoT Core message broker on the 443 instead of the standard 8883 port.

The contest command-line tool activates automatically these ALPN extensions if you specify the port 443 in the command line options :

contest \
  --aws:iot:keyPath=path/to/private.key \
  --aws:iot:certPath=path/to/certificate.pem \
  --aws:iot:caPath=path/to/root-ca.pem \
  --aws:iot:host=aws-iot-endpoint \
  --aws:iot:port=443

Update the AWS region

When contest assess the connectivity against AWS services, it will use by default the us-east-1 region. If you wish to change the region, you can pass the following option on the command-line tool :

contest --aws:global:region=us-east-2

Note that all AWS services are not available in every regions tested by contest, in this case a meaningful error will be raised on that particular service during the tests if it is not implemented in the region you have selected.

Using Proxy servers

This tool supports both http, https and socks proxy servers to tunnel HTTP and HTTPS connections to AWS APIs and MQTTS connections to the AWS IoT Core service and assess the connectivity of your hosts to the public Internet.

Using HTTP(S) Proxies

When specifying an HTTP proxy, the AWS SDK as well as the AWS IoT SDK (using MQTTS) will tunnel connections through the HTTP proxy. Specify an HTTP proxy using the standard HTTP_PROXY environment variable, and a proxy accepting TLS connections using the standard HTTPS_PROXY environment variable.

HTTP_PROXY=http://http-proxy.domain.name:8080/ \
HTTPS_PROXY=http://https-proxy.domain.name:8080/ \
contest

To tunnel MQTTS, the used HTTP proxy must allow TLS connection encapsulation using the CONNECT method.

_{Contest to proxy request flow.}

Specifying proxy authentication

If a proxy server requires a username/password authentication in order to access to the Internet network, you can pass the username and the password in the URL that you specify in the HTTP_PROXY and HTTPS_PROXY parameters.

HTTP_PROXY=http://username:[e-mail]:8080/ \
HTTPS_PROXY=http://username:[e-mail]:8080/ \
contest

Using SOCKS Proxies

You can specify a Socks 4 and 5 proxy, and contest will tunnel HTTPS and MQTTS connections through it. You can specify a Socks proxy using the standard HTTP_PROXY environment variable.

HTTP_PROXY=socks://socks-proxy.domain.name:8080/ contest

You can use the socks, socks4, socks4a, socks5 and socks5h protocols when specifying a Socks proxy URI.

Traversing proxies with MQTTS

When an MQTTS connection is established to AWS IoT Core during the tests, the default port used is the port 8883. However, most HTTPS proxies will by default refuse connections to destinations which are not using the standard HTTP (80) and HTTPS (443) ports by issuing a 403 return code.

To address this issue, you can specify the port 443 as the MQTTS port to connect to AWS IoT Core as demonstrated in the Connecting to AWS IoT Core using ALPN extensions.

Dismiss failed calls

When using contest using credentials which are bound to specific permissions, the output can become full of errors for each AWS service for which contest does not currently have access to using the current AWS credentials. To alleviate this issue, you can use the --aws:dismiss-failed-calls to mask the calls to AWS services which have failed and only display the ones that have succeeded.

contest --aws:dismiss-failed-calls

Supported Services

Below you will find a list of all the AWS Services which are supported, along with their associated protocol and proxy support status. Click the below menu to unfold the list.

AWS Service	Protocol	Proxy Support
API Gateway	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS AppSync	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS IoT Core	HTTPS - MQTTS	Yes (HTTPS, Socks 4 & 5)
AWS IoT Analytics	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Greengrass	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS DynamoDB	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Neptune	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS EMR	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS ECS	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS CloudWatch	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS CloudWatch Logs	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS EC2	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS IAM	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Kinesis	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Kinesis Firehose	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Kinesis Video Stream	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS SQS	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Cognito Identity	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS ElastiCache	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS ElasticSearch	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS SageMaker	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Athena	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Redshift	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS SSM	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS SNS	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS S3	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS MSK	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS MQ	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS OpsWorks	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS RDS	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Cloud9	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS CloudFront	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS CloudTrail	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Comprehend	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS EKS	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)
AWS Lambda	HTTPS	Yes (HTTP, HTTPS, Socks 4 & 5)

See also

• The aws-cli command-line tool.