htb 0.1.0

data/lib/htb/machines.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module HTB
+  class Machines
+    def initialize(client)
+      @client = client
+    end
+
+    # List all machines
+    # GET /api/v4/machine/list
+    def list
+      @client.get("/machine/list")
+    end
+
+    # Get machine profile by ID or name
+    # GET /api/v4/machine/profile/{id_or_name}
+    def profile(id_or_name)
+      @client.get("/machine/profile/#{id_or_name}")
+    end
+
+    # Get active machine
+    # GET /api/v4/machine/active
+    def active
+      @client.get("/machine/active")
+    end
+
+    # Play/start a machine (free VPN users)
+    # POST /api/v4/machine/play/{machine_id}
+    def play(machine_id)
+      @client.post("/machine/play/#{machine_id}")
+    end
+
+    # Stop a machine
+    # POST /api/v4/machine/stop
+    def stop
+      @client.post("/machine/stop")
+    end
+
+    # Submit flag for machine ownership
+    # POST /api/v4/machine/own
+    # @param machine_id [Integer] Machine ID
+    # @param flag [String] The flag to submit
+    # @param difficulty [Integer] Difficulty rating (10-100)
+    def own(machine_id:, flag:, difficulty: 50)
+      @client.post("/machine/own", {
+        id: machine_id,
+        flag: flag,
+        difficulty: difficulty
+      })
+    end
+
+    # Submit user flag
+    # POST /api/v4/machine/own/user/{machine_id}
+    def own_user(machine_id, flag:, difficulty: 50)
+      @client.post("/machine/own/user/#{machine_id}", {
+        flag: flag,
+        difficulty: difficulty
+      })
+    end
+
+    # Submit root flag
+    # POST /api/v4/machine/own/root/{machine_id}
+    def own_root(machine_id, flag:, difficulty: 50)
+      @client.post("/machine/own/root/#{machine_id}", {
+        flag: flag,
+        difficulty: difficulty
+      })
+    end
+
+    # Get machine activity
+    # GET /api/v4/machine/activity/{machine_id}
+    def activity(machine_id)
+      @client.get("/machine/activity/#{machine_id}")
+    end
+
+    # Get todo list for machine
+    # GET /api/v4/machine/todo/{machine_id}
+    def todo(machine_id)
+      @client.get("/machine/todo/#{machine_id}")
+    end
+
+    # Update todo status for machine
+    # POST /api/v4/machine/todo/update/{machine_id}
+    def update_todo(machine_id, flag_type:)
+      @client.post("/machine/todo/update/#{machine_id}", { flag_type: flag_type })
+    end
+
+    # Submit machine review
+    # POST /api/v4/machine/review
+    # @param machine_id [Integer] Machine ID
+    # @param stars [Integer] Star rating (1-5)
+    # @param headline [String] Review headline
+    # @param review [String] Review text
+    def review(machine_id:, stars:, headline:, review:)
+      @client.post("/machine/review", {
+        id: machine_id,
+        stars: stars,
+        headline: headline,
+        review: review
+      })
+    end
+
+    # Get recommended machines
+    # GET /api/v4/machine/recommended
+    def recommended
+      @client.get("/machine/recommended")
+    end
+
+    # Get spawned machines
+    # GET /api/v4/machine/spawned
+    def spawned
+      @client.get("/machine/spawned")
+    end
+
+    # Get retired machines
+    # GET /api/v4/machine/list/retired
+    def retired
+      @client.get("/machine/list/retired")
+    end
+
+    # Get starting point machines
+    # GET /api/v4/machine/list/sp
+    def starting_point
+      @client.get("/machine/list/sp")
+    end
+
+    # Get paginated machine list
+    # GET /api/v4/machine/paginated
+    def paginated(page: 1, per_page: 20, sort_by: nil, sort_type: nil)
+      params = { page: page, per_page: per_page }
+      params[:sort_by] = sort_by if sort_by
+      params[:sort_type] = sort_type if sort_type
+      @client.get("/machine/paginated", params)
+    end
+
+    # Search machines
+    # GET /api/v4/search/fetch?query={query}&tags=[]
+    def search(query, tags: [])
+      @client.get("/search/fetch", { query: query, tags: tags })
+    end
+  end
+end

