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

data/lib/aws_security_viz/cli.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+require_relative "logging"
+require_relative "../aws_security_viz"
+
+module AwsSecurityViz
+  # Command line front end: `CLI.new(argv).run` returns the exit status (0, 1, or 130 on Ctrl-C).
+  class CLI
+    RISK_EXIT = 2
+
+    def initialize(argv, env: ENV, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @env = env
+      @out = out
+      @err = err
+    end
+
+    def run
+      AwsSecurityViz.logger = AwsSecurityViz.build_logger(@err)
+      opts = defaults
+      parser = build_parser(opts)
+      begin
+        parser.parse!(@argv)
+      rescue OptionParser::ParseError => e
+        AwsSecurityViz.logger.error("#{e.message} (try --help)")
+        return 1
+      end
+      return 0 if opts[:exit]
+      command = @argv.shift
+      unknown = [command, *@argv].compact.reject { |a| a == command && %w[setup init].include?(a) }
+      unless unknown.empty?
+        AwsSecurityViz.logger.error("unknown command '#{unknown.first}' (expected setup or init; try --help)")
+        return 1
+      end
+      return setup(opts) if command
+      if opts[:source_file] && (opts[:region] || opts[:all_regions])
+        AwsSecurityViz.logger.warn("--region and --all-regions are ignored with --source-file")
+      end
+      if opts[:source_file] && opts[:show_unused]
+        AwsSecurityViz.logger.warn("--show-unused is ignored with --source-file: network interfaces are not part of describe-security-groups output")
+        opts.delete(:show_unused)
+      end
+      visualize(opts)
+    end
+
+    private
+
+    def defaults
+      {
+        access_key: @env["AWS_ACCESS_KEY"] || @env["AWS_ACCESS_KEY_ID"],
+        secret_key: @env["AWS_SECRET_KEY"] || @env["AWS_SECRET_ACCESS_KEY"],
+        session_token: @env["AWS_SESSION_TOKEN"],
+        config: "opts.yml",
+        color: false,
+        debug: nil,
+        obfuscate: nil
+      }
+    end
+
+    def build_parser(opts)
+      OptionParser.new do |o|
+        o.banner = "Usage: aws_security_viz [options] [setup|init]"
+        o.on("-a", "--access-key=KEY", "AWS access key") { |v| opts[:access_key] = v }
+        o.on("-s", "--secret-key=KEY", "AWS secret key") { |v| opts[:secret_key] = v }
+        o.on("-e", "--session-token=TOKEN", "AWS session token") { |v| opts[:session_token] = v }
+        o.on("-r", "--region=REGION", "AWS region(s) to query, comma-separated (default: SDK chain, e.g. AWS_REGION or profile)") { |v| opts[:region] = v }
+        o.on("--all-regions", "Query every region returned by DescribeRegions") { opts[:all_regions] = true }
+        o.on("-p", "--profile=NAME", "AWS shared-config profile to use (AWS_PROFILE is read by the SDK)") { |v| opts[:profile] = v }
+        o.on("-v", "--vpc-id=ID", "AWS VPC id to show") { |v| opts[:vpc_id] = v }
+        o.on("-o", "--source-file=FILE", "--input=FILE", "JSON source file containing security groups") { |v| opts[:source_file] = v }
+        o.on("-f", "--filename=FILE", "--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)") { |v| opts[:filename] = v }
+        o.on("-c", "--config=FILE", "Config file (opts.yml)") { |v| opts[:config] = v }
+        o.on("-l", "--[no-]color", "Deprecated, ignored: edges are blue for ingress and red for egress, risky public ingress is dashed crimson") { |v| opts[:color] = v }
+        o.on("-n", "--renderer=NAME", "Deprecated, use the -f extension instead: renderer (#{Renderer.all.join("|")})") { |v| opts[:renderer] = v }
+        o.on("-y", "--layout=ENGINE", "Graphviz layout engine (#{AwsConfig::LAYOUTS.join("|")}); overrides opts.yml format") { |v| opts[:layout] = v }
+        o.on("-d", "--[no-]debug", "Verbose output and stack traces (or DEBUG=true)") { |v| opts[:debug] = v }
+        o.on("-b", "--[no-]obfuscate", "Hash group names and ports (or OBFUSCATE=true)") { |v| opts[:obfuscate] = v }
+        o.on("-u", "--source-filter=FILTER", "Source filter") { |v| opts[:source_filter] = v }
+        o.on("-t", "--target-filter=FILTER", "Target filter") { |v| opts[:target_filter] = v }
+        o.on("--show-unused", "Mark groups with no attached network interfaces (needs ec2:DescribeNetworkInterfaces; ignored with --source-file)") { opts[:show_unused] = true }
+        o.on("--fail-on-risk", "Exit 2 when 0.0.0.0/0 or ::/0 can reach a sensitive port (the output is still written)") { opts[:fail_on_risk] = true }
+        o.on("-i", "--version", "Print version and exit") {
+          @out.puts "aws_security_viz v#{VERSION}"
+          opts[:exit] = true
+        }
+        o.on("-h", "--help", "Show this message") {
+          @out.puts o
+          opts[:exit] = true
+        }
+      end
+    end
+
+    def setup(opts)
+      AwsConfig.write(opts[:config])
+      @out.puts "#{opts[:config]} created in current directory."
+      0
+    end
+
+    def visualize(opts)
+      debug = false
+      CliGuard.run(debug: -> { debug }) do
+        AwsSecurityViz.logger.warn("--color is deprecated and ignored; edges are blue (ingress) or red (egress)") if opts[:color]
+        # An explicit --[no-]debug / --[no-]obfuscate beats the env var; nil means "not given".
+        debug = opts[:debug].nil? ? AwsConfig.boolean(@env["DEBUG"], "DEBUG") : opts[:debug]
+        overrides = {
+          obfuscate: opts[:obfuscate].nil? ? AwsConfig.boolean(@env["OBFUSCATE"], "OBFUSCATE") : opts[:obfuscate],
+          debug: debug,
+          layout: opts[:layout]
+        }.compact
+        config = AwsConfig.load(opts[:config]).merge(overrides)
+        opts[:renderer] = resolve_renderer(opts[:renderer])
+        filename = opts[:filename] || Renderer.default_file(opts[:renderer] || Renderer::DEFAULT)
+        warn_renderer_conflict(opts[:renderer], opts[:filename])
+        risky = VisualizeAws.new(config, opts).unleash(filename).to_i
+        report_risk(risky)
+        return RISK_EXIT if risky > 0 && opts[:fail_on_risk]
+      end
+    end
+
+    def report_risk(count)
+      if count > 0
+        AwsSecurityViz.logger.warn("#{count} risky edge#{"s" unless count == 1}: public ingress (0.0.0.0/0 or ::/0) on a sensitive port or all traffic")
+      else
+        AwsSecurityViz.logger.info("no risky public ingress found")
+      end
+    end
+
+    # An explicit --renderer wins over the -f extension; say so when the two disagree (e.g. -n json -f out.png).
+    def warn_renderer_conflict(renderer, file_name)
+      return if renderer.nil? || file_name.nil?
+      ext = File.extname(file_name.to_s).delete_prefix(".").downcase
+      inferred = Renderer::EXTENSIONS[ext]
+      return if inferred.nil? || inferred == renderer.to_sym
+      AwsSecurityViz.logger.warn("--renderer #{renderer} overrides the .#{ext} extension of #{file_name}; the file will be written as #{renderer}")
+    end
+
+    # --renderer is a deprecated alias for the extension-based format; the removed navigator renderer is the html viewer now.
+    def resolve_renderer(name)
+      return nil if name.nil?
+      if name.to_s == "navigator"
+        AwsSecurityViz.logger.warn("--renderer navigator is deprecated and now writes the html viewer; use -f FILE.html")
+        return "html"
+      end
+      Renderer.validate!(name)
+      AwsSecurityViz.logger.warn("--renderer is deprecated; the output format is inferred from the -f extension")
+      name
+    end
+  end
+end

data/lib/aws_security_viz/cli_guard.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "aws-sdk-ec2"
+require_relative "logging"
+
+module AwsSecurityViz
+  # Runs the CLI body and turns failures into a message and an exit status:
+  # 0 on success, 130 on Ctrl-C (quietly), 1 on any other error. `debug` (a flag or a callable)
+  # re-raises after printing so the backtrace is visible.
+  module CliGuard
+    INTERRUPTED = 130
+
+    def self.run(debug: false, logger: AwsSecurityViz.logger)
+      yield
+      0
+    rescue Interrupt
+      INTERRUPTED
+    rescue => e
+      logger.error(message(e))
+      raise e if debug.respond_to?(:call) ? debug.call : debug
+      1
+    end
+
+    def self.message(error)
+      case error
+      when Aws::Errors::MissingRegionError
+        "no AWS region; pass -r/--region or set AWS_REGION (or use a profile with a region)"
+      when Aws::Errors::MissingCredentialsError
+        "no AWS credentials found; pass -a/-s, set AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or use --profile"
+      when Aws::Errors::ServiceError
+        "AWS #{error.class.name.split("::").last}: #{error.message}"
+      when Seahorse::Client::NetworkingError
+        "could not reach AWS: #{error.message}"
+      else
+        error.message
+      end
+    end
+  end
+end

data/lib/aws_security_viz/directed_graph.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AwsSecurityViz
+  # A small directed graph kept as insertion-ordered adjacency lists.
+  class DirectedGraph
+    Edge = Data.define(:source, :target) do
+      def to_s = "(#{source}-#{target})"
+    end
+
+    # DirectedGraph[1, 2, 2, 3] builds the edges 1->2 and 2->3.
+    def self.[](*pairs)
+      new.tap { |g| pairs.each_slice(2) { |u, v| g.add_edge(u, v) } }
+    end
+
+    def initialize
+      @adjacency = {}
+    end
+
+    def add_vertex(v)
+      @adjacency[v] ||= Set.new
+      self
+    end
+
+    def add_edge(u, v)
+      add_vertex(u)
+      add_vertex(v)
+      @adjacency[u] << v
+      self
+    end
+
+    def has_vertex?(v) = @adjacency.key?(v)
+
+    def vertices = @adjacency.keys
+
+    def edges
+      @adjacency.flat_map { |u, targets| targets.map { |v| Edge.new(u, v) } }
+    end
+
+    def reverse
+      each_edge_into(self.class.new) { |g, u, v| g.add_edge(v, u) }
+    end
+
+    # Vertices reachable from +start+ (including it), by breadth-first search.
+    def reachable_from(start)
+      return Set.new unless has_vertex?(start)
+      seen = Set[start]
+      queue = [start]
+      until queue.empty?
+        @adjacency[queue.shift].each { |v| queue << v if seen.add?(v) }
+      end
+      seen
+    end
+
+    # The subgraph on +keep+ and the edges between its vertices.
+    def induced(keep)
+      sub = self.class.new
+      @adjacency.each_key { |v| sub.add_vertex(v) if keep.include?(v) }
+      @adjacency.each { |u, ts| ts.each { |v| sub.add_edge(u, v) if keep.include?(u) && keep.include?(v) } }
+      sub
+    end
+
+    def to_s = edges.map(&:to_s).sort.join
+
+    private
+
+    def each_edge_into(target)
+      vertices.each { |v| target.add_vertex(v) }
+      edges.each { |e| yield target, e.source, e.target }
+      target
+    end
+  end
+end

data/lib/aws_security_viz/ec2/security_groups.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../model"
+require_relative "../risk"
+
+module AwsSecurityViz
+  class SecurityGroups
+    include Enumerable
+
+    def initialize(provider, config)
+      @groups = provider.security_groups
+      @config = config
+    end
+
+    def each(&block)
+      @groups.reject { |sg| @config.exclusions.match(sg.name) }.each(&block)
+    end
+
+    def size
+      @groups.size
+    end
+
+    # Group id -> name for referenced groups whose name is known.
+    def peer_names(group)
+      directed_rules(group).flat_map { |rule, _| rule.peers }
+        .select { |p| p.kind == :group && p.name != p.id }.to_h { |p| [p.id, p.name] }
+    end
+
+    def traffic(group)
+      all_traffic = directed_rules(group).flat_map { |rule, ingress| rule_traffic(group, rule, ingress) }.uniq
+      CidrGroupMapping.new(@groups, @config.groups, peer_names(group)).map(all_traffic)
+    end
+
+    private
+
+    # [rule, ingress?] pairs; egress rules only when configured.
+    def directed_rules(group)
+      rules = group.ingress.map { |r| [r, true] }
+      @config.egress? ? rules + group.egress.map { |r| [r, false] } : rules
+    end
+
+    def rule_traffic(group, rule, ingress)
+      rule.peers.reject { |peer| @config.exclusions.match(peer.name) }.map { |peer|
+        text = peer.description.to_s.strip
+        Traffic.new(ingress: ingress, from: peer.id, to: group.id, port_range: rule.port_range,
+          risky: ingress && Risk.risky?(rule, peer, @config.risky_ports),
+          descriptions: text.empty? ? [] : [{ports: rule.port_range, text: text}])
+      }
+    end
+  end
+
+  class CidrGroupMapping
+    def initialize(all_groups, user_groups, peer_names = {})
+      @all_groups = all_groups
+      @user_groups = user_groups
+      @peer_names = peer_names
+    end
+
+    def map(all_traffic)
+      traffic = all_traffic.collect { |traffic|
+        traffic.with(from: mapping(traffic.from), to: mapping(traffic.to))
+      }
+      traffic.uniq.group_by { |t| [t.from, t.to, t.ingress] }.collect { |k, v| Traffic.grouped(v) }.uniq
+    end
+
+    private
+
+    def mapping(val)
+      group = @all_groups.find { |g| g.id == val }
+      name = group ? group.name : @peer_names[val]
+      @user_groups[val] || (name && @user_groups[name]) || val
+    end
+  end
+end

data/lib/aws_security_viz/exclusions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AwsSecurityViz
+  class Exclusions
+    attr_reader :patterns
+
+    def initialize(patterns)
+      @patterns = patterns.map { |p| /#{p}/ } unless patterns.nil?
+    end
+
+    def match(str)
+      return false if patterns.nil?
+      patterns.any? { |p|
+        p.match(str)
+      }
+    end
+  end
+end

data/lib/aws_security_viz/export/html/viewer.html

@@ -0,0 +1,222 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:">
+<title>AWS security groups</title>
+<style>
+  html, body { margin: 0; height: 100%; font: 13px/1.4 system-ui, sans-serif; color: #222; }
+  #app { display: flex; flex-direction: column; height: 100%; }
+  #bar { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; padding: 8px 12px; border-bottom: 1px solid #ccc; background: #f6f6f6; }
+  #bar input[type=search] { width: 220px; padding: 3px 6px; }
+  #main { display: flex; flex: 1; min-height: 0; }
+  #cy { flex: 1; }
+  #details { width: 320px; overflow: auto; padding: 10px 12px; border-left: 1px solid #ccc; background: #fafafa; }
+  #details h2 { margin: 0 0 6px; font-size: 15px; }
+  #details h3 { margin: 12px 0 4px; font-size: 13px; }
+  #details ul { margin: 0; padding-left: 18px; }
+  .risky { color: #b00020; font-weight: bold; }
+  .muted { color: #666; }
+  #legend span { margin-right: 10px; }
+</style>
+</head>
+<body>
+<div id="app">
+  <div id="bar">
+    <input id="search" type="search" placeholder="Search groups" aria-label="Search groups">
+    <label><input id="ingress" type="checkbox" checked> Ingress</label>
+    <label><input id="egress" type="checkbox" checked> Egress</label>
+    <label><input id="risky-only" type="checkbox"> Risky only</label>
+    <button id="reset" type="button">Reset view</button>
+    <span id="legend" class="muted"><span style="color:#1f5fbf">blue: ingress</span><span style="color:#c0392b">red: egress</span><span class="risky">thick dashed: risky public ingress</span><span>grey dashed node: unused</span></span>
+  </div>
+  <div id="main">
+    <div id="cy"></div>
+    <div id="details"><p class="muted">Click a group or an edge to see its details.</p></div>
+  </div>
+</div>
+<script type="application/json" id="graph-data">/*DATA*/</script>
+<script>/*CYTOSCAPE*/</script>
+<script>
+(function () {
+  "use strict";
+  var data = JSON.parse(document.getElementById("graph-data").textContent);
+  var nodeById = {};
+  data.nodes.forEach(function (n) { nodeById[n.id] = n; });
+
+  // Compound parents: region (when several regions were queried) containing VPC.
+  var elements = [];
+  var seen = {};
+  function parent(id, label, kind, parentId) {
+    if (!seen[id]) {
+      seen[id] = true;
+      var d = { id: id, label: label, kind: kind };
+      if (parentId) d.parent = parentId;
+      elements.push({ group: "nodes", data: d, classes: kind });
+    }
+    return id;
+  }
+  data.nodes.forEach(function (n) {
+    var d = { id: n.id, label: n.label, kind: "group", unused: !!n.unused };
+    var up = null;
+    if (n.region) up = parent("region:" + n.region, n.region, "region", null);
+    if (n.vpc) up = parent("vpc:" + (n.region || "") + "|" + n.vpc, n.vpc, "vpc", up);
+    if (up) d.parent = up;
+    elements.push({ group: "nodes", data: d, classes: n.unused ? "unused" : "" });
+  });
+  data.edges.forEach(function (e) {
+    elements.push({ group: "edges", data: { id: e.id, source: e.source, target: e.target, label: e.label || "", kind: e.kind, risky: !!e.risky }, classes: e.kind + (e.risky ? " risky" : "") });
+  });
+
+  var cy = cytoscape({
+    container: document.getElementById("cy"),
+    elements: elements,
+    wheelSensitivity: 0.3,
+    style: [
+      { selector: "node", style: { label: "data(label)", "font-size": 11, "text-valign": "center", "text-halign": "center", "background-color": "#e8f0fe", "border-width": 1, "border-color": "#5b7bd5", shape: "round-rectangle", width: "label", height: "label", padding: "8px" } },
+      { selector: "node.region, node.vpc", style: { "text-valign": "top", "background-opacity": 0.06, "background-color": "#555", "border-color": "#999", "border-style": "dashed", padding: "14px", "font-weight": "bold", "font-size": 12 } },
+      { selector: "node.unused", style: { "background-color": "#eee", "border-style": "dashed", "border-color": "#888", color: "#555" } },
+      { selector: "edge", style: { label: "data(label)", "font-size": 9, width: 1.5, "curve-style": "bezier", "target-arrow-shape": "triangle", "text-background-color": "#fff", "text-background-opacity": 0.85, "text-background-padding": "1px" } },
+      { selector: "edge.ingress", style: { "line-color": "#1f5fbf", "target-arrow-color": "#1f5fbf" } },
+      { selector: "edge.egress", style: { "line-color": "#c0392b", "target-arrow-color": "#c0392b" } },
+      { selector: "edge.risky", style: { width: 4, "line-style": "dashed", "line-color": "#dc143c", "target-arrow-color": "#dc143c", color: "#b00020" } },
+      { selector: ".dim", style: { opacity: 0.12 } },
+      { selector: ".match", style: { "border-width": 3, "border-color": "#f39c12" } },
+      { selector: ":selected", style: { "overlay-color": "#f39c12", "overlay-opacity": 0.25 } }
+    ],
+    layout: { name: "cose", animate: false, nodeDimensionsIncludeLabels: true, padding: 30 }
+  });
+
+  window.awsSecurityViz = { cy: cy }; // read by the browser spec
+
+  var details = document.getElementById("details");
+
+  function el(tag, text, cls) {
+    var e = document.createElement(tag);
+    if (text !== undefined) e.textContent = text;
+    if (cls) e.className = cls;
+    return e;
+  }
+  function field(label, value) {
+    var p = el("p");
+    p.appendChild(el("strong", label + ": "));
+    p.appendChild(document.createTextNode(value));
+    return p;
+  }
+  function describeEdges(title, edges, other) {
+    var box = document.createDocumentFragment();
+    if (!edges.length) return box;
+    box.appendChild(el("h3", title));
+    var ul = el("ul");
+    edges.forEach(function (e) {
+      var li = el("li");
+      li.appendChild(document.createTextNode(other(e).data("label") + " : " + (e.data("label") || "all")));
+      if (e.data("risky")) li.appendChild(el("span", " (risky)", "risky"));
+      ul.appendChild(li);
+    });
+    box.appendChild(ul);
+    return box;
+  }
+  function descriptionList(descs) {
+    var ul = el("ul");
+    (descs || []).forEach(function (d) {
+      ul.appendChild(el("li", (d.ports ? d.ports + ": " : "") + d.text));
+    });
+    return ul;
+  }
+  var edgeData = {};
+  data.edges.forEach(function (e) { edgeData[e.id] = e; });
+
+  function show(target) {
+    details.textContent = "";
+    if (target.isEdge()) {
+      var e = edgeData[target.id()];
+      details.appendChild(el("h2", target.source().data("label") + " -> " + target.target().data("label")));
+      details.appendChild(field("Direction", e.kind));
+      details.appendChild(field("Ports", e.label || "all"));
+      if (e.risky) details.appendChild(el("p", "Risky: public ingress on a sensitive port or all traffic", "risky"));
+      if (e.descriptions && e.descriptions.length) {
+        details.appendChild(el("h3", "Rule descriptions"));
+        details.appendChild(descriptionList(e.descriptions));
+      }
+      return;
+    }
+    var n = nodeById[target.id()];
+    if (!n) {
+      details.appendChild(el("h2", target.data("label")));
+      details.appendChild(field("Type", target.data("kind").toUpperCase()));
+      return;
+    }
+    details.appendChild(el("h2", n.label));
+    details.appendChild(field("Id", n.id));
+    if (n.vpc) details.appendChild(field("VPC", n.vpc));
+    if (n.region) details.appendChild(field("Region", n.region));
+    if (n.unused) details.appendChild(el("p", "Unused: no network interfaces attached", "muted"));
+    details.appendChild(describeEdges("Incoming", target.incomers("edge").toArray(), function (e) { return e.source(); }));
+    details.appendChild(describeEdges("Outgoing", target.outgoers("edge").toArray(), function (e) { return e.target(); }));
+    var withDescs = target.connectedEdges().toArray().filter(function (e) { var d = edgeData[e.id()].descriptions; return d && d.length; });
+    if (withDescs.length) {
+      details.appendChild(el("h3", "Rule descriptions"));
+      withDescs.forEach(function (e) {
+        details.appendChild(el("p", e.source().data("label") + " -> " + e.target().data("label"), "muted"));
+        details.appendChild(descriptionList(edgeData[e.id()].descriptions));
+      });
+    }
+  }
+
+  function clearFocus() { cy.elements().removeClass("dim"); }
+  function focus(target) {
+    clearFocus();
+    var keep = target.isNode() ? target.closedNeighborhood().union(target.ancestors()).union(target.neighborhood().ancestors()) : target.union(target.connectedNodes()).union(target.connectedNodes().ancestors());
+    cy.elements().not(keep).addClass("dim");
+  }
+
+  cy.on("tap", "node, edge", function (evt) {
+    var t = evt.target;
+    if (t.isNode() && t.isParent()) { show(t); return; }
+    show(t);
+    focus(t);
+  });
+  cy.on("tap", function (evt) {
+    if (evt.target === cy) {
+      clearFocus();
+      details.textContent = "";
+      details.appendChild(el("p", "Click a group or an edge to see its details.", "muted"));
+    }
+  });
+
+  function applyFilters() {
+    var ingress = document.getElementById("ingress").checked;
+    var egress = document.getElementById("egress").checked;
+    var riskyOnly = document.getElementById("risky-only").checked;
+    cy.edges().forEach(function (e) {
+      var visible = (e.data("kind") === "ingress" ? ingress : egress) && (!riskyOnly || e.data("risky"));
+      e.style("display", visible ? "element" : "none");
+    });
+  }
+  ["ingress", "egress", "risky-only"].forEach(function (id) {
+    document.getElementById(id).addEventListener("change", applyFilters);
+  });
+
+  document.getElementById("search").addEventListener("input", function (evt) {
+    var q = evt.target.value.trim().toLowerCase();
+    cy.nodes().removeClass("match");
+    if (!q) return;
+    var hits = cy.nodes().filter(function (n) {
+      return !n.isParent() && (String(n.data("label")).toLowerCase().indexOf(q) !== -1 || String(n.id()).toLowerCase().indexOf(q) !== -1);
+    });
+    hits.addClass("match");
+    if (hits.length) cy.animate({ fit: { eles: hits, padding: 80 }, duration: 0 });
+  });
+
+  document.getElementById("reset").addEventListener("click", function () {
+    clearFocus();
+    cy.nodes().removeClass("match");
+    document.getElementById("search").value = "";
+    cy.fit(undefined, 30);
+  });
+})();
+</script>
+</body>
+</html>

data/lib/aws_security_viz/graph.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "directed_graph"
+require_relative "port_label"
+require_relative "obfuscation"
+require_relative "logging"
+
+module AwsSecurityViz
+  class Graph
+    attr_reader :underlying
+
+    def initialize(config, underlying = DirectedGraph.new)
+      @config = config
+      @underlying = underlying
+      @edge_properties = {}
+      @node_properties = {}
+    end
+
+    def add_node(name, opts)
+      log("node: #{loggable(name)}, opts: #{@config.obfuscate? ? Obfuscation.node_opts(opts) : opts}")
+      @underlying.add_vertex(name)
+      @node_properties[name] = opts
+    end
+
+    # Labels a node that only appears as an edge endpoint (e.g. a group outside the
+    # described set); a node already added with properties is left alone.
+    def describe_node(key, opts)
+      @node_properties[key] ||= opts if @underlying.has_vertex?(key)
+    end
+
+    def add_edge(from, to, opts)
+      log("edge: #{loggable(from)} -> #{loggable(to)}")
+      @underlying.add_edge(from, to)
+      @edge_properties[[from, to]] = merge_edge(@edge_properties[[from, to]], opts)
+    end
+
+    def filter(source, destination)
+      @underlying = GraphFilter.new(underlying).filter(resolve(source), resolve(destination))
+    end
+
+    # Risky edges that survived filtering.
+    def risky_edge_count
+      @underlying.edges.count { |e| opts(e.source, e.target)[:risky] }
+    end
+
+    def output(renderer)
+      nodes = @underlying.vertices.map { |v| [v, @node_properties[v] || {}] }
+      edges = @underlying.edges.map { |e| [e.source, e.target, opts(e.source, e.target)] }
+      nodes, edges = Obfuscation.apply(nodes, edges) if @config.obfuscate?
+      nodes.each { |v, node_opts| renderer.add_node(v, node_opts) }
+      edges.each { |u, v, edge_opts| renderer.add_edge(u, v, edge_opts) }
+      renderer.output
+    end
+
+    def log(msg)
+      AwsSecurityViz.logger.debug(msg) if @config.debug?
+    end
+
+    private
+
+    # Debug output is what users paste into bug reports, so it is hashed like the rest.
+    def loggable(value)
+      @config.obfuscate? ? Obfuscation.hash(value) : value
+    end
+
+    # A filter may be a group id (a node key) or a group name (a node label).
+    def resolve(filter)
+      return filter if filter.nil? || @underlying.has_vertex?(filter)
+      keys = @underlying.vertices.select { |v| @node_properties.dig(v, :label) == filter }
+      raise ArgumentError, "no group or peer matches '#{filter}'" if keys.empty?
+      if keys.size > 1
+        raise ArgumentError, "'#{filter}' matches several groups (#{keys.map { |k| loggable(k) }.join(", ")}); use a group id"
+      end
+      keys.first
+    end
+
+    # Rules from several groups (or egress and ingress) can map to one edge: union the
+    # port labels and pick the colour independently of rule order (ingress blue wins
+    # over egress red).
+    def merge_edge(existing, opts)
+      return opts unless existing
+      color = [existing[:color], opts[:color]].include?(:blue) ? :blue : opts[:color]
+      merged = existing.merge(opts).merge(color: color, label: PortLabel.normalise("#{existing[:label]},#{opts[:label]}"))
+      merged[:risky] = true if existing[:risky] || opts[:risky]
+      descriptions = (existing[:descriptions].to_a + opts[:descriptions].to_a).uniq
+      descriptions.empty? ? merged : merged.merge(descriptions: descriptions)
+    end
+
+    def opts(u, v)
+      @edge_properties[[u, v]]
+    end
+  end
+end