scaled 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e7b20aff254a7d3778443bde18004a88fe3f95d9a066a3bc04dc7965099be01
-  data.tar.gz: 9880c240d23f84a6bf64ff40e56de7a40cfe2d8894a4a8d5c81096366c0ab6e4
+  metadata.gz: 2a020a9c01e0e1d4412044cbd43e4d839d125820ccaa2f5d2c47f21d0117b0ef
+  data.tar.gz: f1caec44fa505d4587c9cef1e18b4f337e490147c9880274bc106c31d683f2c1
 SHA512:
-  metadata.gz: f5d23f531c3d6079363f71716064f79e7b17181f4b35c4f4cbac60d85640912e6012a1b76edee9921ee5e5692a36225b4de5a03e288a5c429645754324277c53
-  data.tar.gz: de5e1ecab2b985a02c2a75e61e9ff316ff75031fcf2ce9eccd68d07c31944ae0758e8962a2d91d3da3cb2e42158ebd7426db3505712b3bc5e2db45b0d85a9622
+  metadata.gz: 6d3ed8af11e8d86bb04b59fc605522bcce575a96ff49049636953fc23c5343f45ebc0060dd0d239e3c8421f746a3112815897b3e2ce6e58087516774efe6e27d
+  data.tar.gz: 82440e425e2c3d25be7d43f5cb248f331fca4203535e9183fc3a8a18599b92df8fdaf4ea9cf810c322b23fc3fa1049d1d68267159e314872385afc78b8b0d033

data/README.md

@@ -6,8 +6,10 @@
 
 Current scope of the gem:
 - devices inventory (`list`, `get`)
+- device routes (`device_routes.get`) — advertised/enabled subnet routes and exit nodes
 - keys metadata (`list`, `get`)
 - logs (`configuration`, `network`)
+- policy file / ACL (`acl.get`) — `acls`/`grants`, `tagOwners`, `groups`
 
 No create/update/delete actions are exposed in resource wrappers.
 
@@ -187,78 +189,66 @@ curl -sS \
   "https://api.tailscale.com/api/v2/tailnet/-/devices"
 ```
 
-### Get one device
-
-```ruby
-response = client.devices.get("device-id")
-```
+Example server response:
 
-```bash
-curl -sS \
-  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
-  "https://api.tailscale.com/api/v2/device/device-id"
+```json
+{
+  "devices": [
+    {
+      "id": "n123456CNTRL",
+      "name": "macbook-pro.tailnet.ts.net",
+      "addresses": ["100.101.102.103", "fd7a:115c:a1e0::abcd:1234"],
+      "user": "user@example.com",
+      "os": "macOS",
+      "created": "2026-03-12T07:12:30Z",
+      "lastSeen": "2026-03-12T08:25:44Z",
+      "authorized": true
+    }
+  ]
+}
 ```
 
-### List keys
+### Get one device
 
 ```ruby
-response = client.keys.list
+response = client.devices.get("device-id")
 ```
 
 ```bash
 curl -sS \
   -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
-  "https://api.tailscale.com/api/v2/tailnet/-/keys"
+  "https://api.tailscale.com/api/v2/device/device-id"
 ```
 
-### Read configuration logs
+Example server response:
 
-```ruby
-response = client.logs.configuration(query: { limit: 100 })
-```
-
-```bash
-curl -sS \
-  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
-  "https://api.tailscale.com/api/v2/tailnet/-/logging/configuration?limit=100"
+```json
+{
+  "id": "n123456CNTRL",
+  "name": "macbook-pro.tailnet.ts.net",
+  "hostname": "macbook-pro",
+  "addresses": ["100.101.102.103", "fd7a:115c:a1e0::abcd:1234"],
+  "user": "user@example.com",
+  "os": "macOS",
+  "created": "2026-03-12T07:12:30Z",
+  "lastSeen": "2026-03-12T08:25:44Z",
+  "authorized": true
+}
 ```
 
-### Read network logs
+### List keys
 
 ```ruby
