aws-security-viz - GitLite

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #golang #go #machine-learning #windows #awesome #cli #kubernetes #vue #openai #ios #mcp

aws-security-viz

(★ 722)

Visualize your aws security groups.

File Explorer

Download Latest Version (.zip)

- - ruby.yml
  - rubygem.yml
  - rubygem_release.yml
- dependabot.yml
- boot.rb
- aws_security_viz
- sample.png
- - parse_log.rb
- - ip_permission.rb
  - security_groups.rb
  - traffic.rb
- - ec2.rb
  - json.rb
- - all.rb
  - graphviz.rb
  - json.rb
  - navigator.rb
- aws_config.rb
- aws_security_viz.rb
- color_picker.rb
- debug_graph.rb
- exclusions.rb
- graph.rb
- graph_filter.rb
- opts.yml.sample
- version.rb
- - aws_expected.json
  - dummy.dot
  - dummy.json
  - expected.json
  - navigator.json
  - visualize_aws_spec.rb
- color_picker_spec.rb
- graph_filter_spec.rb
- spec_helper.rb
- visualize_aws_spec.rb
.dockerignore
.editorconfig
.gitignore
.tool-versions
aws_security_viz.gemspec
CHANGELOG.md
CODE_OF_CONDUCT.md
Dockerfile
Gemfile
LICENSE.md
Rakefile
README.md
Vagrantfile

🚀 Installation Guide

1. Get the code

git clone https://github.com/anaynayak/aws-security-viz

Downloads the entire project code from GitHub to your computer.

cd aws-security-viz

Moves into the project folder you just downloaded.

2. Docker

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

docker build -t aws-security-viz .

Builds a runnable image based on the Dockerfile.

docker run -p 8080:80 aws-security-viz

Runs the built image as an actual container.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

3. Ruby

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Ruby Ruby is required to use the bundle command.

bundle install

Installs the Ruby libraries listed in the Gemfile.

✅ If bundle install finishes without errors, continue with the run command from the README (e.g. rails server).

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

aws-security-viz -- A tool to visualize aws security groups
============================================================
[![Build Status](https://github.com/anaynayak/aws-security-viz/workflows/Ruby/badge.svg)](https://github.com/anaynayak/aws-security-viz/actions?query=workflow%3ARuby)
[![License](https://img.shields.io/github/license/anaynayak/aws-security-viz.svg?maxAge=2592000)]()
[![Docker Pulls](https://img.shields.io/docker/pulls/anay/aws-security-viz)](https://hub.docker.com/r/anay/aws-security-viz/)
[![Dependency Status](https://img.shields.io/librariesio/github/anaynayak/aws-security-viz.png?maxAge=259200)](https://libraries.io/github/anaynayak/aws-security-viz)
![Gem Downloads (for latest version)](https://img.shields.io/gem/dtv/aws_security_viz)

## 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 <profile_name> -- 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](#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.

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

Alternatively you can use [aws-vault](https://github.com/99designs/aws-vault/) and run it using short lived temporary credentials.

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

#### 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 @ whynospam-awsviz@yahoo.co.in

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](https://github.com/aws/aws-cli) to execute the command

`aws ec2 describe-security-groups`

## EXAMPLES

#### Graphviz export

![](https://github.com/anaynayak/aws-security-viz/raw/main/images/sample.png)

#### 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`
![](https://user-images.githubusercontent.com/416211/51426583-bb5e0180-1c12-11e9-903b-7b2a2d354ede.png)

#### JSON view
Via json renderer `aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer json`
![](https://cloud.githubusercontent.com/assets/416211/11912582/0e66cdbc-a669-11e5-82ab-1e26e3c6949b.png)

## 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