huntress 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b47fbf82bfacb413dde2b52eed39dfaf2aa240d38798a315efdf3e669b3859c8
+  data.tar.gz: 7726b763502f9ab5f18a1c86057c9118a44abd5ddf518161b528add65cfeaf04
+SHA512:
+  metadata.gz: 075da61fc4b04310b673b0a1e72d32eb2d2a1c044667587fa28781952753873604361c6ccb0c4f87a9dc7e4e16833982ecc754696351596953c14a10d3c9dfc1
+  data.tar.gz: 7c6c0769058c8e5da1b5eefeb9577a9c47b83fb99078e718bd9cd78cbdda79ea494fca3906db623198dc99d129ea3aa603215735de0dd45fb3cba246f6a1d1ab

data/.env.template

@@ -0,0 +1,2 @@
+HUNTRESS_API_KEY=xxx
+HUNTRESS_API_SECRET=xxx

data/.gitignore

@@ -0,0 +1,44 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/data/
+*.log
+*.txt
+*.json
+*.yml
+
+# Used by dotenv library to load environment variables.
+.env
+
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+Gemfile.lock

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.1.0] - 2025-10-31
+
+- Initial release
+

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cloudally.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rubocop', '~> 1.7'
+gem 'simplecov', require: false, group: :test

data/README.md

