Phishing

---
name: "KnowBe4 Phishing"
description: >
  KnowBe4 phishing simulations: campaign creation and lifecycle, security test
  management, recipient interaction tracking (sent, opened, clicked, reported),
  phish-prone percentage calculation, template selection, landing pages, and
  click tracking.
when_to_use: >-
  When creating, managing, or analyzing KnowBe4 phishing simulation campaigns. Use when:
  knowbe4 phishing, phishing campaign, phishing simulation, phish-prone percentage, security test
  knowbe4, phishing template, click tracking, phishing results, simulated phishing, phishing
  report, recipient tracking, phishing landing page, or phishing test.
---

# 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.

## Anti-triggers

- **A real phishing email that reached a user** — every campaign,
  click, and "failure" here is a simulation the MSP sent on purpose.
  Genuine inbound phishing is detected by the mail-security vendor:
  `proofpoint-tap`, `avanan-threats`, or
  `abnormal-security-threats`.
- **Finding, releasing, or pulling a message out of a mailbox** —
  KnowBe4 never touches production mail flow. Use
  `proofpoint-quarantine` or `avanan-quarantine` to release,
  and `proofpoint-forensics` to remove delivered mail.
- **"Phish Alert Button" reports as a threat-intake queue** — this
  skill counts PAB reports as a pass/fail signal on a simulation; the
  real user-reported phishing triage queue is `ironscales-incidents`.
- **Enrolling the users who failed into remedial training** — the
  enrollment side is `knowbe4-training`.
- **Organization-wide phish-prone percentage or department
  breakdowns** — per-campaign results are here; rolled-up metrics and
  benchmarks are `knowbe4-reporting`.

## 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:

```javascript
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 | Parameters (required in **bold**) |
|------|-------------|----------------|
| `knowbe4_phishing_campaigns_list` | List all phishing campaigns | `page`, `per_page` |
| `knowbe4_phishing_campaigns_get` | Get campaign details, including its associated security tests | **`campaign_id`** |
| `knowbe4_phishing_campaign_tests` | List the Phishing Security Tests belonging to **one** campaign | **`campaign_id`**, `page`, `per_page` |
| `knowbe4_phishing_security_tests_list` | List Phishing Security Tests across **all** campaigns | `page`, `per_page` |
| `knowbe4_phishing_security_test_get` | Get detailed results for one PST — PPP, clicked/opened/reported counts | **`pst_id`** |
| `knowbe4_phishing_security_test_recipients` | Recipient-level results for one PST: who clicked, opened, reported | **`pst_id`**, `page`, `per_page` |
| `knowbe4_phishing_security_test_recipient` | One recipient's result within one PST | **`pst_id`**, **`recipient_id`** |

There is no campaign-level recipient tool. Recipients hang off a Phishing
Security Test, never off a campaign, so "who clicked in this campaign"
is two steps: `knowbe4_phishing_campaign_tests` to get the campaign's
PSTs, then `knowbe4_phishing_security_test_recipients` per PST. A
recipient ID is only meaningful alongside the `pst_id` it came from —
`knowbe4_phishing_security_test_recipient` requires both.

**There is no phishing-template tool.** Nothing in this plugin lists the
template library or reads a single template's content, and no `page`/
`per_page` sweep will find one. Template selection is console work.
Campaign and PST records name the template that was used, which is enough
to compare how templates performed after the fact, but not to browse what
is available before a send.

None of the list tools filter by status or date. Narrowing to "completed
campaigns since March" means paginating and filtering client-side.

## 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 | Message | Resolution |
|------|---------|------------|
| 400 | Invalid campaign parameters | Check date formats and required fields |
| 401 | Invalid API token | Verify KNOWBE4_API_KEY |
| 403 | Insufficient permissions | API token needs Reporting permissions |
| 404 | Campaign not found | Verify campaign_id exists |
| 429 | Rate limit exceeded | Implement backoff (see api-patterns) |

### Data Considerations

| Issue | Cause | Resolution |
|-------|-------|------------|
| Zero delivered count | Campaign just started | Wait for delivery to complete |
| High bounce rate | Invalid email addresses | Clean user list before next campaign |
| No reported count | PAB not deployed | Install Phish Alert Button |
| Opened count higher than delivered | Email previews/security scanners | Filter by user agent if available |

## Best Practices

1. **Vary templates** -- Use different phishing scenarios to avoid pattern recognition
2. **Spread delivery** -- Send over days/weeks, not all at once, to avoid "water cooler effect"
3. **Track trends, not individual tests** -- Single campaigns can be noisy; look at 3-6 month trends
4. **Combine with training** -- Auto-enroll failed users in relevant training modules
5. **Use realistic scenarios** -- Match templates to actual threats your clients face
6. **Baseline first** -- Run an initial campaign before training to establish baseline PPP
7. **Report to leadership** -- Share PPP trends with management to justify security awareness investment
8. **Test all levels** -- Include executives and IT staff, not just general users
9. **Respect local regulations** -- Some regions have restrictions on simulated phishing
10. **Set proper tracking duration** -- Allow 72 hours minimum for accurate click data

## Related Skills

- [KnowBe4 Training](../training/SKILL.md) - Training campaign management and enrollment
- [KnowBe4 Users](../users/SKILL.md) - User management and risk scores
- [KnowBe4 Reporting](../reporting/SKILL.md) - Security awareness metrics and dashboards
- [KnowBe4 API Patterns](../api-patterns/SKILL.md) - Authentication, pagination, and rate limits