gophish-ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59b79d410ed7e2467c187c89992d394ee71d911da58524ecc3cc4b4eb5fb2a39
-  data.tar.gz: 62ca19b3ecdfb8cc88bfedc2bd4f53fca272db9a9f5de8846398573413daf4ae
+  metadata.gz: abf879c22c4f9f1521c61af8ebc635956ba6f70b3d6292019707b34168c32c73
+  data.tar.gz: 41e2452769f172e282a83f0e6a4d186e82f4544683f405745790f736532a03d2
 SHA512:
-  metadata.gz: 78d1964ebcb0d3caba10c53d0f78e819b356b88961af7dfe48dde8611469e4c1919991cf7dec2aae991ccccea30e66a2f0bfea56f51420ebec4e8e0bbb07807e
-  data.tar.gz: 321297b58bdd280855faf6d988bfc9f4d2c062a5569a41316371c501bafabc7c8175e9312f5cb22f10fd0df1452ee439b65fe5c0475f01bd5243125868ab2c28
+  metadata.gz: 3b1d75bff457c5f276fa014daffeff9834b9d44771a2dd2d41b12353d3060ff5b04fd5665aaf92a93417ababfaef3a26acc48edee5c4d165cde3c69b0749b47b
+  data.tar.gz: 702c43a976ae0ab06dbaa49ad01e7631b0b2a5405a6d41a13384f8c3e2b58c339d04b143fc78f65940119d52c5851bb17ae7c464c2e8c783ba82f468dfae5a42

data/CHANGELOG.md

@@ -7,21 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-01-15
+
 ### Added
+
+- **Page Management System**
+  - `Gophish::Page` class for managing landing pages in phishing campaigns
+  - Full CRUD operations for pages (create, read, update, delete)
+  - Support for HTML content with credential capture capabilities
+  - Comprehensive validations requiring page name and HTML content
+  - Site import functionality with `Page.import_site` class method
+  - Option to include resources (CSS, JS, images) during site import
+  - Built-in methods for checking page configuration: `#captures_credentials?`, `#captures_passwords?`, `#has_redirect?`
+
+- **Template Management System**
+  - `Gophish::Template` class for managing email templates
+  - Full CRUD operations for templates (create, read, update, delete)
+  - Support for HTML and plain text email content
+  - Comprehensive validations requiring template name and content
+  - Email import functionality with `Template.import_email` class method
+  - Option to convert links during email import for tracking
+
+- **Attachment Management**
+  - Add attachments to templates with `#add_attachment` method
+  - Remove attachments by name with `#remove_attachment` method
+  - Query attachment status with `#has_attachments?` and `#attachment_count`
+  - Automatic Base64 encoding of attachment content
+  - Validation of attachment structure (content, type, name required)
+
+- **Enhanced Change Tracking**
+  - Migrated from custom change tracking to ActiveModel::Dirty
+  - Improved change detection with `#changed?` and `#clear_changes_information`
+  - Better integration with Rails-style attribute tracking
+
 - Comprehensive documentation with getting started guide, API reference, and examples
 - Enhanced README with detailed usage instructions and configuration examples
 
 ### Changed
+
+- **Breaking Change**: Replaced custom `@changed_attributes` system with ActiveModel::Dirty
+- Updated Base class to use `define_attribute_methods` for proper dirty tracking
+- Modified `#update_record` to include `id` in update payload for proper API calls
 - Improved error messages for validation failures
 - Enhanced CSV import validation with better error reporting
 
 ### Fixed
+
 - Console script requiring wrong file name (`gophish_ruby` → `gophish-ruby`)
 - Spec helper requiring wrong file name for consistent naming
+- Corrected require statement in main library file for Template class
 
 ## [0.1.0] - 2025-08-29
 
 ### Added
+
 - **Core SDK Foundation**
   - `Gophish::Configuration` class for managing API credentials and settings
   - `Gophish::Base` abstract class providing common CRUD operations
