aws_security_viz 0.2.5.pre.alpha.pre.34 → 1.0.0

data/lib/aws_security_viz/graph_filter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "directed_graph"
+
+module AwsSecurityViz
+  class GraphFilter
+    def initialize(graph)
+      @graph = graph
+    end
+
+    def filter(source, destination)
+      return @graph if source.nil? && destination.nil?
+      return @graph.induced(@graph.reachable_from(source)) if destination.nil?
+      return @graph.induced(@graph.reverse.reachable_from(destination)) if source.nil?
+      # Keep every vertex on some path source -> destination: reachable from the
+      # source and able to reach the destination. Two searches, O(V+E).
+      @graph.induced(@graph.reachable_from(source) & @graph.reverse.reachable_from(destination))
+    end
+  end
+end

data/lib/aws_security_viz/logging.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module AwsSecurityViz
+  # Diagnostics (warnings, errors, debug output) go to stderr so stdout stays clean for output.
+  def self.logger
+    @logger ||= build_logger($stderr)
+  end
+
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  def self.build_logger(io)
+    Logger.new(io, formatter: proc { |severity, _time, _prog, msg| "[#{severity}] #{msg}\n" })
+  end
+end

data/lib/aws_security_viz/model.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "port_label"
+
+module AwsSecurityViz
+  # Where a rule's traffic comes from or goes to. kind is :cidr4, :cidr6, :prefix_list or :group;
+  # id is the CIDR, prefix list id or group id and name is what exclusions and labels match on.
+  # description is the free-text rule description (nil or empty when none was given).
+  Peer = Data.define(:kind, :id, :name, :description) do
+    def initialize(kind:, id:, name: nil, description: nil)
+      super(kind: kind, id: id, name: name || id, description: description)
+    end
+  end
+
+  Rule = Data.define(:protocol, :from_port, :to_port, :peers) do
+    def port_range
+      PortLabel.format(protocol, from_port, to_port)
+    end
+  end
+
+  # region is only set when several regions are queried, so nodes can be grouped by region.
+  # unused is true only when --show-unused found no network interface attached to the group.
+  SecurityGroup = Data.define(:id, :name, :vpc_id, :ingress, :egress, :region, :unused) do
+    def initialize(id:, name:, vpc_id:, ingress:, egress:, region: nil, unused: false)
+      super
+    end
+
+    # Builds a group from a describe-security-groups hash with snake_case keys (see Model.normalize).
+    def self.from_hash(hash)
+      new(
+        id: hash[:group_id], name: hash[:group_name], vpc_id: hash[:vpc_id],
+        ingress: (hash[:ip_permissions] || []).map { |ip| Rule.from_hash(ip) },
+        egress: (hash[:ip_permissions_egress] || []).map { |ip| Rule.from_hash(ip) }
+      )
+    end
+  end
+
+  class Rule
+    def self.from_hash(ip)
+      peers = (ip[:ip_ranges] || []).map { |r| Peer.new(kind: :cidr4, id: r[:cidr_ip], description: r[:description]) } +
+        (ip[:ipv6_ranges] || []).map { |r| Peer.new(kind: :cidr6, id: r[:cidr_ipv6], description: r[:description]) } +
+        (ip[:prefix_list_ids] || []).map { |r| Peer.new(kind: :prefix_list, id: r[:prefix_list_id], description: r[:description]) } +
+        (ip[:user_id_group_pairs] || []).map { |g| Peer.new(kind: :group, id: g[:group_id] || g[:group_name], name: g[:group_name], description: g[:description]) }
+      new(protocol: ip[:ip_protocol], from_port: ip[:from_port], to_port: ip[:to_port], peers: peers)
+    end
+  end
+
+  # descriptions: the non-empty rule descriptions behind this traffic, as {ports:, text:} hashes.
+  # risky: public ingress on a sensitive port (see Risk), decided on the real rule.
+  Traffic = Data.define(:ingress, :from, :to, :port_range, :descriptions, :risky) do
+    def initialize(ingress:, from:, to:, port_range:, descriptions: [], risky: false)
+      super
+    end
+
+    def self.grouped(traffic_list)
+      t = traffic_list.first
+      port_range = PortLabel.normalise(traffic_list.collect(&:port_range).join(","))
+      new(ingress: t.ingress, from: t.from, to: t.to, port_range: port_range,
+        descriptions: traffic_list.flat_map(&:descriptions).uniq, risky: traffic_list.any?(&:risky))
+    end
+  end
+
+  module Model
+    # Deep-converts the AWS CLI's PascalCase keys (and the SDK's ipv_6 spelling) to snake_case symbols.
+    def self.normalize(value)
+      case value
+      when Hash then value.to_h { |k, v| [key(k), normalize(v)] }
+      when Array then value.map { |v| normalize(v) }
+      else value
+      end
+    end
+
+    def self.key(name)
+      name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.sub("ipv_6", "ipv6").to_sym
+    end
+
+    # EC2 often omits GroupName in group peers; take it from the described groups so name-based
+    # exclusions and labels see the real name (an id is the last resort).
+    def self.resolve_peer_names(groups)
+      names = groups.to_h { |g| [g.id, g.name] }
+      resolve = ->(rule) {
+        rule.with(peers: rule.peers.map { |p| (p.kind == :group && p.name == p.id) ? p.with(name: names[p.id] || p.id) : p })
+      }
+      groups.map { |g| g.with(ingress: g.ingress.map(&resolve), egress: g.egress.map(&resolve)) }
+    end
+  end
+end

