Skill: jacob-masse/flowtriq (version 1.0.0)

--- name: flowtriq-monitor description: > Monitor and manage Flowtriq DDoS detection in real time using the Flowtriq API. Use this skill whenever the user asks about active attacks, node status, incident history, traffic metrics, PCAP captures, agent config, or mitigation status on their Flowtriq-monitored infrastructure. Triggers on phrases like "check my nodes", "any attacks", "what's hitting my server", "show incidents", "is anything under attack", "flowtriq status", "check traffic", "pull my incidents", or any mention of Flowtriq combined with monitoring, alerts, status, or traffic. Requires FLOWTRIQ_API_KEY and FLOWTRIQ_NODE_UUID env vars. metadata: openclaw: requires: env: - FLOWTRIQ_API_KEY - FLOWTRIQ_NODE_UUID --- # Flowtriq Monitor Skill This skill lets you monitor your Flowtriq-protected infrastructure directly from your OpenClaw agent. Ask natural language questions and the agent will query the Flowtriq API and interpret the results for you. **Base URL:** `https://flowtriq.com` **Auth headers required on all agent endpoints:** ``` Authorization: Bearer $FLOWTRIQ_API_KEY X-Node-UUID: $FLOWTRIQ_NODE_UUID ``` --- ## What You Can Ask - "Are any of my nodes under attack right now?" - "What's the current traffic on my server?" - "Show me recent incidents" - "What was the peak PPS in the last attack?" - "Is my agent online?" - "Pull my node config and thresholds" - "Any IOC matches recently?" --- ## API Calls Reference ### Check Agent Health / Node Status ``` GET https://flowtriq.com/api/health ``` No auth needed. Returns `{ "status": "ok" }`. Use this first to confirm the Flowtriq platform is reachable before making authenticated calls. --- ### Get Node Config + Current Thresholds ``` GET https://flowtriq.com/api/v1/agent/config Headers: Authorization + X-Node-UUID ``` Returns the node's current PPS threshold, baseline stats (p99, mean), loaded IOC patterns, and any pending commands queued for the agent. Key fields to surface to the user: - `pps_threshold` — what PPS level triggers an incident - `baseline.p99_pps` — the node's normal p99 traffic level - `baseline.mean_pps` — average baseline - `ioc_patterns` — count how many are loaded - `pending_commands` — flag any that exist, user may want to review --- ### Get Latest Metrics (Current Traffic) ``` POST https://flowtriq.com/api/v1/agent/metrics Headers: Authorization + X-Node-UUID ``` The agent POSTs metrics to this endpoint every second. To read current traffic state, use the dashboard API. Since the dashboard endpoints require session auth, instruct the user to check `https://flowtriq.com/dashboard` for a live view, or pull from config endpoint for baseline context. --- ### Submit / Check Incidents ``` POST https://flowtriq.com/api/v1/agent/incident Headers: Authorization + X-Node-UUID ``` The agent uses this to open and update incidents. When interpreting incident data returned or confirmed by the user, extract and explain: | Field | What to tell the user | |---|---| | `attack_family` | Plain English: "UDP flood", "SYN flood", etc. | | `severity` | Low / Medium / High / Critical | | `peak_pps` | "peaked at X packets per second" | | `peak_bps` | Convert to Gbps/Mbps for readability | | `source_ip_count` | "came from X unique source IPs" | | `geo_breakdown` | Top countries by volume | | `ioc_matches` | Named botnet/pattern matches | | `spoofing_detected` | Warn user if true | | `botnet_detected` | Warn user if true | **Attack family plain-English map:** - `udp_flood` = UDP Flood - `syn_flood` = SYN Flood - `http_flood` = HTTP Flood - `icmp_flood` = ICMP/Ping Flood - `dns_flood` = DNS Amplification - `multi_vector` = Multi-Vector (combined attack types) - `unknown` = Unclassified **Severity guidance:** - `low` = below 2x baseline, informational - `medium` = 2-5x baseline, monitor closely - `high` = 5-20x baseline, mitigation likely active - `critical` = 20x+ baseline, full response mode --- ### Register a New Node (if user asks) ``` POST https://flowtriq.com/api/deploy Headers: [REDACTED_SECRET] Body: { "name": "node-name", "ip": "x.x.x.x" } ``` Note: this uses a **deploy token** not the node API key. The user must provide their deploy token separately. Returns a new `node_uuid` and `api_key` for the registered node. --- ## Interpreting Results for the User Always translate raw API data into plain NOC-style summaries. Example patterns: **All clear:** > "Your node is online. Baseline p99 is 12,000 PPS, threshold set at > 50,000 PPS. No active incidents. 8 IOC patterns loaded." **Active attack:** > "Active incident on [node]. SYN flood, critical severity. Peaked at > 47,821 PPS (1.7 Gbps). 3,241 source IPs, spoofing detected. IOC match: > mirai-variant (94% confidence). Mitigation should be active — check your > dashboard for FlowSpec rule status." **Degraded / agent offline:** > "The Flowtriq platform is reachable but your node hasn't sent a heartbeat > recently. Your agent may be down. Run `sudo systemctl status ftagent` on > the server to check." --- ## Error Handling | HTTP | Meaning | Tell the user | |---|---|---| | 401 | Bad API key | "Your API key looks wrong or expired. Rotate it in the Flowtriq dashboard." | | 402 | Payment issue | "Your Flowtriq subscription may have lapsed. Check billing." | | 409 | Duplicate node name | "A node with that name already exists in your workspace." | | 400 | Missing fields | Show which fields are missing and ask user to provide them | | 5xx | Platform error | "Flowtriq returned a server error. Check https://flowtriq.com/status for outages." | --- ## Setup Reminder (if user hasn't configured env vars) If `FLOWTRIQ_API_KEY` or `FLOWTRIQ_NODE_UUID` are missing, tell the user: > "To use this skill you need two environment variables set in OpenClaw: > - `FLOWTRIQ_API_KEY` — find this in your Flowtriq dashboard under > Settings > API Keys > - `FLOWTRIQ_NODE_UUID` — find this on your node's settings page > > Add them to your OpenClaw env config and reload the agent." --- ## Reference Files - `references/attack-types.md` — detailed breakdown of all 8 attack families, what causes them, and recommended responses - `references/api-endpoints.md` — full endpoint reference with all parameters for quick lookup during complex tasks

