Welcome to controltowerlib’s documentation!¶

Contents:

controltowerlib¶

A library to provide access to AWS service catalog provided by Control Tower and basic functionality with interfacing with it.

Documentation: https://controltowerlib.readthedocs.org/en/latest

Development Workflow¶

The workflow supports the following steps

lint

test

build

document

upload

graph

These actions are supported out of the box by the corresponding scripts under _CI/scripts directory with sane defaults based on best practices. Sourcing setup_aliases.ps1 for windows powershell or setup_aliases.sh in bash on Mac or Linux will provide with handy aliases for the shell of all those commands prepended with an underscore.

The bootstrap script creates a .venv directory inside the project directory hosting the virtual environment. It uses pipenv for that. It is called by all other scripts before they do anything. So one could simple start by calling _lint and that would set up everything before it tried to actually lint the project

Once the code is ready to be delivered the _tag script should be called accepting one of three arguments, patch, minor, major following the semantic versioning scheme. So for the initial delivery one would call

$ _tag –minor

which would bump the version of the project to 0.1.0 tag it in git and do a push and also ask for the change and automagically update HISTORY.rst with the version and the change provided.

So the full workflow after git is initialized is:

repeat as necessary (of course it could be test - code - lint :) )

code

lint

test

commit and push

develop more through the code-lint-test cycle

tag (with the appropriate argument)

build

upload (if you want to host your package in pypi)

document (of course this could be run at any point)

Important Information¶

This template is based on pipenv. In order to be compatible with requirements.txt so the actual created package can be used by any part of the existing python ecosystem some hacks were needed. So when building a package out of this do not simple call

$ python setup.py sdist bdist_egg

as this will produce an unusable artifact with files missing. Instead use the provided build and upload scripts that create all the necessary files in the artifact.

Project Features¶

Lists accounts and OUs under Control Tower
Lists OUs under Organization
Create and delete and OU under Control Tower and register in Control Tower an OU created under Organizations
Create and terminate accounts under Control Tower

(Accounts terminated are deleted from control tower and service catalog and moved under Organizations in an OU called
Suspended. The OU needs to exist and it should have a completely restrictive SCP applied to it)
Some other stuff…

Installation¶

At the command line:

$ pip install controltowerlib

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv controltowerlib
$ pip install controltowerlib

Or, if you are using pipenv:

$ pipenv install controltowerlib

Or, if you are using pipx:

$ pipx install controltowerlib

Usage¶

To develop on controltowerlib:

# The following commands require pipenv as a dependency

# To lint the project
_CI/scripts/lint.py

# To execute the testing
_CI/scripts/test.py

# To create a graph of the package and dependency tree
_CI/scripts/graph.py

# To build a package of the project under the directory "dist/"
_CI/scripts/build.py

# To see the package version
_CI/scripts/tag.py

# To bump semantic versioning [--major|--minor|--patch]
_CI/scripts/tag.py --major|--minor|--patch

# To upload the project to a pypi repo if user and password are properly provided
_CI/scripts/upload.py

# To build the documentation of the project
_CI/scripts/document.py

To use controltowerlib in a project:

from controltowerlib import ControlTower
tower = ControlTower('arn:aws:iam::ACCOUNTID:role/ValidAdministrativeRole')

for account in tower.accounts:
    print(account.name)
>>> root
    Audit
    Log archive

for account in tower.accounts:
    print(account.guardrail_compliance_status)
>>> COMPLIANT
    COMPLIANT
    COMPLIANT

for ou in tower.organizational_units:
    print(ou.name)
>>> Custom
    Core
    Root

tower.create_organizational_unit('TestOU')
>>> True

tower.delete_organizational_unit('TestOU')
>>> True

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Submit Feedback¶

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.

Get Started!¶

Ready to contribute? Here’s how to set up controltowerlib for local development. Using of pipenv is highly recommended.

Clone your fork locally:

$ git clone git@github.com:schubergphilis/controltowerlib.git

