aws-edges 0.8

data/README.md

@@ -0,0 +1,163 @@
+# aws-edges
+
+## Overview
+
+**aws-edges** allows you to created high level graphviz digraphs of your AWS components. Currently this does not cover everything returned from the AWS Ruby SDK, only select components so far. 
+
+## Installation
+
+```
+$ gem install aws-edges
+```
+
+## Usage
+
+```
+$ ./aws-edges -h
+Usage: aws-edges [options]
+    -c, --config [CONFIG_FILE]       Config file
+    -f, --config-format [yaml|json]  Config file format (yaml or json)
+    -a [ACCESS_KEY_ID],              AWS Access Key ID
+        --access-key-id
+    -s [SECRET_ACCESS_KEY],          AWS Secret Access Key
+        --secret-key-id
+    -r, --region [REGION]            AWS Region (ie: us-east-1)
+    -C, --list-colors                Prints out a list of supported colors
+    -S, --list-shapes                Prints out a list of supported shapes
+    -?, --help                       Shows this message
+```
+
+## Configuration Example
+
+There are some examples located in the 'examples' directory. Below is one of them. The *sources* section tells the *aws-edges* script what to pull from AWS. And the rest is pretty self explanatory. 
+
+The basic structure is show below. The `name` key provides the output name of the graph generated. Which will generate both a *.dot* and *.png* file by default. 
+
+```
+---
+  name: "my graph name"
+  rotate: true
+  sources: 
+    - "ec2"
+    - "subnet"
+  edges: 
+    -
+      from: "ec2_hypervisor"
+      from_color: "orange"
+      from_shape: "invhouse"
+      to: "ec2_virtualization_type"
+      to_color: "coral"
+      to_shape: "diamond"
+    -
+      from: "ec2_virtualization_type"
+      to: "ec2_instance_id"
+    -
+      from: "ec2_instance_id"
+      from_color: "dodgerblue"
+      to: "ec2_subnet_id"
+      to_color: "darkturquoise"
+    -
+      from: "subnet_cidr_block"
+      to: "subnet_availability_zone"
+      to_color: "crimson"
+  cluster:
+    label: "Subnet Legend"
+    edges:
+      - 
+        from: "subnet_subnet_id"
+        to: "subnet_cidr_block"
+        to_color: "firebrick"
+```
+### Specifying output format
+
+If you like to save the graph in a different format other than the default `png`. You can specify the `save_as: "pdf"` or some other image format such as tiff. 
+
+### Mapping a 'many' node
+
+What is a 'many' node? Simply put, it is a object containing many entries or an Hash of an Array of Hashes.
+
+The syntax for mapping a 'many' node is `"redshift_cluster_nodes-private_ip_address"`. The `-` character indicating that `redshift_cluster_nodes` is an Array and you want all the `private_ip_address` objects/property.
+
+### Grouping edges
+
+Sometime you would like to visually group a set or sets of edges together so they appear in a container. This can help distinguish the relation between edge objects. You will need to group your objects using the `cluster` key and can label it using something like; `label: "My VPCs"`. Below is an example config snippet:
+
+```
+---
+  name: "example"
+  rotate: true
+  sources: 
+    - "vpc"
+  cluster: 
+    label: "Virtual Private Clouds"
+    edges: 
+      - 
+        to: "vpc_cidr_block"
+        from: "vpc_vpc_id"
+```
+
+### Changing the layout
+
+By default graphs are generated in a horizontal top down structure. If you like a vertical left to right representation you will need to set the `rotate: true` property in your config like so:
+
+```
+$ cat myconfig.yml
+---
+  name: "example"
+  rotate: true
+  sources: 
+    - "vpc"
+    - "ec2"
+    - "subnet"
+```
+
+### Adding edge colors
+
+In order to make it easier to identify groups of like edges, coloring (fill) support has been added. Being that this utilizes the `graph` gem it supports all of the colors supported by it. 
+
+[Visit Graphviz Colors to see what they look like](http://www.graphviz.org/content/color-names)
+
+To see what colors are available run the following command:
+
+```
+$ aws-edges -C
+```
+
+or
+
+```
+$ aws-edges --list-colors
+```
+
+To use colors, in your config simply add either `to_color: "orange"` or `from_color: "brown"` to the `edges` section of the config. (See example above)
+
+### Adding edges shapes
+
+In order to make it easier to identify *like* edges, shape support has been added. As with colors, it supports the shapes available to the `graph` gem on which the gem requires.
+
+[Visit Graphviz Shapes to see what the look like](http://www.graphviz.org/content/node-shapes)
+
+To list the supported shapes, run the following command:
+
+```
+$ aws-edges -S
+```
+
+or
+
+```
+$ aws-edges --list-shapes
+```
+
+To use shapes, in your config simply add either `to_shape: "triangle"` or `from_shape: "egg"` to the `edges` section of the config. (See example above)
+
+## Hacking and Contributing
+
+Fork it and start hacking. Below is a brief summary of the layout of the code.
+
+Inside 'lib/aws-edges' are the classes used. These are kind of categorized by the AWS Ruby SDK "describe*" methods and client types. For example, *subnet.rb* only parses the EC2 *describe-subnets* output. Each class file contains an *initialize* method and a *supported_fields* public method.
+
+The 'config.rb' is used to parse the configuration file (which can be either yaml or json). It uses the *supported_fields* method to validate what is entered in the config. It also contains a *valid_keys*, *valid_sources*, *valid_prefixes*.
+
+'graph.rb' is what creates the graphs.
+

data/SHA256

@@ -0,0 +1 @@
+9076d60c640f2c8a55ca30f030897529861201eb9454fc8de39c8ef16d2e1281 aws-edges-0.7.gem

data/aws-edges.gemspec

@@ -0,0 +1,17 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'aws-edges/version'
+
+Gem::Specification.new 'aws-edges', AWSEdges::VERSION do |s| 
+  s.license = 'GPL-3.0'
+  s.date  = '2016-04-07'
+  s.summary = 'Simple AWS architecture charts'
+  s.description = 'AWS Edges is used to chart out your AWS environments'
+  s.files = `git ls-files`.split("\n") - %w[]
+  s.author  = 'Rick Briganti'
+  s.email = 'jeviolle@newaliases.org'
+  s.homepage  = 'http://github.com/jeviolle/aws-edges'
+  s.add_runtime_dependency 'aws-sdk', '~> 1.34', '>=1.34.0'
+  s.add_runtime_dependency 'graph', '~> 2.6', '>=2.6.0'
+  s.bindir = 'bin'
+  s.executables << 'aws-edges'
+end

data/bin/aws-edges

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+#
+
+$LOAD_PATH.push(File.absolute_path(File.dirname(__FILE__)) + '/../lib')
+
+require 'aws-sdk'
+require 'aws-edges'
+require 'optparse'
+require 'pp'
+
+options = {}
+OptionParser.new do |opts|
+  opts.on('-c','--config [CONFIG_FILE]', 'Config file') do |v|
+    options[:config] = v
+  end
+  opts.on('-a','--access-key-id [ACCESS_KEY_ID]', 'AWS Access Key ID') do |v|
+    options[:access_key_id] = v
+  end
+  opts.on('-s','--secret-key-id [SECRET_ACCESS_KEY]', 'AWS Secret Access Key') do |v|
+    options[:secret_access_key] = v
+  end
+  opts.on('-r','--region [REGION]', 'AWS Region (ie: us-east-1)') do |v|
+    options[:region] = v
+  end
+  opts.on('-C','--list-colors', 'Prints out a list of supported colors') do |v|
+    options[:colors] = v
+  end
+  opts.on('-S','--list-shapes', 'Prints out a list of supported shapes') do |v|
+    options[:shapes] = v
+  end
+  opts.on('-?','--help','Shows this message') do 
+    puts opts
+    exit 255
+  end
+end.parse!
+
+class Array
+  def longest_word
+    group_by(&:size).max.last
+  end
+end
+
+def display_supported(type)
+  display_types = [] 
+
+  case type
+  when "colors"
+    puts
+    puts "http://graphviz.org/content/color-names"
+    display_types = digraph.class::BOLD_COLORS + digraph.class::LIGHT_COLORS
+  when "shapes"
+    puts
+    puts "http://graphviz.org/content/node-shapes"
+    display_types = digraph.class::SHAPES
+  end
+
+  maxlen = display_types.longest_word[0].length
+  puts
+  puts "Supported #{type.capitalize}"
+  puts "----------------"
+  display_types.each_with_index do |obj, idx|
+    if idx.to_i.even?
+      print obj
+      (maxlen - obj.length).times{print " "}
+      print "\t"
+    end
+    puts "#{obj}" if idx.to_i.odd?
+  end
+  puts
+end
+
+if options[:colors] and options[:shapes]
+  %w/colors shapes/.each{|i| display_supported i}
+  exit 255
+elsif options[:colors]
+  display_supported "colors"
+  exit 255
+elsif options[:shapes]
+  display_supported "shapes"
+  exit 255
+end
+
+unless options[:access_key_id] and options[:secret_access_key] and options[:region] and options[:config] 
+  puts "[ERROR] Missing required option, please run with '--help' for more info"
+  exit 1
+end
+
+AWS.config({
+  :access_key_id => options[:access_key_id],
+  :secret_access_key => options[:secret_access_key],
+  :region => options[:region]
+})
+
+# parse config
+config = AWSEdges::Config.new
+config_data = config.parse(options[:config])
+
+aws_sources = config_data.delete('sources')
+aws_data = {
+  :vpc => {}, :subnet => {}, :ec2 => {},
+  :rds => {}, :redshift => {}, :iam => {}
+}
+# run aws clients to describe and retrieve data
+aws_data[:iam] = AWSEdges::IAM.new(AWS::IAM::Client.new).nodes if aws_sources.include?("iam")
+aws_data[:vpc] = AWSEdges::VPC.new(AWS::EC2::Client.new.describe_vpcs.data).nodes if aws_sources.include?("vpc")
+aws_data[:subnet] = AWSEdges::Subnet.new(AWS::EC2::Client.new.describe_subnets.data).nodes if aws_sources.include?("subnet")
+aws_data[:ec2] = AWSEdges::EC2.new(AWS::EC2::Client.new.describe_instances.data).nodes if aws_sources.include?("ec2")
+aws_data[:rds] = AWSEdges::RDS.new(AWS::RDS::Client.new.describe_db_instances.data).nodes if aws_sources.include?("rds")
+aws_data[:redshift] = AWSEdges::Redshift.new(AWS::Redshift::Client.new.describe_clusters.data).nodes if aws_sources.include?("redshift")
+
+# graph a graph based on the config and inputs
+grapher = AWSEdges::Graph.new(config_data, aws_data)
+grapher.create_graph()

data/examples/config.yml

@@ -0,0 +1,34 @@
+---
+  name: "my graph name"
+  rotate: true
+  sources: 
+    - "ec2"
+    - "subnet"
+  edges: 
+    -
+      from: "ec2_hypervisor"
+      from_color: "orange"
+      from_shape: "invhouse"
+      to: "ec2_virtualization_type"
+      to_color: "coral"
+      to_shape: "diamond"
+    -
+      from: "ec2_virtualization_type"
+      to: "ec2_instance_id"
+    -
+      from: "ec2_instance_id"
+      from_color: "dodgerblue"
+      to: "ec2_subnet_id"
+      to_color: "darkturquoise"
+    -
+      from: "subnet_cidr_block"
+      to: "subnet_availability_zone"
+      to_color: "crimson"
+  cluster:
+    label: "Subnet Legend"
+    edges:
+      - 
+        from: "subnet_subnet_id"
+        to: "subnet_cidr_block"
+        to_color: "firebrick"
+

data/examples/iam.yml

@@ -0,0 +1,23 @@
+---
+  name: "iam_structure"
+  rotate: True
+  sources:
+    - "iam"
+  edges:
+    -
+      from_color: "lightseagreen"
+      from: "iam_user_name"
+      to_shape: "note"
+      to_color: "peru"
+      to: "iam_user_policies-policy_name"
+    -
+      from_color: "lightseagreen"
+      from: "iam_users-user_name"
+      to: "iam_group_name"
+    -
+      from_shape: "folder"
+      from_color: "orange"
+      from: "iam_group_name"
+      to: "iam_group_policies-policy_name"
+      to_color: "peru"
+      to_shape: "note"

data/lib/aws-edges.rb

@@ -0,0 +1,19 @@
+require 'json'
+require 'yaml'
+require 'graph'
+require 'aws-edges/vpc.rb'
+require 'aws-edges/subnet.rb'
+require 'aws-edges/iam.rb'
+require 'aws-edges/ec2.rb'
+require 'aws-edges/rds.rb'
+require 'aws-edges/redshift.rb'
+require 'aws-edges/version.rb'
+require 'aws-edges/config.rb'
+require 'aws-edges/graph.rb'
+
+##
+# AWS Edges creates a simple chart of your
+# current AWS environment. 
+#
+module AWSEdges
+end

data/lib/aws-edges/config.rb

@@ -0,0 +1,166 @@
+module AWSEdges
+  class Config
+    @@valid_keys = ["name", "sources", "cluster", "label", "edges", 
+                    "from", "from_shape", "from_color", 
+                    "to", "to_shape", "to_color" ,"rotate", "save_as"]
+    @@valid_sources = ["VPC","EC2","RDS","Redshift","Subnet","IAM"]
+    @@valid_prefixes = @@valid_sources
+
+    def initialize
+      @node_types = @@valid_sources.map{|s| 
+        eval "AWSEdges::#{s}.supported_fields.map{|f| s.downcase + '_' + f}"
+      }.flatten
+    end
+
+    def msg_and_exit(msg)
+      puts msg
+      exit 1
+    end
+
+    ##
+    # Validate the source section of the config file
+    #
+    def validate_sources(sources)
+      msg_and_exit("No sources specified in the config") if sources.nil?
+      sources.each do |source|
+        unless @@valid_sources.map{|i| i.downcase}.include?(source)
+          msg_and_exit("Invalid source detected in config: #{source}")
+        end
+      end
+    end
+
+    ##
+    # Verify that a graph name is specified in the config
+    #
+    def validate_name(graph_name)
+      msg_and_exit("No graph name specified in the config") if graph_name.nil?
+    end
+
+    ##
+    # Confirm that from and to edges are specified properly and are 
+    # not a many-to-many relationship
+    def validate_nodes(hashed_data)
+      nodes = []
+      hashed_data.each do |k,v|
+        if k == "edges"
+          v.each{|e| 
+            if e["from"].include?('-') and e["to"].include?('-')
+              msg_and_exit("Error: from many to many edges detected in config:\n (#{e['from']}) -> (#{e['to']})")
+            end
+            nodes.push e["from"]
+            nodes.push e["to"]
+          } 
+        end
+        nodes.push(validate_nodes(v)) if v.class == Hash
+      end
+      nodes.flatten.uniq.each do |u|
+        unless @node_types.include?(u)
+          msg_and_exit("Invalid edge node specified: #{u}")
+        end
+      end
+    end
+
+    ##
+    # Internal method for testing a color
+    private def test_color(color)
+      colors = digraph.class::BOLD_COLORS + digraph.class::LIGHT_COLORS
+      msg_and_exit("Invalid color specified: #{color}") unless colors.include?(color) 
+    end
+
+    ##
+    # Verify that the colors defined are supported by the 
+    # underlying Graph gem
+    def validate_colors(hashed_data)
+      hashed_data.each do |k,v|
+        if k == "edges"
+          v.each{|e|
+            if e["from_color"]
+              test_color(e["from_color"])
+            end
+
+            if e["to_color"]
+              test_color(e["to_color"])
+            end
+          }
+        end
+      end
+    end
+
+    ##
+    # Internal method for testing a shape
+    private def test_shape(shape)
+      shapes = digraph.class::SHAPES
+      msg_and_exit("Invalid shape specified: #{shape}") unless shapes.include?(shape)
+    end
+
+    ##
+    # Verify that the shapes defined are supported by the 
+    # underlying Graph gem
+    def validate_shapes(hashed_data)
+      hashed_data.each do |k,v|
+        if k == "edges"
+          v.each{|e|
+            if e["from_shape"]
+              test_shape(e["from_shape"])
+            end
+
+            if e["to_shape"]
+              test_shape(e["to_shape"])
+            end
+          }
+        end
+      end
+    end
+
+    ##
+    # Validate that the 'keys' are valid in the config
+    def validate_keys(hashed_data)
+      keys = []
+      hashed_data.each do |k,v|
+        unless k == "edges"
+          keys.push(k)
+          keys.push(validate_keys(v)) if v.class == Hash 
+        else
+          v.each{|e|
+            keys.push(validate_keys(e)) 
+          }
+        end
+      end
+      keys.flatten.uniq.each do |u|
+        unless @@valid_keys.include?(u)
+          msg_and_exit("Invalid key found in config: #{u}")
+        end
+      end
+    end
+
+    ##
+    # Attempt to parse the json/yaml config and run through
+    # validation
+    def parse(config_file)
+      begin
+        contents = File.read(config_file)
+      rescue Exception => e
+        msg_and_exit("Failed to read config: #{e.message}")
+      end
+
+      begin
+        config = YAML.load(contents)
+      rescue Exception => e
+        config = JSON.parse(contents)
+      rescue Exception => e
+        msg_and_exit("Failed to parse config: #{e.message}")
+      end
+
+      # run through validation checks
+      validate_keys(config)
+      validate_colors(config)
+      validate_shapes(config)
+      validate_sources(config['sources'])
+      validate_nodes(config)
+      validate_name(config['name'])
+
+      return config
+    end
+
+  end
+end