KnowBe4 Phishing

KnowBe4 Phishing Simulation Management

Overview

KnowBe4 phishing simulations are the core mechanism for testing and improving an organization's resilience to social engineering attacks. Campaigns deliver simulated phishing emails to users and track their interactions -- whether they opened the email, clicked the link, submitted data on the landing page, reported it via the Phish Alert Button, or took no action. The phish-prone percentage is the key metric derived from these campaigns.

Key Concepts

Campaign Lifecycle

CREATED ──> SCHEDULED ──> IN_PROGRESS ──> COMPLETED
                │                              │
                └──── CANCELLED                └──> ARCHIVED

• Created: Campaign configured but not yet scheduled
• Scheduled: Campaign queued for delivery at a specific date/time
• In Progress: Emails are being sent and interactions tracked
• Completed: Campaign delivery finished, final results available
• Cancelled: Campaign aborted before completion
• Archived: Completed campaign moved to archive

Security Test Types

| Type | Description | Use Case | |------|-------------|----------| | Phishing | Standard email with link to landing page | Most common, baseline testing | | Vishing | Voice-based social engineering simulation | Phone-based attack awareness | | Smishing | SMS-based phishing simulation | Mobile threat awareness | | USB | Physical USB drop test | Physical security awareness | | QR Code | QR code-based phishing | Emerging threat vector |

Recipient Interaction States

Each recipient in a campaign progresses through trackable states:

| State | Description | Indicates | |-------|-------------|-----------| | Delivered | Email successfully delivered | Baseline count | | Opened | Recipient opened the email | Curiosity/engagement | | Clicked | Recipient clicked the phishing link | Failed the test | | Replied | Recipient replied to the email | Failed the test (data leakage risk) | | Attachment Opened | Recipient opened an attachment | Failed the test | | Macro Enabled | Recipient enabled macros in attachment | Critical failure | | Data Entered | Recipient submitted data on landing page | Critical failure | | Reported | Recipient reported via Phish Alert Button | Passed the test | | No Action | No interaction recorded | Neutral (may not have seen it) |

Phish-Prone Percentage Calculation

The phish-prone percentage (PPP) is the primary metric for organizational risk:

function calculatePhishPronePercentage(campaign) {
  const totalDelivered = campaign.recipients.filter(r => r.delivered).length;
  const totalFailed = campaign.recipients.filter(r =>
    r.clicked || r.replied || r.attachmentOpened || r.macroEnabled || r.dataEntered
  ).length;

  if (totalDelivered === 0) return 0;
  return ((totalFailed / totalDelivered) * 100).toFixed(1);
}

Industry Benchmarks: | PPP Range | Rating | Context | |-----------|--------|---------| | 0-5% | Excellent | Well-trained organization | | 5-15% | Good | Regular training in place | | 15-30% | Average | Industry baseline for new programs | | 30-50% | Poor | Needs immediate attention | | 50%+ | Critical | High-risk organization |

Field Reference

Campaign Fields

| Field | Type | Description | |-------|------|-------------| | campaign_id | int | Unique campaign identifier | | name | string | Campaign name | | status | string | Current status (created, scheduled, in_progress, completed) | | create_date | datetime | When campaign was created | | start_date | datetime | Scheduled start date | | end_date | datetime | Campaign end date | | duration_type | string | How long the campaign runs (e.g., one_week, two_weeks) | | send_duration | string | Email delivery spread period | | track_duration | string | How long to track interactions after delivery | | frequency_type | string | One-time, weekly, bi-weekly, monthly | | phishing_template_id | int | Template used for the phishing email | | landing_page_id | int | Landing page shown after click | | groups | array | Target groups for the campaign |

Phishing Security Test (PST) Fields

| Field | Type | Description | |-------|------|-------------| | pst_id | int | Unique security test identifier | | status | string | Test status | | started_at | datetime | When the test began | | category | object | Template category info | | template | object | Email template details | | landing_page | object | Landing page details | | scheduled_count | int | Recipients scheduled to receive | | delivered_count | int | Emails successfully delivered | | opened_count | int | Emails opened | | clicked_count | int | Links clicked | | replied_count | int | Replies sent | | attachment_open_count | int | Attachments opened | | macro_enabled_count | int | Macros enabled | | data_entered_count | int | Data entered on landing page | | reported_count | int | Reported via PAB | | bounced_count | int | Emails bounced |

Recipient Fields

| Field | Type | Description | |-------|------|-------------| | recipient_id | int | Unique recipient identifier | | pst_id | int | Parent security test | | user | object | User details (name, email, department) | | scheduled_at | datetime | When email is scheduled | | delivered_at | datetime | When email was delivered | | opened_at | datetime | When email was opened | | clicked_at | datetime | When link was clicked | | replied_at | datetime | When reply was sent | | attachment_opened_at | datetime | When attachment was opened | | macro_enabled_at | datetime | When macro was enabled | | data_entered_at | datetime | When data was entered | | reported_at | datetime | When it was reported | | bounced_at | datetime | When email bounced | | ip | string | IP address of interaction | | browser | string | Browser used for click |

MCP Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | knowbe4_phishing_list_campaigns | List all phishing campaigns | status, page, per_page | | knowbe4_phishing_get_campaign | Get campaign details | campaign_id | | knowbe4_phishing_list_security_tests | List security tests for a campaign | campaign_id | | knowbe4_phishing_get_security_test | Get detailed security test results | pst_id | | knowbe4_phishing_list_recipients | List recipients for a security test | pst_id, page, per_page | | knowbe4_phishing_get_recipient | Get individual recipient details | recipient_id | | knowbe4_phishing_list_templates | List available phishing templates | category, page, per_page | | knowbe4_phishing_get_template | Get template details | template_id |

Common Workflows

Review Campaign Results

1. List campaigns to find the target campaign
2. Get campaign details for overview metrics
3. List security tests within the campaign
4. Get security test results for detailed interaction counts
5. List recipients to identify who clicked/failed
6. Calculate PPP from the results

Identify High-Risk Users

1. List completed campaigns from a date range
2. Get recipients who clicked or entered data across campaigns
3. Cross-reference with user profiles for repeat offenders
4. Generate report of users who failed multiple tests

Compare Campaign Performance Over Time

1. List all campaigns sorted by date
2. Get PPP for each campaign
3. Track trend -- PPP should decrease over time with training
4. Identify anomalies -- sudden PPP increase may indicate new attack vector or template difficulty

Post-Campaign Remediation

1. Get failed recipients from completed campaign
2. Enroll failed users in remedial training
3. Schedule follow-up test targeting the same users
4. Compare results to measure improvement

Error Handling

Common API Errors

| Code