raygatherer 0.1.0

data/lib/raygatherer/api_client.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Raygatherer
+  class ApiClient
+    class ApiError < StandardError; end
+    class ConnectionError < StandardError; end
+    class ParseError < StandardError; end
+
+    def initialize(host, username: nil, password: nil, verbose: false, stderr: $stderr)
+      @host = normalize_host(host)
+      @username = username
+      @password = password
+      @verbose = verbose
+      @stderr = stderr
+    end
+
+    def fetch_live_analysis_report
+      get("/api/analysis-report/live") do |body|
+        log_verbose "Parsing NDJSON response..."
+        result = parse_ndjson(body)
+        log_verbose "Parsed successfully: metadata + #{result[:rows].length} rows"
+        result
+      end
+    end
+
+    def fetch_analysis_report(name)
+      encoded = URI.encode_www_form_component(name)
+      get("/api/analysis-report/#{encoded}") do |body|
+        log_verbose "Parsing NDJSON response..."
+        result = parse_ndjson(body)
+        log_verbose "Parsed successfully: metadata + #{result[:rows].length} rows"
+        result
+      end
+    end
+
+    def fetch_manifest
+      get("/api/qmdl-manifest") do |body|
+        log_verbose "Parsing JSON response..."
+        result = parse_json(body)
+        log_verbose "Parsed successfully: #{result["entries"]&.length || 0} entries"
+        result
+      end
+    end
+
+    def fetch_analysis_status
+      get("/api/analysis") do |body|
+        log_verbose "Parsing JSON response..."
+        result = parse_json(body)
+        log_verbose "Parsed successfully"
+        result
+      end
+    end
+
+    def fetch_config
+      get("/api/config") do |body|
+        log_verbose "Parsing JSON response..."
+        result = parse_json(body)
+        log_verbose "Parsed successfully"
+        result
+      end
+    end
+
+    def fetch_system_stats
+      get("/api/system-stats") do |body|
+        log_verbose "Parsing JSON response..."
+        result = parse_json(body)
+        log_verbose "Parsed successfully"
+        result
+      end
+    end
+
+    def test_notification
+      post("/api/test-notification", expected_code: "200")
+    end
+
+    def set_config(json_body)
+      post("/api/config", body: json_body, content_type: "application/json")
+    end
+
+    def download_recording(name, io:, format: :qmdl)
+      encoded = URI.encode_www_form_component(name)
+      path = case format
+      when :qmdl then "/api/qmdl/#{encoded}"
+      when :pcap then "/api/pcap/#{encoded}"
+      when :zip then "/api/zip/#{encoded}"
+      end
+      stream_to(path, io)
+    end
+
+    def delete_recording(name)
+      post("/api/delete-recording/#{URI.encode_www_form_component(name)}")
+    end
+
+    def start_analysis(name)
+      encoded = URI.encode_www_form_component(name)
+      body = post("/api/analysis/#{encoded}")
+      parse_json(body)
+    end
+
+    def stop_recording
+      post("/api/stop-recording")
+    end
+
+    def start_recording
+      post("/api/start-recording")
+    end
+
+    private
+
+    def get(path)
+      response, body = request(:get, path, ok_code: "200", ok_status_text: "OK")
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ApiError, server_error_message(response, body)
+      end
+
+      yield body
+    rescue ParseError => e
+      log_verbose "Parse failed: #{e.message}"
+      raise
+    end
+
+    def post(path, expected_code: "202", body: nil, content_type: nil)
+      ok_status_text = (expected_code == "202") ? "Accepted" : "OK"
+      response, resp_body = request(:post, path, ok_code: expected_code,
+        ok_status_text: ok_status_text, body: body, content_type: content_type)
+
+      unless response.code == expected_code
+        raise ApiError, server_error_message(response, resp_body)
+      end
+
+      resp_body
+    end
+
+    def request(method, path, ok_code:, ok_status_text:, body: nil, content_type: nil)
+      url = "#{@host}#{path}"
+      uri = URI.parse(url)
+
+      log_verbose "HTTP #{method.to_s.upcase} #{url}"
+      log_verbose "Basic Auth: user=#{@username}" if @username
+
+      req = build_request(method, uri, body: body, content_type: content_type)
+      response, resp_body = execute_request(uri, req, ok_code: ok_code, ok_status_text: ok_status_text)
+
+      [response, resp_body]
+    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      log_verbose "Connection error: #{e.class} - #{e.message}"
+      raise ConnectionError, "Failed to connect to #{@host}: #{e.message}"
+    end
+
+    def build_request(method, uri, body: nil, content_type: nil)
+      req = case method
+      when :get then Net::HTTP::Get.new(uri.request_uri)
+      when :post then Net::HTTP::Post.new(uri.request_uri)
+      end
+      req.basic_auth(@username, @password) if @username && @password
+      if body
+        req.body = body
+        req["Content-Type"] = content_type if content_type
+      end
+      req
+    end
+
+    def execute_request(uri, req, ok_code:, ok_status_text:)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+
+      start_time = Time.now
+      log_verbose "Request started at: #{start_time.utc}"
+
+      response = http.request(req)
+
+      elapsed = Time.now - start_time
+      status_text = (response.code == ok_code) ? ok_status_text : response.message.to_s
+      log_verbose "Response received: #{response.code} #{status_text} (#{format("%.3f", elapsed)}s)"
+
+      body = response.body.to_s
+      log_verbose "Raw response body (#{body.bytesize} bytes):"
+      log_verbose body if @verbose
+
+      [response, body]
+    end
+
+    def stream_to(path, io)
+      uri = URI.parse("#{@host}#{path}")
+
+      log_verbose "HTTP GET #{uri} (streaming)"
+
+      start_time = Time.now
+      log_verbose "Request started at: #{start_time.utc}"
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request.basic_auth(@username, @password) if @username && @password
+
+        http.request(request) do |response|
+          elapsed = Time.now - start_time
+          status_text = (response.code == "200") ? "OK" : response.message.to_s
+          log_verbose "Response received: #{response.code} #{status_text} (#{format("%.3f", elapsed)}s)"
+
+          unless response.is_a?(Net::HTTPSuccess)
+            error_body = response.read_body
+            raise ApiError, server_error_message(response, error_body)
+          end
+
+          response.read_body do |chunk|
+            io.write(chunk)
+          end
+        end
+      end
+    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      log_verbose "Connection error: #{e.class} - #{e.message}"
+      raise ConnectionError, "Failed to connect to #{@host}: #{e.message}"
+    end
+
+    def server_error_message(response, body)
+      detail = body.to_s.strip
+      detail = response.message if detail.empty?
+      "Server returned #{response.code}: #{detail}"
+    end
+
+    def log_verbose(message)
+      return unless @verbose
+      @stderr.puts message
+    end
+
+    def parse_ndjson(body)
+      lines = body.split("\n").reject(&:empty?)
+
+      raise ParseError, "No data received from server" if lines.empty?
+
+      metadata = parse_line(lines.first, "metadata")
+      rows = lines[1..].map.with_index do |line, index|
+        parse_line(line, "row #{index + 1}")
+      end
+
+      {metadata: metadata, rows: rows}
+    rescue JSON::ParserError => e
+      raise ParseError, "Failed to parse response: #{e.message}"
+    end
+
+    def parse_line(line, context)
+      JSON.parse(line)
+    rescue JSON::ParserError => e
+      raise ParseError, "Failed to parse #{context}: #{e.message}"
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise ParseError, "Failed to parse response: #{e.message}"
+    end
+
+    def normalize_host(host)
+      # Add http:// if no scheme is present
+      if !%r{^https?://}.match?(host)
+        "http://#{host}"
+      else
+        host
+      end
+    end
+  end
+end

data/lib/raygatherer/cli.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "config"
+
+module Raygatherer
+  class CLI
+    # Custom exception to handle early returns without calling exit
+    class EarlyExit < StandardError
+      attr_reader :exit_code
+
+      def initialize(exit_code)
+        @exit_code = exit_code
+        super()
+      end
+    end
+
+    ROUTES = {
+      ["stats", nil] => {file: "commands/stats", klass: "Commands::Stats", json: true},
+      ["alerts", nil] => {file: "commands/alerts", klass: "Commands::Alerts", json: true},
+      ["recording", "list"] => {file: "commands/recording/list", klass: "Commands::Recording::List", json: true},
+      ["recording", "download"] => {file: "commands/recording/download", klass: "Commands::Recording::Download", json: false},
+      ["recording", "delete"] => {file: "commands/recording/delete", klass: "Commands::Recording::Delete", json: false},
+      ["recording", "stop"] => {file: "commands/recording/stop", klass: "Commands::Recording::Stop", json: false},
+      ["recording", "start"] => {file: "commands/recording/start", klass: "Commands::Recording::Start", json: false},
+      ["analysis", "status"] => {file: "commands/analysis/status", klass: "Commands::Analysis::Status", json: true},
+      ["analysis", "run"] => {file: "commands/analysis/run", klass: "Commands::Analysis::Run", json: true},
+      ["config", "show"] => {file: "commands/config/show", klass: "Commands::Config::Show", json: true},
+      ["config", "set"] => {file: "commands/config/set", klass: "Commands::Config::Set", json: false},
+      ["config", "test-notification"] => {file: "commands/config/test_notification", klass: "Commands::Config::TestNotification", json: false}
+    }.freeze
+
+    def self.run(argv, stdout: $stdout, stderr: $stderr, config: Config.new)
+      new(argv, stdout: stdout, stderr: stderr, config: config).run
+    end
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, config: Config.new)
+      @argv = argv
+      @stdout = stdout
+      @stderr = stderr
+      @config = config
+      @verbose = false
+    end
+
+    def run
+      # Extract global flags BEFORE processing
+      cli_verbose = @argv.delete("--verbose") ? true : nil
+      cli_json = @argv.delete("--json") ? true : nil
+      cli_host = extract_value_flag("--host")
+      cli_username = extract_value_flag("--basic-auth-user")
+      cli_password = extract_value_flag("--basic-auth-password")
+
+      config_values = @config.load
+
+      @verbose = cli_verbose.nil? ? (config_values["verbose"] || false) : cli_verbose
+      @json = cli_json.nil? ? (config_values["json"] || false) : cli_json
+      @host = cli_host || config_values["host"]
+      @username = cli_username || config_values["basic_auth_user"]
+      @password = cli_password || config_values["basic_auth_password"]
+
+      if @argv.empty?
+        show_help
+        return Commands::EXIT_CODE_SUCCESS
+      end
+
+      # Check if first argument is a flag
+      if /^-/.match?(@argv.first)
+        parse_options
+        return Commands::EXIT_CODE_SUCCESS
+      end
+
+      # Route to commands
+      command = @argv.shift
+      subcommand = @argv.first
+
+      route = ROUTES[[command, subcommand]]
+      if route
+        @argv.shift # consume subcommand
+      else
+        route = ROUTES[[command, nil]]
+      end
+
+      unless route
+        @stderr.puts "Unknown command: #{[command, subcommand].compact.join(" ")}"
+        show_help(@stderr)
+        return Commands::EXIT_CODE_ERROR
+      end
+
+      require_relative route[:file]
+      return Commands::EXIT_CODE_ERROR unless require_host!
+
+      kwargs = {stdout: @stdout, stderr: @stderr, api_client: build_api_client}
+      kwargs[:json] = @json if route[:json]
+
+      resolve_class(route[:klass]).run(@argv, **kwargs)
+    rescue Config::ConfigError => e
+      @stderr.puts "Error: #{e.message}"
+      Commands::EXIT_CODE_ERROR
+    rescue OptionParser::InvalidOption => e
+      @stderr.puts e.message
+      show_help(@stderr)
+      Commands::EXIT_CODE_ERROR
+    rescue EarlyExit => e
+      e.exit_code
+    end
+
+    private
+
+    def parse_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: raygatherer [options] [command]"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-v", "--version", "Show version") do
+          @stdout.puts "raygatherer version #{Raygatherer::VERSION}"
+          raise EarlyExit, Commands::EXIT_CODE_SUCCESS
+        end
+
+        opts.on("-h", "--help", "Show this help message") do
+          show_help
+          raise EarlyExit, Commands::EXIT_CODE_SUCCESS
+        end
+
+        opts.separator ""
+        opts.separator "Commands will be added in future iterations."
+      end.parse!(@argv)
+    end
+
+    def require_host!
+      return true if @host
+      return true if @argv.include?("--help") || @argv.include?("-h")
+      @stderr.puts "Error: --host is required"
+      show_help(@stderr)
+      false
+    end
+
+    def build_api_client
+      return nil unless @host
+      ApiClient.new(@host, username: @username, password: @password,
+        verbose: @verbose, stderr: @stderr)
+    end
+
+    def resolve_class(name)
+      name.split("::").reduce(Raygatherer) { |mod, part| mod.const_get(part) }
+    end
+
+    def extract_value_flag(flag)
+      index = @argv.index(flag)
+      return nil unless index
+      @argv.delete_at(index) # remove the flag
+      @argv.delete_at(index) # remove the value (shifted into same index)
+    end
+
+    def show_help(output = @stdout)
+      output.puts "Usage: raygatherer [options] [command]"
+      output.puts ""
+      output.puts "Options:"
+      output.puts "    -v, --version                    Show version"
+      output.puts "    -h, --help                       Show this help message"
+      output.puts "        --verbose                    Show detailed HTTP request/response information"
+      output.puts "        --host HOST                  Rayhunter host URL (required)"
+      output.puts "        --basic-auth-user USER       Basic auth username"
+      output.puts "        --basic-auth-password PASS   Basic auth password"
+      output.puts "        --json                       Output JSON (for scripts/piping)"
+      output.puts ""
+      output.puts "Commands:"
+      output.puts "    alerts                           Check for active IMSI catcher alerts"
+      output.puts "    recording list                   List recordings on the device"
+      output.puts "    recording download <name>        Download a recording from the device"
+      output.puts "    recording delete <name>          Delete a recording from the device"
+      output.puts "    recording stop                   Stop the current recording"
+      output.puts "    recording start                  Start a new recording"
+      output.puts "    analysis status                   Show analysis queue status"
+      output.puts "    analysis run <name>               Queue a recording for analysis"
+      output.puts "    analysis run --all                Queue all recordings for analysis"
+      output.puts "    config show                       Show device configuration"
+      output.puts "    config set                        Update device configuration (reads JSON from stdin)"
+      output.puts "    config test-notification          Send a test notification"
+      output.puts "    stats                            Show device system stats"
+      output.puts ""
+      output.puts "Configuration:"
+      output.puts "    Config file: ~/.config/raygatherer/config.yml"
+      output.puts "    (or $XDG_CONFIG_HOME/raygatherer/config.yml)"
+      output.puts ""
+      output.puts "    Supported keys: host, basic_auth_user, basic_auth_password, json, verbose"
+      output.puts "    CLI flags always override config file values."
+      output.puts "    Note: config file may contain credentials; consider restricting file permissions."
+      output.puts ""
+      output.puts "Run 'raygatherer COMMAND --help' for more information on a command."
+    end
+  end
+end