@@ -68,12 +107,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Rake tasks for testing and quality checks
 
 ### Technical Details
+
 - **Dependencies**: HTTParty 0.23.1, ActiveSupport/ActiveModel/ActiveRecord 8.0+
 - **Ruby Version**: Requires Ruby >= 3.1.0
 - **Architecture**: Modular design with inheritance-based API resources
 - **Security**: Built-in API key authentication for all requests
 
 ### Development Infrastructure
+
 - Bundler gem management with proper gemspec configuration
 - GitHub integration with proper repository URLs and metadata
 - MIT license for open source distribution

data/README.md

@@ -11,9 +11,13 @@ A Ruby SDK for the [Gophish](https://getgophish.com/) phishing simulation platfo
 - **ActiveModel Integration**: Familiar Rails-like attributes, validations, and callbacks
 - **Automatic Authentication**: Built-in API key authentication for all requests
 - **CSV Import Support**: Easy bulk import of targets from CSV files
+- **Email Template Management**: Create, modify, and manage email templates with attachment support
+- **Email Import**: Import existing emails and convert them to templates
+- **Site Import**: Import landing pages directly from existing websites
+- **Page Management**: Create, modify, and manage landing pages with credential capture
 - **SSL Configuration**: Configurable SSL verification for development environments
 - **Debug Support**: Built-in debugging capabilities for API interactions
-- **Change Tracking**: Automatic tracking of attribute changes
+- **Change Tracking**: Automatic tracking of attribute changes with ActiveModel::Dirty
 - **Comprehensive Validation**: Built-in validations for all data models
 
 ## Installation
@@ -184,9 +188,110 @@ unless group.valid?
 end
 ```
 
+### Templates Management
+
+Templates define the email content for your phishing campaigns, including HTML/text content and attachments.
+
+#### Creating a Template
+
+```ruby
+# Create a new email template
+template = Gophish::Template.new(
+  name: "Phishing Awareness Test",
+  subject: "Security Update Required",
+  html: "<h1>Important Security Update</h1><p>Please click <a href='{{.URL}}'>here</a> to update your password.</p>",
+  text: "Important Security Update\n\nPlease visit {{.URL}} to update your password."
+)
+
+if template.save
+  puts "Template created successfully with ID: #{template.id}"
+else
+  puts "Failed to create template: #{template.errors.full_messages}"
+end
+```
+
+#### Adding Attachments
+
+```ruby
+template = Gophish::Template.new(
+  name: "Invoice Template",
+  subject: "Invoice #12345",
+  html: "<p>Please find your invoice attached.</p>"
+)
+
+# Add an attachment
+file_content = File.read("path/to/invoice.pdf")
+template.add_attachment(file_content, "application/pdf", "invoice.pdf")
+
+puts "Template has #{template.attachment_count} attachments"
+```
+
+#### Managing Attachments
+
+```ruby
+# Check if template has attachments
+if template.has_attachments?
+  puts "Template has attachments"
+end
+
+# Remove an attachment by name
+template.remove_attachment("invoice.pdf")
+puts "Attachments remaining: #{template.attachment_count}"
+```
+
+#### Importing Email Content
+
+```ruby
+# Import an existing email (.eml file content)
+email_content = File.read("path/to/email.eml")
+
+imported_data = Gophish::Template.import_email(
+  email_content, 
+  convert_links: true  # Convert links to Gophish tracking format
+)
+
+# Create template from imported data
+template = Gophish::Template.new(imported_data)
+template.name = "Imported Email Template"
+template.save
+```
+
+#### Retrieving Templates
+
+```ruby
+# Get all templates
+templates = Gophish::Template.all
+puts "Found #{templates.length} templates"
+
+# Find a specific template by ID
+template = Gophish::Template.find(1)
+puts "Template: #{template.name}"
+```
+
+#### Updating a Template
+
+```ruby
+template = Gophish::Template.find(1)
+template.subject = "Updated Subject Line"
+template.html = "<h1>Updated Content</h1>"
+
+if template.save
+  puts "Template updated successfully"
+end
+```
+
+#### Deleting a Template
+
+```ruby
+template = Gophish::Template.find(1)
+if template.destroy
+  puts "Template deleted successfully"
+end
+```
+
 ### Change Tracking
 
-The SDK automatically tracks changes to attributes:
+The SDK automatically tracks changes to attributes using ActiveModel::Dirty:
 
 ```ruby
 group = Gophish::Group.find(1)
@@ -198,6 +303,174 @@ puts group.attribute_changed?(:name)  # => true
 puts group.attribute_was(:name)  # => "Original Name"
 ```
 
+### Pages Management
+
+Pages represent landing pages that targets will see when they click on phishing links in your campaigns.
+
+#### Creating a Page
+
+```ruby
+# Create a simple landing page
+page = Gophish::Page.new(
+  name: "Microsoft Login Page",
+  html: <<~HTML
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>Microsoft Account Login</title>
+      <style>
+        body { font-family: Arial, sans-serif; margin: 0; padding: 40px; background-color: #f5f5f5; }
+        .login-container { max-width: 400px; margin: 0 auto; background: white; padding: 40px; border-radius: 8px; }
+        .form-group { margin-bottom: 20px; }
+        input { width: 100%; padding: 12px; border: 1px solid #ddd; border-radius: 4px; }
+        button { width: 100%; padding: 12px; background: #0078d4; color: white; border: none; border-radius: 4px; }
+      </style>
+    </head>
+    <body>
+      <div class="login-container">
+        <h2>Sign in to your account</h2>
+        <form method="post">
+          <div class="form-group">
+            <input type="email" name="email" placeholder="Email" required>
+          </div>
+          <div class="form-group">
+            <input type="password" name="password" placeholder="Password" required>
+          </div>
+          <button type="submit">Sign in</button>
+        </form>
+      </div>
+    </body>
+    </html>
+  HTML
+)
+
+# Save the page to Gophish
+if page.save
+  puts "Page created successfully with ID: #{page.id}"
+else
+  puts "Failed to create page: #{page.errors.full_messages}"
+end
+```
+
+#### Creating a Page with Credential Capture
+
+```ruby
+# Create a page that captures login credentials
+page = Gophish::Page.new(
+  name: "Banking Login - Credential Capture",
+  html: <<~HTML
+    <html>
+    <body>
+      <h1>Online Banking</h1>
+      <form method="post">
+        <input type="text" name="username" placeholder="Username" required>
+        <input type="password" name="password" placeholder="Password" required>
+        <button type="submit">Login</button>
+      </form>
+    </body>
+    </html>
+  HTML,
+  capture_credentials: true,
+  capture_passwords: true,
+  redirect_url: "https://www.realbank.com/login"
+)
+
+if page.save
+  puts "Page created with credential capture enabled"
+  puts "Captures credentials: #{page.captures_credentials?}"
+  puts "Captures passwords: #{page.captures_passwords?}"
+  puts "Has redirect: #{page.has_redirect?}"
+end
+```
+
+#### Importing a Website as a Landing Page
+
+```ruby
+# Import an existing website as a landing page template
+begin
+  imported_data = Gophish::Page.import_site(
+    "https://login.microsoft.com", 
+    include_resources: true  # Include CSS, JS, and images
+  )
+  
+  # Create a page from the imported data
+  page = Gophish::Page.new(imported_data)
+  page.name = "Imported Microsoft Login Page"
+  page.capture_credentials = true
+  
+  if page.save
+    puts "Successfully imported and created page from website"
+  end
+rescue StandardError => e
+  puts "Failed to import site: #{e.message}"
+end
+```
+
+#### Retrieving Pages
+
+```ruby
+# Get all pages
+pages = Gophish::Page.all
+puts "Found #{pages.length} pages"
+
+# Find a specific page by ID
+page = Gophish::Page.find(1)
+puts "Page: #{page.name}"
+puts "HTML length: #{page.html.length} characters"
+```
+
+#### Updating a Page
+
+```ruby
+# Update page content and settings
+page = Gophish::Page.find(1)
+page.name = "Updated Page Name"
+page.capture_credentials = true
+page.redirect_url = "https://example.com/success"
+
+# Update HTML content
+page.html = page.html.gsub("Sign in", "Login")
+
+if page.save
+  puts "Page updated successfully"
+end
+```
+
+#### Deleting a Page
+
+```ruby
+page = Gophish::Page.find(1)
+if page.destroy
+  puts "Page deleted successfully"
+end
+```
+
+### Validation and Error Handling
+
+The SDK provides comprehensive validation for pages:
+
+```ruby
+# Invalid page (missing required fields)
+page = Gophish::Page.new(name: "", html: "")
+
+unless page.valid?
+  puts "Validation errors:"
+  page.errors.full_messages.each { |msg| puts "  - #{msg}" }
+  # => ["Name can't be blank", "Html can't be blank"]
+end
+
+# Check page configuration
+page = Gophish::Page.new(
+  name: "Test Page",
+  html: "<html><body>Test</body></html>",
+  capture_credentials: true
+)
+
+if page.captures_credentials?
+  puts "This page will capture submitted credentials"
+end
+```
+
 ## API Documentation
 
 ### Core Classes
@@ -258,6 +531,73 @@ Each target in the `targets` array should have:
 
 - `#import_csv(csv_data)` - Import targets from CSV data
 
+#### `Gophish::Template`
+
+Represents a Gophish email template.
+
+**Attributes:**
+
+- `id` (Integer) - Unique template identifier
+- `name` (String) - Template name (required)
+- `subject` (String) - Email subject line
+- `text` (String) - Plain text email content
+- `html` (String) - HTML email content
+- `modified_date` (String) - Last modification timestamp
+- `attachments` (Array) - Array of attachment hashes
+
+**Attachment Structure:**
+Each attachment in the `attachments` array should have:
+
+- `content` (String) - Base64 encoded file content (required)
+- `type` (String) - MIME type of the attachment (required)
+- `name` (String) - Filename of the attachment (required)
+
+**Class Methods:**
+
+- `.import_email(content, convert_links: false)` - Import email content and return template data
+
+**Instance Methods:**
+
+- `#add_attachment(content, type, name)` - Add an attachment to the template
+- `#remove_attachment(name)` - Remove an attachment by filename
+- `#has_attachments?` - Check if template has any attachments
+- `#attachment_count` - Get the number of attachments
+
+**Validations:**
+
+- Template must have a name
+- Template must have either text or HTML content (or both)
+- All attachments must have content, type, and name
+
+#### `Gophish::Page`
+
+Represents a Gophish landing page for phishing campaigns.
+
+**Attributes:**
+
+- `id` (Integer) - Unique page identifier
+- `name` (String) - Page name (required)
+- `html` (String) - HTML content of the page (required)
+- `capture_credentials` (Boolean) - Whether to capture credentials (default: false)
+- `capture_passwords` (Boolean) - Whether to capture passwords (default: false)
+- `redirect_url` (String) - URL to redirect users after form submission
+- `modified_date` (String) - Last modification timestamp
+
+**Class Methods:**
+
+- `.import_site(url, include_resources: false)` - Import a website as a landing page template
+
+**Instance Methods:**
+
+- `#captures_credentials?` - Check if page is configured to capture credentials
+- `#captures_passwords?` - Check if page is configured to capture passwords
+- `#has_redirect?` - Check if page has a redirect URL configured
+
+**Validations:**
+
+- Page must have a name
+- Page must have HTML content
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -3,7 +3,7 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new :spec
 
 require "rubocop/rake_task"