path: references/api-endpoints.md
content: # Flowtriq API Endpoints Reference

Base URL: `https://flowtriq.com`
All timestamps UTC ISO 8601. All responses JSON.

---

## Authentication

**Node API endpoints** (`/api/v1/agent/*`) require both headers:
```
[REDACTED_SECRET]
X-Node-UUID: YOUR_NODE_UUID
```

**Deploy endpoint** (`/api/deploy`) uses a workspace deploy token:
```
[REDACTED_SECRET]
```

**Health check** requires no auth.

---

## Platform Health

### GET /api/health
No auth. Returns `{ "status": "ok" }`. Use to check platform reachability.

---

## Deploy API

### POST /api/deploy
Register a new node.

**Headers:** `[REDACTED_SECRET]`

**Body:**
```json
{
  "name": "node-display-name",   // required
  "ip": "203.0.113.10",          // required
  "location": "nyc-1",           // optional
  "os": "Ubuntu 22.04",          // optional
  "interface": "eth0"            // optional, default eth0
}
```

**Response 200:**
```json
{
  "ok": true,
  "node_uuid": "a1b2c3d4-...",
  "api_key": "64-char-hex",
  "name": "node-display-name",
  "ip": "203.0.113.10"
}
```

**Errors:**
- `401` Bad deploy token
- `400` Missing name or IP
- `402` No active subscription
- `409` Node name already exists

---

## Agent API