data/lib/raygatherer/commands/alerts.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+require_relative "base"
+require_relative "../formatters/json"
+
+module Raygatherer
+  module Commands
+    class Alerts < Base
+      SEVERITY_ORDER = {
+        "Informational" => 0,
+        "Low" => 1,
+        "Medium" => 2,
+        "High" => 3
+      }.freeze
+
+      EXIT_CODE_LOW_SEVERITY = 10
+      EXIT_CODE_MEDIUM_SEVERITY = 11
+      EXIT_CODE_HIGH_SEVERITY = 12
+
+      def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
+        super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
+        @json = json
+        @latest = false
+        @after = nil
+        @recording = nil
+      end
+
+      def run
+        with_error_handling do
+          parse_options
+
+          data = if @recording
+            @api_client.fetch_analysis_report(@recording)
+          else
+            @api_client.fetch_live_analysis_report
+          end
+          alerts = extract_alerts(data[:rows], data[:metadata])
+          alerts = filter_after(alerts) if @after
+          alerts = filter_latest(alerts, data[:rows]) if @latest
+
+          # Select formatter based on --json flag
+          formatter = @json ? Formatters::JSON.new : Formatters::Human.new
+          @stdout.puts formatter.format(alerts)
+
+          # Return severity-based exit code
+          severity_exit_code(alerts)
+        end
+      end
+
+      private
+
+      def parse_options
+        OptionParser.new do |opts|
+          opts.banner = "Usage: raygatherer alerts [options]"
+          opts.separator ""
+          opts.separator "Options:"
+
+          opts.on("--recording NAME", "Analyze a past recording instead of live") do |name|
+            @recording = name
+          end
+
+          opts.on("--latest", "Show only alerts from the most recent message") do
+            @latest = true
+          end
+
+          opts.on("--after TIMESTAMP", "Show only alerts after this time (ISO 8601)") do |ts|
+            @after = parse_timestamp(ts)
+          end
+
+          opts.on("-h", "--help", "Show this help message") do
+            show_help
+            raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+          end
+        end.parse!(@argv)
+      end
+
+      def extract_alerts(rows, metadata)
+        analyzers = metadata&.dig("analyzers") || []
+        alerts = []
+
+        rows.each do |row|
+          events = row["events"] || []
+
+          events.each_with_index do |event, index|
+            next if event.nil?
+
+            event_type = event["event_type"]
+            next unless event_type
+
+            severity_level = SEVERITY_ORDER[event_type] || 0
+            next if severity_level == 0
+
+            alerts << {
+              severity: event_type,
+              message: event["message"],
+              packet_timestamp: row["packet_timestamp"],
+              analyzer: analyzers.dig(index, "name")
+            }
+          end
+        end
+
+        alerts
+      end
+
+      def parse_timestamp(str)
+        Time.parse(str)
+      rescue ArgumentError
+        raise ArgumentError, "invalid timestamp: #{str}"
+      end
+
+      def filter_after(alerts)
+        alerts.select { |a| a[:packet_timestamp] && Time.parse(a[:packet_timestamp]) > @after }
+      end
+
+      def filter_latest(alerts, rows)
+        latest_timestamp = if @after
+          alerts.map { |a| a[:packet_timestamp] }.compact.max
+        else
+          rows.map { |r| r["packet_timestamp"] }.compact.max
+        end
+        return [] if latest_timestamp.nil?
+
+        alerts.select { |a| a[:packet_timestamp] == latest_timestamp }
+      end
+
+      def show_help(output = @stdout)
+        output.puts "Usage: raygatherer [global options] alerts [options]"
+        output.puts ""
+        output.puts "Options:"
+        output.puts "    --recording NAME                 Analyze a past recording instead of live"
+        output.puts "    --after TIMESTAMP                Show only alerts after this time (ISO 8601, exclusive)"
+        output.puts "    --latest                         Show only alerts from the most recent message"
+        output.puts "    -h, --help                       Show this help message"
+        output.puts ""
+        print_global_options(output, json: true)
+        output.puts ""
+        output.puts "Exit Codes:"
+        output.puts "    #{EXIT_CODE_SUCCESS}   No alerts detected"
+        output.puts "    #{EXIT_CODE_ERROR}   Error (connection, parse, missing --host, etc.)"
+        output.puts "    #{EXIT_CODE_LOW_SEVERITY}  Low severity alert"
+        output.puts "    #{EXIT_CODE_MEDIUM_SEVERITY}  Medium severity alert"
+        output.puts "    #{EXIT_CODE_HIGH_SEVERITY}  High severity alert"
+        output.puts ""
+        output.puts "Examples:"
+        output.puts "  raygatherer --host http://192.168.1.100:8080 alerts"
+        output.puts "  raygatherer --host http://192.168.1.100:8080 --json alerts"
+        output.puts "  raygatherer --host http://rayhunter --json alerts"
+        output.puts "  raygatherer --host http://rayhunter alerts --after 2024-02-07T14:25:33Z"
+        output.puts "  [ $? -ge #{EXIT_CODE_MEDIUM_SEVERITY} ] && telegram-send 'Medium+ severity alert!'"
+      end
+
+      def severity_exit_code(alerts)
+        return EXIT_CODE_SUCCESS if alerts.empty?
+
+        max_severity = alerts.map { |a| SEVERITY_ORDER[a[:severity]] || 0 }.max
+        case max_severity
+        when 1 then EXIT_CODE_LOW_SEVERITY
+        when 2 then EXIT_CODE_MEDIUM_SEVERITY
+        when 3 then EXIT_CODE_HIGH_SEVERITY
+        else EXIT_CODE_SUCCESS
+        end
+      end
+    end
+  end
+end