data/lib/aws_security_viz/obfuscation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AwsSecurityViz
+  # Replaces names, ids and port labels with short stable hashes. It runs on the finished
+  # graph (after merging and filtering), so filters still match real names and ids and
+  # merged edges keep deduplicated, hashed port tokens.
+  module Obfuscation
+    LENGTH = 10
+
+    def self.apply(nodes, edges)
+      [
+        nodes.map { |key, opts| [hash(key), node_opts(opts)] },
+        edges.map { |from, to, opts| [hash(from), hash(to), hash_edge_opts(opts)] }
+      ]
+    end
+
+    def self.node_opts(opts)
+      %i[label vpc_id region group_id].each_with_object(opts.dup) { |field, hashed|
+        hashed[field] = hash(opts[field]) if opts.key?(field) && !opts[field].nil?
+      }
+    end
+
+    def self.hash_edge_opts(opts)
+      hashed = opts.merge(label: hash_tokens(opts[:label]))
+      hashed[:descriptions] = hash_descriptions(opts[:descriptions]) if opts.key?(:descriptions)
+      hashed
+    end
+
+    # Free text can name people and systems, so descriptions are hashed like everything else.
+    def self.hash_descriptions(descriptions)
+      descriptions.to_a.map { |d| {ports: hash_tokens(d[:ports]), text: hash(d[:text])} }
+    end
+
+    # Hash each comma-separated port token so that one token always maps to the same value.
+    def self.hash_tokens(label)
+      label.to_s.split(",").map { |token| hash(token) }.join(",")
+    end
+
+    def self.hash(text)
+      Digest::SHA256.hexdigest(text.to_s)[0, LENGTH]
+    end
+  end
+end

data/lib/{opts.yml.sample → aws_security_viz/opts.yml.sample}

@@ -1,6 +1,8 @@
 --- 
 :format: dot
 #:egress: true
+# Ports flagged when open to 0.0.0.0/0 or ::/0 (all-traffic rules always are):
+#:risky_ports: [22, 3389, 3306, 5432, 1433, 6379, 9200, 27017]
 #:exclude: 
 #- .*test.*
 #- .*perf.*