All endpoints below: `POST/GET https://flowtriq.com/api/v1/agent/{endpoint}`
All require `Authorization` + `X-Node-UUID` headers.

---

### POST /v1/agent/heartbeat
Sent by ftagent every 30 seconds.

**Body:**
```json
{
  "agent_version": "1.2.3",
  "uptime": 86400,
  "os": "Ubuntu 22.04"
}
```

---

### POST /v1/agent/metrics
Sent by ftagent every second with current traffic data.

**Body:**
```json
{
  "pps": 12400,
  "bps": 430000000,
  "tcp_pct": 62.3,
  "udp_pct": 35.1,
  "icmp_pct": 2.6,
  "conn_count": 1840,
  "recorded_at": "2026-03-15T09:44:18Z"
}
```

---

### POST /v1/agent/incident
Opens or updates an active incident.

**Body:**
```json
{
  "attack_family": "syn_flood",
  "severity": "high",
  "peak_pps": 47821,
  "peak_bps": 1700000000,
  "protocol_breakdown": { "tcp": 15.2, "udp": 82.1, "icmp": 2.7 },
  "tcp_flag_breakdown": { "SYN": 1200, "ACK": 400, "RST": 50 },
  "geo_breakdown": { "US": 4200, "CN": 1800, "RU": 920 },
  "source_ip_count": 3241,
  "top_src_ips": [
    { "ip": "1.2.3.4", "count": 5000 }
  ],
  "top_dst_ports": [
    { "port": 80, "count": 12000 }
  ],
  "ioc_matches": ["mirai-variant"],
  "spoofing_detected": true,
  "botnet_detected": true
}
```

**Attack families:** `udp_flood` `syn_flood` `http_flood` `icmp_flood`
`dns_flood` `multi_vector` `unknown`

**Severity levels:** `low` `medium` `high` `critical`

---

### POST /v1/agent/pcap
Upload a PCAP file. Multipart form, max 50 MB.

**Form fields:**
- `incident_id` (integer, required)
- `file` (PCAP file, required)

---

### GET /v1/agent/config
Returns node config, IOC patterns, and pending commands.

**Response 200:**
```json
{
  "node_id": 1,
  "pps_threshold": 50000,
  "baseline": {
    "p99_pps": 12000,
    "mean_pps": 3400
  },
  "ioc_patterns": [
    { "id": 1, "name": "mirai-variant", "protocol": "udp" }
  ],
  "pending_commands": [
    { "id": 5, "command": "iptables -I INPUT -s 1.2.3.4 -j DROP" }
  ]
}
```

---

## Rate Limits

See `https://flowtriq.com/docs?section=rate-limits` for current limits.
Standard node API endpoints are designed for high-frequency agent use and
are not rate-limited for normal agent traffic. Direct API use from external
tooling may be subject to limits.

---

## Error Codes

| Code | Meaning |
|---|---|
| 400 | Bad request, missing or invalid parameters |
| 401 | Invalid or missing API key / deploy token |
| 402 | Payment failed or subscription lapsed |
| 409 | Conflict (e.g. duplicate node name) |
| 500+ | Platform error, check https://flowtriq.com/status |

Full error reference: `https://flowtriq.com/docs?section=errors`


path: references/attack-types.md
content: # Flowtriq Attack Types Reference

All 8 attack families Flowtriq classifies, with context on what they are,
what the traffic looks like, and recommended responses.

---

## UDP Flood (`udp_flood`)

**What it is:** High-volume UDP packets sent to random or specific ports to
saturate bandwidth or exhaust server resources.

**Traffic signature:** Sudden spike in UDP traffic, often targeting UDP/53
(DNS), UDP/123 (NTP), or random high ports. High BPS relative to PPS.

**IOC matches to watch for:** Generic UDP flood patterns, Mirai variants.

**Recommended response:**
- FlowSpec rate-limit on UDP if BGP is configured
- iptables drop rule on targeted port if specific port attack
- Check geo breakdown — UDP floods often originate from reflection sources

