admin / Syanpse-Vanguard

# Setting up the Synapse IronNode → Synapse-Vanguard event feed

This guide walks an administrator through connecting **Synapse IronNode** to a
**Synapse-Vanguard** SIEM so that IronNode incidents are pushed into Vanguard as
security events.

The connection uses a single **API key** and **ingest URL** that Vanguard issues
and IronNode stores. Once set up, IronNode forwards each incident automatically
through its lifecycle (triggered → triage → closed).

```
  Synapse IronNode  ──POST /v1/ingest/events (Bearer <API key>)──▶  Synapse-Vanguard
   (incidents)                                                        (event search)
```

---

## Before you start

| You need | Where |
|---|---|
| A **Vanguard admin** account (role: *System Administrator*) | Vanguard login |
| An **IronNode** account with **3rd Line Analyst** rank or above | IronNode login |
| Network path from IronNode to Vanguard on the app port (default **5500**) | firewall / LAN |

> The two apps talk over HTTP(S) on Vanguard's app port. If they're on different
> hosts, make sure IronNode can reach `http://<vanguard-host>:5500`.

---

## Step 1 — Generate the API key in Vanguard

1. Sign in to Vanguard (`http://<vanguard-host>:5500/`) as an administrator.
2. In the top-right, open the **Admin ▾** menu and choose **🔑 Ingress API (IronNode)**.
3. You'll see two things:
   - **Ingest URL** — e.g. `http://<vanguard-host>:5500/v1/ingest/events`
   - **API key** — created when you click **Generate key**
4. Click **Generate key**. A key beginning with `svg_…` appears.
5. Use the **Copy** buttons to copy **both** the Ingest URL and the API key —
   you'll paste them into IronNode next.

> **Keep the key safe.** Anyone with the key + URL can send events to Vanguard.
> The key is stored encrypted; you can re-open this panel any time to copy it
> again, or **Regenerate** it (which immediately disables the old key).

The **Enable/Disable** toggle controls whether the ingest endpoint accepts data
at all. Leave it **enabled**.

---

## Step 2 — Configure IronNode

1. Sign in to IronNode as a **3rd Line Analyst** (or higher).
2. Go to **Settings** → find the **Synapse-Vanguard SIEM forwarder** card.
3. Fill in:
   - **Vanguard ingest URL** — paste the Ingest URL from Step 1
     (e.g. `http://<vanguard-host>:5500/v1/ingest/events`).
   - **Vanguard API key** — paste the `svg_…` key from Step 1.
4. Click **Test connection**.
   - ✅ *"Connected — Vanguard accepted the API key."* → you're good.
   - ❌ See [Troubleshooting](#troubleshooting) below.
5. Click **Save**.
6. Turn the **Forward incidents to Vanguard** toggle **on**.

The status pill at the top of the card should now read **Forwarding**.

> The API key is stored **AES-256-GCM encrypted** in IronNode's tenant vault and
> is never shown again in the browser. Re-enter it only if you regenerate it in
> Vanguard.

---

## Step 3 — Verify it works

1. In IronNode, trigger a playbook (via its webhook, or however you normally
   raise an incident). This creates an incident.
2. In Vanguard, go to the main dashboard and search with **Source type =
   `ironnode`**.
3. You should see incident events appear, for example:
   - `Incident TRIGGERED — <playbook>` when the incident is raised
   - `Incident AWAITING_TRIAGE — <playbook> (severity N/10)` once the AI scores it
   - `Incident CLOSED — <playbook>` when the playbook finishes

High-severity incidents show as **Critical/Emergency** and pulse red in the
Vanguard event table.

---

## How severity maps

IronNode scores incidents **1–10** (10 = most severe). Vanguard uses the syslog
**0–7** scale (0 = most severe). IronNode converts automatically:

| IronNode risk score | Vanguard severity |
|---|---|
| 10 | EMERGENCY (pulses red) |
| 9 | ALERT |
| 7–8 | CRITICAL (pulses red) |
| 6 | ERROR |
| 5 | WARNING |
| 3–4 | NOTICE |
| 2 | INFO |
| 1 | DEBUG |
| (not yet scored) | NOTICE |

> In Vanguard, **EMERGENCY** and **CRITICAL** rows pulse red so the most serious
> incidents stand out immediately.

---

## Rotating / revoking the key

**To rotate the key** (e.g. if it may have leaked):

1. In Vanguard: **Admin ▾ → Ingress API (IronNode) → Regenerate key**. The old
   key stops working immediately.
2. Copy the new key.
3. In IronNode: **Settings → Synapse-Vanguard SIEM forwarder**, paste the new key
   into the **API key** field, **Test connection**, **Save**.

**To stop the feed entirely**, do either:
- In Vanguard, toggle the Ingress API **off** (rejects all pushes), **or**
- In IronNode, toggle **Forward incidents to Vanguard** **off** (stops sending).

The key stays stored in both apps until you overwrite it, so you can pause and
resume without re-entering anything.

---

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| Test says **"Rejected: invalid or disabled API key"** (HTTP 401) | The key is wrong or Vanguard's Ingress API is toggled off. Re-copy the key from Vanguard; make sure the Ingress API is **enabled**. |
| Test says **"Connection failed"** or a timeout | IronNode can't reach the URL. Check the host/port, that Vanguard is running, and that a firewall isn't blocking port **5500**. |
| Test says **HTTP 404** | The URL is wrong — it must end in `/v1/ingest/events`. |
| Saved but **no events in Vanguard** | Confirm the **Forward incidents** toggle is on in IronNode, that incidents are actually being raised, and search Vanguard for source type `ironnode` (not a host filter). |
| **"Forbidden — 3rd Line Analyst or above required"** | Your IronNode account lacks the `INTEGRATION_MANAGE` capability. Ask an administrator to raise your rank or configure it for you. |
| Events appear but severity looks off | See [How severity maps](#how-severity-maps) — IronNode 1–10 is inverted to Vanguard's 0–7 scale. |

---

## Reference — the API (for advanced/manual use)

Any external system can push events with the same key, not just IronNode.

**Endpoint**

```
POST http://<vanguard-host>:5500/v1/ingest/events
Authorization: Bearer <svg_… API key>
Content-Type: application/json
```

**Body**

```json
{
  "events": [
    {
      "ts": "2026-07-03T10:00:00Z",
      "host": "synapse-ironnode",
      "message": "Incident TRIGGERED — Brute Force (severity 9/10)",
      "severity": 1,
      "category": "incident",
      "mitre_technique": "T1110",
      "fields": { "incident_id": "i-123", "status": "TRIGGERED" }
    }
  ]
}
```

- `severity` is the syslog scale **0–7** (0 = emergency). Omit it to default to INFO.
- All fields except `message` are optional; unknown keys can go under `fields`.
- An **empty** `{"events": []}` body is a valid connection probe (returns
  `{"accepted": 0}` with a good key, `401` with a bad one).

**Response**

```json
{ "accepted": 1 }
```

Max 5000 events per request.