gophish-ruby 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aadeeb636e448907a3b5f3e33427c19373d903c52f8961b99b28265fe94872de
-  data.tar.gz: 9ef3e492ec39d8ce16327018358c0d873c70ebc20fb8064d4909d9ec66a9a3f4
+  metadata.gz: c44a4676be791cb9f3b20de06e1f2b0c07537d1baf2439fd6b8e0a176257f5d6
+  data.tar.gz: bc03e673ed3ce98ff701b013b45ff5bb6a3b241373669b4f8fbceafd763f55e2
 SHA512:
-  metadata.gz: a2678d8b475ef9c5c970a625f9b294ed95afde10781f5251cee81160240a80864654158887fa2df6a7b1ef17c6e7a325a4a3e051b536b72942f4f8123018ee9a
-  data.tar.gz: 94b1ae168de255a5e8d1154285b6b786070a1271b689965e503d5c87a6339ed959ce2df6c41a78fb5e87da245b5bc49961a29debc3a11b67b36e92722cee43ca
+  metadata.gz: 7065f2c3465bf572a5c9f918d597d37414e70143ce7130bcafacd60e164411e19cc8dce6fb3c52a4a52846ee81b12411ef20e52fca91b69fc59606755b3cfb70
+  data.tar.gz: '008bea10cdd42881b93dfa0e27179f29987dbb1624bee9c21d07c2d3a7ffb50472daefb84c8d76409f980be0ca5695a4ab475d36840ca648b581151ac1e89b46'

data/CHANGELOG.md

@@ -7,7 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2025-01-15
+## [1.0.0] - 2025-09-01
+
+### Added
+
+- **Campaign Management System** 🎯
+  - `Gophish::Campaign` class for creating, managing, and monitoring phishing campaigns
+  - Full CRUD operations for campaigns (create, read, update, delete)
+  - Campaign scheduling with `launch_date` and `send_by_date` attributes
+  - Comprehensive campaign result tracking and analysis
+  - Timeline monitoring for detailed campaign progression
+  - Campaign status management with `#in_progress?`, `#completed?`, `#launched?` methods
+  - Campaign completion functionality with `#complete!` method
+  - Class methods for efficient data retrieval: `.get_results()`, `.get_summary()`, `.complete()`
+  - Support for referencing existing templates, pages, groups, and SMTP profiles
+  - Automatic validation of all campaign components and dependencies
+
+- **Campaign Result Analysis**
+  - `Campaign::Result` nested class for individual target interaction tracking
+  - Detailed result status methods: `#clicked?`, `#opened?`, `#sent?`, `#submitted_data?`, `#reported?`
+  - Geographic tracking with latitude/longitude coordinates
+  - IP address tracking for security analysis
+  - Comprehensive result validation and error handling
+
+- **Campaign Timeline Tracking**
+  - `Campaign::Event` nested class for timeline event management
+  - Detailed event tracking with timestamps, messages, and JSON details
+  - Event analysis methods: `#has_details?`, `#parsed_details`
+  - Complete campaign progression monitoring
+
+- **Enhanced Template Management**
+  - Added `envelope_sender` attribute to Template class for advanced email delivery control
+  - New `#has_envelope_sender?` method to check envelope sender configuration
+  - Improved email header management capabilities
+  - Enhanced template validation with envelope sender support
+
+### Changed
+
+- Updated gem version to 1.0.0 (major release with full campaign management)
+- Added `require_relative 'gophish/campaign'` to main library file
+- Enhanced Template class with envelope sender functionality
+- Improved documentation with comprehensive campaign examples
+- Updated API documentation to include all campaign-related classes and methods
+
+### Technical Enhancements
+
+- **Advanced Object Conversion System**
+  - Intelligent conversion between hash references and object instances
+  - Automatic handling of nested object relationships (templates, pages, groups, SMTP)
+  - Graceful error handling for unknown attributes during object creation
+  - Support for both string names and full object references
+
+- **Comprehensive Validation Framework**
+  - Multi-level validation for campaign components
+  - Detailed error messages for campaign structure validation
+  - Group structure validation with index-specific error reporting
+  - Result and timeline data structure validation
+  - Enhanced error handling with descriptive failure messages
+
+- **Robust API Integration**
+  - Campaign-specific API endpoints for results, summary, and completion
+  - Optimized payload building for campaign creation and updates
+  - Proper serialization of nested objects and references
+  - Enhanced error handling for API communication
+
+### Breaking Changes
+
+- This is a major version release (1.0.0) indicating API stability
+- No breaking changes from 0.4.0, fully backward compatible
+- Campaign functionality is additive and does not affect existing code
+
+### Documentation Updates
+
+- Complete campaign management examples in README.md
+- Enhanced API reference documentation for all campaign-related classes
+- Updated getting started guide with campaign examples
+- Comprehensive validation and error handling examples
+- Production-ready code examples with proper error handling
+
+## [0.4.0] - 2025-09-01
+
+### Added
+
+- **SMTP Management System**
+  - `Gophish::Smtp` class for managing SMTP sending profiles in phishing campaigns
+  - Full CRUD operations for SMTP profiles (create, read, update, delete)
+  - Support for SMTP server configuration with host, from_address, and authentication
+  - Comprehensive validations requiring name, host, and valid from_address email format
+  - Authentication support with username and password credentials
+  - SSL certificate error handling with `ignore_cert_errors` option
+  - Custom header management with add/remove functionality
+  - Built-in methods for checking SMTP configuration: `#has_authentication?`, `#ignores_cert_errors?`, `#has_headers?`, `#header_count`
+
+### Changed
+
+- Updated gem version to 0.4.0
+- Added `require_relative 'gophish/smtp'` to main library file for SMTP class availability
+
+## [0.3.0] - 2025-09-01
 
 ### Added
 