---

## SYN Flood (`syn_flood`)

**What it is:** Massive volume of TCP SYN packets to exhaust connection
state tables on the target server.

**Traffic signature:** Very high PPS, TCP flag breakdown shows SYN dominant
(80%+), low ACK count. `tcp_flag_breakdown.SYN` will be high.

**IOC matches to watch for:** SYN flood patterns, spoofed source IPs.

**Recommended response:**
- Enable SYN cookies on the server (`sysctl net.ipv4.tcp_syncookies=1`)
- FlowSpec rate-limit on TCP SYN flags
- Check `spoofing_detected` — SYN floods are commonly spoofed

---

## HTTP Flood (`http_flood`)

**What it is:** High volume of HTTP/HTTPS requests to overwhelm the web
application layer. Hard to distinguish from legitimate traffic at the
network layer.

**Traffic signature:** High request rate (req/s), TCP traffic, port 80/443
dominant in `top_dst_ports`. PPS may not be extreme but requests per second
will be high.

**Recommended response:**
- Rate limiting at load balancer or CDN level
- Cloudflare WAF rules if scrubbing is configured
- Review top source IPs for botnet patterns

---

## ICMP Flood (`icmp_flood`)

**What it is:** High-volume ICMP echo requests (ping flood) to consume
bandwidth.

**Traffic signature:** ICMP dominant in protocol breakdown. Often simple
and unsophisticated.

**Recommended response:**
- iptables drop ICMP at the node level
- FlowSpec ICMP rate-limit

---

## DNS Amplification (`dns_flood`)

**What it is:** Reflection/amplification attack using misconfigured open
DNS resolvers to bounce large UDP responses at the target.

**Traffic signature:** Very high BPS relative to PPS (amplification ratio
can be 50x+). Inbound traffic appears to come from legitimate DNS server
IPs. UDP/53 dominant.

**IOC matches to watch for:** DNS amplification patterns, known open
resolver IP ranges.

**Recommended response:**
- FlowSpec rate-limit on UDP/53
- Verify you don't have an open DNS resolver yourself
  (`flowtriq.com/tools/dns-resolver-checker`)
- Source IPs will be legitimate resolvers — blocking them is a last resort

---

## Multi-Vector (`multi_vector`)

**What it is:** Simultaneous attack combining two or more attack types.
Designed to overwhelm defences that are tuned for single-vector attacks.

**Traffic signature:** Mixed protocol breakdown, multiple attack families
detected at once. Flowtriq will show combined confidence scores.

**Recommended response:**
- Escalate to cloud scrubbing if BGP mitigation alone is insufficient
- Review each vector in the protocol breakdown separately
- Check if mitigation rules are addressing all vectors

---

## NTP Amplification (detected as `udp_flood` subtype)

**What it is:** UDP amplification using NTP monlist responses. Similar to
DNS amplification but via UDP/123.

**Traffic signature:** High BPS, UDP/123 dominant in destination ports.

**Recommended response:**
- FlowSpec rate-limit UDP/123
- Check NTP amplification exposure: `flowtriq.com/tools/ntp-amplification-checker`

---

## Unknown (`unknown`)

**What it is:** Traffic anomaly detected above threshold but doesn't match
any known attack signature.

**Recommended response:**
- Download the PCAP from the dashboard and inspect manually
- Use the Wireshark filter cheatsheet: `flowtriq.com/tools/wireshark-filters`
- Check IOC pattern list is up to date

---

## Severity Levels

| Severity | PPS Multiplier | Meaning |
|---|---|---|
| `low` | < 2x baseline | Probably noise or a probe. Monitor. |
| `medium` | 2-5x baseline | Real traffic anomaly. Watch for escalation. |
| `high` | 5-20x baseline | Active attack. Mitigation should be deploying. |
| `critical` | 20x+ baseline | Major attack. Check mitigation is active. Consider escalating to cloud scrubbing. |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)