IRONSCALES Incidents · diff
git:20260806.2d05ac2 to git:20260806.ad583a2
191 added, 101 removed. Audit A to A.
---
name: "IRONSCALES Incidents"
description: >
- Ironscales phishing incidents end to end: incident sources and statuses, the
- phishing/spam/legitimate classification model and the remediation each one
- triggers, the response fields that drive triage decisions, daily-triage and
- campaign-blocking workflows, and the failure modes — already-closed incidents,
- partial remediation, and allowlist scope.
+ Ironscales phishing incidents end to end: incident statuses and severities, the
+ five remediation actions and which of them are irreversible, the stateless AI
+ email-classification tool and the message content it exports, allowlist entries
+ for email/domain/IP, daily-triage and campaign workflows, and the failure modes —
+ already-closed incidents, partial remediation, and allowlist scope.
when_to_use: >-
- When triaging, classifying, or remediating an Ironscales phishing incident, managing
- the sender allowlist, or reviewing company phishing statistics. Use when:
+ When triaging, investigating, or remediating an Ironscales phishing incident, managing
+ the sender allowlist, asking Ironscales' AI to classify raw email content, or reviewing
+ company phishing statistics. Use when:
ironscales incident, phishing incident, ironscales remediation, classify email ironscales,
- ironscales phishing, ironscales allowlist, ironscales triage, ironscales spam, ironscales
+ ironscales phishing, ironscales allowlist, ironscales triage, ironscales quarantine, ironscales
legitimate, or ironscales dashboard.
---
# Ironscales Phishing Incidents
## Overview
- Ironscales combines AI-powered threat detection with crowdsourced employee phishing reports to identify and remediate phishing attacks. When a user reports a suspicious email (via the Ironscales Outlook add-in or Gmail extension) or Ironscales AI auto-detects a threat, an incident is created. Security administrators triage these incidents, classify each email, and take remediation actions. Ironscales uses federated learning — decisions made on one tenant inform the global threat model, improving detection over time.
+ Ironscales combines AI-powered threat detection with crowdsourced employee phishing reports to identify and remediate phishing attacks. When a user reports a suspicious email (via the Ironscales Outlook add-in or Gmail extension) or Ironscales AI auto-detects a threat, an incident is created. Security administrators triage these incidents and take remediation actions against the delivered mail. Ironscales uses federated learning — decisions made on one tenant inform the global threat model, improving detection over time.
## Anti-triggers
- **A phishing report that arrived in a different platform** — Ironscales
incidents originate from its own add-in or its own AI. Abnormal's abuse
mailbox produces separate objects with separate IDs; use
`Abnormal Security Cases`.
- **A simulated phish, or who clicked one** — Ironscales incidents come
from real inbound mail. Campaign results and click rates are
`KnowBe4 Phishing`.
- **Mail held at a gateway before it reached anyone** — Ironscales acts
on mail already sitting in mailboxes and has no pre-delivery queue. Use
`SpamTitan Quarantine` or `Mimecast Message Tracking`.
- **Resetting the credentials a phish harvested** — remediation here
removes mail and blocks senders. The identity action happens in the
tenant; use `cipp-users`.
- **A phish caught by the other API-based platform on the tenant** —
Check Point Harmony Email (Avanan) inspects the same mailboxes and
detects the same mail independently. It has no incident object to
correlate against — its API surfaces the offending mail itself — so use
`checkpoint-avanan-threats` and match on the message, not on an ID.
## Key Concepts
- ### Incident Sources
-
- | Source | Description |
- |--------|-------------|
- | `USER_REPORT` | Employee used the Ironscales add-in to report a suspicious email |
- | `AI_DETECTION` | Ironscales AI automatically flagged the email without a user report |
-
### Incident Status
+ `ironscales_incidents_list` accepts exactly these four values in `status`:
+
| Status | Description |
|--------|-------------|
| `open` | Newly reported, awaiting review |
| `in_progress` | Under active investigation |
- | `resolved` | Classification applied and remediation complete |
- | `closed` | Incident closed (may be false positive or resolved) |
+ | `pending` | Awaiting an external step before it can progress |
+ | `closed` | Incident closed (false positive, or remediation complete) |
- ### Email Classifications
+ There is no `resolved` status. Passing one is a 400.
- | Classification | Description |
- |----------------|-------------|
- | `phishing` | Confirmed phishing email — malicious intent, credential harvesting, or fraud |
- | `spam` | Unwanted bulk email — not targeted/malicious, but should be blocked |
- | `legitimate` | Safe email — false positive report from user |
+ ### Incident Severity
- Once classified, Ironscales can take automatic remediation actions based on the classification:
- - **Phishing** → Remove from all mailboxes, block sender, update threat intelligence
- - **Spam** → Block sender, optionally remove from mailboxes
- - **Legitimate** → Close incident, optionally add sender to allowlist
+ `ironscales_incidents_list` also accepts `severity`, which is the only
+ prioritisation filter the API offers:
+ | Severity | Meaning |
+ |----------|---------|
+ | `critical` / `high` | Triage first |
+ | `medium` | Routine queue |
+ | `low` | Batch review |
+
+ ### Incident Sources — not a filter
+
+ Incidents originate either from a user's add-in report or from Ironscales
+ AI. **There is no `source` parameter.** You cannot ask the API for only
+ user-reported incidents. If you need the split, list without a source
+ filter and partition the returned records yourself.
+
+ ### Classifying an email is not an incident action
+
+ `ironscales_email_classify` is a stateless AI lookup. You assemble a raw
+ email — `sender` is required, everything else optional — POST it to
+ Ironscales, and get a verdict back. It does **not** reference an incident,
+ does not set `classification` on anything, and changes no state anywhere.
+ There is no tool on this server that writes a phishing/spam/legitimate
+ verdict onto an existing incident. The only way this server changes
+ incident state is `ironscales_remediation_act`.
+
+ Because you supply the content, this tool sends the customer's message —
+ subject, plain-text body, HTML body, URLs, headers — outbound to
+ Ironscales for analysis. Its schema explicitly says to pass attachment
+ *metadata* only (`filename`, `content_type`, `size_bytes`); never the file
+ contents.
+
### Remediation Actions
- | Action | Description |
- |--------|-------------|
- | `remove_emails` | Remove the email from all affected mailboxes |
- | `block_sender` | Block the sender email address globally |
- | `block_domain` | Block the entire sender domain |
- | `allowlist_sender` | Add sender to allowlist (for false positives) |
+ `ironscales_remediation_act` accepts exactly five values in `action`.
+ They are not all tightenings:
+ | Action | Effect | Reversible? |
+ |--------|--------|-------------|
+ | `quarantine` | Moves the message out of inboxes into quarantine | Yes — the message can be released |
+ | `delete` | Permanently removes the message from **all** mailboxes | **No** — the evidence goes with it |
+ | `block_sender` | Adds the sender address to the blocklist | Yes, by editing the blocklist |
+ | `mark_false_positive` | Marks the mail legitimate and **restores** it to recipients | Reverses containment |
+ | `report_to_microsoft` | Submits the message to Microsoft for analysis | **No** — cannot be recalled |
+
+ `quarantine` is the default choice. Reach for `delete` only when the
+ message is confirmed malicious and you have already captured whatever
+ evidence the investigation needs, because `delete` destroys it.
+
+ `notify_users` (boolean, default `false`) mails the affected end users
+ about the remediation. It is an outbound communication to your customer's
+ staff and it cannot be unsent. Leave it `false` unless someone has
+ explicitly asked for the notification.
+
+ There is **no `block_domain` action**. Campaign-wide domain blocking is
+ not exposed by this server — see *Handle a Phishing Campaign* below.
+
+ ### Allowlist Entries
+
+ `ironscales_allowlist_manage` takes an `operation` (not an `action`), and
+ entries are typed: an entry is an `email`, a `domain`, or an `ip`. An
+ allowlist entry exempts its target from phishing detection for the whole
+ company, so a `domain` entry is a far larger trust grant than an `email`
+ one.
+
## API Patterns
- All incident tools are offset-paginated and scoped to the connected company ID.
+ `ironscales_incidents_list` is offset-paginated. All tools are scoped to
+ the connected company ID.
| Tool | Key parameters |
|------|----------------|
- | `ironscales_list_incidents` | `status` (`open`/`in_progress`/`resolved`/`closed`), `source` (`USER_REPORT`/`AI_DETECTION`), `offset`, `limit` (default 50, max 100) |
- | `ironscales_get_incident` | `incidentId` |
- | `ironscales_classify_email` | `incidentId`, `classification` (`phishing`/`spam`/`legitimate`), optional `comment` |
- | `ironscales_remediate_incident` | `incidentId`, `action` (`remove_emails`/`block_sender`/`block_domain`/`allowlist_sender`), optional `comment` |
- | `ironscales_get_company_stats` | `period` (`7d`/`30d`/`90d`, default `30d`) |
- | `ironscales_manage_allowlist` | `action` (`add`/`remove`/`list`), `senderEmail`, optional `senderDomain`, optional `comment` |
+ | `ironscales_incidents_list` | `status` (`open`/`closed`/`in_progress`/`pending`), `severity` (`low`/`medium`/`high`/`critical`), `limit` (default 50, max 100), `offset` (default 0) |
+ | `ironscales_incidents_get` | `incident_id` (required) |
+ | `ironscales_email_classify` | `sender` (required), `subject`, `sender_display_name`, `reply_to`, `body_text`, `body_html`, `headers`, `urls`, `attachments` |
+ | `ironscales_remediation_act` | `incident_id` (required), `action` (required — `quarantine`/`delete`/`block_sender`/`mark_false_positive`/`report_to_microsoft`), `reason`, `notify_users` (default `false`) |
+ | `ironscales_stats_company` | `period` (`7d`/`30d`/`90d`/`1y`, default `30d`) |
+ | `ironscales_allowlist_manage` | `operation` (required — `add`/`remove`/`list`), `entry_type` (`email`/`domain`/`ip`, required for add/remove), `value` (required for add/remove), `reason` |
- The fields that drive triage decisions:
+ The incident fields this server reads and normalises for the incident
+ card, and therefore the ones you can rely on:
- - `aiVerdict` — Ironscales AI's pre-classified verdict, **not** yet confirmed by an admin.
- - `aiConfidence` — 0–1 score; above 0.9 is high confidence.
- - `classification` — stays `null` until an admin explicitly classifies the incident.
- - `recipientCount` — mailboxes that received the email; the campaign-breadth signal.
- - `indicators[]` — why the AI flagged it (e.g. `SUSPICIOUS_DOMAIN`, `REPLY_TO_MISMATCH`, `FINANCIAL_REQUEST`), returned only by `ironscales_get_incident`.
- - `links[].verdict` — per-URL verdict; a `malicious` link is a strong phishing signal.
- - `remediationTriggered` / `remediationActions` — whether classification auto-fired remediation, and which actions ran.
+ - `id`, `subject`, `status`, `severity`, `sender`, `created_at`
+ - `recipients[]` and `recipient_count` — the campaign-breadth signal.
+ - `threat_indicators[]` — why the mail was flagged.
- Statistics metrics worth tracking: `averageTimeToResolve` (mean minutes to
- classification), `userReportRate` (share of incidents caught by user reports
- rather than AI alone), and `topTargetedUsers` (high-value targets).
+ `ironscales_incidents_get` returns the vendor payload verbatim, so it may
+ carry further fields; treat anything beyond the list above as
+ tenant-dependent and verify it is present before branching on it.
See [references/api.md](references/api.md) for full parameter lists and
request/response examples for every tool.
## Common Workflows
### Daily Incident Triage
- 1. Call `ironscales_list_incidents` with `status=open`
- 2. Sort incidents by `aiConfidence` descending — high-confidence AI detections first
- 3. For each incident:
- - Review `subject`, `senderEmail`, and `aiVerdict`
- - For high-confidence phishing (`aiConfidence > 0.9`), call `ironscales_classify_email` with `phishing`
- - For ambiguous cases, call `ironscales_get_incident` to review full indicators before classifying
- 4. For incidents where classification is spam or legitimate, classify accordingly
- 5. Review `remediationTriggered` — verify automatic remediation fired for phishing classifications
+ 1. Call `ironscales_incidents_list` with `status=open`.
+ 2. Work `severity=critical` and `severity=high` first — re-run the list
+ with the `severity` filter rather than sorting client-side, so you page
+ through less.
+ 3. For each incident, call `ironscales_incidents_get` with `incident_id`
+ and review `threat_indicators`, `sender`, and `recipient_count`.
+ 4. Decide an action per incident and call `ironscales_remediation_act`.
+ Default to `quarantine`; escalate to `delete` only for confirmed
+ malicious mail whose evidence you no longer need.
+ 5. Incidents you judge benign take `mark_false_positive`, which restores
+ the message to its recipients.
- ### Investigate Before Classification
+ There is no auto-classification step. Nothing in this server labels an
+ incident for you, so nothing can be labelled in bulk without a human
+ deciding each remediation.
- 1. Call `ironscales_get_incident` with the incident ID
- 2. Review `indicators` array — each indicator explains why AI flagged this email
- 3. Check `links` — malicious URL verdict is a strong phishing signal
- 4. Review `replyTo` vs. `senderEmail` — mismatches are a common BEC/phishing indicator
- 5. Check `senderIp` against known threat intelligence sources if available
- 6. Based on findings, call `ironscales_classify_email` with the appropriate classification
+ ### Investigate Before Remediating
+ 1. Call `ironscales_incidents_get` with the incident ID.
+ 2. Review `threat_indicators` — each entry explains why the mail was
+ flagged.
+ 3. Check `recipient_count` and `recipients` — breadth tells you whether
+ this is a campaign or a one-off.
+ 4. Compare the reply-to against `sender` if the payload carries it;
+ mismatches are a common BEC indicator.
+ 5. If you want a second opinion on the content itself, assemble the
+ message into `ironscales_email_classify` (`sender` required, plus
+ subject/body/URLs). Remember this ships that content to Ironscales and
+ returns only a verdict — it will not change the incident.
+ 6. Call `ironscales_remediation_act` with the chosen action.
+
### Process False Positive Reports
- 1. Call `ironscales_list_incidents` with `status=open` and `source=USER_REPORT`
- 2. For each incident where `aiVerdict=legitimate` or `aiConfidence < 0.5`:
- - The user likely reported a safe email
- - Call `ironscales_classify_email` with `legitimate`
- 3. After classifying as legitimate, consider adding the sender to the allowlist with `ironscales_manage_allowlist` (action=add)
- 4. Respond to the reporting user confirming the email is safe
+ 1. Call `ironscales_incidents_list` with `status=open`. There is no
+ `source` filter, so if you only want user-reported items, partition the
+ returned records yourself after the call.
+ 2. For each incident you judge benign, call `ironscales_remediation_act`
+ with `action=mark_false_positive`. This restores the message to the
+ people who received it — confirm that is what you want before calling.
+ 3. To stop the same sender recurring, call `ironscales_allowlist_manage`
+ with `operation=add`, `entry_type=email`, and the address as `value`.
+ Use `entry_type=domain` only when you intend to exempt every sender on
+ that domain.
+ 4. Respond to the reporting user confirming the email is safe.
- ### Block a Phishing Campaign
+ ### Handle a Phishing Campaign
- 1. Identify a phishing campaign — multiple incidents from the same domain or with the same URL pattern
- 2. Classify each incident as `phishing` using `ironscales_classify_email`
- 3. For the first incident, use `ironscales_remediate_incident` with `action=block_domain` to block the entire sending domain
- 4. Verify `remediationStatus` confirms the block is active
- 5. Check `ironscales_get_company_stats` for the period to quantify campaign scope
+ 1. Identify the campaign — multiple incidents sharing a sending domain or
+ URL pattern. You will have to correlate these yourself; the API has no
+ campaign object.
+ 2. Remediate each incident individually with
+ `ironscales_remediation_act`. `quarantine` contains the mail;
+ `block_sender` stops that one address.
+ 3. **Campaign-wide domain blocking is not available through this server.**
+ `block_sender` is per-address and there is no `block_domain` action.
+ A domain-level block has to be done in the Ironscales console or in the
+ upstream mail filter. Do not promise a customer a domain block from
+ here.
+ 4. `ironscales_allowlist_manage` is the opposite operation — it exempts a
+ domain from detection. Never reach for it to "handle" a campaign.
+ 5. Call `ironscales_stats_company` for the period to quantify scope.
### Weekly Statistics Review
- 1. Call `ironscales_get_company_stats` with `period=7d`
- 2. Review `topTargetedUsers` — these users need additional security awareness training
- 3. Check `userReportRate` — below 50% indicates users are not using the Ironscales add-in frequently
- 4. Review `topAttackTypes` — trending attack types inform security awareness focus areas
- 5. Compare `phishingConfirmed` vs. `falsePositives` — a high false positive rate indicates overly aggressive AI tuning or user education needed
+ 1. Call `ironscales_stats_company` with `period=7d`. `30d`, `90d`, and
+ `1y` are also accepted — use `1y` for annual reporting.
+ 2. Review the top targeted users — these people need additional security
+ awareness training. Treat the list as sensitive security information.
+ 3. Review trending attack types to inform awareness focus areas.
+ 4. Compare confirmed phishing against false positives — a high false
+ positive rate indicates aggressive tuning or a gap in user education.
## Error Handling
- ### Classification Fails — Incident Already Closed
+ ### Remediation Fails — Incident Already Closed
- **Cause:** The incident status is `closed` or `resolved` — only open/in-progress incidents can be classified.
- **Solution:** Use `ironscales_list_incidents` to verify incident status before classifying.
+ **Cause:** The incident status is `closed`. The resulting error often reads
+ like a permissions failure.
+ **Solution:** Call `ironscales_incidents_list` and confirm the status
+ before acting. Remember the valid statuses are `open`, `in_progress`,
+ `pending`, and `closed` — there is no `resolved`.
### Remediation Reports Partial Success
- **Cause:** Some mailboxes may be offline, the email may have been deleted by the user, or Exchange/M365 integration permissions may be incomplete.
- **Solution:** Verify the Ironscales M365 integration in the platform. For remaining mailboxes, manually delete the email.
+ **Cause:** Some mailboxes may be offline, the email may have been deleted
+ by the user, or Exchange/M365 integration permissions may be incomplete.
+ **Solution:** Verify the Ironscales M365 integration in the platform. For
+ remaining mailboxes, remove the email manually.
### Allowlist Not Preventing New Incidents
- **Cause:** An allowlist entry for a sender email does not block incidents from the same domain via different addresses.
- **Solution:** Use `senderDomain` in the allowlist entry to allowlist the entire domain instead of a single address.
+ **Cause:** An `email` entry does not cover other addresses on the same
+ domain.
+ **Solution:** Use `entry_type=domain` — but understand you are exempting
+ the entire domain from phishing detection, which is a much larger grant.
- ### Low AI Confidence Score with Phishing Indicators
+ ### Classification Returned a Verdict but Nothing Changed
- **Cause:** Ironscales AI scores based on multiple factors; a legitimate-looking sender or domain may reduce confidence even if individual indicators are strong.
- **Solution:** Review `indicators` manually — a REPLY_TO_MISMATCH combined with a SUSPICIOUS_DOMAIN is a strong phishing signal regardless of AI confidence score.
+ **Cause:** Working as designed. `ironscales_email_classify` is stateless.
+ **Solution:** If you wanted incident state to change, call
+ `ironscales_remediation_act`.
## Best Practices
- - Triage all open incidents at least once per business day — user-reported incidents reflect real user exposure
- - Trust high-confidence AI verdicts (`aiConfidence > 0.9`) and classify quickly to keep queue clear
- - Always investigate incidents with `recipientCount > 10` — these are broad campaigns affecting many users
- - Use `block_domain` sparingly — block entire domains only when you are confident all mail from that domain is malicious
- - Build the allowlist proactively — common internal notification senders, HR systems, and monitoring tools should be added to prevent recurring false positives
- - Review `topTargetedUsers` monthly and ensure those users have MFA enabled and recent security awareness training
- - Track `averageTimeToResolve` — reducing this metric minimizes user exposure window
+ - Triage open incidents at least once per business day — user-reported
+ incidents reflect real user exposure.
+ - Filter on `severity` rather than pulling the whole queue; it is the only
+ prioritisation the API offers.
+ - Prefer `quarantine` over `delete`. `delete` is permanent and takes the
+ evidence with it.
+ - Leave `notify_users` at `false` unless the customer asked to be
+ notified — that mail cannot be unsent.
+ - Treat `mark_false_positive` as a release, not a filing action: it puts
+ the message back in front of the recipients.
+ - Never assume `ironscales_email_classify` did anything to an incident.
+ Verify with `ironscales_incidents_get` if you are unsure.
+ - Before pasting message content into `ironscales_email_classify`, confirm
+ you are authorised for that tenant — the content leaves your control.
+ - Build the allowlist proactively with `entry_type=email` for internal
+ notification senders, HR systems, and monitoring tools. Reserve
+ `entry_type=domain` for cases you can justify in writing.
+ - Always investigate incidents with a high `recipient_count` — these are
+ broad campaigns affecting many users.
## Related Skills
- [api-patterns](../api-patterns/SKILL.md) - Authentication, pagination, error codes