> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitelshield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traffic analytics and attack forensics

> Use Orbitel Shield traffic analytics to inspect per-prefix telemetry, investigate attacks, and export events through the API. Covers live views, attack history, alert channels, and API authentication.

Orbitel Shield traffic analytics shows what arrives for each of your prefixes, what the edge drops and why, and the clean traffic that reaches you. The panel refreshes every ten seconds, and every attack is recorded with its peak, flows, vectors, and whether it was a pulse wave. You can also pull the same data into your own dashboards and on-call tools through the API.

This page explains how to read the live traffic view, investigate an attack, set up alerts, and query the API safely.

## Live per-prefix telemetry

Every prefix gets its own live view, built from the reports of every scrubbing node that carries it. The panel aggregates those reports into a single view you can read at a glance.

### What the panel shows for each prefix

| Metric | What it means |
| - | - |
| **Offered** | All traffic that arrived at the edge for the prefix |
| **Dropped** | Traffic the edge blocked, with the guard or rule that stopped it |
| **Delivered** | Clean traffic that passed through and reached your network |
| **Challenged** | A separate traffic category listed by the panel; the public page does not define its exact accounting |
| **Flows** | Number of distinct flows seen and dropped, which helps describe the distribution of traffic |
| **Peak** | The highest rate observed in the current window |

### Peaks, not averages

Graphs plot the peak in every interval, so a ten-second burst still shows up in the 24-hour view. This matters because short spikes can be hidden by averaging, and you need to see the real load the edge handled.

### Every node, added up

Each scrubbing node reports in, and the numbers you see add all of them together. You do not need to sum node counts yourself.

### Attack status at a glance

Each prefix shows whether it is under attack right now and how many attacks it has seen in the current window.

### Time windows and refresh

The panel refreshes every ten seconds. You can choose the window you want to see:

| Window | Use case |
| - | - |
| **1 hour** | Spotting a current attack or verifying recent changes |
| **6 hours** | Reviewing the morning or afternoon pattern |
| **24 hours** | Daily summary and shift handoff |

**1. Open the traffic panel**