@@ -121,4 +218,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Code of conduct and contributing guidelines
 - Comprehensive test suite foundation with RSpec
 
-This initial release provides a solid foundation for interacting with the Gophish API, focusing on group management as the primary use case while establishing patterns for future resource implementations.
+This initial release provides a solid foundation for interacting with the Gophish API, focusing on group management as the primary use case while establishing patterns for future resource implementations.

data/README.md

@@ -10,11 +10,13 @@ A Ruby SDK for the [Gophish](https://getgophish.com/) phishing simulation platfo
 - **Full API Coverage**: Complete implementation of Gophish API endpoints
 - **ActiveModel Integration**: Familiar Rails-like attributes, validations, and callbacks
 - **Automatic Authentication**: Built-in API key authentication for all requests
+- **Campaign Management**: Create, launch, monitor, and manage phishing campaigns with comprehensive result tracking
 - **CSV Import Support**: Easy bulk import of targets from CSV files
-- **Email Template Management**: Create, modify, and manage email templates with attachment support
+- **Email Template Management**: Create, modify, and manage email templates with attachment support and envelope sender configuration
 - **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
+- **SMTP Configuration**: Create, modify, and manage SMTP sending profiles with authentication and header support
 - **SSL Configuration**: Configurable SSL verification for development environments
 - **Debug Support**: Built-in debugging capabilities for API interactions
 - **Change Tracking**: Automatic tracking of attribute changes with ActiveModel::Dirty
@@ -471,6 +473,359 @@ if page.captures_credentials?
 end
 ```
 
+### SMTP Management
+
+SMTP sending profiles define the mail server configuration for sending phishing emails in your campaigns.
+
+#### Creating an SMTP Profile
+
+```ruby
+# Create a basic SMTP profile
+smtp = Gophish::Smtp.new(
+  name: "Company Mail Server",
+  host: "smtp.company.com",
+  from_address: "security@company.com"
+)
+
+# Save the SMTP profile to Gophish
+if smtp.save
+  puts "SMTP profile created successfully with ID: #{smtp.id}"
+else
+  puts "Failed to create SMTP profile: #{smtp.errors.full_messages}"
+end
+```
+
+#### Creating an SMTP Profile with Authentication
+
+```ruby
+# Create an SMTP profile with username/password authentication
+smtp = Gophish::Smtp.new(
+  name: "Gmail SMTP",
+  host: "smtp.gmail.com",
+  from_address: "phishing@company.com",
+  username: "smtp_username",
+  password: "smtp_password",
+  ignore_cert_errors: false
+)
+
+if smtp.save
+  puts "SMTP profile created with authentication"
+  puts "Has authentication: #{smtp.has_authentication?}"
+  puts "Ignores cert errors: #{smtp.ignores_cert_errors?}"
+end
+```
+
+#### Managing Custom Headers
+
+```ruby
+# Add custom headers to the SMTP profile
+smtp = Gophish::Smtp.new(
+  name: "Custom Headers SMTP",
+  host: "mail.company.com",
+  from_address: "security@company.com"
+)
+
+# Add headers for email routing and identification
+smtp.add_header("X-Mailer", "Company Security Tool")
+smtp.add_header("X-Campaign-Type", "Phishing Simulation")
+smtp.add_header("Return-Path", "bounces@company.com")
+
+puts "Header count: #{smtp.header_count}"
+puts "Has headers: #{smtp.has_headers?}"
+
+# Remove a specific header
+smtp.remove_header("X-Campaign-Type")
+puts "Headers after removal: #{smtp.header_count}"
+```
+
+#### Retrieving SMTP Profiles
+
+```ruby
+# Get all SMTP profiles
+smtp_profiles = Gophish::Smtp.all
+puts "Found #{smtp_profiles.length} SMTP profiles"
+
+# Find a specific SMTP profile by ID
+smtp = Gophish::Smtp.find(1)
+puts "SMTP Profile: #{smtp.name} (#{smtp.host})"
+```
+
+#### Updating an SMTP Profile
+
+```ruby
+# Update SMTP profile settings
+smtp = Gophish::Smtp.find(1)
+smtp.name = "Updated SMTP Server"
+smtp.ignore_cert_errors = true
+
+# Add new headers
+smtp.add_header("X-Priority", "1")
+
+if smtp.save
+  puts "SMTP profile updated successfully"
+end
+```
+
+#### Deleting an SMTP Profile
+
+```ruby
+smtp = Gophish::Smtp.find(1)
+if smtp.destroy
+  puts "SMTP profile deleted successfully"
+end
+```
+
+### SMTP Validation and Error Handling
+
+The SDK provides comprehensive validation for SMTP profiles:
+
+```ruby
+# Invalid SMTP profile (missing required fields)
+smtp = Gophish::Smtp.new(name: "", host: "", from_address: "")
+
+unless smtp.valid?
+  puts "Validation errors:"
+  smtp.errors.full_messages.each { |msg| puts "  - #{msg}" }
+  # => ["Name can't be blank", "Host can't be blank", "From address can't be blank"]
+end
+
+# Invalid email format
+smtp = Gophish::Smtp.new(
+  name: "Test SMTP",
+  host: "smtp.test.com",
+  from_address: "invalid-email-format"
+)
+
+unless smtp.valid?
+  puts smtp.errors.full_messages
+  # => ["From address must be a valid email format (email@domain.com)"]
+end
+
+# Check SMTP configuration
+if smtp.has_authentication?
+  puts "SMTP uses authentication"
+end
+
+if smtp.ignores_cert_errors?
+  puts "SMTP ignores certificate errors (not recommended for production)"
+end
+```
+
+### Campaign Management
+
+Campaigns are the core of Gophish phishing simulations, orchestrating the sending of phishing emails to target groups using templates, landing pages, and SMTP profiles.
+
+#### Creating a Campaign
+
+```ruby
+# Create a basic phishing campaign
+campaign = Gophish::Campaign.new(
+  name: "Q1 Security Awareness Training",
+  template: { name: "Phishing Template" },  # Reference existing template
+  page: { name: "Login Page" },             # Reference existing landing page
+  groups: [{ name: "Marketing Team" }],     # Reference existing groups
+  smtp: { name: "Company SMTP" },           # Reference existing SMTP profile
+  url: "https://phishing.company.com"       # Base URL for campaign
+)
+
+# Save the campaign to Gophish
+if campaign.save
+  puts "Campaign created successfully with ID: #{campaign.id}"
+  puts "Campaign status: #{campaign.status}"
+else
+  puts "Failed to create campaign: #{campaign.errors.full_messages}"
+end
+```
+
+#### Creating a Campaign with Scheduling
+
+```ruby
+# Create a campaign with launch and send-by dates
+campaign = Gophish::Campaign.new(
+  name: "Scheduled Phishing Test",
+  template: { name: "Email Template" },
+  page: { name: "Landing Page" },
+  groups: [{ name: "HR Department" }],
+  smtp: { name: "SMTP Profile" },
+  url: "https://training.company.com",
+  launch_date: "2024-01-15T09:00:00Z",      # When to start sending
+  send_by_date: "2024-01-15T17:00:00Z"      # Deadline for sending all emails
+)
+
+if campaign.save
+  puts "Scheduled campaign created"
+  puts "Launched? #{campaign.launched?}"
+  puts "Has send by date? #{campaign.has_send_by_date?}"
+end
+```
+
+#### Monitoring Campaign Status
+
+```ruby
+# Check campaign status and progress
+campaign = Gophish::Campaign.find(1)
+
+puts "Campaign: #{campaign.name}"
+puts "Status: #{campaign.status}"
+puts "In progress? #{campaign.in_progress?}"
+puts "Completed? #{campaign.completed?}"
+
+# Get campaign results
+results = campaign.get_results
+puts "Total results: #{results.length}"
+
+# Get campaign summary
+summary = campaign.get_summary
+puts "Campaign summary: #{summary}"
+```
+
+#### Managing Campaign Results
+
+```ruby
+# Access detailed campaign results
+campaign = Gophish::Campaign.find(1)
+
+campaign.results.each do |result|
+  puts "Target: #{result.email}"
+  puts "  Status: #{result.status}"
+  puts "  Clicked: #{result.clicked?}"
+  puts "  Opened: #{result.opened?}"
+  puts "  Submitted data: #{result.submitted_data?}"
+  puts "  Reported: #{result.reported?}"
+  puts "  IP: #{result.ip}" if result.ip
+  puts ""
+end
+
+# Filter results by status
+clicked_results = campaign.results.select(&:clicked?)
+puts "#{clicked_results.length} users clicked the link"
+
+reported_results = campaign.results.select(&:reported?)
+puts "#{reported_results.length} users reported the email"
+```
+
+#### Monitoring Campaign Timeline
+
+```ruby
+# Access campaign timeline events
+campaign = Gophish::Campaign.find(1)
+
+campaign.timeline.each do |event|
+  puts "#{event.time}: #{event.message}"
+  puts "  Email: #{event.email}"
+  
+  # Check for additional details (JSON data)
+  if event.has_details?
+    details = event.parsed_details
+    puts "  Details: #{details}"
+  end
+  puts ""
+end
+```
+
+#### Completing a Campaign
+
+```ruby
+# Manually complete a running campaign
+campaign = Gophish::Campaign.find(1)
+
+if campaign.in_progress?
+  result = campaign.complete!
+  
+  if result['success']
+    puts "Campaign completed successfully"
+    puts "Final status: #{campaign.status}"
+  else
+    puts "Failed to complete campaign: #{result['message']}"
+  end
+else
+  puts "Campaign is not in progress"
+end
+```
+
+#### Retrieving Campaigns
+
+```ruby
+# Get all campaigns
+campaigns = Gophish::Campaign.all
+puts "Found #{campaigns.length} campaigns"
+
+campaigns.each do |campaign|
+  puts "#{campaign.name}: #{campaign.status}"
+end
+
+# Find a specific campaign by ID
+campaign = Gophish::Campaign.find(1)
+puts "Campaign: #{campaign.name}"
+puts "Groups: #{campaign.groups.map(&:name).join(', ')}"
+```
+
+#### Using Class Methods for Results
+
+```ruby
+# Get results without loading full campaign
+results = Gophish::Campaign.get_results(1)
+puts "Campaign has #{results.length} results"
+
+# Get summary without loading full campaign
+summary = Gophish::Campaign.get_summary(1)
+puts "Campaign summary stats: #{summary['stats']}"
+
+# Complete campaign without loading it
+Gophish::Campaign.complete(1)
+```
+
+#### Campaign Validation and Error Handling
+
+```ruby
+# Invalid campaign (missing required components)
+campaign = Gophish::Campaign.new(name: "Incomplete Campaign")
+
+unless campaign.valid?
+  puts "Validation errors:"
+  campaign.errors.full_messages.each { |msg| puts "  - #{msg}" }
+  # => ["Template can't be blank", "Page can't be blank", "Groups can't be blank", 
+  #     "Smtp can't be blank", "Url can't be blank"]
+end
+
+# Campaign with invalid group structure
+campaign = Gophish::Campaign.new(
+  name: "Test Campaign",
+  template: { name: "Template" },
+  page: { name: "Page" },
+  groups: [{}],  # Invalid: group missing name
+  smtp: { name: "SMTP" },
+  url: "https://test.com"
+)
+
+unless campaign.valid?
+  puts campaign.errors.full_messages
+  # => ["Groups item at index 0 must have a name"]
+end
+```
+
+### Template Enhancement - Envelope Sender
+
+Templates now support envelope sender configuration for better email delivery control.
+
+#### Using Envelope Sender
+
+```ruby
+# Create a template with envelope sender
+template = Gophish::Template.new(
+  name: "Corporate Phishing Test",
+  envelope_sender: "noreply@company.com",  # Envelope sender address
+  subject: "IT Security Update Required",
+  html: "<h1>Please update your credentials</h1><p>Click <a href='{{.URL}}'>here</a></p>"
+)
+
+if template.save
+  puts "Template created with envelope sender"
+  puts "Has envelope sender: #{template.has_envelope_sender?}"
+  puts "Envelope sender: #{template.envelope_sender}"
+end
+```
+
 ## API Documentation
 
 ### Core Classes
@@ -539,6 +894,7 @@ Represents a Gophish email template.
 
 - `id` (Integer) - Unique template identifier
 - `name` (String) - Template name (required)
+- `envelope_sender` (String) - Envelope sender email address
 - `subject` (String) - Email subject line
 - `text` (String) - Plain text email content
 - `html` (String) - HTML email content
@@ -562,6 +918,7 @@ Each attachment in the `attachments` array should have:
 - `#remove_attachment(name)` - Remove an attachment by filename
 - `#has_attachments?` - Check if template has any attachments
 - `#attachment_count` - Get the number of attachments
+- `#has_envelope_sender?` - Check if template has an envelope sender configured
 
 **Validations:**
 
@@ -598,6 +955,139 @@ Represents a Gophish landing page for phishing campaigns.
 - Page must have a name
 - Page must have HTML content
 
+#### `Gophish::Smtp`
+
+Represents a Gophish SMTP sending profile for email campaigns.
+
+**Attributes:**
+
+- `id` (Integer) - Unique SMTP profile identifier
+- `name` (String) - SMTP profile name (required)
+- `username` (String) - SMTP authentication username
+- `password` (String) - SMTP authentication password
+- `host` (String) - SMTP server hostname (required)
+- `interface_type` (String) - Interface type (default: "SMTP")
+- `from_address` (String) - From email address (required, must be valid email format)
+- `ignore_cert_errors` (Boolean) - Whether to ignore SSL certificate errors (default: false)
+- `modified_date` (String) - Last modification timestamp
+- `headers` (Array) - Array of custom header hashes
+
+**Header Structure:**
+Each header in the `headers` array should have:
+
+- `key` (String) - Header name (required)
+- `value` (String) - Header value (required)
+
+**Instance Methods:**
+
+- `#add_header(key, value)` - Add a custom header to the SMTP profile
+- `#remove_header(key)` - Remove a header by key name
+- `#has_headers?` - Check if SMTP profile has any custom headers
+- `#header_count` - Get the number of custom headers
+- `#has_authentication?` - Check if SMTP profile uses authentication (username/password)
+- `#ignores_cert_errors?` - Check if SMTP profile ignores SSL certificate errors
+
+**Validations:**
+
+- SMTP profile must have a name
+- SMTP profile must have a host
+- SMTP profile must have a from_address in valid email format
+- All headers must have both key and value
+
+#### `Gophish::Campaign`
+
+Represents a Gophish phishing campaign that orchestrates email sending to target groups.
+
+**Attributes:**
+
+- `id` (Integer) - Unique campaign identifier
+- `name` (String) - Campaign name (required)
+- `created_date` (String) - Campaign creation timestamp
+- `launch_date` (String) - When the campaign should start sending emails
+- `send_by_date` (String) - Deadline for sending all campaign emails
+- `completed_date` (String) - When the campaign was completed
+- `template` - Reference to email template (required, can be hash or Template instance)
+- `page` - Reference to landing page (required, can be hash or Page instance)
+- `status` (String) - Current campaign status (e.g., "In progress", "Completed")
+- `results` (Array) - Array of Result instances showing target interactions
+- `groups` (Array) - Array of target groups (required, can be hashes or Group instances)
+- `timeline` (Array) - Array of Event instances showing campaign timeline
+- `smtp` - Reference to SMTP profile (required, can be hash or Smtp instance)
+- `url` (String) - Base URL for the campaign (required)
+
+**Class Methods:**
+
+- `.get_results(id)` - Get campaign results by campaign ID
+- `.get_summary(id)` - Get campaign summary statistics by ID
+- `.complete(id)` - Complete a campaign by ID
+
+**Instance Methods:**
+
+- `#get_results` - Get detailed campaign results
+- `#get_summary` - Get campaign summary statistics
+- `#complete!` - Complete the campaign and update status
+- `#in_progress?` - Check if campaign is currently running
+- `#completed?` - Check if campaign has been completed
+- `#launched?` - Check if campaign has a launch date set
+- `#has_send_by_date?` - Check if campaign has a send-by deadline
+
+**Validations:**
+
+- Campaign must have a name
+- Campaign must reference a template
+- Campaign must reference a page
+- Campaign must have at least one group
+- Campaign must reference an SMTP profile
+- Campaign must have a URL
+- All groups must have names
+- All results must have email addresses
+- All timeline events must have time and message
+
+**Nested Classes:**
+
+##### `Gophish::Campaign::Result`
+
+Represents individual target results within a campaign.
+
+**Attributes:**
+
+- `id` (String) - Result identifier
+- `first_name` (String) - Target's first name
+- `last_name` (String) - Target's last name
+- `position` (String) - Target's position
+- `email` (String) - Target's email address
+- `status` (String) - Current result status
+- `ip` (String) - IP address of target interactions
+- `latitude` (Float) - Geographic latitude
+- `longitude` (Float) - Geographic longitude
+- `send_date` (String) - When email was sent
+- `reported` (Boolean) - Whether target reported the email
+- `modified_date` (String) - Last modification timestamp
+
+**Instance Methods:**
+
+- `#reported?` - Check if target reported the phishing email
+- `#clicked?` - Check if target clicked the phishing link
+- `#opened?` - Check if target opened the email
+- `#sent?` - Check if email was sent to target
+- `#submitted_data?` - Check if target submitted data on landing page
+
+##### `Gophish::Campaign::Event`
+
+Represents timeline events within a campaign.
+
+**Attributes:**
+
+- `email` (String) - Target email associated with event
+- `time` (String) - Event timestamp
+- `message` (String) - Event description
+- `details` (String) - Additional event details (JSON string)
+
+**Instance Methods:**
+
+- `#has_details?` - Check if event has additional details
+- `#parsed_details` - Parse details JSON into hash
+
 ## 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.