Getting Started

If you're interested in trying your hand at writing some security blueprints of your own and testing out the Tython framework, follow along with our Python example below.

1. Get the Tython CLI

To get started writing your own security blueprints with the Tython framework, head to the releases page to download and install the CLI. Platform-specific instructions can be found below.


Homebrew users can easily install the Tython CLI by adding the Tython tap repository:
brew tap oak9io/tap
brew install tython
When a new version of the CLI is released, the Tython CLI can be updated with the following Homebrew command
brew update
brew upgrade tython

Windows and Linux

Windows and Linux users can download the CLI binary from the releases page. It is recommended to add the CLI binary to your PATH so Tython commands can be executed from any directory.

2. Initialize a Tython project utilizing the Python SDK

With the Tython CLI in tow, we're ready to write security rules for our cloud infrastructure. The below example initializes a new Tython module in a blank directory that utilizes the Python SDK.
mkdir my-blueprints
cd my-blueprints
tython init python
The tython init python command will pull in the files necessary to get started creating a Tython module. This includes:
Each of these files is playing a critical role in the Tython module lifecycle:


In order to properly execute Tython blueprint modules, we need metadata about the contents of the blueprints. Today module.yml is quite lean, but oak9 is maintaining a roadmap that will expand on the power that Tython can offer. In the meantime, you'll notice that module.yml contains a runtime field set to python. This tells the Tython CLI that our security blueprint utilizes the Python SDK.


requirements.txt is a widely used convention in the Python community for specifying dependencies of a Python project. It allows developers to list out the required packages and their versions in a plain text file, which can be used to install those packages easily using pip.
To install all Tython dependencies, we can use pip:
python -m pip install --upgrade pip
pip install -r requirements.txt

This is our templated blueprint file and where the power of Tython will really begin to shine! Continue on to Step 3 to get started writing your first Tython blueprint. Be sure to read through the comments and examples listed in the file for some blueprint-writing hints.

3. Write a validation rule for your architecture

For a real-world example of a security blueprint, check out our fully functional!
Follow the example to build a validation rule for an architecture or technology of your choice.

4. Sign up for oak9 and create a project

Now that we've defined the blueprint that will validate specific architectural properties, we can test them against cloud architectures that are defined in IaC languages or deployed in the major cloud service providers. To use this beta version, Tython requires a free Community Edition account for the oak9 platform at After finishing the sign-up process, you can create an oak9 project with a code repository integration. oak9 has many other project types, but the Tython Beta support is limited to projects with code repository integrations. For help getting started with oak9 and projects, visit these documentation resources:
Feel free to use your own Infrastructure as Code, but to get started with some example resources, oak9 provides several "insecure by design" Terraform repositories called "Terraoak" that we recommend forking. Please note that the Tython Beta is limited to 200 cloud resources if you do decide to use your own IaC. Additionally, oak9 only supports AWS, Azure, and GCP Terraform, AWS CloudFormation and Kubernetes Manifests.

A (optional): Fork one of the Terraoak repositories

Try forking one of our Terraoak IaC repositories for some sample cloud resources for your blueprints:

5. Obtain an oak9 Tython API Key

At this point we can configure the Tython CLI to reach out to the oak9 API and pull in the cloud resources associated with our new project. These fetched resources can be run against the blueprint we've just created for feedback, but first we need to authorize the CLI for communication with oak9. Start by adding a new oak9 Integration:
We can configure the Tython CLI using the command shown on-screen. In this example we can pass the following command to the CLI to get set up with using our project's cloud resources:
tython config set -o tythonisprettycool -p proj-tythonisprettycool-1 -k MyTythonKeyThatIWillKeepSecret

6. Execute your blueprint against your IaC

This is where the magic begins! Tython offer two ways to check your IaC against your defined security blueprints:
tython test ./
tython apply ./


The test command will pull in the cloud resources defined in your specified oak9 project and check them against any blueprints in the directory. After completion, Tython reports on what it found in your terminal.


The apply command acts very similarly to test, but also checks your IaC against oak9's blueprint library. The findings from both your own blueprint and oak9's can be viewed in the oak9 console when using the apply command.

7. Results in the oak9 console and remediation steps

To view your blueprint's validation results side-by-side with the oak9 blueprints, sign in to the oak9 console. You should also check your code repository for Pull Requests opened by oak9 to remediate your IaC.