data/lib/htb/users.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module HTB
+  class Users
+    def initialize(client)
+      @client = client
+    end
+
+    # Get current user info
+    # GET /api/v4/user/info
+    def info
+      @client.get("/user/info")
+    end
+
+    # Get user profile by ID
+    # GET /api/v4/user/profile/basic/{user_id}
+    def profile(user_id)
+      @client.get("/user/profile/basic/#{user_id}")
+    end
+
+    # Get current user's profile
+    # GET /api/v4/user/profile/basic/me
+    def me
+      @client.get("/user/profile/basic/me")
+    end
+
+    # Get user's activity
+    # GET /api/v4/user/profile/activity/{user_id}
+    def activity(user_id)
+      @client.get("/user/profile/activity/#{user_id}")
+    end
+
+    # Get user's bloods (first solves)
+    # GET /api/v4/user/profile/bloods/{user_id}
+    def bloods(user_id)
+      @client.get("/user/profile/bloods/#{user_id}")
+    end
+
+    # Get user's progress
+    # GET /api/v4/user/profile/progress/machines/os/{user_id}
+    def machine_progress(user_id)
+      @client.get("/user/profile/progress/machines/os/#{user_id}")
+    end
+
+    # Get user's challenge progress
+    # GET /api/v4/user/profile/progress/challenges/{user_id}
+    def challenge_progress(user_id)
+      @client.get("/user/profile/progress/challenges/#{user_id}")
+    end
+
+    # Get user's content (writeups, etc.)
+    # GET /api/v4/user/profile/content/{user_id}
+    def content(user_id)
+      @client.get("/user/profile/content/#{user_id}")
+    end
+
+    # Update user settings
+    # PUT /api/v4/user/settings
+    def update_settings(settings)
+      @client.put("/user/settings", settings)
+    end
+
+    # Get user's connections (followers/following)
+    # GET /api/v4/user/profile/connections/{user_id}
+    def connections(user_id)
+      @client.get("/user/profile/connections/#{user_id}")
+    end
+
+    # Follow a user
+    # POST /api/v4/user/follow/{user_id}
+    def follow(user_id)
+      @client.post("/user/follow/#{user_id}")
+    end
+
+    # Unfollow a user
+    # DELETE /api/v4/user/follow/{user_id}
+    def unfollow(user_id)
+      @client.delete("/user/follow/#{user_id}")
+    end
+
+    # Get user's badges
+    # GET /api/v4/user/profile/badges/{user_id}
+    def badges(user_id)
+      @client.get("/user/profile/badges/#{user_id}")
+    end
+
+    # Get subscriptions info
+    # GET /api/v4/user/subscriptions
+    def subscriptions
+      @client.get("/user/subscriptions")
+    end
+
+    # Get user's rank history
+    # GET /api/v4/user/profile/graph/{period}/{user_id}
+    # period: 1M, 3M, 6M, 1Y
+    def rank_history(user_id, period: "1Y")
+      @client.get("/user/profile/graph/#{period}/#{user_id}")
+    end
+  end
+end

data/lib/htb/version.rb

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

data/lib/htb/vm.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module HTB
+  class VM
+    def initialize(client)
+      @client = client
+    end
+
+    # Spawn a machine (VIP/Starting Point)
+    # POST /api/v4/vm/spawn
+    # @param machine_id [Integer] The machine ID to spawn
+    # @return [Hash] Response containing spawn status
+    #
+    # @example
+    #   client.vm.spawn(811)
+    #   # => { "success" => "1", "message" => "Machine is being spawned..." }
+    #
+    # Note: This endpoint is used for VIP and Starting Point machines.
+    # The base URI changed from www.hackthebox.com to labs.hackthebox.com
+    def spawn(machine_id)
+      @client.post("/vm/spawn", { machine_id: machine_id })
+    end
+
+    # Terminate a running machine
+    # POST /api/v4/vm/terminate
+    # @param machine_id [Integer] The machine ID to terminate
+    def terminate(machine_id)
+      @client.post("/vm/terminate", { machine_id: machine_id })
+    end
+
+    # Reset a machine
+    # POST /api/v4/vm/reset
+    # @param machine_id [Integer] The machine ID to reset
+    def reset(machine_id)
+      @client.post("/vm/reset", { machine_id: machine_id })
+    end
+
+    # Extend machine time
+    # POST /api/v4/vm/extend
+    # @param machine_id [Integer] The machine ID to extend
+    def extend(machine_id)
+      @client.post("/vm/extend", { machine_id: machine_id })
+    end
+
+    # Get VM status
+    # GET /api/v4/vm/status
+    def status
+      @client.get("/vm/status")
+    end
+
+    # Get active VM
+    # GET /api/v4/vm/active
+    def active
+      @client.get("/vm/active")
+    end
+
+    # Transfer VM to another lab
+    # POST /api/v4/vm/transfer
+    def transfer(machine_id:, lab_id:)
+      @client.post("/vm/transfer", { machine_id: machine_id, lab_id: lab_id })
+    end
+  end
+end

