<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-user-reporting-workflows
description: >-
  Design and deploy phishing report button integrations, automated triage
  pipelines, reporter feedback loops, and SOC escalation workflows for
  user-reported suspicious emails.
domain: cybersecurity
subdomain: phishing-defense
tags:
  - user-reporting
  - phishing-report-button
  - soar
  - triage
  - soc-workflow
  - security-awareness
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1566"]
---

# Implementing User Reporting Workflows

## Overview

User reporting is the last line of defense against phishing. A well-designed
reporting workflow makes it easy for users to report suspicious emails, automates
initial triage, provides feedback to reporters, and escalates confirmed threats.
This skill covers report button deployment, automated analysis pipelines, SOC
triage procedures, and metrics tracking.

## Prerequisites

| Requirement | Install |
|---|---|
| Python 3.10+ | Agent tooling runtime |
| Email client add-in | Report Phishing button (M365/Google) |
| SOAR platform | TheHive, Cortex XSOAR, or Tines |
| Shared mailbox | `phishing-reports@company.com` |
| Ticketing system | ServiceNow, Jira, or similar |

## Key Concepts

### Reporting Pipeline

```
User Reports Suspicious Email
├── 1. Report Button Click
│   ├── Email forwarded to shared mailbox (as attachment)
│   ├── Original removed from user mailbox (optional)
│   └── Confirmation message sent to reporter
├── 2. Automated Triage (SOAR)
│   ├── Header extraction and authentication check
│   ├── URL analysis (reputation, sandbox)
│   ├── Attachment analysis (hash lookup, sandbox)
│   ├── Sender reputation check
│   └── Auto-classify: Spam | Phishing | BEC | Clean
├── 3. SOC Analyst Review
│   ├── Verify automated classification
│   ├── Extract additional IOCs
│   ├── Determine scope (other recipients)
│   └── Decide: Escalate | Close | Remediate
├── 4. Response Actions
│   ├── Block sender/domain at gateway
│   ├── Purge from all mailboxes (search and destroy)
│   ├── Block URLs at proxy/firewall
│   └── Reset credentials if harvesting confirmed
└── 5. Reporter Feedback
    ├── Thank reporter (always, even if clean)
    ├── Confirm if phishing was real
    └── Track reporter metrics for recognition
```

### Metrics Dashboard

| Metric | Target | Description |
|---|---|---|
| Reports per month | Trending up | User engagement |
| Triage time (automated) | < 5 min | SOAR processing speed |
| Analyst review time | < 30 min | SOC efficiency |
| True positive rate | > 30% | Report quality |
| Reporter feedback rate | 100% | Always acknowledge |
| Unique reporters | > 20% of org | Breadth of participation |

## Workflow

### 1. Report Button Deployment

```bash
# M365: Deploy Report Message add-in
# Set-App -Identity "ReportMessage" -DefaultStateForUser Enabled
# Set-ReportSubmissionPolicy -ReportJunkToCustomizedAddress $true \
#   -ReportJunkAddresses "phishing-reports@company.com"

# Generate deployment configuration
node agent.js configure-button --platform m365

# Google Workspace: Enable phishing report
# Admin Console → Apps → Google Workspace → Gmail → User Settings
# → Enable "Report phishing" button
```

### 2. SOAR Playbook Configuration

```bash
# Generate SOAR playbook for phishing triage
node agent.js generate-playbook --platform thehive

# Triage automation steps:
# 1. Parse email (extract headers, body, attachments, URLs)
# 2. Check sender against known-good whitelist
# 3. Submit URLs to VT/URLhaus
# 4. Submit attachments to sandbox
# 5. Check authentication results (SPF/DKIM/DMARC)
# 6. Auto-classify based on scoring
# 7. Create ticket with findings
```

### 3. SOC Triage Procedures

```bash
# Generate triage checklist
node agent.js triage-checklist

# Search for email across all mailboxes (M365)
# New-ComplianceSearch -Name "Phish-2026-001" \
#   -ExchangeLocation All \
#   -ContentMatchQuery 'from:attacker@evil.com AND subject:"Urgent Payment"'
# Start-ComplianceSearch -Identity "Phish-2026-001"

# Purge confirmed phishing from all mailboxes
# New-ComplianceSearchAction -SearchName "Phish-2026-001" -Purge -PurgeType SoftDelete
```

### 4. Reporter Feedback Loop

```bash
# Generate feedback templates
node agent.js feedback-templates

# Track reporter metrics
node agent.js reporter-stats --period monthly
```

## Detection

```yaml
title: User Reporting Workflows Detection
id: 75990533-452d-46d6-8194-f1ec97eaa877
status: experimental
description: Detects suspicious activity related to implementing user reporting workflows techniques in phishing defense context
logsource:
  category: email
  service: o365
detection:
  selection:
    Subject: "*urgent*"
  condition: selection
level: high
tags:
  - attack.t1566
  - attack.initial_access
falsepositives:
  - Security awareness training platform sending simulated phishing emails
```

## Verification

| Check | Method |
|---|---|
| Report button deployed | Test report from user mailbox |
| Emails reach shared mailbox | Verify email arrives as attachment |
| SOAR playbook triggers | Test end-to-end automation |
| Auto-classification working | Submit known-phish and known-clean |
| Feedback sent to reporter | Verify acknowledgment email delivery |
| Metrics dashboard populated | Check reporting statistics |

## References

- [Microsoft Report Message Add-in](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/submissions-users-report-message-add-in-configure)
- [TheHive Project](https://thehive-project.org/)
- [Cortex XSOAR](https://www.paloaltonetworks.com/cortex/cortex-xsoar)
- [Tines Automation](https://www.tines.com/)
- [NIST SP 800-61 — Incident Handling](https://csrc.nist.gov/publications/detail/sp/800-61/rev-2/final)