data/lib/aws_security_viz/port_label.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AwsSecurityViz
+  # Edge labels are comma-joined tokens such as "22/tcp", "1000-2000/udp", "icmp" or "proto 50",
+  # or "all" for all traffic.
+  module PortLabel
+    ALL = "all"
+    PROTOCOL_NAMES = {"1" => "icmp", "6" => "tcp", "17" => "udp", "58" => "icmpv6"}.freeze
+    ICMP = %w[icmp icmpv6].freeze
+
+    # Label for one permission. For tcp/udp from/to are ports; for icmp they are the type and code
+    # (-1 meaning any); other protocols carry no ports and are shown by name or number.
+    def self.format(protocol, from, to)
+      protocol = protocol.to_s
+      return ALL if protocol == "-1"
+      name = PROTOCOL_NAMES.fetch(protocol, protocol)
+      return icmp(name, from, to) if ICMP.include?(name)
+      return "proto #{name}" if name.match?(/\A\d+\z/)
+      return name if from.nil? && to.nil?
+      "#{[from, to].uniq.join("-")}/#{name}"
+    end
+
+    def self.icmp(name, type, code)
+      return name if type.nil? || type == -1
+      (code.nil? || code == -1) ? "#{name} #{type}" : "#{name} #{type}/#{code}"
+    end
+    private_class_method :icmp
+
+    TOKEN = %r{\A(-?\d+)(?:-(-?\d+))?/(.*)\z}
+
+    # Deduplicates tokens and sorts them by from port, then protocol; "all" swallows everything else.
+    def self.normalise(label)
+      tokens = label.to_s.split(",").uniq
+      return ALL if tokens.include?(ALL)
+      tokens.sort_by { |token| sort_key(token) }.join(",")
+    end
+
+    def self.sort_key(token)
+      match = TOKEN.match(token)
+      return [1, 0, "", 0, token] unless match
+      [0, match[1].to_i, match[3], (match[2] || match[1]).to_i, token]
+    end
+  end
+end

