Visualize your aws security groups.

License: MIT

Language: Ruby

Keywords: aws, aws-cli, ec2, graph, graphviz, json, ruby, security, security-groups, visualization, viz

aws-security-viz -- A tool to visualize aws security groups

Build Status Gem Version License Code Climate Docker image Dependency Status


Need a quick way to visualize your current aws/amazon ec2 security group configuration? aws-security-viz does just that based on the EC2 security group ingress configuration.


  • Output to any of the formats that Graphviz supports.
  • EC2 classic and VPC security groups


  $ gem install aws_security_viz
  $ aws_security_viz --help


  • graphviz brew install graphviz

USAGE (See Examples section below for more)

To generate the graph directly using AWS keys

  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg --color=true

To generate the graph using an existing security_groups.json (created using aws-cli)

  $ aws_security_viz -o data/security_groups.json -f viz.svg --color

To generate a web view

  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator
  • Generates two files: aws.json and navigator.html.
  • The json file name needs to be passed in as a html fragment identifier.
  • The generated graph can be viewed in a webserver e.g. http://localhost:3000/navigator.html#aws.json by using ruby -run -e httpd -- -p 3000


Cleanup + add Docker from off the shelf image

If you don't want to install the dependencies and ruby libs you can execute aws-security-viz inside a docker container. To do so, follow these steps:

  1. Clone this repository, open it in a console.
  2. Build the docker container: docker build -t sec-viz .
  3. Run the container: docker run -i --rm -t -p 3000:3000 -v $(pwd)/aws-viz:/aws-security-viz --name sec-viz sec-viz (Description: -i interactive shell, --rm remove the container after usage, -t attach this terminal to it, -p 3000:3000 we expose port 3000 for the HTTP server, -v $(pwd)/aws-viz:aws-security-viz mount tmp directory for generated artifacts, -name sec-viz the container will have the same name as the image we will start)
  4. Now you can use the tool as described in usage. Make sure that you use the commands with bundler exec as prefix. For example: aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json.
  5. To start the web view, execute ruby -run -e httpd -- -p 3000 in the container. You can open it with your local browser at There you can view the generated images and the graph. Use Ctrl+C to close the HTTP server.
  6. Terminate the docker container by typing exit in the console.


$ aws_security_viz --help
  -a, --access-key=<s>       AWS access key
  -s, --secret-key=<s>       AWS secret key
  -e, --session-token=<s>    AWS session token
  -r, --region=<s>           AWS region to query (default: us-east-1)
  -v, --vpc-id=<s>           AWS VPC id to show
  -o, --source-file=<s>      JSON source file containing security groups
  -f, --filename=<s>         Output file name (default: aws-security-viz.png)
  -c, --config=<s>           Config file (opts.yml) (default: opts.yml)
  -l, --color                Colored node edges
  -u, --source-filter=<s>    Source filter
  -t, --target-filter=<s>    Target filter
  -h, --help                 Show this message

Advanced configuration

You can generate a configuration file using the following command:

  $ aws_security_viz setup [-c opts.yml]

The opts.yml file lets you define the following options:

  • Grouping of CIDR ips
  • Define exclusion patterns
  • Change graphviz format (neato, dot, sfdp etc)


To generate the graph with debug statements, execute the following command

$ DEBUG=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg

If it doesn't indicate the problem, please share the generated json file with me @

You can send me an obfuscated version using the following command:

$ DEBUG=true OBFUSCATE=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg

Execute the following command to generate the json. You will need aws-cli to execute the command

aws ec2 describe-security-groups


Graphviz export

Navigator view (useful with very large number of nodes)

Via navigator renderer aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator

JSON view

Via json renderer aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer json

Additional examples

Generate aws-security-viz.png image for us-west-1 region

  $ aws_security_viz --region us-west-1 -f aws-security-viz.png

Generate visualization for us-west-1 with target filter as sec-group-1. This will display all routes through which we can arrive at sec-group-1

  $ aws_security_viz --region us-west-1 --target-filter=sec-group-1

Generate visualization for us-west-1 restricted to vpc-id vpc-12345

  $ aws_security_viz --region us-west-1 --vpc-id=vpc-12345

Generate visualization for us-west-1 restricted to vpc-id vpc-12345

  $ aws_security_viz --region us-west-1 --vpc-id=vpc-12345

Project Statistics

Sourcerank 7
Repository Size 225 KB
Stars 473
Forks 80
Watchers 34
Open issues 0
Dependencies 9
Contributors 15
Tags 9
Last updated
Last pushed

Top Contributors See all

Anay Nayak ayucat Eric Herot Lars Lühr dependabot-preview[bot] Jack Danger Karun Japhet Andrii Melekhovskiy Wonno dependabot-bot Sheogorath Jared Short Philip Snowberger Matt Ferrante Daisuke Fujita

Packages Referencing this Repo

Provides a quick mechanism to visualize your EC2 security groups in multiple formats
Latest release 0.2.2.pre.alpha.pre.419 - Updated - 473 stars

Recent Tags See all

v0.2.1 June 20, 2020
v0.2.0 January 23, 2019
v0.1.6 January 14, 2019
v0.1.5 October 10, 2018
v0.1.4 February 03, 2017
v0.1.3 March 22, 2016
v0.1.2 January 26, 2016
v0.1.1 October 18, 2015
v0.1.0 October 15, 2015

Something wrong with this page? Make a suggestion

Last synced: 2020-10-03 08:27:52 UTC

Login to resync this repository