@@ -0,0 +1,86 @@
+# Sophos Central Partner API
+
+[![Version](https://img.shields.io/gem/v/huntress.svg)](https://rubygems.org/gems/huntress)
+
+
+This is a wrapper for the Huntress API.
+You can see the [API endpoints](https://api.huntress.io/docs)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'huntress'
+```
+
+And then execute:
+
+```console
+> bundle install
+```
+
+Or install it yourself as:
+
+```console
+> gem install huntress
+```
+
+## Usage
+
+Before you start making the requests to API provide the client id and client secret
+and email/password using the configuration wrapping.
+
+```ruby
+require 'huntress'
+
+LOGGER = 'huntres-api.log'
+
+Huntress.reset
+Huntress.logger = Logger.new(AUTH_LOGGER)
+
+Huntress.configure do |config|
+  config.client_id = ENV['HUNTRESS_API_KEY']
+  config.client_secret = ENV['HUNTRESS_API_SECRET']
+end
+client = Huntress.client
+result = client.login
+```
+
+## Resources
+
+### Authentication
+
+```ruby
+# setup configuration
+#
+client.login
+```
+
+|Resource|API endpoint|Description|
+|:--|:--|:--|
+|.login|||
+
+### Operations
+
+Huntress endpoint implemented
+
+|Resource|API endpoint|
+|:--|:--|
+|.account                                               |/v1/account|
+|.actor                                                 |/v1/actor|
+|.agents, .agent(id)                                    |/v1/agents/{id}|
+|.billing_reports, .billing_report                      |/v1/billing_reports/{id}|
+|.incident_reports, .incident_report(id)                |/v1/incident_reports/{id}|
+|.remediations(report_id), .remediation(report_id, id)  |/v1incident_reports/{report_id}/remediations/{id}|
+|.organizations, .organization(id)                      |/v1/organizations/{id}|
+|.reports, .report(id)                                  |/v1/reports/{id}|
+|.signals, .signal(id)                                  |/v1/signals/{id}|
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jancotanis/huntress).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'dotenv'
+require 'rake/testtask'
+
+Dotenv.load
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+  at_exit do
+    system './bin/cc-test-reporter after-build'
+  end
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+task default: %i[test rubocop]

data/huntress.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/huntress/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'huntress'
+  s.version     = Huntress::VERSION
+  s.authors     = ['Janco Tanis']
+  s.email       = 'gems@jancology.com'
+  s.license     = 'MIT'
+
+  s.summary     = 'A Ruby wrapper for the Huntress APIs (readonly)'
+  s.homepage    = 'https://rubygems.org/gems/huntress'
+
+  s.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
+
+  s.metadata['homepage_uri'] = s.homepage
+  s.metadata['source_code_uri'] = 'https://github.com/jancotanis/huntress'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  s.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  s.bindir        = 'exe'
+  s.executables   = s.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.platform = Gem::Platform::RUBY
+  s.add_runtime_dependency 'faraday'
+  s.add_runtime_dependency 'wrapi', ">= 0.5.0"
+  s.add_development_dependency 'dotenv'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rubocop'
+end

data/lib/huntress/api.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'wrapi'
+require File.expand_path('connection', __dir__)
+require File.expand_path('authentication', __dir__)
+
+module Huntress
+  # @private
+  class API
+    # @private
+    attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new API and copies settings from singleton
+    def initialize(options = {})
+      options = Huntress.options.merge(options)
+      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def config
+      conf = {}
+      WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
+        conf[key] = send key
+      end
+      conf
+    end
+
+    include WrAPI::Connection
+    include Connection
+    include WrAPI::Request
+    include WrAPI::Authentication
+    include Authentication
+  end
+end

data/lib/huntress/authentication.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'base64'
+require File.expand_path('error', __dir__)
+
+module Huntress
+  # Deals with authentication flow and stores it within global configuration
+  module Authentication
+    #
+    # Authorize to the Hudu portal and return access_token
+    def login(options = {})
+      raise ArgumentError, 'client_id not set' unless client_id
+      raise ArgumentError, 'client_secret not set' unless client_secret
+
+      # pass api key (id) and secret using basic authentication/connection
+      self.token_type = 'Basic'
+      self.access_token = Base64.strict_encode64("#{client_id}:#{client_secret}")
+
+      # will do sanitty check if token if valid
+      get('/v1/account', options)
+    rescue Faraday::Error => e
+      raise AuthenticationError, e
+    end
+  end
+end

data/lib/huntress/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require File.expand_path('api', __dir__)
+#require File.expand_path('asset_helper', __dir__)
+
+module Huntress
+  # The Client class serves as a wrapper for the Hudu REST API, providing methods to interact
+  # with various Hudu resources.
+  #
+  # This class dynamically defines methods to fetch, create, update, and manipulate Hudu resources
+  # such as companies, articles, assets, and more.
+  #
+  # @example Basic Usage
+  #   client.companies # Fetch all companies
+  #   client.company(1) # Fetch a company by ID
+  #   client.update_company(1, { name: "Updated Company" }) # Update a company
+  #   client.create_company({ name: "New Company" }) # Create a new company
+  class Client < API
+
+    # Dynamically defines methods for interacting with Hudu API resources.
+    #
+    # Depending on the arguments, this will define methods to:
+    # - Fetch all records for a resource
+    # - Fetch a specific record by ID
+    # - Update a record
+    # - Create a new record
+    #
+    # @param method [Symbol] The method name for fetching all records.
+    # @param singular_method [Symbol, nil] The method name for fetching a single record by ID. Optional.
+    # @param path [String] The API path for the resource. Defaults to the method name.
+    #
+    # @example Defining endpoints
+    #   api_endpoint :companies, :company
+    #   # Defines:
+    #   # - `companies(params = {})` to fetch all companies.
+    #   # - `company(id, params = {})` to fetch a single company by ID.
+    #   # - `update_companies(id, params = {})` to update a company.
+    #   # - `create_companies(params = {})` to create a new company.
+    def self.api_endpoint(method, singular_method = nil, path = method)
+      if singular_method
+        # Define method to fetch all records and one by id
+        send(:define_method, method) do |params = {}|
+          r = get_paged(api_url(path), params)
+        end
+        # Define method to fetch a single record by ID
+        send(:define_method, singular_method) do |id, params = {}|
+          r = get(api_url("#{path}/#{id}"), params)
+        end
+      else
+        # Define simple method to fetch data
+        send(:define_method, method) do |params = {}|
+          get(api_url(path), params)
+        end
+      end
+    end
+
+    def account(options = {})
+      get(api_url('account'), options)
+    end
+
+    def actor(options = {})
+      get(api_url('actor'), options)
+    end
+
+    def remediation(incident_report_id, remediation, options = {})
+      get_paged(api_url("incident_reports/#{incident_report_id}/remediations/#{remediation}"), options)
+    end
+
+    def remediations(incident_report_id, options = {})
+      #get_paged(api_url("incident_reports/#{incident_report_id}/remediations"), options)
+      remediation(incident_report_id, nil, options)
+    end
+
+    # Define API endpoints for various resources
+    api_endpoint :agents, :agent
+    api_endpoint :billing_reports, :billing_report
+    api_endpoint :incident_reports, :incident_report
+    api_endpoint :organizations, :organization
+    api_endpoint :reports, :report
+    api_endpoint :signals, :signal
+
+
+    # Constructs the full API URL for a given path.
+    #
+    # @param path [String] The API path.
+    # @return [String] The full API URL.
+    def api_url(path)
+      "/v1/#{path}"
+    end
+
+  end
+end

data/lib/huntress/connection.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Huntress
+  # Create connection including and keep it persistent so we add the rate throtling middleware only once
+  module Connection
+    private
+
+    def connection
+      unless @connection
+        @connection = super
+        @connection.use WrAPI::RateThrottleMiddleware, limit: 60, period: 60
+      end
+      @connection
+    end
+  end
+end

data/lib/huntress/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Huntress
+  # Generic error to be able to rescue all Hudu errors
+  class HuntressError < StandardError; end
+
+  # Error when authentication fails
+  class AuthenticationError < HuntressError; end
+end

data/lib/huntress/pagination.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+
+module Huntress
+  # Defines HTTP request methods
+  # @see https://api.huntress.io/docs
+  module RequestPagination
+    # The PaginationPager class provides a mechanism to handle pagination information for API responses.
+    #
+    # It manages the current page, page size, and provides utilities for determining if there are more pages to fetch.
+    #
+    # @example Basic Usage
+    #   pager = PaginationPager.new(50)
+    #   while pager.more_pages?
+    #     response = api_client.get_data(pager.page_options)
+    #     pager.next_page!(response.body)
+    #   end
+    class PaginationPager
+      # Initializes a new PaginationPager instance.
+      #
+      # @param page_size [Integer] The number of records to fetch per page.
+      def initialize(page_size)
+        @page = 1
+        @page_token = @pagination_data = nil
+        @limit = page_size
+      end
+
+      # Provides the current pagination parameter options for each rest request.
+      #
+      # @return [Hash] A hash containing the current page and page size.
+      #
+      # @example
+      #   pager.page_options # => { page_token: 'Mjadso43289', page_size: 50 }
+      def page_options
+        options = { limit: @limit }
+        options.merge!({ page_token: @page_token }) if @page_token
+        options
+      end
+
+      # Advances to the next page based on the response body and updates internal pagination state.
+      #
+      # @param body [Hash] The response body from the API, expected to contain a paginated resource.
+      # @return [Integer] The updated page total, typically the count of items on the current page.
+      #
+      # @example
+      #   response_body = { "items" => [...] }
+      #   pager.next_page!(response_body)
+      def next_page!(body)
+        @page += 1
+        @pagination_data = PaginationPager.pagination_data(body)
+      end
+
+      # Determines whether there are more pages to fetch.
+      #
+      # @return [Boolean] Returns `true` if the current page is full, indicating another page might exist.
+      #
+      # @example
+      #   pager.more_pages? # => true or false
+      def more_pages?
+        # while full page we have next page
+        if @pagination_data
+          @page_token = @pagination_data["next_page_token"]
+        else
+          @page.eql? 1
+        end
+      end
+
+      # Extracts paginated data from the response body.
+      #
+      # @param body [Hash] The response body containing resource data, expected to be in a hash format.
+      # @return [Array, Hash, Object] Returns the extracted data, which could be an array, hash, or other object.
+      #
+      # @example
+      #   response_body = { "items" => [1, 2, 3] }
+      #   PaginationPager.data(response_body) # => [1, 2, 3]
+      def self.data(body)
+        # assume hash {"resource":[...]}, get first key and return array data
+        result = body
+        if result.is_a?(Hash)
+          _k, v = body.first
+          result = v if v.is_a?(Array) || v.is_a?(Hash)
+        end
+        result
+      end
+
+      # Extracts pagination information
+      #
+      # @param body [Hash] The response body containing resource data, and pagination infromation in a hash format.
+      # @return Hash Returns the extracted data, which could be an array, hash, or other object.
+      #
+      # @example
+      #   response_body = { 
+      #     "items" => [1, 2, 3],
+      #     "pagination" => {"current_page" => 1, "current_page_count": 10, "limit": 10, "total_count":60, "next_page": 2,
+      #     "next_page_url": "https://api.xx.io/v1/signals?page_token=NjEyNjgxMzE%3D&limit=10", "next_page_token": "NjEyNjgxMzE=" } }
+      #   PaginationPager.pagination_data(response_body) # => {"current_page" => 1, "current_page_count": 10, ...
+      def self.pagination_data(body)
+        # assume hash {"resource":[...], "pagination":{}}, return pagination data
+        result = nil
+        if body.is_a?(Hash)
+          result = body["pagination"]
+        end
+        result
+      end
+    end
+  end
+end

data/lib/huntress/version.rb

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

data/lib/huntress.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'wrapi'
+require File.expand_path('huntress/version', __dir__)
+require File.expand_path('huntress/client', __dir__)
+require File.expand_path('huntress/pagination', __dir__)
+
+# The Huntress module provides utilities to manage and manipulate assets within the Huntress api
+module Huntress
+  extend WrAPI::Configuration
+  extend WrAPI::RespondTo
+
+  # Default User-Agent header sent with API requests, including gem version information.
+  DEFAULT_UA = "Huntress Ruby API wrapper #{Huntress::VERSION}"
+  # Default api endpoint
+  DEFAULT_ENDPOINT = 'https://api.huntress.io'
+  DEFAULT_PAGINATION = RequestPagination::PaginationPager
+  DEFAULT_PAGE_SIZE = 25
+
+  #
+  # @return [Huntress::Client]
+  def self.client(options = {})
+    Huntress::Client.new({
+      endpoint: DEFAULT_ENDPOINT,
+      user_agent: DEFAULT_UA,
+      page_size: DEFAULT_PAGE_SIZE,
+      pagination_class: DEFAULT_PAGINATION
+    }.merge(options))
+  end
+
+  # Resets the Skykick configuration to default values.
+  #
+  # This method resets the configuration values to their defaults:
+  # - `DEFAULT_UA` for the User-Agent
+  #
+  # @example Reset the Huntress configuration:
+  #   Huntress.reset
+  def self.reset
+    super
+    self.endpoint = DEFAULT_ENDPOINT
+    self.user_agent = DEFAULT_UA
+    self.page_size        = DEFAULT_PAGE_SIZE
+    self.pagination_class = DEFAULT_PAGINATION
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: huntress
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Janco Tanis
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: wrapi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email: gems@jancology.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.template"
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- README.md
+- Rakefile
+- huntress.gemspec
+- lib/huntress.rb
+- lib/huntress/api.rb
+- lib/huntress/authentication.rb
+- lib/huntress/client.rb
+- lib/huntress/connection.rb
+- lib/huntress/error.rb
+- lib/huntress/pagination.rb
+- lib/huntress/version.rb
+homepage: https://rubygems.org/gems/huntress
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubygems.org/gems/huntress
+  source_code_uri: https://github.com/jancotanis/huntress
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A Ruby wrapper for the Huntress APIs (readonly)
+test_files: []