data/lib/aws_security_viz/provider/ec2.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "aws-sdk-ec2"
+require_relative "../model"
+require_relative "../logging"
+
+module AwsSecurityViz
+  class Ec2Provider
+    # Per-region failures that must not abort a multi-region run (region not enabled, no permission).
+    SKIPPABLE_ERRORS = [Aws::EC2::Errors::UnauthorizedOperation, Aws::EC2::Errors::AuthFailure, Aws::EC2::Errors::OptInRequired].freeze
+
+    # client: a single injected client (used as-is, one region); otherwise one client is built per region.
+    def initialize(options, client: nil)
+      @options = options
+      @client = client
+    end
+
+    def security_groups
+      regions = @client ? [nil] : region_list
+      errors = []
+      groups = regions.flat_map do |region|
+        describe(@client || build_client(region), (regions.size > 1) ? region : nil)
+      rescue *SKIPPABLE_ERRORS => e
+        raise if regions.size == 1
+        AwsSecurityViz.logger.warn("skipping region #{region}: #{e.class.name.split("::").last}: #{e.message}")
+        errors << e
+        []
+      end
+      raise errors.first if errors.size == regions.size
+      Model.resolve_peer_names(groups)
+    end
+
+    private
+
+    def describe(client, region)
+      params = {}
+      params[:filters] = [{name: "vpc-id", values: [@options[:vpc_id]]}] if @options[:vpc_id]
+      groups = client.describe_security_groups(params).flat_map { |page|
+        page.security_groups.collect { |sg| SecurityGroup.from_hash(Model.normalize(sg.to_h)).with(region: region) }
+      }
+      return groups unless @options[:show_unused]
+      used = begin
+        attached_group_ids(client, params)
+      rescue Aws::EC2::Errors::UnauthorizedOperation
+        # Without the permission the groups are still worth drawing; just leave them unmarked.
+        AwsSecurityViz.logger.warn("--show-unused needs ec2:DescribeNetworkInterfaces; no groups are marked unused#{" in #{region}" if region}")
+        return groups
+      end
+      groups.map { |g| g.with(unused: !used.include?(g.id)) }
+    end
+
+    # Ids of groups attached to at least one network interface (extra call, only for --show-unused).
+    def attached_group_ids(client, params)
+      client.describe_network_interfaces(params).each_with_object(Set.new) { |page, ids|
+        page.network_interfaces.each { |eni| eni.groups.each { |g| ids << g.group_id } }
+      }
+    end
+
+    # [nil] means one client on the SDK default region chain (AWS_REGION, profile).
+    def region_list
+      names = @options[:region].to_s.split(",").map(&:strip).reject(&:empty?).uniq
+      # With --all-regions, -r only names the region used to call DescribeRegions.
+      return build_client(names.first).describe_regions.regions.map(&:region_name).sort if @options[:all_regions]
+      names.empty? ? [nil] : names
+    end
+
+    def build_client(region)
+      Aws::EC2::Client.new(client_options(@options, region))
+    end
+
+    # An explicit profile wins over static keys so the SSO/shared-config login is used.
+    def client_options(options, region)
+      conn_opts = {region: region, profile: options[:profile]}
+      unless options[:profile]
+        conn_opts.merge!(
+          access_key_id: options[:access_key],
+          secret_access_key: options[:secret_key],
+          session_token: options[:session_token]
+        )
+      end
+      conn_opts.delete_if { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/aws_security_viz/provider/json.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../model"
+
+module AwsSecurityViz
+  class JsonProvider
+    def initialize(options)
+      @groups = Model.normalize(JSON.parse(File.read(options[:source_file]))["SecurityGroups"])
+      @groups = @groups.select { |sg| sg[:vpc_id] == options[:vpc_id] } if options[:vpc_id]
+    end
+
+    def security_groups
+      Model.resolve_peer_names(@groups.map { |sg| SecurityGroup.from_hash(sg) })
+    end
+  end
+end

data/lib/aws_security_viz/renderer/all.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "html"
+require_relative "json"
+require_relative "graphviz"
+require_relative "mermaid"
+module AwsSecurityViz
+  module Renderer
+    ALL = {graphviz: Renderer::GraphViz, json: Renderer::Json, html: Renderer::Html, mermaid: Renderer::Mermaid}
+    DEFAULT = "html"
+    EXTENSIONS = {
+      "html" => :html, "htm" => :html, "json" => :json, "mmd" => :mermaid,
+      "dot" => :graphviz, "gv" => :graphviz
+    }.merge(GraphViz::IMAGE_EXTENSIONS.to_h { |e| [e, :graphviz] }) { |_, mine, _| mine }.freeze
+
+    # Without an explicit renderer the output file's extension decides (see .infer).
+    def self.pick(r, output_file, config)
+      ALL.fetch(validate!(r || infer(output_file))).new(output_file, config)
+    end
+
+    # Renderer implied by the file extension; html when there is no file name. An unknown or missing extension
+    # goes to graphviz, which rejects it with a message listing the usable extensions.
+    def self.infer(file_name)
+      return DEFAULT.to_sym if file_name.nil?
+      EXTENSIONS.fetch(File.extname(file_name.to_s).delete_prefix(".").downcase, :graphviz)
+    end
+
+    # Returns the renderer as a symbol, or raises listing the valid choices.
+    def self.validate!(r)
+      name = (r || DEFAULT).to_s
+      return name.to_sym if ALL.key?(name.to_sym)
+      raise ArgumentError, "unknown renderer '#{name}' (choose from: #{all.join(", ")})"
+    end
+
+    # Default output file name: an image for graphviz, text for mermaid, JSON data for json, a page for html.
+    def self.default_file(r)
+      case validate!(r)
+      when :graphviz then "aws-security-viz.png"
+      when :mermaid then "aws-security-viz.#{Renderer::Mermaid::DEFAULT_EXTENSION}"
+      when :json then "aws-security-viz.json"
+      else "aws-security-viz.html"
+      end
+    end
+
+    def self.all
+      ALL.keys
+    end
+  end
+end

data/lib/aws_security_viz/renderer/graphviz.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module AwsSecurityViz
+  module Renderer
+    # Builds DOT text directly. `.dot`/`.gv` output is the text itself and needs no Graphviz;
+    # any other extension is rendered by piping the text through `dot -T<ext> -K<layout>`.
+    class GraphViz
+      DOT_EXTENSIONS = %w[dot gv].freeze
+      IMAGE_EXTENSIONS = %w[png svg pdf jpg jpeg gif webp bmp tiff ps eps json].freeze
+      UNUSED_ATTRS = {style: "dashed,filled", fillcolor: "lightgrey", fontcolor: "gray30", tooltip: "Unused: no network interfaces attached"}.freeze
+      GRAPH_ATTRS = {overlap: false, splines: true, sep: 1, concentrate: true, rankdir: "LR"}.freeze
+
+      def initialize(file_name, config)
+        @file_name = file_name
+        @config = config
+        @nodes = {}
+        @clusters = {}
+        @root_nodes = []
+        @edges = []
+      end
+
+      def add_node(name, opts)
+        @nodes[name] ||= begin
+          node_attrs = {label: opts[:label] || name}
+          node_attrs.merge!(UNUSED_ATTRS) if opts[:unused]
+          line = "#{quote(name)} [#{attrs(node_attrs)}];"
+          if opts[:vpc_id].nil? && opts[:region].nil?
+            @root_nodes << line
+          else
+            (@clusters[[opts[:region], opts[:vpc_id]]] ||= []) << line
+          end
+          true
+        end
+      end
+
+      def add_edge(from, to, opts)
+        add_node(from, {})
+        add_node(to, {})
+        # Edges live in the root graph: an edge inside a cluster would pull its other endpoint in.
+        edge_attrs = {style: "bold"}.merge(opts.except(:descriptions, :risky))
+        edge_attrs = edge_attrs.merge(color: "crimson", style: "dashed", penwidth: 3) if opts[:risky]
+        edge_attrs[:tooltip] = tooltip(opts[:descriptions]) unless opts[:descriptions].to_a.empty?
+        @edges << "#{quote(from)} -> #{quote(to)} [#{attrs(edge_attrs)}];"
+      end
+
+      def to_dot
+        lines = ["digraph \"G\" {"]
+        lines << "  graph [#{attrs(GRAPH_ATTRS)}];"
+        @clusters.group_by { |(region, _), _| region }.each do |region, entries|
+          indent = region ? "    " : "  "
+          body = entries.flat_map { |(_, vpc_id), node_lines| vpc_block(vpc_id, region, node_lines, indent) }
+          lines.concat(region ? cluster(region, body) : body)
+        end
+        (@root_nodes + @edges).each { |l| lines << "  #{l}" }
+        lines << "}"
+        lines.join("\n") + "\n"
+      end
+
+      def output
+        engine = @config.layout # validates the engine even when no image is rendered
+        format = File.extname(@file_name.to_s).delete_prefix(".").downcase
+        return File.write(@file_name, to_dot) if DOT_EXTENSIONS.include?(format)
+
+        unless IMAGE_EXTENSIONS.include?(format)
+          shown = format.empty? ? "no file extension" : "unknown file extension '.#{format}'"
+          raise ArgumentError, "cannot pick an output format from #{@file_name.to_s.inspect}: #{shown} (supported: .html, .json, .mmd, .dot/.gv, or an image: #{(IMAGE_EXTENSIONS - %w[json]).map { |e| ".#{e}" }.join(", ")})"
+        end
+        raise ArgumentError, "Graphviz 'dot' not found; install graphviz" unless on_path?("dot")
+        image, err, status = Open3.capture3("dot", "-T#{format}", "-K#{engine}", stdin_data: to_dot, binmode: true)
+        raise ArgumentError, "Graphviz failed: #{err.strip}" unless status.success?
+        File.binwrite(@file_name, image)
+      end
+
+      private
+
+      # Nodes of one VPC (or loose nodes of a region without a VPC), indented.
+      def vpc_block(vpc_id, region, node_lines, indent)
+        return node_lines.map { |l| "#{indent}#{l}" } unless vpc_id
+        id = region ? "cluster_#{region}/#{vpc_id}" : "cluster_#{vpc_id}"
+        ["#{indent}subgraph #{quote(id)} {", "#{indent}  label=#{quote(vpc_id)};"] +
+          node_lines.map { |l| "#{indent}  #{l}" } + ["#{indent}}"]
+      end
+
+      # One line per rule description, prefixed by its ports; quote() escapes the free text.
+      def tooltip(descriptions)
+        descriptions.map { |d| "#{d[:ports]}: #{d[:text]}" }.join("\n")
+      end
+
+      def cluster(region, body)
+        ["  subgraph #{quote("cluster_#{region}")} {", "    label=#{quote(region)};"] + body + ["  }"]
+      end
+
+      # Quotes an ID or label for DOT: backslash and double quote are escaped, newlines become \n.
+      # A backslash is escaped too, so a literal "\N" in data cannot be read as a Graphviz escape.
+      def quote(value)
+        escaped = value.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\\"' }.gsub(/\r\n|\r|\n/) { "\\n" }
+        "\"#{escaped}\""
+      end
+
+      def attrs(opts)
+        opts.map { |k, v| "#{k}=#{quote(v)}" }.join(", ")
+      end
+
+      def on_path?(command)
+        pathext = ENV.fetch("PATHEXT", "").split(File::PATH_SEPARATOR).reject(&:empty?)
+        # PATHEXT is upper case (.EXE) but the file is usually dot.exe; only Windows matches case-insensitively.
+        suffixes = [""] + pathext.flat_map { |ext| [ext, ext.downcase] }.uniq
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir|
+          suffixes.any? { |suffix|
+            path = File.join(dir, command + suffix)
+            File.file?(path) && File.executable?(path)
+          }
+        }
+      end
+    end
+  end
+end

data/lib/aws_security_viz/renderer/html.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AwsSecurityViz
+  module Renderer
+    # Writes one self-contained .html file: the vendored Cytoscape.js and the graph data are inlined, so it
+    # opens from file:// with no network access. Data only reaches the page as JSON (see viewer.html, which
+    # builds the DOM with textContent), never as markup.
+    class Html
+      TEMPLATE = File.expand_path("../export/html/viewer.html", __dir__)
+      CYTOSCAPE = File.expand_path("../vendor/cytoscape/cytoscape.min.js", __dir__)
+
+      def initialize(file_name, config)
+        @file_name = file_name
+        @config = config
+        @nodes = []
+        @edges = []
+      end
+
+      def add_node(name, opts)
+        @nodes << {id: name, label: opts[:label] || name, vpc: opts[:vpc_id], region: opts[:region], unused: (true if opts[:unused])}.compact
+      end
+
+      def add_edge(from, to, opts)
+        edge = {id: "#{from}-#{to}", source: from, target: to, label: opts[:label], kind: (opts[:color] == :red) ? "egress" : "ingress"}
+        edge[:descriptions] = opts[:descriptions] if opts[:descriptions]
+        edge[:risky] = true if opts[:risky]
+        @edges << edge
+      end
+
+      def output
+        parts = {"/*CYTOSCAPE*/" => File.read(CYTOSCAPE), "/*DATA*/" => json_for_script({nodes: @nodes, edges: @edges})}
+        # One pass, so neither inlined part can be mistaken for the other's placeholder.
+        File.write(@file_name, File.read(TEMPLATE).gsub(%r{/\*(?:CYTOSCAPE|DATA)\*/}) { |marker| parts.fetch(marker) })
+      end
+
+      private
+
+      # "<" is escaped so no value can close the script element or open a comment.
+      def json_for_script(data)
+        data.to_json.gsub("<", "\\u003c")
+      end
+    end
+  end
+end

data/lib/aws_security_viz/renderer/json.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AwsSecurityViz
+  module Renderer
+    class Json
+      def initialize(file_name, config)
+        @nodes = []
+        @edges = []
+        @file_name = file_name
+        @config = config
+      end
+
+      def add_node(name, opts)
+        @nodes << {id: name, label: opts[:label] || name, region: opts[:region], unused: (true if opts[:unused])}.compact
+      end
+
+      def add_edge(from, to, opts)
+        edge = {id: "#{from}-#{to}", source: from, target: to, label: opts[:label]}
+        edge[:descriptions] = opts[:descriptions] if opts[:descriptions]
+        edge[:risky] = true if opts[:risky]
+        @edges << edge
+      end
+
+      def output
+        IO.write(@file_name, {nodes: @nodes, edges: @edges}.to_json)
+      end
+    end
+  end
+end

data/lib/aws_security_viz/renderer/mermaid.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module AwsSecurityViz
+  module Renderer
+    # Writes a Mermaid flowchart (.mmd). Node and subgraph ids are generated (n0, g0, ...) so no
+    # data can break the syntax; names, ports and VPC/region titles only appear as quoted labels.
+    # Rule descriptions have no Mermaid equivalent (no tooltips) and are left out.
+    class Mermaid
+      DEFAULT_EXTENSION = "mmd"
+      RISKY_STYLE = "stroke:#dc143c,stroke-width:4px,stroke-dasharray:6 3"
+      UNUSED_STYLE = "fill:#eeeeee,stroke:#888888,stroke-dasharray:4 2,color:#555555"
+      MAX_EDGES = 500 # Mermaid's default maxEdges
+      MAX_TEXT_SIZE = 50_000 # Mermaid's default maxTextSize
+      EDGE_STYLES = {blue: "stroke:#1f5fbf", red: "stroke:#c0392b"}.freeze
+
+      def initialize(file_name, config)
+        @file_name = file_name
+        @config = config
+        @ids = {}
+        @labels = {}
+        @unused = []
+        @groups = {}
+        @edges = []
+      end
+
+      def add_node(name, opts)
+        id = node_id(name)
+        return if @labels.key?(id)
+        @labels[id] = opts[:label] || name
+        @unused << id if opts[:unused]
+        (@groups[[opts[:region], opts[:vpc_id]]] ||= []) << id if opts[:vpc_id] || opts[:region]
+      end
+
+      def add_edge(from, to, opts)
+        add_node(from, {})
+        add_node(to, {})
+        @edges << [node_id(from), node_id(to), opts]
+      end
+
+      def to_mermaid
+        lines = ["flowchart LR"]
+        grouped = @groups.values.flatten
+        sequence = 0
+        @groups.group_by { |(region, _), _| region }.each do |region, entries|
+          indent = region ? "    " : "  "
+          lines << "  subgraph g#{sequence += 1}[#{quote(region)}]" if region
+          entries.each do |(_, vpc_id), ids|
+            if vpc_id
+              lines << "#{indent}subgraph g#{sequence += 1}[#{quote(vpc_id)}]"
+              ids.each { |id| lines << "#{indent}  #{node(id)}" }
+              lines << "#{indent}end"
+            else
+              ids.each { |id| lines << "#{indent}#{node(id)}" }
+            end
+          end
+          lines << "  end" if region
+        end
+        (@labels.keys - grouped).each { |id| lines << "  #{node(id)}" }
+        @edges.each { |from, to, opts| lines << "  #{from} #{arrow(opts)} #{to}" }
+        @edges.each_with_index do |(_, _, opts), index|
+          style = opts[:risky] ? RISKY_STYLE : EDGE_STYLES[opts[:color]]
+          lines << "  linkStyle #{index} #{style}" if style
+        end
+        unless @unused.empty?
+          lines << "  classDef unused #{UNUSED_STYLE}"
+          lines << "  class #{@unused.join(",")} unused"
+        end
+        lines.join("\n") + "\n"
+      end
+
+      def output
+        text = to_mermaid
+        warn_if_large(text)
+        File.write(@file_name, text)
+      end
+
+      private
+
+      def warn_if_large(text)
+        return if @edges.size <= MAX_EDGES && text.size <= MAX_TEXT_SIZE
+        AwsSecurityViz.logger.warn("mermaid output has #{@edges.size} edges and #{text.size} characters (Mermaid defaults: maxEdges #{MAX_EDGES}, maxTextSize #{MAX_TEXT_SIZE}); GitHub and mmdc may refuse to render it")
+      end
+
+      def node_id(name)
+        @ids[name] ||= "n#{@ids.size}"
+      end
+
+      def node(id)
+        "#{id}[#{quote(@labels[id])}]"
+      end
+
+      def arrow(opts)
+        label = opts[:label].to_s
+        label.empty? ? "-->" : "-->|#{quote(label)}|"
+      end
+
+      # Mermaid quoted text takes HTML-style entity codes; '#' goes first so it never re-escapes.
+      def quote(value)
+        escaped = value.to_s.gsub("#", "#35;").gsub('"', "#quot;").gsub("<", "#lt;").gsub(">", "#gt;")
+          .gsub("`", "#96;").gsub(/\r\n|\r|\n/, " ")
+        "\"#{escaped}\""
+      end
+    end
+  end
+end