# 🛡️ Firewall Alert — URL IOC Enrichment (VirusTotal + URLScan)

An n8n workflow that automatically enriches suspicious URLs from firewall alerts using **VirusTotal** and **URLScan.io**, then creates a fully attributed **MISP** event for threat intelligence sharing and analyst triage.

---

## How It Works

```
Firewall/SIEM Alert
        │
        ▼
   ┌─ Webhook ─────────────────────────────┐
   │         (POST /firewall-url-enrich)    │
   └────┬──────────────────────────────┬────┘
        │                              │
        ▼                              ▼
  VirusTotal API                 URLScan.io
  (URL report)               (submit + fetch)
        │                              │
        └──────────┬───────────────────┘
                   ▼
           Merge & Build
         enrichment object
                   │
                   ▼
        Create MISP Event
                   │
                   ▼
       Prepare MISP Attributes
                   │
                   ▼
       ┌── Loop each item ──┐
       │                    │
       ▼                    ▼
   Tag items          Attribute items
  (create tag →      (create attribute
   attach to event)   on event)
       │                    │
       └────────────────────┘
                   │
                   ▼
                 Done ✅
```

## Webhook Payload

Send a `POST` request to `/webhook/firewall-url-enrich` with a JSON body:

```json
{
  "url": "https://suspicious-domain.ru/phish/login",
  "src_ip": "192.168.1.100",
  "machine_ips": ["192.168.1.100"]
}
```

| Field          | Type       | Required | Description                                      |
| -------------- | ---------- | -------- | ------------------------------------------------ |
| `url`          | `string`   | ✅       | The suspicious URL to enrich                     |
| `src_ip`       | `string`   | No       | Single source IP (fallback if `machine_ips` absent) |
| `machine_ips`  | `string[]` | No       | Array of internal machine IPs that triggered the alert |

## What Gets Created in MISP

### Event

A new MISP event is created with:

- **Threat Level:** High
- **Distribution:** Your organisation only
- **Analysis:** Initial

### Attributes

| MISP Type   | Category            | Source                                               |
| ----------- | ------------------- | ---------------------------------------------------- |
| `ip-src`    | Network activity    | Source machine IPs from the firewall alert            |
| `url`       | Network activity    | The suspicious URL that was flagged                   |
| `ip-dst`    | Network activity    | Destination IPs observed by URLScan during page load  |
| `domain`    | Network activity    | Domains observed by URLScan (excludes Cloudflare CDN) |
| `link`      | External analysis   | Permalinks to VirusTotal and URLScan reports          |
| `comment`   | External analysis   | Human-readable verdict summaries from both engines    |

### Tags

Tags are derived automatically from the enrichment verdicts:

| Tag                              | Condition                                        |
| -------------------------------- | ------------------------------------------------ |
| `tlp:amber`                      | Always applied                                   |
| `phishing`                       | VT or URLScan flags the URL as malicious         |
| `misp-galaxy:phishing`           | URLScan explicitly categorises as phishing        |
| `malware_download`               | VT threat names include `malware_download`        |
| `workflow:automated-enrichment`  | Always applied (marks event as machine-generated) |

## Node-by-Node Breakdown

### 1 · Webhook
Receives the firewall alert via POST. Uses `responseNode` mode so a response can be sent downstream. Immediately fans out into two parallel enrichment paths.

### 2a · Prepare URL for VT → GET URL from VT
Encodes the URL into a base64 URL-safe ID (required by VT's v3 API), then queries `GET /api/v3/urls/{id}` for the full analysis report — detection stats, threat names, vendor verdicts, reputation score, and category classifications.

### 2b · Submit URLScan → Wait → GET URLScan Results
Submits the URL for an **unlisted** scan on URLScan.io. A Wait node (currently **disabled**) provides a 60-second delay for the scan to finish before fetching the results — page metadata, observed IPs/domains, verdicts, and a report link.

> ⚠️ **Production note:** Enable the Wait node so URLScan has time to complete the scan before results are fetched.

### 3 · Merge VT + URLScan → Build MISP Event
Joins both enrichment branches and consolidates them into a single object containing the original URL, source IPs, and both enrichment payloads.

### 4 · Create MISP Event → Prepare MISP Attributes
Creates the MISP event, then transforms all enrichment data into a flat array of attribute items. A special `__event_tags__` sentinel item carries the derived tags array separately from real attributes.

### 5 · Loop Attributes & Tags → Tag Check (IF)
A `splitInBatches` node iterates over each item. The IF node routes based on `type`:

- **`__event_tags__`** → Tag path: explodes the tags array, creates each tag in MISP, then attaches it to the event.
- **Everything else** → Attribute path: creates the MISP attribute on the event.

Both paths loop back into the batch iterator until all items are processed.

## Prerequisites

### Credentials

| Service       | Credential Type     | Notes                                  |
| ------------- | ------------------- | -------------------------------------- |
| VirusTotal    | `virusTotalApi`     | API key with URL report read access    |
| URLScan.io    | `urlScanIoApi`      | API key with scan submit + read access |
| MISP          | `mispApi`           | API key + instance URL                 |

### Infrastructure

- **n8n** instance (self-hosted or cloud) with webhook access
- **MISP** instance reachable from the n8n host
- Network access to `virustotal.com` and `urlscan.io` APIs

## Setup

1. **Import** the workflow JSON into your n8n instance.
2. **Configure credentials** for VirusTotal, URLScan.io, and MISP in n8n's credential manager.
3. **Update the MISP org ID** in the "Create MISP Event" node if your org is not `1`.
4. **Enable the Wait node** if URLScan scans need time to complete (recommended for production).
5. **Activate** the workflow.
6. **Point your firewall/SIEM** alert rule at the webhook URL.

## Customisation Ideas

- **Add a Respond to Webhook node** to return the enrichment summary back to the caller.
- **Add Slack/email notifications** after the MISP event is created for real-time alerting.
- **Adjust tag logic** in the "Prepare MISP attributes" code node to add custom tags based on your threat model.
- **Extend the Cloudflare domain filter** to exclude other CDN/infrastructure domains you trust.
- **Chain with a SOAR playbook** by adding a downstream HTTP request to trigger containment actions.

## License

Internal use. Modify and extend as needed for your environment.