Sign in to the [Orbitel Shield portal](https://portal.orbitelshield.com/login), go to **Analytics**, and select the prefix you want to inspect.

**2. Choose a window**

Pick 1h, 6h, or 24h from the window selector. The graph and totals update.

**3. Read the breakdown**

Look at offered, dropped, delivered, and challenged. If dropped is high, open the attack record or the vector breakdown to see which guard handled it.

**4. Check flows**

Compare flows seen versus flows dropped. Flow counts describe the distribution of traffic but do not by themselves diagnose a specific attack vector.

## Forensics for every attack

When something hits, you get more than a spike on a graph. Each attack is recorded as an event you can take apart.

### Attack record fields

| Field | What it tells you |
| - | - |
| **Started** | Timestamp when the attack began |
| **Ended** | Timestamp when the attack stopped, or ongoing if it has not |
| **Lasted** | Duration in minutes and seconds |
| **Peak** | Highest rate observed |
| **Flows** | Total flows seen during the attack |
| **Vectors** | Each vector used, with the share of the attack it represented and the guard that dropped it |
| **Pulse wave** | Flag set when the attack shows burst behavior, so you can tell one recurring attack from a string of separate floods |

### Vector breakdown example

The following table shows an illustrative example of how vector data may appear for an attack on `203.0.113.0/24`. Percentages and values are representative website data, not live telemetry:

| Vector | Guard | Share of attack |
| - | - | - |
| DNS reflection | Reflection guard | 61.4% |
| NTP reflection | Reflection guard | 22.7% |
| SYN flood | SYN flood guard | 10.9% |
| Crafted packets | Header checks | 3.8% |
| ICMP flood | ICMP guard | 1.2% |

This tells you the attack was mostly reflection-based, with a smaller direct flood component. You can use recorded vectors to decide whether to review reflection rules or add SYN flood tuning.

### Attack history

Every attack goes into your attack history with its start, end, peak, and vectors, so you can review later or pull from the API.

## Alerts and notifications

Your team should hear about an attack when it starts, not when a customer calls. Orbitel Shield supports up to ten alert channels, each with the events it should hear about.

### Supported channels

| Channel | How it works |
| - | - |
| **Email** | Sent to the addresses you configure |
| **Discord** | Posted to the channel you choose |
| **Slack** | Posted to the channel you choose |
| **Webhook** | Delivered to an HTTPS endpoint with an HMAC-SHA256 signature and timestamp |

### Alert events

You can choose which events each channel receives:

* Attack started
* Attack ended
* Mitigation changed
* Tunnel down

### Signed webhooks

Every webhook carries an HMAC-SHA256 signature with a timestamp, so your systems can check it came from Orbitel Shield. The source lists channels and HMAC timestamp but does not define a specific signing format or secret location.

**1. Open alert settings**

Review your alert-channel configuration in the panel, or ask your engineer where to configure it.

**2. Choose destination and events**

Select the channel type, enter the destination, and choose which events the channel should receive. You can send different events to different channels.

**3. Follow panel instructions or ask an engineer**

The portal shows the specific configuration steps for each channel type. If anything is unclear, ask an Orbitel Shield engineer for help.

## API access

Everything in the panel is also available through the API, so attacks can land in your own dashboards, tickets, and on-call tools.

### What the API returns

* Traffic per prefix, as time series
* Attack events with their vectors
* Full attack history

All responses are JSON over HTTPS.

### Authentication

API requests use a Bearer token in the Authorization header. You create and manage keys in the portal under **API keys**.

### Scoped keys, IP allowlists, and expiry

You can configure each key with the following limits:

* **Scopes**: Give each key only the permissions it needs. For example, a read-only monitoring key should not be able to change protection settings.
* **IP allowlists**: Restrict the key to requests from your own addresses.
* **Expiry**: Set the key to expire after a chosen date, so old keys do not stay active indefinitely.

### Example request

Replace `$ORBITEL_API` with the API address shown under **API keys** in the portal. Replace `$SERVICE` with your actual service identifier, which you can get from the panel or an engineer. Replace `$ORBITEL_API_KEY` with your key. Never print secrets in logs or share them in tickets.

```bash theme={null}
curl "$ORBITEL_API/protection/$SERVICE/analytics/events?window=24h" \
  -H "Authorization: Bearer $ORBITEL_API_KEY"
```

The response below is illustrative website data, not live telemetry:

```json theme={null}
{
  "events": {
    "window": "24h",
    "events": [
      {
        "prefix": "203.0.113.0/24",
        "started_at": "2026-11-08T14:07:12Z",
        "seconds": 277,
        "peak_pps": 3104000,
        "flows": 182400,
        "pulse": true,
        "vectors": [
          { "reflection": "dns", "flows": 120400, "dropped": 512340000 },
          { "syn_flood": "tcp", "flows": 30100, "dropped": 90770000 }
        ]
      }
    ]
  }
}
```

> [!NOTE]
>
> The exact API address for your account is shown in the portal under **API keys**. Use that address in place of `$ORBITEL_API`. Never hardcode secrets into scripts; load them from environment variables or a secrets manager.

## Practical attack investigation workflow

When you see an alert or a spike in the panel, follow this workflow to understand what happened and whether you need to act.

**1. Confirm the prefix and window**

Open the traffic panel, select the affected prefix, and set the window to 1h. Check whether the spike is still active or has ended.

**2. Compare offered, dropped, and delivered**

Review how much traffic the edge drops and how much it delivers. Compare the graphs against actual application availability; a high dropped percentage alone does not prove legitimate users are unaffected.

**3. Open the attack record**

Click the attack in the history or the live view. Read the peak, duration, and whether it is flagged as a pulse wave.

**4. Read the vector breakdown**

Identify which guards dropped the traffic. Large reflection shares may mean open resolvers or NTP servers are being abused. Large SYN or ACK shares may mean a direct flood.

**5. Check flows**

Flow counts describe the distribution of traffic. Use them alongside recorded vectors to understand the attack pattern, not as a definitive diagnosis.

**6. Decide whether to tune**

If the same vector repeats, you may want to review the relevant guard or add a custom rule. If you suspect legitimate traffic is affected, review the configuration with an engineer rather than tightening rules based only on dropped percentages.

**7. Pull the API record for your SIEM**

Use the API to fetch the event and store it in your own systems for long-term analysis and reporting.

## Troubleshooting

> [accordion] The panel shows no data for my prefix
>
> Make sure the prefix is announced and carried by at least one scrubbing node. If the issue persists, open a support ticket at [portal support](https://portal.orbitelshield.com/support/new).

> [accordion] An attack shows in history but not in the live graph
>
> The live graph covers only the selected window (1h, 6h, or 24h). If the attack ended before the window started, it will appear in history but not on the graph. Use the API to fetch older events.

> [accordion] Webhook signatures fail verification
>
> Check that you are using the correct secret for that channel. Verify that the timestamp in the signature is recent. The source lists HMAC-SHA256 with timestamp but does not define a specific signing format.

> [accordion] API requests return an error
>
> Confirm the key is active, has not expired, and is scoped for the endpoint you are calling. Check that the request originates from an allowed address if you configured an IP allowlist.

> [accordion] Alerts are not arriving
>
> Check that the channel is enabled and that the correct events are selected. For Discord and Slack, verify the integration configuration. For webhooks, check that your endpoint is reachable from the internet.

## Frequently asked questions

> [accordion] How fresh is the data?
>
> The panel refreshes every ten seconds, and an attack shows up while it is still going, not only once it has ended.

> [accordion] How far back can I look?
>
> The traffic graphs cover the last hour, six hours, or day. Every attack is also kept in your attack history, so you can look back further than that through the history view or the API.

> [accordion] Can I get the data into my own monitoring?
>
> Yes. The API returns the same traffic, attack, and history data as the panel, as JSON, with keys you can scope, limit to your own addresses, and set to expire.

> [accordion] Where can alerts go?
>
> Email, Discord, Slack, or any HTTPS webhook. You can set up to ten channels and choose which events each one hears about.

> [accordion] Are analytics included in my plan?
>
> Yes. Every plan includes live analytics, attack history, alerts, and the API, at no extra cost.

## Next steps

> [card] [Network protection](https://docs.orbitelshield.com/protection/network.md)
>
> Configure always-on BGP scrubbing for your IP ranges.

> [card] [Application protection](https://docs.orbitelshield.com/protection/application.md)
>
> Set up Layer 7 filtering, rate limits, and bot defense.

> [card] [Protected tunnels](https://docs.orbitelshield.com/protection/tunnels.md)
>
> Deliver clean traffic over GRE or WireGuard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.