htb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e6caea0b99b8c05235a7d882577af1a106b5313efdbe8e8034bdd18a18f1c83
+  data.tar.gz: d8e9addfbe08acc7acaaf30d5a033871b93b9271bcc93a0d85dd2bd33c914da5
+SHA512:
+  metadata.gz: 053eb8609fd604dd1921c30279a686bc86d4362f9e4756e518168a505deeb720210d75aea4e2d84ddedf8510da71e49a036e7076560f304ab19076a2a96f3787
+  data.tar.gz: 853a12f640c67d268078cbf8fbf540bf5d7875d186ee8c1b0896d58db2b3f1f0f64b5c58bfcc3d4702fae675a2b902c401d631bdbd9c53cc71be2b2d94294e81

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-17
+
+### Added
+
+- Initial release
+- Machine management (list, profile, play, stop, own)
+- VM management (spawn, terminate, reset, extend)
+- User profiles and activity
+- Challenge management
+- VPN and lab information
+- Support for the updated base URI (`labs.hackthebox.com`)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 usiegj00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,369 @@
+# HTB Ruby
+
+A Ruby gem for interacting with the [Hack The Box](https://www.hackthebox.com/) API v4.
+
+## Important: Base URI Change
+
+The HTB API base URI has changed from the legacy `www.hackthebox.com` to `labs.hackthebox.com`. This gem uses the correct, updated base URI.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'htb'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install htb
+```
+
+## Configuration
+
+You'll need an HTB API token. You can obtain one from your [HTB Account Settings](https://app.hackthebox.com/profile/settings).
+
+### Interactive Login (Recommended)
+
+The easiest way to configure your token:
+
+```bash
+htb login
+```
+
+This will:
+1. Prompt you for your API token (input is masked)
+2. Validate the token with HTB
+3. Save it securely to `~/.htbrc` (with 600 permissions)
+
+### Environment Variable
+
+Alternatively, set an environment variable (takes priority over config file):
+
+```bash
+export HTB_API_TOKEN=your_token_here
+```
+
+### Managing Configuration
+
+```bash
+htb config   # Show current configuration
+htb login    # Set/update API token
+htb logout   # Remove saved token
+```
+
+## CLI Usage
+
+The gem includes a full-featured command-line interface.
+
+### Quick Start
+
+```bash
+# First time? Login to save your token
+htb login
+
+# Show your profile
+htb me
+
+# Show current status (VM + VPN)
+htb status
+
+# List machines
+htb machines list
+htb machines list --retired
+htb machines list --sp
+
+# Get machine info
+htb machines info Gavel
+htb machines info 811
+
+# Spawn/terminate machines
+htb spawn 811
+htb terminate 811
+
+# Or using subcommands
+htb vm spawn 811
+htb vm terminate 811
+htb vm reset 811
+htb vm extend 811
+
+# Submit flags
+htb machines own 811 --flag "HTB{...}"
+```
+
+### All CLI Commands
+
+```bash
+# Main commands
+htb status              # Show VM and VPN status
+htb me                  # Show your profile
+htb spawn MACHINE_ID    # Spawn a machine (shortcut)
+htb terminate MACHINE_ID # Terminate a machine (shortcut)
+htb version             # Show version
+
+# Machine commands
+htb machines list       # List active machines
+htb machines list --retired  # List retired machines
+htb machines list --sp  # List Starting Point machines
+htb machines info NAME  # Show machine details
+htb machines active     # Show active machine
+htb machines play ID    # Start machine (free VPN)
+htb machines stop       # Stop current machine
+htb machines own ID --flag FLAG  # Submit a flag
+htb machines search QUERY  # Search machines
+htb machines recommended   # Show recommendations
+
+# VM commands
+htb vm spawn ID         # Spawn machine (VIP/SP)
+htb vm terminate ID     # Terminate machine
+htb vm reset ID         # Reset machine
+htb vm extend ID        # Extend time
+htb vm status           # Show VM status
+htb vm active           # Show active VM
+
+# User commands
+htb users me            # Your profile
+htb users info USER_ID  # User profile by ID
+htb users activity USER_ID  # User activity
+htb users bloods USER_ID    # User's first bloods
+htb users badges USER_ID    # User's badges
+htb users subscriptions     # Your subscriptions
+
+# Challenge commands
+htb challenges list     # List challenges
+htb challenges list --retired  # Retired challenges
+htb challenges info ID  # Challenge details
+htb challenges start ID # Start a challenge
+htb challenges stop ID  # Stop a challenge
+htb challenges spawn ID # Spawn instance
+htb challenges own ID --flag FLAG  # Submit flag
+htb challenges categories  # List categories
+htb challenges active   # Show active challenge
+
+# VPN commands
+htb vpn status          # Connection status
+htb vpn servers         # List VPN servers
+htb vpn switch ID       # Switch server
+htb vpn regenerate      # Regenerate config
+htb vpn labs            # List labs
+htb vpn prolabs         # List Pro Labs
+htb vpn endgames        # List Endgames
+htb vpn fortresses      # List Fortresses
+```
+
+## Ruby Library Usage
+
+```ruby
+require 'htb'
+
+# Configure globally
+HTB.configure do |config|
+  config.api_token = ENV['HTB_API_TOKEN']
+end
+
+# Or create a client directly
+client = HTB::Client.new(api_token: ENV['HTB_API_TOKEN'])
+```
+
+## Library Examples
+
+### Machines
+
+```ruby
+client = HTB::Client.new(api_token: ENV['HTB_API_TOKEN'])
+
+# List all machines
+machines = client.machines.list
+
+# Get machine profile
+machine = client.machines.profile("Gavel")  # by name
+machine = client.machines.profile(811)       # by ID
+
+# Get active machine
+active = client.machines.active
+
+# Get retired machines
+retired = client.machines.retired
+
+# Get Starting Point machines
+sp = client.machines.starting_point
+
+# Submit a flag
+client.machines.own(machine_id: 811, flag: "HTB{...}", difficulty: 50)
+```
+
+### VM Management (Spawn/Terminate)
+
+```ruby
+# Spawn a machine (VIP/Starting Point)
+client.vm.spawn(811)
+
+# Get VM status
+status = client.vm.status
+
+# Get active VM
+active = client.vm.active
+
+# Terminate a machine
+client.vm.terminate(811)
+
+# Reset a machine
+client.vm.reset(811)
+
+# Extend machine time
+client.vm.extend(811)
+```
+
+### Users
+
+```ruby
+# Get current user info
+me = client.users.me
+
+# Get user profile by ID
+user = client.users.profile(12345)
+
+# Get user activity
+activity = client.users.activity(12345)
+
+# Get user badges
+badges = client.users.badges(12345)
+
+# Get subscriptions
+subs = client.users.subscriptions
+```
+
+### Challenges
+
+```ruby
+# List all challenges
+challenges = client.challenges.list
+
+# Get challenge info
+challenge = client.challenges.info(123)
+
+# Start a challenge
+client.challenges.start(123)
+
+# Submit flag
+client.challenges.own(challenge_id: 123, flag: "HTB{...}", difficulty: 50)
+
+# Stop a challenge
+client.challenges.stop(123)
+```
+
+### VPN
+
+```ruby
+# Get VPN servers
+servers = client.vpn.servers
+
+# Get connection status
+status = client.vpn.status
+
+# Get available labs
+labs = client.vpn.labs
+
+# Get Prolabs list
+prolabs = client.vpn.prolabs
+
+# Get Endgames list
+endgames = client.vpn.endgames
+```
+
+## API Endpoints Reference
+
+This gem implements the HTB v4 API endpoints. The base URI is `https://labs.hackthebox.com/api/v4`.
+
+### Machines
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/machine/list` | List all machines |
+| GET | `/machine/profile/{id_or_name}` | Get machine profile |
+| GET | `/machine/active` | Get active machine |
+| POST | `/machine/play/{machine_id}` | Play machine (free VPN) |
+| POST | `/machine/stop` | Stop machine |
+| POST | `/machine/own` | Submit flag |
+| GET | `/machine/recommended` | Get recommended machines |
+| GET | `/machine/list/retired` | List retired machines |
+| GET | `/machine/list/sp` | List Starting Point machines |
+
+### VM Management
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/vm/spawn` | Spawn a machine (VIP/SP) |
+| POST | `/vm/terminate` | Terminate a machine |
+| POST | `/vm/reset` | Reset a machine |
+| POST | `/vm/extend` | Extend machine time |
+| GET | `/vm/status` | Get VM status |
+| GET | `/vm/active` | Get active VM |
+
+### Users
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/user/info` | Get current user info |
+| GET | `/user/profile/basic/{user_id}` | Get user profile |
+| GET | `/user/profile/basic/me` | Get own profile |
+| GET | `/user/profile/activity/{user_id}` | Get user activity |
+| GET | `/user/profile/bloods/{user_id}` | Get user bloods |
+| GET | `/user/profile/badges/{user_id}` | Get user badges |
+
+### Challenges
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/challenge/list` | List all challenges |
+| GET | `/challenge/info/{id}` | Get challenge info |
+| POST | `/challenge/start/{id}` | Start a challenge |
+| POST | `/challenge/stop/{id}` | Stop a challenge |
+| POST | `/challenge/own` | Submit flag |
+| GET | `/challenge/categories/list` | Get categories |
+
+### VPN & Labs
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/connections/servers` | Get VPN servers |
+| GET | `/connections/status` | Get VPN status |
+| GET | `/labs/list` | Get labs list |
+| GET | `/prolab/list` | Get Prolabs list |
+| GET | `/endgame/list` | Get Endgames list |
+
+## Error Handling
+
+```ruby
+begin
+  client.machines.profile("nonexistent")
+rescue HTB::AuthenticationError => e
+  puts "Invalid API token"
+rescue HTB::NotFoundError => e
+  puts "Resource not found"
+rescue HTB::RateLimitError => e
+  puts "Rate limited, slow down"
+rescue HTB::Error => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aluminumio/htb-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Disclaimer
+
+This gem is not officially affiliated with or endorsed by Hack The Box. Use responsibly and in accordance with HTB's Terms of Service.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/htb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "htb"
+require "htb/cli"
+
+HTB::CLI::Main.start(ARGV)

data/htb.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "htb"
+  spec.version       = "0.1.0"
+  spec.authors       = ["usiegj00"]
+  spec.email         = ["usiegj00@users.noreply.github.com"]
+
+  spec.summary       = "Ruby client for the Hack The Box API v4"
+  spec.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."
+  spec.homepage      = "https://github.com/aluminumio/htb-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/aluminumio/htb-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/aluminumio/htb-ruby/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "thor", "~> 1.0"
+  spec.add_dependency "tty-table", "~> 0.12"
+  spec.add_dependency "tty-spinner", "~> 0.9"
+  spec.add_dependency "tty-prompt", "~> 0.23"
+  spec.add_dependency "pastel", "~> 0.8"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+end

data/lib/htb/challenges.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module HTB
+  class Challenges
+    def initialize(client)
+      @client = client
+    end
+
+    # List all challenges
+    # GET /api/v4/challenge/list
+    def list
+      @client.get("/challenge/list")
+    end
+
+    # Get challenge info by ID
+    # GET /api/v4/challenge/info/{challenge_id}
+    def info(challenge_id)
+      @client.get("/challenge/info/#{challenge_id}")
+    end
+
+    # Get active challenge
+    # GET /api/v4/challenge/active
+    def active
+      @client.get("/challenge/active")
+    end
+
+    # Start a challenge
+    # POST /api/v4/challenge/start/{challenge_id}
+    def start(challenge_id)
+      @client.post("/challenge/start/#{challenge_id}")
+    end
+
+    # Stop a challenge
+    # POST /api/v4/challenge/stop/{challenge_id}
+    def stop(challenge_id)
+      @client.post("/challenge/stop/#{challenge_id}")
+    end
+
+    # Submit flag for challenge
+    # POST /api/v4/challenge/own
+    # @param challenge_id [Integer] Challenge ID
+    # @param flag [String] The flag to submit
+    # @param difficulty [Integer] Difficulty rating
+    def own(challenge_id:, flag:, difficulty: 50)
+      @client.post("/challenge/own", {
+        id: challenge_id,
+        flag: flag,
+        difficulty: difficulty
+      })
+    end
+
+    # Download challenge files
+    # GET /api/v4/challenge/download/{challenge_id}
+    def download(challenge_id)
+      @client.get("/challenge/download/#{challenge_id}")
+    end
+
+    # Get challenge categories
+    # GET /api/v4/challenge/categories/list
+    def categories
+      @client.get("/challenge/categories/list")
+    end
+
+    # Get retired challenges
+    # GET /api/v4/challenge/list/retired
+    def retired
+      @client.get("/challenge/list/retired")
+    end
+
+    # Get challenge activity
+    # GET /api/v4/challenge/activity/{challenge_id}
+    def activity(challenge_id)
+      @client.get("/challenge/activity/#{challenge_id}")
+    end
+
+    # Submit challenge review
+    # POST /api/v4/challenge/review
+    def review(challenge_id:, stars:, headline:, review:)
+      @client.post("/challenge/review", {
+        id: challenge_id,
+        stars: stars,
+        headline: headline,
+        review: review
+      })
+    end
+
+    # Get recommended challenges
+    # GET /api/v4/challenge/recommended
+    def recommended
+      @client.get("/challenge/recommended")
+    end
+
+    # Get challenge todo status
+    # GET /api/v4/challenge/todo/{challenge_id}
+    def todo(challenge_id)
+      @client.get("/challenge/todo/#{challenge_id}")
+    end
+
+    # Spawn challenge instance
+    # POST /api/v4/challenge/spawn
+    def spawn(challenge_id)
+      @client.post("/challenge/spawn", { challenge_id: challenge_id })
+    end
+
+    # Terminate challenge instance
+    # POST /api/v4/challenge/terminate
+    def terminate(challenge_id)
+      @client.post("/challenge/terminate", { challenge_id: challenge_id })
+    end
+  end
+end