{"id":13539244,"url":"https://github.com/anaynayak/aws-security-viz","last_synced_at":"2025-05-14T02:04:55.855Z","repository":{"id":1682672,"uuid":"2410040","full_name":"anaynayak/aws-security-viz","owner":"anaynayak","description":"Visualize your aws security groups.","archived":false,"fork":false,"pushed_at":"2025-04-07T13:20:04.000Z","size":276,"stargazers_count":712,"open_issues_count":1,"forks_count":108,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-04-10T19:09:02.987Z","etag":null,"topics":["aws","aws-cli","ec2","graph","graphviz","json","ruby","security","security-groups","visualization","viz"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anaynayak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-09-18T15:44:21.000Z","updated_at":"2025-03-07T03:38:46.000Z","dependencies_parsed_at":"2024-07-21T18:16:36.050Z","dependency_job_id":"cae6fae3-4ebb-4f23-901e-31fc17a344fa","html_url":"https://github.com/anaynayak/aws-security-viz","commit_stats":{"total_commits":195,"total_committers":19,"mean_commits":"10.263157894736842","dds":0.2974358974358975,"last_synced_commit":"5191ef658c1321aefa8f0994a8df4b5406e5a68f"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anaynayak%2Faws-security-viz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anaynayak%2Faws-security-viz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anaynayak%2Faws-security-viz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anaynayak%2Faws-security-viz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anaynayak","download_url":"https://codeload.github.com/anaynayak/aws-security-viz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052692,"owners_count":22006716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cli","ec2","graph","graphviz","json","ruby","security","security-groups","visualization","viz"],"created_at":"2024-08-01T09:01:22.312Z","updated_at":"2025-05-14T02:04:55.833Z","avatar_url":"https://github.com/anaynayak.png","language":"Ruby","funding_links":[],"categories":["\u003ca id=\"c71ad1932bbf9c908af83917fe1fd5da\"\u003e\u003c/a\u003eAWS","Ruby"],"sub_categories":["\u003ca id=\"0476f6b97e87176da0a0d7328f8747e7\"\u003e\u003c/a\u003eblog"],"readme":"aws-security-viz -- A tool to visualize aws security groups\n============================================================\n[![Build Status](https://github.com/anaynayak/aws-security-viz/workflows/Ruby/badge.svg)](https://github.com/anaynayak/aws-security-viz/actions?query=workflow%3ARuby)\n[![License](https://img.shields.io/github/license/anaynayak/aws-security-viz.svg?maxAge=2592000)]()\n[![Docker Pulls](https://img.shields.io/docker/pulls/anay/aws-security-viz)](https://hub.docker.com/r/anay/aws-security-viz/)\n[![Dependency Status](https://img.shields.io/librariesio/github/anaynayak/aws-security-viz.png?maxAge=259200)](https://libraries.io/github/anaynayak/aws-security-viz)\n![Gem Downloads (for latest version)](https://img.shields.io/gem/dtv/aws_security_viz)\n\n\n## DESCRIPTION\n  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.\n\n## FEATURES\n\n* Output to any of the formats that Graphviz supports.\n* EC2 classic and VPC security groups\n\n## INSTALLATION\n```\n  $ gem install aws_security_viz\n  $ aws_security_viz --help\n```\n\n## DEPENDENCIES\n\n* graphviz `brew install graphviz`\n\n## USAGE (See Examples section below for more)\n\nTo generate the graph directly using AWS keys\n\n```\n  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg --color=true\n```\n\nTo generate the graph using an existing security_groups.json (created using aws-cli)\n\n```\n  $ aws_security_viz -o data/security_groups.json -f viz.svg --color\n```\n\nTo generate a web view\n\n```\n  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator\n```\n\n* Generates two files: aws.json and navigator.html.\n* The json file name needs to be passed in as a html fragment identifier.\n* 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`\n\n## DOCKER USAGE\n\nIf 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:\n\n1. Clone this repository, open it in a console.\n2. Build the docker container: `docker build -t sec-viz .`\n\n3.a With aws-vault (Recommended):\n\n```aws-vault exec \u003cprofile_name\u003e -- 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``` . \n\nYou can open it with your local browser at `http://localhost:3000/navigator.html#aws-security-viz.png`. \n\n3.b With AWS credentials passed as parameters:\n\n```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```. \n\nYou can open it with your local browser at `http://localhost:3000/navigator.html#aws-security-viz.png`. \n\nParameters passed to the docker command:\n* `-v $(pwd)/aws-viz:aws-security-viz` local directory where output will be generated.\n* `-i` interactive shell\n* `--rm` remove the container after usage\n* `-t` attach this terminal to it\n* `-p 3000:3000` we expose port 3000 for the HTTP server\n* `-name sec-viz` the container will have the same name as the image we will start\n\nYou can also use other parameters as specified in [usage](#USAGE)\n\n### Help\n\n```\n$ aws_security_viz --help\nOptions:\n  -a, --access-key=\u003cs\u003e       AWS access key\n  -s, --secret-key=\u003cs\u003e       AWS secret key\n  -e, --session-token=\u003cs\u003e    AWS session token\n  -r, --region=\u003cs\u003e           AWS region to query (default: us-east-1)\n  -v, --vpc-id=\u003cs\u003e           AWS VPC id to show\n  -o, --source-file=\u003cs\u003e      JSON source file containing security groups\n  -f, --filename=\u003cs\u003e         Output file name (default: aws-security-viz.png)\n  -c, --config=\u003cs\u003e           Config file (opts.yml) (default: opts.yml)\n  -l, --color                Colored node edges\n  -u, --source-filter=\u003cs\u003e    Source filter\n  -t, --target-filter=\u003cs\u003e    Target filter\n  --serve=\u003ci\u003e                Serve a HTTP server at specified port\n  -h, --help                 Show this message\n```\n\n#### Configuration \n\naws-security-viz only uses the `ec2:DescribeSecurityGroups` api so a minimal IAM policy which grants only `ec2:DescribeSecurityGroups` access should be enough.\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": \"ec2:DescribeSecurityGroups\",\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\nAlternatively you can use [aws-vault](https://github.com/99designs/aws-vault/) and run it using short lived temporary credentials.\n\n`$ aws-vault exec \u003cprofile\u003e -- aws_security_viz -f aws.json --renderer navigator --serve 9091`\n\n#### Advanced configuration\n\nYou can generate a configuration file using the following command:\n```\n  $ aws_security_viz setup [-c opts.yml]\n```\n\nThe opts.yml file lets you define the following options:\n\n* Grouping of CIDR ips\n* Define exclusion patterns\n* Change graphviz format (neato, dot, sfdp etc)\n\n## DEBUGGING\n\nTo generate the graph with debug statements, execute the following command\n\n```\n$ DEBUG=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg\n```\n\nIf it doesn't indicate the problem, please share the generated json file with me @ whynospam-awsviz@yahoo.co.in\n\nYou can send me an obfuscated version using the following command:\n\n```\n$ DEBUG=true OBFUSCATE=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg\n```\n\nExecute the following command to generate the json. You will need [aws-cli](https://github.com/aws/aws-cli) to execute the command\n\n`aws ec2 describe-security-groups`\n\n\n## EXAMPLES\n\n#### Graphviz export\n\n![](https://github.com/anaynayak/aws-security-viz/raw/main/images/sample.png)\n\n#### Navigator view (useful with very large number of nodes)\nVia navigator renderer `aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator`\n![](https://user-images.githubusercontent.com/416211/51426583-bb5e0180-1c12-11e9-903b-7b2a2d354ede.png)\n\n#### JSON view\nVia json renderer `aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer json`\n![](https://cloud.githubusercontent.com/assets/416211/11912582/0e66cdbc-a669-11e5-82ab-1e26e3c6949b.png)\n\n## Additional examples\n\n#### Generate `aws-security-viz.png` image for `us-west-1` region\n\n```\n  $ aws_security_viz --region us-west-1 -f aws-security-viz.png\n```\n\n#### 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`\n\n```\n  $ aws_security_viz --region us-west-1 --target-filter=sec-group-1\n```\n\n#### Generate visualization for `us-west-1` restricted to vpc-id `vpc-12345`\n```\n  $ aws_security_viz --region us-west-1 --vpc-id=vpc-12345\n```\n\n#### Generate visualization for `us-west-1` restricted to vpc-id `vpc-12345`\n```\n  $ aws_security_viz --region us-west-1 --vpc-id=vpc-12345\n```\n\n#### Serve webserver for the navigator view at port 3000\n```\n  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator --serve 3000\n```\nThe browser link to the view is printed on the CLI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanaynayak%2Faws-security-viz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanaynayak%2Faws-security-viz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanaynayak%2Faws-security-viz/lists"}