hookd-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b373613f2ef4194aafacdb65fc585e39163d8673d619aa720834ac46083506e9
+  data.tar.gz: a432227574294bbcb7f80c15be7d97a901dc7b33f79e450fcd13f9b9ef7b5f66
+SHA512:
+  metadata.gz: 4f3e6702167c4a92e5110d6da8d946c5f73029dd64df94bd49db1716b053e923a525e83e97ef5c6c3473f5d68ddcdd634ec98d3b50ae4d494a514391cab1902e
+  data.tar.gz: bc2629120bf46c57d13627406cbf886daba9ab2569a5d54cbc9808475311cb5ec6eae3c66cd2c0e442f5ecb8d331f4a2792fd13f24a8b9c4c051b3ace3920201

data/README.md

@@ -0,0 +1,158 @@
+# Hookd Ruby Client
+
+Ruby client library for [Hookd](https://github.com/JoshuaMart/hookd/server), a DNS/HTTP interaction server for security testing and debugging.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hookd-client'
+```
+
+Or install it yourself as:
+
+```bash
+gem install hookd-client
+```
+
+## Usage
+
+### Basic Example
+
+```ruby
+require 'hookd'
+require 'typhoeus'
+
+# Initialize the client
+client = Hookd::Client.new(
+  server: "https://hookd.example.com",
+  token: ENV['HOOKD_TOKEN']
+)
+
+# Register a new hook
+hook = client.register
+puts "DNS endpoint: #{hook.dns}"
+puts "HTTP endpoint: #{hook.http}"
+puts "HTTPS endpoint: #{hook.https}"
+
+# Make a request to the HTTP endpoint to simulate an interaction
+Typhoeus.get(hook.http)
+
+# Poll for interactions
+interactions = client.poll(hook.id)
+interactions.each do |interaction|
+  if interaction.dns?
+    puts "DNS query: #{interaction.data}"
+  elsif interaction.http?
+    puts "HTTP request: #{interaction.data}"
+  end
+end
+```
+
+### Configuration
+
+The client requires two configuration parameters:
+
+- `server`: The Hookd server URL (e.g., `https://hookd.example.com`)
+- `token`: Authentication token for API access
+
+### API Reference
+
+#### `Hookd::Client`
+
+Main client class for interacting with the Hookd server.
+
+##### `#register`
+
+Register a new hook and get DNS/HTTP endpoints.
+
+```ruby
+hook = client.register
+# => #<Hookd::Hook id="abc123" dns="abc123.hookd.example.com" ...>
+```
+
+Returns: `Hookd::Hook` object
+
+Raises:
+- `Hookd::AuthenticationError` - Authentication failed
+- `Hookd::ServerError` - Server error (5xx)
+- `Hookd::ConnectionError` - Connection failed
+
+##### `#poll(hook_id)`
+
+Poll for interactions captured by a hook.
+
+```ruby
+interactions = client.poll("abc123")
+# => [#<Hookd::Interaction type="dns" ...>, ...]
+```
+
+Parameters:
+- `hook_id` (String) - The hook ID to poll
+
+Returns: Array of `Hookd::Interaction` objects
+
+Raises:
+- `Hookd::AuthenticationError` - Authentication failed
+- `Hookd::NotFoundError` - Hook not found
+- `Hookd::ServerError` - Server error (5xx)
+- `Hookd::ConnectionError` - Connection failed
+
+##### `#metrics`
+
+Get server metrics (requires authentication).
+
+```ruby
+metrics = client.metrics
+# => {"total_hooks" => 42, "total_interactions" => 1337, ...}
+```
+
+Returns: Hash with metrics data
+
+#### `Hookd::Hook`
+
+Represents a registered hook with endpoints.
+
+Attributes:
+- `id` (String) - Unique hook identifier
+- `dns` (String) - DNS endpoint
+- `http` (String) - HTTP endpoint
+- `https` (String) - HTTPS endpoint
+- `created_at` (String) - Creation timestamp
+
+#### `Hookd::Interaction`
+
+Represents a captured DNS or HTTP interaction.
+
+Attributes:
+- `type` (String) - Interaction type ("dns" or "http")
+- `timestamp` (String) - When the interaction was captured
+- `data` (Hash) - Interaction details
+
+Methods:
+- `#dns?` - Returns true if this is a DNS interaction
+- `#http?` - Returns true if this is an HTTP interaction
+
+### Error Handling
+
+The client raises specific exceptions for different error conditions:
+
+```ruby
+begin
+  hook = client.register
+rescue Hookd::AuthenticationError
+  puts "Invalid token"
+rescue Hookd::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+rescue Hookd::ServerError => e
+  puts "Server error: #{e.message}"
+end
+```
+
+Exception hierarchy:
+- `Hookd::Error` (base class)
+  - `Hookd::AuthenticationError` - 401 Unauthorized
+  - `Hookd::NotFoundError` - 404 Not Found
+  - `Hookd::ServerError` - 5xx Server Error
+  - `Hookd::ConnectionError` - Network/connection errors

data/lib/hookd/client.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Hookd
+  # HTTP client for interacting with Hookd server
+  class Client
+    attr_reader :server, :token
+
+    def initialize(server:, token:)
+      @server = server
+      @token = token
+      @uri = URI.parse(server)
+    end
+
+    # Register a new hook
+    # @return [Hookd::Hook] the newly registered hook
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    def register
+      response = post('/register')
+      Hook.from_hash(response)
+    end
+
+    # Poll for interactions on a hook
+    # @param hook_id [String] the hook ID to poll
+    # @return [Array<Hookd::Interaction>] array of interactions (may be empty)
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::NotFoundError] if hook not found
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    def poll(hook_id)
+      response = get("/poll/#{hook_id}")
+
+      # Response is {"interactions": [...]}
+      interactions = response['interactions']
+      return [] if interactions.nil? || interactions.empty? || !interactions.is_a?(Array)
+
+      interactions.map { |i| Interaction.from_hash(i) }
+    rescue NoMethodError => e
+      raise Error, "Invalid response format: #{e.message}"
+    end
+
+    # Get server metrics (requires authentication)
+    # @return [Hash] metrics data
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    def metrics
+      get('/metrics')
+    end
+
+    private
+
+    def get(path)
+      request = Net::HTTP::Get.new(path)
+      request['Authorization'] = "Bearer #{token}"
+      execute_request(request)
+    end
+
+    def post(path, body = nil)
+      request = Net::HTTP::Post.new(path)
+      request['Authorization'] = "Bearer #{token}"
+      request['Content-Type'] = 'application/json'
+      request.body = body.to_json if body
+      execute_request(request)
+    end
+
+    def execute_request(request)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = @uri.scheme == 'https'
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200, 201
+        raise Error, 'Empty response body from server' if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      when 401
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 404
+        raise NotFoundError, "Resource not found: #{response.body}"
+      when 500..599
+        raise ServerError, "Server error (#{response.code}): #{response.body}"
+      else
+        raise Error, "Unexpected response (#{response.code}): #{response.body}"
+      end
+    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    rescue JSON::ParserError => e
+      raise Error, "Invalid JSON response: #{e.message}"
+    end
+  end
+end

