README.md

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

DESCRIPTION

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.

FEATURES

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

INSTALLATION

  $ gem install aws_security_viz
  $ aws_security_viz --help

DEPENDENCIES

• 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

DOCKER USAGE

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.a With aws-vault (Recommended):

aws-vault exec tldev -- docker run -i -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN -e AWS_SECURITY_TOKEN --rm -t -p 3000:3000 -v (pwd)/aws-viz:/aws-security-viz --name sec-viz sec-viz /usr/local/bundle/bin/aws_security_viz --renderer navigator --serve 3000 .

You can open it with your local browser at http://localhost:3000/navigator.html#aws-security-viz.png.

3.b With AWS credentials passed as parameters:

docker run -i --rm -t -p 3000:3000 -v (pwd)/aws-viz:/aws-security-viz --name sec-viz sec-viz /usr/local/bundle/bin/aws_security_viz -a REPLACE_AWS_ACCESS_KEY_ID -s REPLACE_SECRET --renderer navigator --serve 3000.

You can open it with your local browser at http://localhost:3000/navigator.html#aws-security-viz.png.

Parameters passed to the docker command:

• -v $(pwd)/aws-viz:aws-security-viz local directory where output will be generated.
• -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
• -name sec-viz the container will have the same name as the image we will start

You can also use other parameters as specified in usage

Help

$ aws_security_viz --help
Options:
  -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
  --serve=<i>                Serve a HTTP server at specified port
  -h, --help                 Show this message

Configuration

aws-security-viz only uses the ec2:DescribeSecurityGroups api so a minimal IAM policy which grants only ec2:DescribeSecurityGroups access should be enough.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ec2:DescribeSecurityGroups",
            "Resource": "*"
        }
    ]
}

Alternatively you can use aws-vault and run it using short lived temporary credentials.

$ aws-vault exec <profile> -- aws_security_viz -f aws.json --renderer navigator

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)

DEBUGGING

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 @ [email protected]

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

EXAMPLES

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

Serve webserver for the navigator view at port 3000

  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator --serve 3000

The browser link to the view is printed on the CLI