data/lib/htb/vpn.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module HTB
+  class VPN
+    def initialize(client)
+      @client = client
+    end
+
+    # Get VPN server list
+    # GET /api/v4/connections/servers
+    def servers
+      @client.get("/connections/servers")
+    end
+
+    # Get current VPN connection status
+    # GET /api/v4/connections/status
+    def status
+      @client.get("/connections/status")
+    end
+
+    # Switch VPN server
+    # POST /api/v4/connections/servers/switch/{server_id}
+    def switch(server_id)
+      @client.post("/connections/servers/switch/#{server_id}")
+    end
+
+    # Regenerate VPN config
+    # POST /api/v4/connections/regenerate
+    def regenerate
+      @client.post("/connections/regenerate")
+    end
+
+    # Download VPN config
+    # GET /api/v4/access/ovpnfile/{server_id}/{tcp_or_udp}
+    # @param server_id [Integer] VPN server ID
+    # @param protocol [String] "tcp" or "udp" (default: "udp")
+    def download_config(server_id, protocol: "udp")
+      @client.get("/access/ovpnfile/#{server_id}/#{protocol}")
+    end
+
+    # Get labs list
+    # GET /api/v4/labs/list
+    def labs
+      @client.get("/labs/list")
+    end
+
+    # Get available labs for user
+    # GET /api/v4/labs/available
+    def available_labs
+      @client.get("/labs/available")
+    end
+
+    # Get lab info
+    # GET /api/v4/lab/info/{lab_id}
+    def lab_info(lab_id)
+      @client.get("/lab/info/#{lab_id}")
+    end
+
+    # Get prolabs list
+    # GET /api/v4/prolab/list
+    def prolabs
+      @client.get("/prolab/list")
+    end
+
+    # Get prolab info
+    # GET /api/v4/prolab/info/{prolab_id}
+    def prolab_info(prolab_id)
+      @client.get("/prolab/info/#{prolab_id}")
+    end
+
+    # Get fortress list
+    # GET /api/v4/fortress/list
+    def fortresses
+      @client.get("/fortress/list")
+    end
+
+    # Get endgame list
+    # GET /api/v4/endgame/list
+    def endgames
+      @client.get("/endgame/list")
+    end
+  end
+end

data/lib/htb.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+require_relative "htb/version"
+require_relative "htb/config"
+require_relative "htb/client"
+require_relative "htb/machines"
+require_relative "htb/users"
+require_relative "htb/vm"
+require_relative "htb/challenges"
+require_relative "htb/vpn"
+
+module HTB
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class NotFoundError < Error; end
+
+  # Base URI for HTB API v4
+  # Note: The base URI changed from www.hackthebox.com to labs.hackthebox.com
+  BASE_URI = "https://labs.hackthebox.com"
+  API_VERSION = "v4"
+
+  class << self
+    attr_accessor :api_token
+
+    def configure
+      yield self
+    end
+
+    def client
+      @client ||= Client.new(api_token: api_token)
+    end
+
+    def reset_client!
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,225 @@
+--- !ruby/object:Gem::Specification
+name: htb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- usiegj00
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby gem for interacting with the Hack The Box (HTB) API v4. Supports
+  machine management, user profiles, VM spawning, flag submission, and more.
+email:
+- usiegj00@users.noreply.github.com
+executables:
+- htb
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/htb
+- htb.gemspec
+- lib/htb.rb
+- lib/htb/challenges.rb
+- lib/htb/cli.rb
+- lib/htb/cli/challenges.rb
+- lib/htb/cli/machines.rb
+- lib/htb/cli/main.rb
+- lib/htb/cli/users.rb
+- lib/htb/cli/vm.rb
+- lib/htb/cli/vpn.rb
+- lib/htb/client.rb
+- lib/htb/config.rb
+- lib/htb/machines.rb
+- lib/htb/users.rb
+- lib/htb/version.rb
+- lib/htb/vm.rb
+- lib/htb/vpn.rb
+homepage: https://github.com/aluminumio/htb-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aluminumio/htb-ruby
+  source_code_uri: https://github.com/aluminumio/htb-ruby
+  changelog_uri: https://github.com/aluminumio/htb-ruby/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby client for the Hack The Box API v4
+test_files: []