Install your local copy into a virtualenv. Assuming you have pipenv installed, this is how you set up your clone for local development:
```
$ cd controltowerlib/
$ pipenv install --ignore-pipfile
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally. Do your development while using the CI capabilities and making sure the code passes lint, test, build and document stages.

Commit your changes and push your branch to the server:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a merge request

controltowerlib¶

controltowerlib package¶

Subpackages¶

controltowerlib.resources package¶

Submodules¶

controltowerlib.resources.configuration module¶

configuration module.

Import all parts from configuration here

controltowerlib.resources.resources module¶

resources module.

Import all parts from resources here

class controltowerlib.resources.resources.AccountFactory(service_catalog_client, data)[source]¶

Bases: object

Models the account factory data of service catalog.

class controltowerlib.resources.resources.ControlTowerAccount(control_tower, data, info_polling_interval=30)[source]¶

Bases: awsauthenticationlib.awsauthenticationlib.LoggerMixin

Models the account data.

property arn¶: Arn.

attach_service_control_policy(name)[source]¶

Attaches a Service Control Policy to the account.

Parameters: name (str) – The name of the SCP to attach
Returns: True on success, False otherwise.
Return type: result (bool)

property created_time¶: Created Time.

delete(suspended_ou_name=None)[source]¶: Delete.

detach_service_control_policy(name)[source]¶

Detaches a Service Control Policy from the account.

Parameters: name (str) – The name of the SCP to detach
Returns: True on success, False otherwise.
Return type: result (bool)

property email¶: Email.

property guardrail_compliance_status¶

Retrieves the guardrail compliancy status for the account.

Returns: COMPLIANT|NON COMPLIANT
Return type: status (str)

property has_available_update¶: If the account is behind the landing zone version.

property id¶: Id.

property idempotency_token¶: Idempotency Token.

property landing_zone_version¶: Landing zone version.

property last_record_id¶: Last Record ID.

property name¶: Name.

property organizational_unit¶: Organizational Unit.

property owner¶: Owner.

property physical_id¶: Physical ID.

property provision_state¶: Provision state.

property provisioning_artifact_id¶: Provisioning artifact ID.

property service_catalog_id¶: Service Catalog ID.

property service_catalog_product_id¶: Service catalog product ID.

property service_catalog_status¶: Service catalog status.

property service_catalog_tags¶: Service catalog tags.

property service_catalog_type¶: Service catalog type.

property service_catalog_user_arn¶: Service catalog user arn.

property sso_user_email¶: SSO user email.

property sso_user_portal¶: SSO user portal.

property stack_arn¶: Stack Arn.

property status¶: Status.

update()[source]¶

Updates the account in service catalog.

Returns: True if the call succeeded False otherwise

property user_arn_session¶: User arn session.

class controltowerlib.resources.resources.ControlTowerOU(control_tower, data)[source]¶

Bases: object

Model the data of a Control Tower managed OU.

property create_date¶: The date the ou was created in timestamp.

delete()[source]¶

Deletes the ou.

Returns: True on success, False otherwise.
Return type: response (bool)

property id¶: OU ID.

property name¶: The name of the OU.

property parent_ou_id¶: The id of the parent OU.

property parent_ou_name¶: The name of the parent OU.

property type¶: The type of the OU.

class controltowerlib.resources.resources.CoreAccount(control_tower, account_label, data)[source]¶

Bases: object

Models the core landing zone account data.

property core_resource_mappings¶: Core resource mappings.

property email¶: Email.

property id¶: Id.

property label¶: Account label.

property stack_set_arn¶: Stack set arn.

class controltowerlib.resources.resources.GuardRail(control_tower, data)[source]¶

Bases: awsauthenticationlib.awsauthenticationlib.LoggerMixin

Models the guard rail data.

property behavior¶: Behavior.

property category¶: Category.

property compliancy_status¶: Compliancy status.

property description¶: Description.

property display_name¶: DisplayName.

property name¶: Name.

property provider¶: Provider.

property regional_preference¶: Regional preference.

property type¶: Type.

class controltowerlib.resources.resources.OrganizationsOU(data)[source]¶

Bases: object

Model the data of an Organizations managed OU.

property arn¶: The arn of the OU.

property id¶: The id of the OU.

property name¶: The name of the OU.

class controltowerlib.resources.resources.ServiceControlPolicy(data)[source]¶

Bases: object

Models the account factory data of service catalog.

property arn¶: Arn.

property aws_managed¶: Aws Managed.

property description¶: Description.

property id¶: Id.

property name¶: Name.

property type¶: Type.

Module contents¶

configuration module.

Import all parts from configuration here

Submodules¶

controltowerlib.controltowerlib module¶

Main code for controltowerlib.

class controltowerlib.controltowerlib.ControlTower(arn, settling_time=90)[source]¶

Bases: awsauthenticationlib.awsauthenticationlib.LoggerMixin

Models Control Tower by wrapping around service catalog.

property accounts¶

The accounts under control tower.

Returns: A list of account objects under control tower’s control.
Return type: accounts (Account)

api_content_type = 'application/x-amz-json-1.1'¶

api_user_agent = 'aws-sdk-js/2.528.0 promise'¶

property baseline_update_available¶: Baseline update available.

property busy¶: Busy.

property catastrophic_drift¶: List of catastrophic drift.

core_account_types = ['PRIMARY', 'LOGGING', 'SECURITY']¶

property core_accounts¶

The core accounts of the landing zone.

Returns: A list of the primary, logging and security account.
Return type: core_accounts (list)

create_account(account_name, account_email, organizational_unit, product_name=None, sso_first_name=None, sso_last_name=None, sso_user_email=None)[source]¶

Creates a Control Tower managed account.

Parameters

account_name (str) – The name of the account.
account_email (str) – The email of the account.
organizational_unit (str) – The organizational unit that the account should be under.
product_name (str) – The product name, if nothing is provided it uses the account name.
sso_first_name (str) – The first name of the SSO user, defaults to “Control”
sso_last_name (str) – The last name of the SSO user, defaults to “Tower”
sso_user_email (str) – The email of the sso, if nothing is provided it uses the account email.

Returns

True on success, False otherwise.

Return type

result (bool)

create_organizational_unit(name)[source]¶

Creates a Control Tower managed organizational unit.

Parameters: name (str) – The name of the OU to create.
Returns: True if successfull, False otherwise.
Return type: result (bool)

decommission()[source]¶

Decommissions a landing zone.

The api call does not seem to be enough and although the resources are decomissioned like with the proper process, control tower responds with a delete failed on the api, so it seems that aws needs to perform actions on their end for the decommissioning to be successful.

Returns: True if the process starts successfully, False otherwise.
Return type: response (bool)

delete_organizational_unit(name)[source]¶

Deletes a Control Tower managed organizational unit.

Parameters: name (str) – The name of the OU to delete.
Returns: True if successfull, False otherwise.
Return type: result (bool)

deploy(logging_account_email, security_account_email, regions=None, retries=10, wait=1)[source]¶

Deploys control tower.

Returns: True on success, False on failure.
Return type: bool

property deploying_messages¶: Deploying messages.

property drift_messages¶: Drift messages.

property enabled_guard_rails¶: Enabled guard rails.

get_account_by_arn(arn)[source]¶

Retrieves an account by arn.

Returns: An account object that matches the arn or None.
Return type: account (Account)

get_account_by_id(id_)[source]¶

Retrieves an account by id.

Returns: An account object that matches the id or None.
Return type: account (Account)

get_account_by_name(name)[source]¶

Retrieves an account by name.

Returns: An account object that matches the name or None.
Return type: account (Account)

get_accounts_with_available_updates()[source]¶

Retrieves the accounts that have available updates from control tower.

Returns: A list of account objects under control tower’s control with available updates.
Return type: accounts (Account)

get_available_accounts()[source]¶

Retrieves the available accounts from control tower.

Returns: A list of available account objects under control tower’s control.
Return type: accounts (Account)

static get_available_regions()[source]¶

The regions that control tower can be active in.

Returns: A list of strings of the regions that control tower can be active in.
Return type: regions (list)

get_changing_accounts()[source]¶

Retrieves the under change accounts from control tower.

Returns: A list of under change account objects under control tower’s control.
Return type: accounts (Account)

get_erroring_accounts()[source]¶

Retrieves the erroring accounts from control tower.

Returns: A list of erroring account objects under control tower’s control.
Return type: accounts (Account)

get_organizational_unit_by_id(id_)[source]¶

Gets a Control Tower managed Organizational Unit by id.

Parameters: id (str) – The id of the organizational unit to retrieve.
Returns: A OU object on success, None otherwise.
Return type: result (ControlTowerOU)

get_organizational_unit_by_name(name)[source]¶

Gets a Control Tower managed Organizational Unit by name.

Parameters: name (str) – The name of the organizational unit to retrieve.
Returns: A OU object on success, None otherwise.
Return type: result (ControlTowerOU)

get_organizations_ou_by_arn(arn)[source]¶

Gets an Organizations managed Organizational Unit by arn.

Parameters: arn (str) – The arn of the organizational unit to retrieve.
Returns: A OU object on success, None otherwise.
Return type: result (OrganizationsOU)

get_organizations_ou_by_id(id_)[source]¶

Gets an Organizations managed Organizational Unit by id.

Parameters: id (str) – The id of the organizational unit to retrieve.
Returns: A OU object on success, None otherwise.
Return type: result (OrganizationsOU)

get_organizations_ou_by_name(name)[source]¶

Gets an Organizations managed Organizational Unit by name.

Parameters: name (str) – The name of the organizational unit to retrieve.
Returns: A OU object on success, None otherwise.
Return type: result (OrganizationsOU)

get_service_control_policy_by_name(name)[source]¶

Retrieves a service control policy by name.

Parameters: name (str) – The name of the SCP to retrieve
Returns: The scp if a match is found else None.
Return type: scp (ServiceControlPolicy)

get_updated_accounts()[source]¶

Retrieves the accounts that have no available updates from control tower.

Returns: A list of account objects under control tower’s control with no available updates.
Return type: accounts (Account)

property guard_rails¶: Guard rails.

property guard_rails_violations¶: List guard rails violations.

property guardrail_update_available¶: Guardrail update available.

property is_deployed¶: The deployment status of control tower.

is_email_used(email)[source]¶: Check email for availability to be used or if it is already in use.

property landing_zone_update_available¶: Landing Zone update available.

property landing_zone_version¶: Landing zone version.

property organizational_units¶

The organizational units under control tower.

Returns: A list of organizational units objects under control tower’s control.
Return type: organizational_units (OrganizationalUnit)

property organizations_ous¶

The organizational units under Organizations.

Returns: A list of organizational units objects under Organizations.
Return type: organizational_units (OrganizationsOU)

property percentage_complete¶: Percentage complete.

property region¶: Region.

property region_metadata_list¶: Region metadata list.

register_organizations_ou(name)[source]¶

Registers an Organizations OU under control tower.

Parameters: name (str) – The name of the Organizations OU to register to Control Tower.
Returns: True if successfull, False otherwise.
Return type: result (bool)

property root_ou¶

The root ou of control tower.

Returns: The root ou object.
Return type: root_ou (ControlTowerOU)

property service_control_policies¶

The service control policies under organization.

Returns: A list of SCPs under the organization.
Return type: service_control_policies (list)

property service_landing_zone_version¶: Service landing zone version.

property status¶: Status.

supported_targets = ['listManagedOrganizationalUnits', 'manageOrganizationalUnit', 'deregisterOrganizationalUnit', 'listManagedAccounts', 'getGuardrailComplianceStatus', 'describeManagedOrganizationalUnit', 'listGuardrailsForTarget', 'getAvailableUpdates', 'describeCoreService', 'getAccountInfo', 'listEnabledGuardrails', 'listGuardrails', 'listOrganizationalUnitsForParent', 'listDriftDetails', 'getLandingZoneStatus', 'setupLandingZone', 'getHomeRegion', 'listGuardrailViolations', 'getCatastrophicDrift', 'getGuardrailComplianceStatus', 'describeAccountFactoryConfig', 'performPreLaunchChecks', 'deleteLandingZone']¶

update()[source]¶

Updates the control tower to the latest version.

Returns: True on success, False on failure.
Return type: bool

property user_landing_zone_version¶: User landing zone version.

validate_availability()[source]¶: Validation decorator.

controltowerlib.controltowerlibexceptions module¶

Custom exception code for controltowerlib.

exception controltowerlib.controltowerlibexceptions.ControlTowerBusy[source]¶

Bases: Exception

The control tower is already executing some action.

exception controltowerlib.controltowerlibexceptions.ControlTowerNotDeployed[source]¶

Bases: Exception

The control tower is deployed at all.

exception controltowerlib.controltowerlibexceptions.EmailCheckFailed[source]¶

Bases: Exception

Checking of the email was not possible.

exception controltowerlib.controltowerlibexceptions.EmailInUse[source]¶

Bases: Exception

The email privided is already in use and cannot be used to deploy an account.

exception controltowerlib.controltowerlibexceptions.NoServiceCatalogAccess[source]¶

Bases: Exception

There is no access to service catalog.

exception controltowerlib.controltowerlibexceptions.NoSuspendedOU[source]¶

Bases: Exception

The suspended ou has not been created.

exception controltowerlib.controltowerlibexceptions.NonExistentSCP[source]¶

Bases: Exception

The SCP requested does not exist.

exception controltowerlib.controltowerlibexceptions.OUCreating[source]¶

Bases: Exception

The organizational unit is still under creation and cannot be used.

exception controltowerlib.controltowerlibexceptions.PreDeployValidationFailed[source]¶

Bases: Exception

The pre deployment validation failed.

exception controltowerlib.controltowerlibexceptions.RoleCreationFailure[source]¶

Bases: Exception

Unable to create the required roles for the deployment of control tower, manual clean up is required.

exception controltowerlib.controltowerlibexceptions.ServiceCallFailed[source]¶

Bases: Exception

The call to the service has failed.

exception controltowerlib.controltowerlibexceptions.UnavailableRegion[source]¶

Bases: Exception

The region or regions provided to control tower to deploy in are not available.

exception controltowerlib.controltowerlibexceptions.UnsupportedTarget[source]¶

Bases: Exception

The target call is not supported by the current implementation.

Module contents¶

controltowerlib module.

Import all parts from controltowerlib here

Credits¶

Development Lead¶

Costas Tyfoxylos <ctyfoxylos@schubergphilis.com>

Contributors¶

None yet. Why not be the first?

History¶

0.0.1 (18-02-2020)¶

First code creation

0.1.0 (12-01-2021)¶

First public release.

0.1.1 (19-01-2021)¶

Working around the OU pagination until the implementation fixes that properly.

0.1.2 (19-01-2021)¶

Fixed pagination bug properly.

0.2.0 (28-01-2021)¶

Implemented control tower versions and account update capabilites.

0.3.0 (26-02-2021)¶

Implemented control tower update, identifying the deployment status and locking when busy, along with exposing some more data like guard rails and drift messages.

0.4.0 (11-03-2021)¶

Made account deletion not depending on the suspended OU existance and account factory retrieval checking for CT being deployed.

0.5.0 (01-04-2021)¶

Implemented (not properly functioning still) decommissioning of control tower.

Welcome to controltowerlib’s documentation!¶

controltowerlib¶

Development Workflow¶

Important Information¶

Project Features¶

Installation¶

Usage¶

Contributing¶

Submit Feedback¶

Get Started!¶

controltowerlib¶

controltowerlib package¶

Subpackages¶

controltowerlib.resources package¶

Submodules¶

controltowerlib.resources.configuration module¶

controltowerlib.resources.resources module¶

Module contents¶

Submodules¶

controltowerlib.controltowerlib module¶

controltowerlib.controltowerlibexceptions module¶

Module contents¶

Credits¶

Development Lead¶

Contributors¶

History¶

0.0.1 (18-02-2020)¶

0.1.0 (12-01-2021)¶

0.1.1 (19-01-2021)¶

0.1.2 (19-01-2021)¶

0.2.0 (28-01-2021)¶

0.3.0 (26-02-2021)¶

0.4.0 (11-03-2021)¶

0.5.0 (01-04-2021)¶

Indices and tables¶