Infrastructure as Code approach on AWS is supported by the CloudFormation (CFT) service, which lets you define code templates to build production-ready cloud architectures. CloudFormation uses templates defined in JSON or YAML syntax, that are human readable and can be easily edited.
The IriusRisk API can be used as an integral part of DevOps Continuous Delivery pipeline so that code that doesn’t meet a risk profile is not deployed to production. Let's show a detailed hands-on example on how to integrate IriusRisk API in a CloudFormation workflow. We can split this process in the following four stages:
- Export your AWS architecture in a CloudFormation template.
- IriusRisk API configuration.
- Threat model generation process using the IriusRisk API.
- Review the generated threat model in IriusRisk.
Export your AWS architecture in a CloudFormation template
Maybe you've started working in the design for a new AWS stack. Chances are that the first step in your workflow is to draw the main elements of your architecture in a diagram. CloudFormation Designer is a great tool to accomplish this.
AWS CloudFormation Designer (Designer) is a graphic tool for creating, viewing, and modifying AWS CloudFormation templates. With Designer, you can diagram your template resources using a drag-and-drop interface, and then edit their details using the integrated JSON and YAML editor. In this example we'll use a very simple example of a Application Load Balancer with some of its basic components, that are highlighted in the following figure:
To begin our journey, let's export this simple cloud architecture to a CloudFormation JSON file (elb-no waf.json):
IriusRisk API configuration
Let’s move on to the IriusRisk configuration. As a first step to take advantage of the IriusRisk API, you should make sure you've enabled it in the “Control Panel”, inside the “Settings” section:
Secondly, you need to generate your API token to be able to interact with the IriusRisk API. To do so, you should go to the "User Profile" section to generate a new API token, as can be seen in the following figure:
For security reasons, the API token is shown only once, so you should copy it and store it in a safe place.
Threat model generation process using the IriusRisk API
Postman and IriusRisk configuration
Now we can use Postman to upload this CloudFormation template and automatically create a new threat model in IriusRisk for this IaC architecture. Postman is an HTTP client that allows you to craft HTTP requests using an easy to use graphical user interface. It's one of the most popular software testing tools which is used for API testing. Postman is available on the web and as a native desktop app for Mac (Intel and M1), Windows (32-bit / 64-bit), and Linux (64-bit) operating systems.
Once you get the latest version of the Postman desktop app for your platform, it's time for some configuration for you to be able to use Postman as an IriusRisk API REST client. The latest version of the IriusRisk API documentation is published at SwaggerHub.
SwaggerHub is an integrated API development platform built for teams to drive standardization and secure collaboration throughout the API lifecycle.
Now we'll export the IriusRisk API definition in a JSON file. To do so, you should click on the upper right side of the screen on "Export->Download API->JSON resolved".
After this, you should import this JSON file as a new collection in Postman. In order to do it, you should click on "Collections" from the main view and click on the "Import" button in Postman.
A file browsing window appears. Select the previously generated IriusRisk API JSON file. If everything went well, you should see the "IriusRisk API" as a new collection in Postman:
The next thing we should do is configure some Postman collection variables.
- The baseURL. This variable is included by default in the "Variables" section of the Postman Collection. You should change the default value (https://demo.iriusrisk.com) for the right IriusRisk URL in your environment.
- The api-token. This variable should be created manually for your collection and its initial value should be set based on your previously generated IriusRisk API Token.
Once you've set those two variables, we move to the "Authorization" section for this collection and instruct Postman to use the api-token variable for the API authorization. To do so, we use double curly brackets in the Value field for the API Key () to reference the collection variable we’ve created in the previous step. Now your configuration should be very similar to the one depicted in the following figure:
Then you can click on the "Save" button to persist these changes for our collection:
Now you're ready to try your first HTTP request. Try to click on the GET method for the /health endpoint to get the status and the version details of our IriusRisk instance.
A new tab is opened with the HTTP request details. Click on the "Send" button and you’ll receive an HTTP response with some basic monitoring information about your IriusRisk instance:
This was our "Hello world" API request. Let's go a little bit deeper. Now, we'll try to create a new IriusRisk project from our previously generated CloudFormation template file.
Create a new IriusRisk threat model from the CloudFormation template
In this section, we’ll try a more advanced API request to be able to generate a new IriusRisk project from a CloudFormation template.
As a first step, you should click on the cloudformation endpoint (POST /api/v1/products/cloudformation) in the collection navigation tree, as it’s shown in the following figure:
A new Postman tab opens. You can set the necessary parameters for this HTTP request in the “Body” submenu, as it can be seen below:
Now, we'll set the HTTP body parameters:
ctf-file: (Required) File that contains the CloudFormation Template.
product-id: (Required) Id of the new project in IriusRisk.
name: (Required) Name of the new project in IriusRisk.
mapping-file: (Optional) File that contains the mapping between AWS components and IriusRisk components. Providing this file will completely override default values.
To keep this first IaC importation template simple we'll use the default mapping between AWS components and IriusRisk components. This way, we won't need to specify the mapping-file and we can deselect this parameter. One example of this mapping file could be found in the StartLeft Github repository.
The next step is to select our CloudFormation template example (elb-no waf.json) as the value of the ctf-file parameter.
Finally, we set the product-id and name parameters that will be used to create a new project in IriusRisk.
We click on the "Save" button to persist this configuration. This is how it looks like the HTTP POST request configuration right now:
We are finally ready to click on the "Send" button to actually send the HTTP request and create the new IriusRisk project from our CloudFormation template. If everything goes well, we'll get a 201 HTTP code from the IriusRisk server and the following Body response:
Review the generated threat model in IriusRisk
If we log in in the IriusRisk UI, we'll see that a new threat model that was automatically created based on our CloudFormation template:
This is how it looks like the project home page:
To see the relevant threats for this simple architecture, you can go to the "Threats" section on the left pane:
To take a look at the recommended countermeasures for this architecture, you should visit the “Countermeasures” section:
In this step-by-step tutorial we've seen how to automatically create a threat model in IriusRisk from a simple IaC architecture designed for AWS. We've been using common tools that are usually in the arsenal of every cloud developer or DevOps engineer. From AWS CloudFormation Designer to Postman. This could be used as a first step to create a CI/CD pipeline that automatically creates threat models for the cloud architectures in the design phase, before the stack is deployed in production.
- IriusRisk Release 4.2: https://www.iriusrisk.com/resources-blog/product-update-release-4-2
- IriusRisk API Swaggerhub documentation: https://app.swaggerhub.com/apis/continuumsecurity/IriusRisk/1.13.0
- IriusRisk StartLeft GitHub project: https://github.com/iriusrisk/startleft
- AWS CloudFormation Designer interface overview: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/working-with-templates-cfn-designer-overview.html
- AWS Application Load Balancer: https://aws.amazon.com/elasticloadbalancing/application-load-balancer/
Jorge leads our Security Content Team, responsible for researching and threat modeling software architectures to derive security controls that can help developers to build security in their SDLC in a scalable way. Jorge believes that threat modeling is a great way to think collaboratively about security trade-offs and has a passion for learning and sharing his knowledge