gophish-ruby 0.1.0

data/docs/GETTING_STARTED.md

@@ -0,0 +1,340 @@
+# Getting Started Guide
+
+This guide will help you get up and running with the Gophish Ruby SDK quickly.
+
+## Prerequisites
+
+- Ruby >= 3.1.0
+- A running Gophish server
+- API access credentials for your Gophish instance
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+# Add to Gemfile
+echo 'gem "gophish-ruby"' >> Gemfile
+bundle install
+
+# Or install directly
+gem install gophish-ruby
+```
+
+## Quick Start
+
+### 1. Configure the SDK
+
+First, configure the SDK with your Gophish server details:
+
+```ruby
+require 'gophish-ruby'
+
+Gophish.configure do |config|
+  config.url = "https://your-gophish-server.com"
+  config.api_key = "your-api-key-here"
+  config.verify_ssl = true
+  config.debug_output = false
+end
+```
+
+**Getting Your API Key:**
+
+1. Log into your Gophish admin panel
+2. Navigate to Settings → Users
+3. Click on your user account
+4. Copy the API Key from the user details
+
+### 2. Test the Connection
+
+Verify your configuration works:
+
+```ruby
+# Try to fetch existing groups (should return empty array if none exist)
+begin
+  groups = Gophish::Group.all
+  puts "✓ Connected successfully! Found #{groups.length} groups."
+rescue StandardError => e
+  puts "✗ Connection failed: #{e.message}"
+  puts "Please check your configuration."
+end
+```
+
+### 3. Create Your First Group
+
+```ruby
+# Create a simple group with one target
+group = Gophish::Group.new(
+  name: "My First Group",
+  targets: [
+    {
+      first_name: "Test",
+      last_name: "User",
+      email: "test@example.com",
+      position: "Tester"
+    }
+  ]
+)
+
+if group.save
+  puts "✓ Group created successfully with ID: #{group.id}"
+else
+  puts "✗ Failed to create group:"
+  group.errors.full_messages.each { |error| puts "  - #{error}" }
+end
+```
+
+## Common Workflows
+
+### Importing Targets from CSV
+
+The most common use case is importing a list of targets from a CSV file:
+
+```ruby
+# Prepare your CSV file with headers: First Name,Last Name,Email,Position
+csv_content = <<~CSV
+  First Name,Last Name,Email,Position
+  John,Doe,john@company.com,Manager
+  Jane,Smith,jane@company.com,Developer
+  Bob,Wilson,bob@company.com,Analyst
+CSV
+
+# Create and import
+group = Gophish::Group.new(name: "Company Employees")
+group.import_csv(csv_content)
+
+puts "Imported #{group.targets.length} targets"
+group.save
+```
+
+### Reading from a File
+
+```ruby
+# Read CSV from file
+csv_content = File.read("employees.csv")
+
+group = Gophish::Group.new(name: "Employees")
+group.import_csv(csv_content)
+
+if group.valid?
+  group.save
+  puts "Imported #{group.targets.length} employees"
+else
+  puts "Validation errors:"
+  group.errors.full_messages.each { |error| puts "  - #{error}" }
+end
+```
+
+### Managing Existing Groups
+
+```ruby
+# List all groups
+puts "Existing groups:"
+Gophish::Group.all.each do |group|
+  puts "  #{group.id}: #{group.name} (#{group.targets.length} targets)"
+end
+
+# Find and update a specific group
+group = Gophish::Group.find(1)
+group.name = "Updated Group Name"
+
+# Add new targets
+group.targets << {
+  first_name: "New",
+  last_name: "Employee",
+  email: "new.employee@company.com",
+  position: "Intern"
+}
+
+group.save
+```
+
+### Deleting Groups
+
+```ruby
+# Find and delete a group
+group = Gophish::Group.find(1)
+if group.destroy
+  puts "Group deleted successfully"
+else
+  puts "Failed to delete group"
+end
+```
+
+## Error Handling
+
+Always handle errors gracefully in production code:
+
+```ruby
+def create_group_safely(name, csv_file_path)
+  # Read CSV file
+  begin
+    csv_content = File.read(csv_file_path)
+  rescue Errno::ENOENT
+    puts "Error: CSV file not found at #{csv_file_path}"
+    return false
+  end
+
+  # Create group
+  group = Gophish::Group.new(name: name)
+
+  # Import CSV
+  begin
+    group.import_csv(csv_content)
+  rescue CSV::MalformedCSVError => e
+    puts "Error: Invalid CSV format - #{e.message}"
+    return false
+  end
+
+  # Validate
+  unless group.valid?
+    puts "Validation errors:"
+    group.errors.full_messages.each { |error| puts "  - #{error}" }
+    return false
+  end
+
+  # Save
+  unless group.save
+    puts "Save failed:"
+    group.errors.full_messages.each { |error| puts "  - #{error}" }
+    return false
+  end
+
+  puts "✓ Group '#{name}' created successfully with #{group.targets.length} targets"
+  true
+end
+
+# Usage
+create_group_safely("Sales Team", "sales_team.csv")
+```
+
+## Development Setup
+
+For development and testing, you might want to use different settings:
+
+```ruby
+# Development configuration
+if ENV['RAILS_ENV'] == 'development' || ENV['RUBY_ENV'] == 'development'
+  Gophish.configure do |config|
+    config.url = "https://localhost:3333"
+    config.api_key = "dev-api-key"
+    config.verify_ssl = false  # For self-signed certificates
+    config.debug_output = true  # See HTTP requests
+  end
+else
+  # Production configuration
+  Gophish.configure do |config|
+    config.url = ENV['GOPHISH_URL']
+    config.api_key = ENV['GOPHISH_API_KEY']
+    config.verify_ssl = true
+    config.debug_output = false
+  end
+end
+```
+
+## Validation and Data Quality
+
+The SDK provides comprehensive validation:
+
+### Required Fields
+
+All these fields are required for each target:
+
+- `first_name`
+- `last_name`
+- `email` (must be valid format)
+- `position`
+
+### Email Validation
+
+The SDK validates email format using a regex pattern:
+
+```ruby
+# Valid emails
+"user@example.com"
+"first.last@company.co.uk"
+"user+tag@domain.org"
+
+# Invalid emails (will cause validation errors)
+"invalid-email"
+"@domain.com"
+"user@"
+""
+```
+
+### Custom Validation
+
+You can check validation before saving:
+
+```ruby
+group = Gophish::Group.new(name: "Test", targets: [...])
+
+if group.valid?
+  puts "✓ All validations passed"
+  group.save
+else
+  puts "✗ Validation failed:"
+
+  # Show all errors
+  group.errors.full_messages.each { |error| puts "  - #{error}" }
+
+  # Check specific field errors
+  if group.errors[:name].any?
+    puts "Name issues: #{group.errors[:name].join(', ')}"
+  end
+
+  if group.errors[:targets].any?
+    puts "Target issues: #{group.errors[:targets].join(', ')}"
+  end
+end
+```
+
+## Next Steps
+
+Now that you have the basics:
+
+1. **Read the [API Reference](API_REFERENCE.md)** for detailed method documentation
+2. **Check out [Examples](EXAMPLES.md)** for more complex scenarios
+3. **Set up proper error handling** for production use
+4. **Consider security** - never log API keys or sensitive data
+
+## Troubleshooting
+
+### Common Issues
+
+**"Connection refused" errors:**
+
+- Check that your Gophish server is running
+- Verify the URL is correct (include protocol: https://)
+- Ensure the port is correct
+
+**"SSL certificate verify failed" errors:**
+
+- Set `config.verify_ssl = false` for self-signed certificates
+- Or properly configure SSL certificates on your Gophish server
+
+**"Invalid API key" errors:**
+
+- Double-check your API key in the Gophish admin panel
+- Ensure there are no extra spaces or characters
+
+**CSV import fails:**
+
+- Verify CSV headers exactly match: "First Name", "Last Name", "Email", "Position"
+- Check for malformed CSV data (unescaped quotes, etc.)
+- Ensure all required fields are present for each row
+
+**Validation errors:**
+
+- Check that all required fields are present
+- Verify email addresses have valid format
+- Ensure group name is not empty
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [API Reference](API_REFERENCE.md) for detailed documentation
+2. Look at [Examples](EXAMPLES.md) for working code samples
+3. Open an issue on [GitHub](https://github.com/EliSebastian/gophish-ruby/issues)
+4. Consult the [Gophish documentation](https://docs.getgophish.com/) for server-side issues

data/lib/gophish/base.rb

@@ -0,0 +1,206 @@
+require 'httparty'
+require 'active_support'
+require 'active_model'
+require 'active_record'
+require 'json'
+require 'uri'
+require_relative 'configuration'
+
+module Gophish
+  class Base
+    include HTTParty
+    include ActiveSupport::Inflector
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Validations
+    include ActiveRecord::Callbacks
+
+    def initialize(attributes = {})
+      @persisted = false
+      @changed_attributes = {}
+      super(attributes)
+    end
+
+    def self.configuration
+      @configuration ||= {
+        base_uri: "#{Gophish.configuration.url}/api",
+        headers: { 'Authorization' => Gophish.configuration.api_key },
+        verify: Gophish.configuration.verify_ssl,
+        debug_output: Gophish.configuration.debug_output ? STDOUT : nil
+      }
+    end
+
+    def self.get(path, options = {})
+      options = configuration.merge options
+      options[:headers] = (options[:headers] || {}).merge(configuration[:headers])
+      super(path, options)
+    end
+
+    def self.post(path, options = {})
+      options = configuration.merge options
+      options[:headers] = (options[:headers] || {}).merge(configuration[:headers])
+      super(path, options)
+    end
+
+    def self.put(path, options = {})
+      options = configuration.merge options
+      options[:headers] = (options[:headers] || {}).merge(configuration[:headers])
+      super(path, options)
+    end
+
+    def self.delete(path, options = {})
+      options = configuration.merge options
+      options[:headers] = (options[:headers] || {}).merge(configuration[:headers])
+      super(path, options)
+    end
+
+    def self.resource_name
+    name.split('::').last.underscore.dasherize
+    end
+
+    def self.resource_path
+      "/#{resource_name.pluralize}"
+    end
+
+    def self.all
+      response = get "#{resource_path}/"
+      if response.response.code == '200'
+        response.parsed_response.map do |data|
+          instance = new filter_attributes(data)
+          instance.instance_variable_set :@persisted, true
+          instance
+        end
+      end
+    end
+
+    def self.find(id)
+      response = get "#{resource_path}/#{id}"
+      raise StandardError, "Resource not found with id: #{id}" if response.response.code != '200'
+
+      data = JSON.parse response.body
+      instance = new filter_attributes(data)
+      instance.instance_variable_set :@persisted, true
+      instance
+    end
+
+    def save
+      return false unless valid?
+
+      return update_record if persisted?
+
+      create_record
+    end
+
+    def update_attributes(attributes)
+      attributes.each { |key, value| send "#{key}=", value if respond_to? "#{key}=" }
+      save
+    end
+
+    def destroy
+      return false unless persisted?
+      return false if id.nil?
+
+      response = self.class.delete "#{self.class.resource_path}/#{id}"
+      return handle_error_response response unless response.success?
+
+      @persisted = false
+      freeze
+      true
+    end
+
+    def persisted?
+      @persisted && !id.nil?
+    end
+
+    def new_record?
+      !persisted?
+    end
+
+    private
+
+    def update_attributes_from_response(parsed_response)
+      return unless parsed_response.is_a? Hash
+
+      parsed_response.each do |key, value|
+        send "#{key}=", value if respond_to? "#{key}="
+      end
+      @persisted = true
+      @changed_attributes.clear
+    end
+
+    def handle_error_response(response)
+      errors.add :base, response.parsed_response['message'] if response.parsed_response['success'] == false
+      false
+    end
+
+    private
+
+    def create_record
+      response = self.class.post "#{self.class.resource_path}/", request_options(body_for_create)
+      return handle_error_response response unless response.success?
+
+      update_attributes_from_response response.parsed_response
+      true
+    end
+
+    def update_record
+      return false if id.nil?
+      return true if @changed_attributes.empty?
+
+      response = self.class.put "#{self.class.resource_path}/#{id}/", request_options(body_for_update)
+      return handle_error_response response unless response.success?
+
+      update_attributes_from_response response.parsed_response
+      true
+    end
+
+    def request_options(body)
+      { body: body.to_json, headers: { 'Content-Type' => 'application/json' } }
+    end
+
+    def self.filter_attributes(data)
+      return data unless data.is_a? Hash
+
+      defined_attributes = attribute_names.map(&:to_s)
+
+      filtered_data = {}
+      data.each do |key, value|
+        snake_case_key = key.to_s.underscore
+        filtered_data[snake_case_key] = value if defined_attributes.include? snake_case_key
+      end
+
+      filtered_data
+    end
+
+    def body_for_create
+      raise NotImplementedError, 'You must implement the body_for_create method in your subclass'
+    end
+
+    def body_for_update
+      body_for_create
+    end
+
+    def attribute_changed?(attribute)
+      @changed_attributes.key? attribute.to_s
+    end
+
+    def changed_attributes
+      @changed_attributes.keys
+    end
+
+    def attribute_was(attribute)
+      @changed_attributes[attribute.to_s]
+    end
+
+    def []=(attribute, value)
+      attribute_str = attribute.to_s
+      current_value = send attribute if respond_to? attribute
+
+      unless current_value == value
+        @changed_attributes[attribute_str] = current_value
+      end
+
+      send "#{attribute}=", value if respond_to? "#{attribute}="
+    end
+  end
+end

data/lib/gophish/configuration.rb

@@ -0,0 +1,5 @@
+module Gophish
+  class Configuration
+    attr_accessor :url, :api_key, :verify_ssl, :debug_output
+  end
+end

data/lib/gophish/group.rb

@@ -0,0 +1,72 @@
+require_relative 'base'
+require 'active_support/core_ext/object/blank'
+require 'csv'
+
+module Gophish
+  class Group < Base
+    attribute :id, :integer
+    attribute :name, :string
+    attribute :modified_date, :string
+    attribute :targets
+
+    validates :name, presence: true
+    validates :targets, presence: true
+    validate :validate_targets_structure
+
+    def body_for_create
+      { name:, targets: }
+    end
+
+    def import_csv(csv_data)
+      targets_array = CSV.parse(csv_data, headers: true).map { |row| parse_csv_row row }
+      self.targets = targets_array
+    end
+
+    private
+
+    def validate_targets_structure
+      return if targets.blank?
+      return errors.add :targets, 'must be an array' unless targets.is_a? Array
+
+      targets.each_with_index { |target, index| validate_target target, index }
+    end
+
+    def parse_csv_row(row)
+      {
+        first_name: row['First Name'],
+        last_name: row['Last Name'],
+        email: row['Email'],
+        position: row['Position']
+      }
+    end
+
+    def validate_target(target, index)
+      return errors.add :targets, "item at index #{index} must be a hash" unless target.is_a? Hash
+
+      validate_target_email target, index
+      validate_required_field target, index, :position
+      validate_required_field target, index, :first_name
+      validate_required_field target, index, :last_name
+    end
+
+    def validate_target_email(target, index)
+      email = target[:email] || target['email']
+      if email.blank?
+        errors.add :targets, "item at index #{index} must have an email"
+      elsif !valid_email_format?(email)
+        errors.add :targets, "item at index #{index} must have a valid email format"
+      end
+    end
+
+    def validate_required_field(target, index, field)
+      value = target[field] || target[field.to_s]
+      return unless value.blank?
+
+      errors.add :targets, "item at index #{index} must have a #{field}"
+    end
+
+    def valid_email_format?(email)
+      email.match?(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/)
+    end
+  end
+end

data/lib/gophish/version.rb

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

data/lib/gophish-ruby.rb

@@ -0,0 +1,18 @@
+require_relative 'gophish/version'
+require_relative 'gophish/configuration'
+require_relative 'gophish/base'
+require_relative 'gophish/group'
+
+module Gophish
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/sig/gophish/ruby.rbs

@@ -0,0 +1,6 @@
+module Gophish
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end