aws_security_viz 0.2.5.pre.alpha.pre.35 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ae64213f8b71718599133461e12d9675934f87c19ccc4374402b582ad439e01
-  data.tar.gz: 62c18a94dc4007888f44f1ba3dfcf327a462ef8ec81e424b94e310fc0911cc85
+  metadata.gz: 57eea04dcfb8bce81f204b046fbb01525194362bf046a7754fb2c26704ad2e4f
+  data.tar.gz: b73a6510229a8fdb6f0697518b4790fe4cf1400b6ac1dcc44f50f4fb4899267f
 SHA512:
-  metadata.gz: 8f5485c18d23a47d690b6e2efac55739e824721a14e388e1dd3f47b8fb7544f7bdc47d42c796f4e4b3b780c52385b7ddb558f054b53bd5c29e9dc9ada3287ad1
-  data.tar.gz: 4e1b6817c3fc74f8c4b2325b3e9725d90c9a66aa62aa02c821f7fa3bd6c9596cb111ea859ec8748f3a2711ef9dfd0e89daef2a2e18563b575825a58e72b7b66c
+  metadata.gz: c85a2f7002c23a0d3676fd7116646c5846e9497b9a10a59fe49c98a1d4b848971627e4ab10a3b009984c5ea4d9e192a08d1f27bfe3d5faee1966cca94a425536
+  data.tar.gz: 2ff0af0aeeaa6fa4e35f760ce6a8f489666e9d2a21bf63cc42812608e08b19de80a43900b1a641f187d8c4170e92ba6c1816c345055ae8cb545caf8af716260f

data/CHANGELOG.md

@@ -2,6 +2,63 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+
+## [1.0.0] - 2026-10-03
+This release also covers the 0.3.0 work, which was never tagged or published.
+
+### Breaking changes
+- Ruby 3.3 or newer is required (it was 3.0 or newer in 0.2.4)
+- The default output is now `aws-security-viz.html`, a self-contained page, instead of `aws-security-viz.png` (`.json` for json and navigator output). The output format is inferred from the -f/--output extension (.html, .json, .mmd, .dot/.gv, or an image such as .png/.svg). Image output still needs the Graphviz `dot` binary
+- The old html viewers and the navigator renderer are removed, along with `--serve`
+- There is no default region (it used to be us-east-1); the region comes from the AWS SDK credential/config chain (AWS_REGION, profile, ...) or -r, and a missing region fails with an error
+- --profile no longer defaults to AWS_PROFILE, so explicit access keys are kept
+- Node ids in JSON output are now security group ids; names are labels, and groups are clustered by VPC (and by region when several are queried)
+- Edges are blue for ingress and red for egress; the per-group colour palette is gone and `--color` is ignored
+- All library code is under the `AwsSecurityViz` namespace and moved to `lib/aws_security_viz/`; the top-level `VisualizeAws`, `Renderer`, `Ec2Provider` and similar constants no longer exist. Use the `aws_security_viz` executable, or `AwsSecurityViz::CLI`
+- Obfuscation hashes are shorter (10 hex characters)
+- Runtime dependencies are now only `aws-sdk-ec2` (>= 1.400, no upper cap) and `rexml`. `graphviz`, `rgl`, `optimist`, `webrick` and `organic_hash` are gone
+
+### Deprecated
+- --renderer: still works but prints a warning; use the -f extension instead. `--renderer navigator` now writes the html viewer
+- --color: ignored, prints a warning
+
+### Added
+- Self-contained HTML viewer (`-f out.html`, the default): one file with Cytoscape.js 3.34.3 vendored and the graph data inlined, a Content-Security-Policy, no CDN or server, works from `file://`
+- Mermaid flowchart output (`-f out.mmd`), with a warning when the diagram exceeds Mermaid's default edge or text limits
+- Multi-region support: `--region us-east-1,eu-west-1` or `--all-regions` (needs `ec2:DescribeRegions`); regions that fail with an authorisation error are skipped with a warning
+- Risky ingress highlighting: 0.0.0.0/0 or ::/0 reaching a sensitive port (22, 3389, 3306, 5432, 1433, 6379, 9200, 27017, configurable with `risky_ports` in opts.yml) or allowing all traffic is drawn distinctly and flagged `risky` in JSON and HTML output. --fail-on-risk exits 2 when any is found
+- --show-unused marks security groups with no attached network interface (dashed grey in DOT, `unused` class in Mermaid, `unused: true` in JSON and HTML output); it needs `ec2:DescribeNetworkInterfaces` and is ignored with --source-file
+- Rule descriptions are kept: JSON edges carry a `descriptions` list and DOT edges a `tooltip` (hashed under --obfuscate)
+- --input and --output aliases for -o/--source-file and -f/--filename; `init` alias for `setup`
+- --layout picks the Graphviz layout engine (overrides `format` in opts.yml; unknown engines are rejected)
+- --debug (or DEBUG=true) for verbose output and stack traces, --obfuscate (or OBFUSCATE=true) to hash group names, ports and ids
+- IPv6 ranges and prefix lists are drawn as rule peers
+- --vpc-id is honoured for --source-file input
+- Tag-triggered release workflow using RubyGems trusted publishing, which also pushes a multi-arch (amd64 and arm64) image to ghcr.io/anaynayak/aws-security-viz tagged `<version>`, `<major>.<minor>` and `latest`. The image is built from this source and runs as a non-root user. Not yet verified locally (task-17: the Docker build and the release workflow have not been run)
+
+### Changed
+- CLI moved into `AwsSecurityViz::CLI` on stdlib OptionParser
+- Warnings, errors and debug output go to stderr through a Logger, keeping stdout clean
+- Exit codes: 0 on success, 1 on error, 2 for --fail-on-risk, 130 on Ctrl-C
+- Graph building uses a small adjacency-list graph and DOT is generated directly; Graphviz is only needed for image formats
+- Rules that allow all traffic, ICMP, or a numeric protocol get readable labels, and all-traffic is labelled "all"
+- Boolean environment variables (DEBUG, OBFUSCATE) are parsed as booleans
+- The html asset is written next to the output file, not the current directory
+- Gemfile.lock is committed, the gemspec has no upper version caps, and CI tests Ruby 3.3, 3.4 and 4.0
+
+### Removed
+- The navigator renderer, the old view.html and navigator.html viewers, --serve and the webrick dependency
+- The `rake docker:push` task and the per-push alpha gem workflow, replaced by the tag-triggered release workflow
+- Support for Ruby older than 3.3
+
+### Fixed
+- Security groups sharing a name in different VPCs no longer collapse into one node
+- Several rules between the same two groups are merged into a single edge with merged port labels
+- DescribeSecurityGroups is paginated and the VPC filter is applied server-side
+- Unknown renderers and layout engines are rejected, and errors are reported cleanly (exit 1, Ctrl-C exits 130)
+- The test suite loads on Ruby 4.0
+
 ## [0.2.4] - 2023-06-10
 - Matrix builds for Ruby v3.0 onwards only
 - Remove support for Ruby v2.x
