Using the Vanguard SDK for continuous attack simulations and automated threat modeling in AWS

The securiCAD Vanguard Python SDK provides a simple client to help you communicate with securiCAD’s APIs. The goal was to make it easier to run continuous attack simulations on your AWS environment as well as to provide a simple point of integration with other tools and CI/CD pipelines. The SDK is open source and available in GitHub.

In this article we will cover the requirements, installation and basic functionality of the SDK to get you started with continuous attack simulations on your AWS environment. Please note, securiCAD Vanguard does not store any data about your AWS environment or access keys and will never store results or models.


You will need a securiCAD Vanguard account, the appropriate permissions in your AWS account and Python 3 and pip installed.

Sign up to securiCAD Vanguard

Go to securiCAD Vanguard and sign up for an account. You need to verify your email address before you can start so make sure to check your spam folder or contact if you have any trouble signing up.

Make sure you have the required permissions in AWS

The required actions can be found in our example IAM policy here. In short, securiCAD Vanguard requires read access to all supported AWS services to be able to generate a model of your environment. Even if you don’t use all the supported services in your account, read access is still required.

Install Python and the required libraries

Download and install Python 3.7 or later and install the securiCAD Vanguard SDK with Pip by running:

pip install securicad-vanguard

That’s it, no other installations or configuration needed.

SDK design

At a high level, the SDK can be broken down into 4 primary functions:

  1. Authenticate with securiCAD Vanguard
  2. Generate a model from provided AWS data
  3. Configure the simulation
  4. Run the simulation and retrieve the results

The securiCAD Vanguard SDK enables this functionality through 4 simple functions easily accessible through the Python library.

Run your first simulation

The following snippet runs a simulation on an AWS environment where the high value asset is an EC2 instance with id i-1a2b3c4d5e6f7 and prints the results.

from securicad import vanguard
# Authentication
client = vanguard.client(username=email, password=password)
# Generating the model
model = client.get_model(access_key=access_key, secret_key=secret_key, region=region)
# Setting high value assets
# Run the simulation and handle the results
results = client.simulate(model, profile=vanguard.Profile.CYBERCRIMINAL)

That is all that is needed to start running automated attack simulations and threat modeling on your AWS environment with the securiCAD Vanguard Python SDK. Let’s dig into the details.


Authentication is handled by AWS Cognito through the pycognito library and the client will receive a JSON Web Token from our servers by providing it with your securiCAD Vanguard email and password.

vanguard.client(username="", password="thisisabadpassword")

The client will stay authenticated and handle all requests to the securiCAD Vanguard server for you.

Generating the model

When authenticated, we can generate a model from our AWS data. The client can fetch the data on your behalf with AWS access keys or you can provide it with locally generated data. Instructions on how to generate the data and the script for it can be found here. get_model will return a model of your current AWS environment in JSON which can be stored and used multiple times.

m = client.get_model(access_key="access_key", secret_key="secret_key", region="us-east-1")

Never hardcode your credentials in source code. Read more about access key management in AWS here and how to store your keys for use with Python and boto3 here.

Setting high value assets

The high value assets in the model will be the target for the attacker in the simulation and should represent the critical assets for your organization and its operations. Currently, we support S3 buckets, EC2 instances and RDS databases as high value assets and are provided as lists of strings.

model.set_high_value_assets(instances=["i-1a2b3c4d5e6f7"], buckets=[], dbinstances=[])

instances are provided as EC2 instance ids, buckets as S3 bucket names and dbinstances as db identifiers. More about how to fetch these identifiers automatically is covered below.

Running the simulation and the retrieving the results

The last thing we need to do is to set the profile of the attacker in the simulation. This will decide how advanced the simulated attacker will be, what types of attacks it will have access to its overall capabilities and resources. The predefined profiles available are OPPORTUNIST, CYBERCRIMINAL and STATESPONSORED.

results = client.simulate(model, profile=vanguard.Profile.CYBERCRIMINAL)

The client will poll for results from the server and return them once the simulation in complete. Results are returned as a dict with results for each provided high value asset. The probability is the probability of a successful attack on that high value asset (high is bad). ttc is the time-to-compromise or the amount of effort required by the to succeed (low is bad).

"buckets": {},
"dbinstances": {},
"instances": {
"i-1a2b3c4d5e6f7": {
"object_name": "web-server",
"probability": 0.5,
"ttc": 59


Continuous attack simulations over time

With the basics out of the way, we can look at how to use this functionality continuously. There are three things we want to achieve:

  1. Setting the high value assets automatically
  2. Store and monitor the results
  3. Examine abnormalities

Setting high value assets automatically

Many AWS environments are altered several times per day with continuous deploys and auto scaling and asset ids will change over time. The AWS Python library boto3 can be used to dynamically fetch ids based on for example tags or names. Read more about how to use boto3 here. In this example we will fetch EC2 instance ids based on a tag using filters.

import boto3
session = boto3.Session()
ec2 = session.resource('ec2')
# List all running EC2 instances with the owner-tag erik
instances = ec2.instances.filter(
{"Name": "tag:owner",
"Values": ["erik"]},
{'Name': 'instance-state-name', 'Values': ['running']}
# Get the instance-id of each filtered instance
instance_ids = [ for instance in instances]

We can then use the resulting list of EC2 instance ids to set high value assets in the model. More examples and code for S3 and RDS can be found here.

Monitor the results

To be able to detect changes in risk exposure of our AWS environment we need to store the results and track them over time. The ttc and probability values gives us tactile feedback on our risk exposure, and we can trigger alarms or warnings if the values change drastically. We can look at the ttc or probability for the whole model, a type of object or a specific instance or bucket.

As the ids are fetched dynamically, we can’t guarantee that they stay the same over time. As such, we should store the results based on how they were fetched e.g., with the tag we used above or name.

"2020-04-01 12:30": {
"instances": {
"tag:owner:erik": {...},
"name:jeff": {...}

If you don’t have granular enough tagging or naming in you AWS environment to single out specific assets over time, you should instead consider setting a baseline for the values and trigger on any asset reporting below or above that value. Just looking and average values can mask big changes for specific high value assets.

Examine abnormalities

It is not yet possible to upload results to securiCAD Vanguard and get a report based on simulations conducted via the SDK. However, this feature should be available in the end of April. As such, we need to run a new simulation via the user interface.

If you used locally generated data, you should store the data together with the results to be able to run the simulations again via the file upload feature in securiCAD Vanguard. Otherwise, you can simply provide securiCAD Vanguard with the same access keys and high value assets via the user interface and run a new simulation again to look at a more detailed report and to find any new weak spots and mitigate or handle them accordingly.


With a few lines of Python code and standard AWS libraries we are able to continouosly simulate attacks on virtual models of our AWS environment to find and mitigate weak spots and misconfigurations. The securiCAD Vanguard SDK is updated frequently and new exiting features will be introduced shortly, such as full results from the simulation for report generation in securiCAD Vanguard without running new simulations, support for vulnerability scanner data and other third-party data sources, new high value asset types and more granular risk reporting.