data/lib/hookd/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Base error class for all Hookd errors
+  class Error < StandardError; end
+
+  # Raised when authentication fails (401)
+  class AuthenticationError < Error; end
+
+  # Raised when a resource is not found (404)
+  class NotFoundError < Error; end
+
+  # Raised when there's a connection error
+  class ConnectionError < Error; end
+
+  # Raised when the server returns a 5xx error
+  class ServerError < Error; end
+end

data/lib/hookd/hook.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Represents a registered hook with DNS and HTTP endpoints
+  class Hook
+    attr_reader :id, :dns, :http, :https, :created_at
+
+    def initialize(id:, dns:, http:, https:, created_at:)
+      @id = id
+      @dns = dns
+      @http = http
+      @https = https
+      @created_at = created_at
+    end
+
+    # Create a Hook from API response hash
+    def self.from_hash(hash)
+      raise ArgumentError, "Invalid hash: expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      new(
+        id: hash['id'],
+        dns: hash['dns'],
+        http: hash['http'],
+        https: hash['https'],
+        created_at: hash['created_at']
+      )
+    end
+
+    def to_s
+      "#<Hookd::Hook id=#{id} dns=#{dns}>"
+    end
+  end
+end

data/lib/hookd/interaction.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Represents a captured DNS or HTTP interaction
+  class Interaction
+    attr_reader :type, :timestamp, :data
+
+    def initialize(type:, timestamp:, data:)
+      @type = type
+      @timestamp = timestamp
+      @data = data
+    end
+
+    # Create an Interaction from API response hash
+    def self.from_hash(hash)
+      new(
+        type: hash['type'],
+        timestamp: hash['timestamp'],
+        data: hash['data']
+      )
+    end
+
+    # Check if this is a DNS interaction
+    def dns?
+      type == 'dns'
+    end
+
+    # Check if this is an HTTP interaction
+    def http?
+      type == 'http'
+    end
+
+    def to_s
+      "#<Hookd::Interaction type=#{type} timestamp=#{timestamp}>"
+    end
+  end
+end

data/lib/hookd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hookd
+  VERSION = '0.1.0'
+end

data/lib/hookd.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'hookd/version'
+require_relative 'hookd/error'
+require_relative 'hookd/hook'
+require_relative 'hookd/interaction'
+require_relative 'hookd/client'
+
+# Hookd client library for interacting with Hookd DNS/HTTP interaction server
+module Hookd
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: hookd-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jomar
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client library for Hookd, a DNS/HTTP interaction server for security
+  testing and debugging
+email:
+- contact@jomar.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hookd.rb
+- lib/hookd/client.rb
+- lib/hookd/error.rb
+- lib/hookd/hook.rb
+- lib/hookd/interaction.rb
+- lib/hookd/version.rb
+homepage: https://github.com/JoshuaMart/hookd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/JoshuaMart/hookd
+  source_code_uri: https://github.com/jomar/JoshuaMart
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for Hookd interaction server
+test_files: []