@@ -95,7 +152,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Begin life as the gem [aws_security_viz](https://rubygems.org/gems/aws_security_viz)
 
 
-[Unreleased]: https://github.com/anaynayak/aws-security-viz/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/anaynayak/aws-security-viz/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/anaynayak/aws-security-viz/compare/v0.2.4...v1.0.0
 [0.1.3]: https://github.com/anaynayak/aws-security-viz/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/anaynayak/aws-security-viz/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/anaynayak/aws-security-viz/compare/v0.1.0...v0.1.1

data/README.md

@@ -2,105 +2,150 @@ 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)
+[![Docker image](https://img.shields.io/badge/ghcr.io-aws--security--viz-blue)](https://github.com/anaynayak/aws-security-viz/pkgs/container/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.
 
+![](https://github.com/anaynayak/aws-security-viz/raw/main/images/sample.png)
+
 ## FEATURES
 
-* Output to any of the formats that Graphviz supports.
-* EC2 classic and VPC security groups
+* Reads the live AWS API, or the JSON from `aws ec2 describe-security-groups`.
+* Output formats: a self-contained HTML viewer, JSON, Mermaid, DOT, and any image format Graphviz supports (png, svg, pdf and others).
+* One region, several regions, or all regions in a single graph; groups are clustered by region and VPC.
+* Risky public ingress (`0.0.0.0/0` or `::/0` on a sensitive port) is drawn as a dashed crimson edge, and `--fail-on-risk` turns it into a failing exit code for CI.
+* `--show-unused` marks security groups that no network interface uses.
 
 ## INSTALLATION
+
+From RubyGems:
+
 ```
   $ gem install aws_security_viz
   $ aws_security_viz --help
 ```
 
+Or run the published image, which has Ruby and Graphviz built in (see [Docker usage](#docker-usage)):
+
+```
+  $ docker pull ghcr.io/anaynayak/aws-security-viz:<version>
+```
+
 ## DEPENDENCIES
 
-* graphviz `brew install graphviz`
+* Ruby 3.3 or newer.
+* Graphviz (`brew install graphviz`), only for image formats (png, svg, pdf and so on). The HTML, JSON, Mermaid and DOT outputs do not need it.
+
+## USAGE
 
-## USAGE (See Examples section below for more)
+The output format follows the extension of `-f/--output`: `.html` (the default is `aws-security-viz.html`), `.json`, `.mmd`, `.dot` or `.gv`, or an image such as `.png` or `.svg`. The older `--renderer` flag is deprecated; it still works and prints a warning.
 
-To generate the graph directly using AWS keys
+To generate a graph from an existing security_groups.json (created using aws-cli, see [Debugging](#debugging))
 
 ```
-  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg --color=true
+  $ aws_security_viz -o security_groups.json -f viz.svg
 ```
 
-To generate the graph using an existing security_groups.json (created using aws-cli)
+To query AWS directly with a shared-config profile (`--profile` also works with SSO profiles after `aws sso login --profile <profile_name>`)
 
 ```
-  $ aws_security_viz -o data/security_groups.json -f viz.svg --color
+  $ aws_security_viz --profile <profile_name> --region us-west-1 -f viz.html
 ```
 
-To generate a web view
+The credentials and region otherwise come from the standard AWS SDK chain (`AWS_PROFILE`, `AWS_REGION`, environment variables, SSO, instance roles). There is no built-in default region, so a missing region fails with `MissingRegionError`.
+
+With [aws-vault](https://github.com/99designs/aws-vault/) and short lived temporary credentials
 
 ```
-  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator
+  $ aws-vault exec <profile_name> -- aws_security_viz --region us-west-1 -f viz.html
 ```
 
-* 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`
+With explicit keys (`-a/--access-key`, `-s/--secret-key`, `-e/--session-token`). Prefer a profile, aws-vault or SSO, because keys passed on the command line end up in your shell history.
+
+### Regions
+
+With several regions (`--region us-east-1,eu-west-1` or `--all-regions`) nodes are grouped by region, then VPC. With `--all-regions`, `-r` (first name if a list) is only the region used to call `DescribeRegions`. A region that fails with `UnauthorizedOperation`, `AuthFailure` or `OptInRequired` is skipped with a warning; the run fails only if every region fails. The JSON and HTML outputs carry the region on each node. `--region` and `--all-regions` are ignored (with a warning) when `--source-file` is used.
+
+### Risky ingress
+
+Ingress from `0.0.0.0/0` or `::/0` on a sensitive port (22, 3389, 3306, 5432, 1433, 6379, 9200, 27017) or on all traffic is flagged on stderr and drawn as a dashed crimson edge. Change the ports with `risky_ports` in opts.yml. `--fail-on-risk` exits with status 2 when any such edge exists; the output file is still written.
 
 ## 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:
+Run aws-security-viz from the published image instead of installing Ruby and Graphviz. Releases push a multi-arch (amd64 and arm64) image to `ghcr.io/anaynayak/aws-security-viz`, tagged `<version>` (for example `1.0.0`), `<major>.<minor>` (for example `1.0`) and `latest` (stable releases only). Pin a version tag for reproducible runs. The image's entrypoint is `bundle exec aws_security_viz`, so everything after the image name is a normal CLI argument. It runs as a non-root user with `/work` as the working directory; mount a local directory there to get the output files.
 
-1. Clone this repository, open it in a console.
-2. Build the docker container: `docker build -t sec-viz .`
+1. With aws-vault (recommended):
 
-3.a With aws-vault (Recommended):
+```
+aws-vault exec <profile_name> -- docker run --rm --user $(id -u):$(id -g) \
+  -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN -e AWS_SECURITY_TOKEN \
+  -v "$(pwd)/aws-viz:/work" ghcr.io/anaynayak/aws-security-viz:<version> -f /work/aws.svg
+```
 
-```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``` . 
+2. With an SSO profile, mounting your AWS config (run `aws sso login --profile <profile_name>` first):
 
-You can open it with your local browser at `http://localhost:3000/navigator.html#aws-security-viz.png`. 
+```
+docker run --rm --user $(id -u):$(id -g) -e HOME=/home/viz -e AWS_PROFILE=<profile_name> -e AWS_REGION \
+  -v "$HOME/.aws:/home/viz/.aws" -v "$(pwd)/aws-viz:/work" \
+  ghcr.io/anaynayak/aws-security-viz:<version> -f /work/aws.svg
+```
 
-3.b With AWS credentials passed as parameters:
+3. 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```. 
+```
+docker run --rm --user $(id -u):$(id -g) -v "$(pwd)/aws-viz:/work" ghcr.io/anaynayak/aws-security-viz:<version> \
+  -a REPLACE_AWS_ACCESS_KEY_ID -s REPLACE_SECRET -r REPLACE_REGION -f /work/aws.svg
+```
 
-You can open it with your local browser at `http://localhost:3000/navigator.html#aws-security-viz.png`. 
+4. To build the image from a checkout instead: `docker build -t sec-viz .` and use `sec-viz` in place of the ghcr.io name.
 
-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
+Notes:
+* `-v "$(pwd)/aws-viz:/work"` is the local directory where output is written. Create it first (`mkdir aws-viz`).
+* `--user $(id -u):$(id -g)` matters on Linux: bind mounts keep the host's ownership, so the container's non-root
+  user cannot write to a directory owned by you and the run fails with "Permission denied". Running as your own
+  uid/gid fixes that and leaves the output files owned by you. Docker Desktop on macOS does not need it.
+* `--rm` removes the container after the run.
 
-You can also use other parameters as specified in [usage](#USAGE)
+You can also use any other option from the [help](#help) below.
 
 ### 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.
+Usage: aws_security_viz [options] [setup|init]
+    -a, --access-key=KEY             AWS access key
+    -s, --secret-key=KEY             AWS secret key
+    -e, --session-token=TOKEN        AWS session token
+    -r, --region=REGION              AWS region(s) to query, comma-separated (default: SDK chain, e.g. AWS_REGION or profile)
+        --all-regions                Query every region returned by DescribeRegions
+    -p, --profile=NAME               AWS shared-config profile to use (AWS_PROFILE is read by the SDK)
+    -v, --vpc-id=ID                  AWS VPC id to show
+    -o, --source-file, --input=FILE  JSON source file containing security groups
+    -f, --filename, --output=FILE    Output file; the format follows the extension: .html, .json, .mmd, .dot/.gv or an image such as .png/.svg (default: aws-security-viz.html)
+    -c, --config=FILE                Config file (opts.yml)
+    -l, --[no-]color                 Deprecated, ignored: edges are blue for ingress and red for egress, risky public ingress is dashed crimson
+    -n, --renderer=NAME              Deprecated, use the -f extension instead: renderer (graphviz|json|html|mermaid)
+    -y, --layout=ENGINE              Graphviz layout engine (dot|neato|sfdp|fdp|twopi|circo); overrides opts.yml format
+    -d, --[no-]debug                 Verbose output and stack traces (or DEBUG=true)
+    -b, --[no-]obfuscate             Hash group names and ports (or OBFUSCATE=true)
+    -u, --source-filter=FILTER       Source filter
+    -t, --target-filter=FILTER       Target filter
+        --show-unused                Mark groups with no attached network interfaces (needs ec2:DescribeNetworkInterfaces; ignored with --source-file)
+        --fail-on-risk               Exit 2 when 0.0.0.0/0 or ::/0 can reach a sensitive port (the output is still written)
+    -i, --version                    Print version and exit
+    -h, --help                       Show this message
+```
+
+#### Configuration
+
+aws-security-viz only uses the `ec2:DescribeSecurityGroups` api, so a minimal IAM policy which grants only that action should be enough. Two flags call more:
+
+1. `--all-regions` calls `ec2:DescribeRegions`.
+2. `--show-unused` calls `ec2:DescribeNetworkInterfaces` (paginated, per region). Without the permission the run still succeeds and logs a warning, but no groups are marked unused.
+
+Add an action to the policy only if you use its flag.
 
 ```json
 {
@@ -108,20 +153,20 @@ aws-security-viz only uses the `ec2:DescribeSecurityGroups` api so a minimal IAM
     "Statement": [
         {
             "Effect": "Allow",
-            "Action": "ec2:DescribeSecurityGroups",
+            "Action": [
+                "ec2:DescribeSecurityGroups",
+                "ec2:DescribeRegions",
+                "ec2:DescribeNetworkInterfaces"
+            ],
             "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:
+You can generate a configuration file using the following command (`init` is an alias for `setup`):
 ```
   $ aws_security_viz setup [-c opts.yml]
 ```
@@ -131,26 +176,25 @@ The opts.yml file lets you define the following options:
 * Grouping of CIDR ips
 * Define exclusion patterns
 * Change graphviz format (neato, dot, sfdp etc)
+* Change the ports flagged as risky (`risky_ports`)
 
 ## DEBUGGING
 
-To generate the graph with debug statements, execute the following command
+To generate the graph with debug statements, pass `--debug` (or set `DEBUG=true`). Debug output goes to stderr.
 
 ```
-$ DEBUG=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg
+$ aws_security_viz --debug --profile <profile_name> --region us-west-1 -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:
+If it doesn't indicate the problem, please open an issue on [GitHub](https://github.com/anaynayak/aws-security-viz/issues) and attach the security group JSON. Obfuscate it first with `--obfuscate` (or `OBFUSCATE=true`), which hashes group names and ports in the output:
 
 ```
-$ DEBUG=true OBFUSCATE=true aws_security_viz -a your_aws_key -s your_aws_secret_key -f viz.svg
+$ aws_security_viz --debug --obfuscate --profile <profile_name> --region us-west-1 -f viz.json
 ```
 
-Execute the following command to generate the json. You will need [aws-cli](https://github.com/aws/aws-cli) to execute the command
+Execute the following command to generate the JSON input for `--source-file`. You will need [aws-cli](https://github.com/aws/aws-cli) to execute the command
 
-`aws ec2 describe-security-groups`
+`aws ec2 describe-security-groups > security_groups.json`
 
 
 ## EXAMPLES
@@ -159,13 +203,11 @@ Execute the following command to generate the json. You will need [aws-cli](http
 
 ![](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)
+Generated from `spec/integration/dummy.json` with `aws_security_viz -o spec/integration/dummy.json -f images/sample.png`.
+
+#### HTML viewer (useful with very large number of nodes)
 
-#### 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)
+`aws_security_viz --profile <profile_name> --region us-west-1 -f aws.html` writes one self-contained file with the graph data inlined. Open it from disk in a browser; no web server is needed.
 
 ## Additional examples
 
@@ -178,21 +220,20 @@ Via json renderer `aws_security_viz -a your_aws_key -s your_aws_secret_key -f aw
 #### 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
+  $ aws_security_viz --region us-west-1 -f aws.html --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
+  $ aws_security_viz --region us-west-1 -f aws.html --vpc-id=vpc-12345
 ```
 
-#### Generate visualization for `us-west-1` restricted to vpc-id `vpc-12345`
+#### Fail a CI job when a sensitive port is open to the internet
 ```
-  $ aws_security_viz --region us-west-1 --vpc-id=vpc-12345
+  $ aws_security_viz --all-regions --fail-on-risk -f aws.json
 ```
 
-#### Serve webserver for the navigator view at port 3000
+#### Generate a Mermaid diagram
 ```
-  $ aws_security_viz -a your_aws_key -s your_aws_secret_key -f aws.json --renderer navigator --serve 3000
+  $ aws_security_viz --region us-west-1 -f aws.mmd
 ```
-The browser link to the view is printed on the CLI

data/exe/aws_security_viz

@@ -1,43 +1,7 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'aws_security_viz'
-require 'optimist'
-require 'webrick'
-require 'version'
+require "aws_security_viz"
+require "aws_security_viz/cli"
 
-opts = Optimist::options do
-  version "aws_security_viz v#{AwsSecurityViz::VERSION}"
-  opt :access_key, 'AWS access key', :default => ENV['AWS_ACCESS_KEY'] || ENV['AWS_ACCESS_KEY_ID'], :type => :string
-  opt :secret_key, 'AWS secret key', :default => ENV['AWS_SECRET_KEY'] || ENV['AWS_SECRET_ACCESS_KEY'], :type => :string
-  opt :session_token, 'AWS session token', :default => ENV['AWS_SESSION_TOKEN'] || nil, :type => :string
-  opt :region, 'AWS region to query', :default => 'us-east-1', :type => :string
-  opt :vpc_id, 'AWS VPC id to show', :type => :string
-  opt :source_file, 'JSON source file containing security groups', :type => :string
-  opt :filename, 'Output file name', :type => :string, :default => 'aws-security-viz.png'
-  opt :config, 'Config file (opts.yml)', :type => :string, :default => 'opts.yml'
-  opt :color, 'Colored node edges', :default => false
-  opt :renderer, "Renderer (#{Renderer.all.join('|')})", :default => 'graphviz'
-  opt :source_filter, 'Source filter', :default => nil, :type => :string
-  opt :target_filter, 'Target filter', :default => nil, :type => :string
-  opt :serve, 'Serve a HTTP server', :default => nil, :type => :integer
-end
-
-cmd = ARGV.shift
-if cmd=="setup"
-  AwsConfig.write(opts[:config])
-  puts "#{opts[:config]} created in current directory."
-  exit
-end
-
-config = AwsConfig.load(opts[:config]).merge(obfuscate: ENV['OBFUSCATE'], debug: ENV['DEBUG'])
-begin
-  VisualizeAws.new(config, opts).unleash(opts[:filename])
-  if opts[:serve]
-    puts "Navigate to http://localhost:#{opts[:serve]}/navigator.html##{opts[:filename]}"
-    WEBrick::HTTPServer.new({Port: opts[:serve], DocumentRoot: '.'}).start
-  end
-rescue Exception => e
-  puts "[ERROR] #{e.message}"
-  raise e if config.debug?
-  exit 1
-end
+exit AwsSecurityViz::CLI.new(ARGV).run

data/lib/aws_security_viz/aws_config.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "risk"
+
+module AwsSecurityViz
+  class AwsConfig
+    def initialize(opts = {})
+      @opts = opts
+      @risky_ports = parse_risky_ports(opts[:risky_ports])
+    end
+
+    def exclusions
+      @exclusions ||= Exclusions.new(@opts[:exclude])
+    end
+
+    def egress?
+      @opts.key?(:egress) ? @opts[:egress] : true
+    end
+
+    def groups
+      @opts[:groups] || {}
+    end
+
+    # Ports whose exposure to 0.0.0.0/0 or ::/0 is flagged (opts.yml :risky_ports); all traffic always is.
+    # Validated once when the config is built.
+    attr_reader :risky_ports
+
+    LAYOUTS = %w[dot neato sfdp fdp twopi circo].freeze
+
+    # Graphviz layout engine: --layout, else `format` in opts.yml, else dot.
+    def layout
+      engine = (@opts[:layout] || @opts[:format] || "dot").to_s
+      return engine if LAYOUTS.include?(engine)
+      raise ArgumentError, "unknown layout engine '#{engine}' (choose from: #{LAYOUTS.join(", ")})"
+    end
+
+    def debug?
+      @opts[:debug] || false
+    end
+
+    def obfuscate?
+      @opts[:obfuscate] || false
+    end
+
+    # Parses an env-style flag: nil/empty is unset, true/1/yes/on and false/0/no/off are booleans.
+    def self.boolean(value, name = "value")
+      text = value.to_s.strip.downcase
+      return nil if text.empty?
+      return true if %w[true 1 yes on].include?(text)
+      return false if %w[false 0 no off].include?(text)
+      raise ArgumentError, "#{name} must be true, false, 1 or 0 (got '#{value}')"
+    end
+
+    def self.load(file)
+      config_opts = File.exist?(file) ? YAML.load_file(file) : {}
+      AwsConfig.new(config_opts)
+    end
+
+    def merge(opts)
+      AwsConfig.new(@opts.merge!(opts))
+    end
+
+    def self.write(file)
+      FileUtils.cp(File.expand_path("../opts.yml.sample", __FILE__), file)
+    end
+
+    private
+
+    # Decimal integers 1-65535 only (an Integer, or a string of digits); anything else is an error.
+    def parse_risky_ports(entries)
+      return Risk::DEFAULT_PORTS if entries.nil?
+      Array(entries).map do |entry|
+        port = Integer(entry.to_s, 10) if entry.to_s.match?(/\A\d+\z/)
+        raise ArgumentError, "risky_ports: invalid entry '#{entry}' (expected a port number 1-65535)" unless port&.between?(1, 65535)
+        port
+      end.freeze
+    end
+  end
+end