Introducing Coto

This post was originally published by me on www.sentialabs.io, it has been slightly adapted to better fit my personal site.

Almost any AWS service can be fully controlled using the AWS API, for this we strongly recommend the use of boto3. The problem is, that there exist some administrative tasks for which there is no public API, and there exist some AWS tasks that still require the AWS Account Root User.

For example when creating a new account in an AWS Organization, there are some things that you are unable to do using the documented APIs, such as:

• set tax registration information (no documented API)
• set additional contacts (no documented API)
• reset AWS Account Root User password (no documented API)
• setup MFA for the AWS Account Root User (requires root user)

To help you solve these tasks, we introduce coto!

coto: An AWS Management Console Client

Coto is a Python library that implements a client for some of the REST APIs that power the AWS Management Console. AWS will be changing these APIs without any upfront warning! As a result of this, coto can break at any moment.

As a result of this, coto can break at any moment.

Since an example piece of code tells more than a thousand words, we show as an example how to use coto to set tax registration.

Example: Set Tax Registration

import coto
from coto.captcha.iterm_solver import iTermSolver
from coto.metadata1.static_generator import StaticGenerator

captcha_solver = iTermSolver()
metadata1_generator = StaticGenerator("XXXXXXXXX")

session = coto.Session(
    email='email@example.com',
    password='s3cur3 p4ssw0rd!',
    mfa_secret='MFAxSECRETxSEEDxXXXXXXXXXXXXXXXXXX',
    metadata1_generator=metadata1_generator,
    captcha_solver=captcha_solver,
)

billing = session.client('billing')
billing.set_tax_registration(
    TaxRegistration={
        'address': {
            'addressLine1': 'Adresweg 1',
            'addressLine2': None,
            'city': 'Delft',
            'countryCode': 'NL',
            'postalCode': '2600 AA',
            'state': 'Zuid-Holland',
        },
        'authority': {'country': 'NL', 'state': None},
        'legalName': 'Besloten Venootschap B.V.',
        'localTaxRegistration': False,
        'registrationId': 'NL000000000B01',
    }
)

What are those iTermSolver and StaticGenerator things?

AWS wants to make sure that only humans login to the AWS Management Console using passwords. Our scripts are, well, not entirely human. AWS uses two methods to identify the user as a human:

• metadata1, a scrambled JSON document that containt information about your browser, the number of clicks, key presses, copies, and pastes, generated by a piece of Javascript spyware
• CAPTCHAs, they throw them at you like candy, but if you pass “correct” metadata1 you will be prompted a lot less!

We have created a plugin system so that you can implement a generator for metadata1 and a solver for CAPTCHAs yourself. The two provided example plugins allow you to:

• provide a static value for the metadata1 (do a manual login and get the value from debugging the network traffic)
• be prompted to enter the captcha in the iTerm2 terminal emulator (see screenshot)
  

Your help is appreciated!

We would greatly value your input.

• You could implement a captcha solver that posts the captcha image in a Slack channel and have your colleagues solve it for karma points. (And, of course, take karama when they solved incorrectly 😱)
• A better metadata1 generator would be awesome, although AWS might frown upon the publication of such a thing…
• The AWS Single Sign-On service is still lacking a public API, shame on AWS, a coto client for this could be really helpful!