-response = client.logs.network(query: { limit: 100 })
+response = client.keys.list
 ```
 
 ```bash
 curl -sS \
   -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
-  "https://api.tailscale.com/api/v2/tailnet/-/logging/network?limit=100"
-```
-
-## Example responses
-
-Response shapes vary by account features and scopes. Examples:
-
-### Devices list (`client.devices.list`)
-
-```json
-{
-  "devices": [
-    {
-      "id": "n123456CNTRL",
-      "name": "macbook-pro.tailnet.ts.net",
-      "addresses": ["100.101.102.103", "fd7a:115c:a1e0::abcd:1234"],
-      "user": "user@example.com",
-      "os": "macOS",
-      "created": "2026-03-12T07:12:30Z",
-      "lastSeen": "2026-03-12T08:25:44Z",
-      "authorized": true
-    }
-  ]
-}
+  "https://api.tailscale.com/api/v2/tailnet/-/keys"
 ```
 
-### Keys list (`client.keys.list`)
+Example server response:
 
 ```json
 {
@@ -281,7 +271,19 @@ Response shapes vary by account features and scopes. Examples:
 }
 ```
 
-### Configuration logs (`client.logs.configuration`)
+### Read configuration logs
+
+```ruby
+response = client.logs.configuration(query: { limit: 100 })
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/logging/configuration?limit=100"
+```
+
+Example server response:
 
 ```json
 {
@@ -299,24 +301,109 @@ Response shapes vary by account features and scopes. Examples:
 }
 ```
 
-### Network logs (`client.logs.network`)
+### Read network logs
+
+Network flow logs require an RFC 3339 `start` and `end` time window (there is no
+`limit` parameter). Source and destination are reported as `addr:port` strings.
+
+```ruby
+response = client.logs.network(
+  query: { start: "2026-03-12T00:00:00Z", end: "2026-03-12T23:59:59Z" }
+)
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/tailnet/-/logging/network?start=2026-03-12T00:00:00Z&end=2026-03-12T23:59:59Z"
+```
+
+Example server response (`logs` is an array of `NetworkFlowLog` objects):
 
 ```json
 {
-  "events": [
+  "logs": [
     {
-      "id": "evt_net_1",
-      "time": "2026-03-12T08:15:00Z",
-      "srcDeviceId": "n123456CNTRL",
-      "dstDeviceId": "n998877CNTRL",
-      "proto": "tcp",
-      "dstPort": 443,
-      "action": "accept"
+      "logged": "2026-03-12T08:15:26Z",
+      "nodeId": "n123456CNTRL",
+      "start": "2026-03-12T08:15:25Z",
+      "end": "2026-03-12T08:15:26Z",
+      "virtualTraffic": [
+        {
+          "proto": "tcp",
+          "src": "100.101.102.103:52343",
+          "dst": "100.110.120.130:443",
+          "txPkts": 10,
+          "txBytes": 1200,
+          "rxPkts": 8,
+          "rxBytes": 900
+        }
+      ],
+      "subnetTraffic": [],
+      "exitTraffic": [],
+      "physicalTraffic": []
     }
   ]
 }
 ```
 
+Traffic is split into `virtualTraffic` (tailnet peer-to-peer), `subnetTraffic`
+(through subnet routers), `exitTraffic` (through exit nodes), and
+`physicalTraffic` (underlying physical endpoints).
+
+### Read device routes
+
+```ruby
+response = client.device_routes.get("device-id")
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  "https://api.tailscale.com/api/v2/device/device-id/routes"
+```
+
+Example server response:
+
+```json
+{
+  "advertisedRoutes": ["10.0.0.0/24", "0.0.0.0/0", "::/0"],
+  "enabledRoutes": ["10.0.0.0/24"]
+}
+```
+
+### Read policy file (ACL)
+
+By default the policy file is returned as JSON. Pass `details: true` to get a
+JSON object with a base64-encoded huJSON `acl` plus `warnings` and `errors`.
+
+```ruby
+policy = client.acl.get
+detailed = client.acl.get(query: { details: true })
+```
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer ${TAILSCALE_API_TOKEN}" \
+  -H "Accept: application/json" \
+  "https://api.tailscale.com/api/v2/tailnet/-/acl"
+```
+
+Example server response:
+
+```json
+{
+  "groups": { "group:eng": ["alice@example.com"] },
+  "tagOwners": { "tag:server": ["group:eng"] },
+  "acls": [
+    { "action": "accept", "src": ["group:eng"], "dst": ["tag:server:443"] }
+  ]
+}
+```
+
+OAuth note: reading routes needs `devices:routes:read`; reading the ACL needs an
+ACL read scope (`acl:read`). Add them to your OAuth scopes when using those calls.
+
 ## Integration smoke tests
 
 Integration tests are opt-in and run only when `RUN_INTEGRATION=1`.

data/examples/topology_graph.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# Build a network-topology graph of a Tailscale tailnet using the read-only
+# Scaled client and export it as Graphviz DOT + JSON.
+#
+# Будує граф топології мережі tailnet за допомогою read-only клієнта Scaled
+# та експортує його у Graphviz DOT + JSON.
+#
+# Endpoints used (verified against https://tailscale.com/api OpenAPI):
+#   1. GET /tailnet/{tailnet}/devices?fields=all   -> вузли + tags, routes, addresses
+#   2. GET /tailnet/{tailnet}/logging/network      -> NetworkFlowLog[] (virtualTraffic)
+#      requires RFC3339 `start` & `end` (NOT `limit`); src/dst are "ip:port".
+#   3. GET /tailnet/{tailnet}/acl?details=true     -> policy (tagOwners, groups) context
+#
+# Usage / Запуск:
+#   TAILSCALE_API_TOKEN=tskey-api-... TAILNET=- \
+#     LOG_START=2026-06-20T00:00:00Z LOG_END=2026-06-21T00:00:00Z \
+#     ruby examples/topology_graph.rb
+#   # -> tmp/topology.dot, tmp/topology.json
+#   # dot -Tsvg tmp/topology.dot -o tmp/topology.svg
+#
+# OAuth scopes needed: devices:core:read, logs:network:read (+ acl:read for ACL).
+
+require "json"
+require "fileutils"
+require_relative "../lib/scaled"
+
+module TopologyGraph
+  module_function
+
+  def build_client
+    if ENV["TAILSCALE_API_TOKEN"]
+      Scaled.client(api_token: ENV.fetch("TAILSCALE_API_TOKEN"), tailnet: ENV.fetch("TAILNET", "-"))
+    else
+      Scaled.client(
+        oauth: {
+          client_id: ENV.fetch("TAILSCALE_OAUTH_CLIENT_ID"),
+          client_secret: ENV.fetch("TAILSCALE_OAUTH_CLIENT_SECRET"),
+          scopes: %w[devices:core:read logs:network:read acl:read]
+        },
+        tailnet: ENV.fetch("TAILNET", "-")
+      )
+    end
+  end
+
+  # Vertices: one node per device, enriched with tags / routes / addresses.
+  # Also build an IP -> deviceId index to resolve flow-log endpoints.
+  # Вершини: вузол на кожен device + індекс IP -> deviceId для зіставлення логів.
+  def collect_nodes(client)
+    # `fields=all` returns tags, enabledRoutes, advertisedRoutes, addresses, clientConnectivity.
+    devices = client.devices.list(query: { fields: "all" }).fetch("devices", [])
+    ip_index = {}
+
+    nodes = devices.each_with_object({}) do |device, acc|
+      id = device.fetch("id")
+      (device["addresses"] || []).each { |addr| ip_index[addr] = id }
+      acc[id] = {
+        id: id,
+        name: device["name"] || device["hostname"],
+        user: device["user"],
+        os: device["os"],
+        addresses: device["addresses"] || [],
+        tags: device["tags"] || [],                          # ACL-теги вузла
+        advertised_routes: device["advertisedRoutes"] || [], # subnet routes / exit node
+        enabled_routes: device["enabledRoutes"] || []
+      }
+    end
+
+    [nodes, ip_index]
+  end
+
+  # Edges: aggregate tailnet peer-to-peer flows (virtualTraffic) from network logs.
+  # src/dst are "ip:port"; the ip is resolved back to a device via ip_index.
+  # Ребра: агрегує tailnet-потоки (virtualTraffic) у зв'язки device -> device.
+  def collect_edges(client, ip_index)
+    logs = client.logs.network(query: { start: log_start, end: log_end }).fetch("logs", [])
+    edges = Hash.new { |hash, key| hash[key] = { pkts: 0, bytes: 0 } }
+
+    logs.each do |entry|
+      Array(entry["virtualTraffic"]).each do |flow|
+        src = ip_index[host(flow["src"])]
+        dst = ip_index[host(flow["dst"])]
+        next unless src && dst
+
+        agg = edges[[src, dst, flow["proto"], port(flow["dst"])]]
+        agg[:pkts] += flow["txPkts"].to_i + flow["rxPkts"].to_i
+        agg[:bytes] += flow["txBytes"].to_i + flow["rxBytes"].to_i
+      end
+    end
+
+    edges
+  end
+
+  # Optional: tagOwners / groups from the policy file for legend context.
+  # Note: `details=true` returns { acl: <base64 huJSON>, warnings, errors }.
+  def collect_policy(client)
+    client.acl.get(query: { details: true })
+  rescue Scaled::Error => e
+    warn "ACL fetch skipped (#{e.class}: #{e.message})"
+    nil
+  end
+
+  def to_dot(nodes, edges)
+    lines = ["digraph tailnet {", "  rankdir=LR;", "  node [shape=box, style=rounded];"]
+
+    nodes.each_value do |node|
+      label = [node[:name], node[:os], (node[:tags].join(",") unless node[:tags].empty?)].compact.join("\\n")
+      color = node[:tags].empty? ? "black" : "darkgreen" # tagged hosts highlighted
+      lines << %(  "#{node[:id]}" [label="#{label}", color="#{color}"];)
+    end
+
+    edges.each do |(src, dst, proto, dport), agg|
+      lines << %(  "#{src}" -> "#{dst}" [label="#{proto}:#{dport} #{agg[:bytes]}B"];)
+    end
+
+    "#{lines.join("\n")}\n}\n"
+  end
+
+  def host(addr_port)
+    return nil unless addr_port
+
+    addr_port.rpartition(":").first # strips :port, keeps IPv4/IPv6 host
+  end
+
+  def port(addr_port)
+    addr_port&.rpartition(":")&.last
+  end
+
+  def log_start
+    ENV.fetch("LOG_START") { raise "set LOG_START (RFC3339), e.g. 2026-06-20T00:00:00Z" }
+  end
+
+  def log_end
+    ENV.fetch("LOG_END") { raise "set LOG_END (RFC3339), e.g. 2026-06-21T00:00:00Z" }
+  end
+
+  def run
+    client = build_client
+    nodes, ip_index = collect_nodes(client)
+    edges = collect_edges(client, ip_index)
+    policy = collect_policy(client)
+
+    FileUtils.mkdir_p("tmp")
+    File.write("tmp/topology.dot", to_dot(nodes, edges))
+    File.write("tmp/topology.json", JSON.pretty_generate(
+                                      nodes: nodes.values,
+                                      edges: edges.map do |(s, d, pr, dp), a|
+                                        { src: s, dst: d, proto: pr, dst_port: dp, **a }
+                                      end,
+                                      tag_owners: policy.is_a?(Hash) ? policy["tagOwners"] : nil
+                                    ))
+
+    puts "nodes=#{nodes.size} edges=#{edges.size} -> tmp/topology.dot, tmp/topology.json"
+  end
+end
+
+TopologyGraph.run if $PROGRAM_NAME == __FILE__

data/lib/scaled/client.rb

@@ -6,6 +6,8 @@ require_relative "http"
 require_relative "resources/devices"
 require_relative "resources/keys"
 require_relative "resources/logs"
+require_relative "resources/acl"
+require_relative "resources/device_routes"
 
 module Scaled
   # Main entry point for interacting with Tailscale API.
@@ -82,6 +84,16 @@ module Scaled
       @logs ||= Resources::Logs.new(self)
     end
 
+    # @return [Scaled::Resources::Acl]
+    def acl
+      @acl ||= Resources::Acl.new(self)
+    end
+
+    # @return [Scaled::Resources::DeviceRoutes]
+    def device_routes
+      @device_routes ||= Resources::DeviceRoutes.new(self)
+    end
+
     private
 
     # @param api_token [String, nil]

data/lib/scaled/resources/acl.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Resources
+    # API wrapper for the tailnet policy file (ACL).
+    # API-обгортка для policy-файлу tailnet (ACL).
+    class Acl
+      # @param client [Scaled::Client] configured API client
+      # @return [void]
+      def initialize(client)
+        @client = client
+      end
+
+      # @param query [Hash, nil] optional query params (e.g. { details: 1 })
+      # @return [Hash, Array, String, nil] parsed policy file (acls/grants, tagOwners, groups, ...)
+      # Note: read-only; returns the current ACL/policy document for the tailnet.
+      # Нотатка: read-only; повертає поточний policy-файл (ACL) для tailnet.
+      def get(query: nil)
+        @client.get("/tailnet/#{@client.tailnet}/acl", query: query)
+      end
+    end
+  end
+end

data/lib/scaled/resources/device_routes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Scaled
+  module Resources
+    # API wrapper for per-device subnet routes.
+    # API-обгортка для маршрутів (subnet routes) окремого device.
+    class DeviceRoutes
+      # @param client [Scaled::Client] configured API client
+      # @return [void]
+      def initialize(client)
+        @client = client
+      end
+
+      # @param device_id [String] Tailscale device identifier
+      # @return [Hash, Array, String, nil] parsed response with advertisedRoutes/enabledRoutes
+      # Note: read-only; reveals subnet routers and exit nodes for the device.
+      # Нотатка: read-only; показує subnet-routers та exit-nodes для device.
+      def get(device_id)
+        @client.get("/device/#{device_id}/routes")
+      end
+    end
+  end
+end

data/lib/scaled/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Scaled
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/sig/scaled.rbs

@@ -39,6 +39,8 @@ module Scaled
     def devices: () -> Resources::Devices
     def keys: () -> Resources::Keys
     def logs: () -> Resources::Logs
+    def acl: () -> Resources::Acl
+    def device_routes: () -> Resources::DeviceRoutes
   end
 
   module Resources
@@ -59,5 +61,15 @@ module Scaled
       def configuration: (?query: Hash[Symbol | String, untyped]?) -> untyped
       def network: (?query: Hash[Symbol | String, untyped]?) -> untyped
     end
+
+    class Acl
+      def initialize: (Client client) -> void
+      def get: (?query: Hash[Symbol | String, untyped]?) -> untyped
+    end
+
+    class DeviceRoutes
+      def initialize: (Client client) -> void
+      def get: (String device_id) -> untyped
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: scaled
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Voloshyn Ruslan
 bindir: exe
 cert_chain: []
-date: 2026-03-12 00:00:00.000000000 Z
+date: 2026-06-21 00:00:00.000000000 Z
 dependencies: []
 description: 'Scaled provides a read-only Ruby SDK for Tailscale API endpoints: devices,
   keys, and logs. Supports API token and OAuth client credentials authentication.'
@@ -24,12 +24,15 @@ files:
 - Rakefile
 - examples/rails/scaled_initializer.rb
 - examples/rails/tailscale_client.rb
+- examples/topology_graph.rb
 - lib/scaled.rb
 - lib/scaled/auth/api_token.rb
 - lib/scaled/auth/oauth_client_credentials.rb
 - lib/scaled/client.rb
 - lib/scaled/errors.rb
 - lib/scaled/http.rb
+- lib/scaled/resources/acl.rb
+- lib/scaled/resources/device_routes.rb
 - lib/scaled/resources/devices.rb
 - lib/scaled/resources/keys.rb
 - lib/scaled/resources/logs.rb