From 2f055ab2c133d5fe8be4ba579b55f264987ac72e Mon Sep 17 00:00:00 2001 From: Jacob Masse Date: Tue, 4 Aug 2026 15:22:40 -0400 Subject: [PATCH 1/4] Add Flowtriq Agent egg Network traffic monitoring and DDoS detection agent that reports to the Flowtriq dashboard. Installs via pip, runs as a Python module, and monitors traffic volume using /proc/net/dev. --- README.md | 4 +++ flowtriq/README.md | 29 +++++++++++++++ flowtriq/egg-flowtriq.json | 73 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+) create mode 100644 flowtriq/README.md create mode 100644 flowtriq/egg-flowtriq.json diff --git a/README.md b/README.md index f5d416bc..be569e6b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Monitoring +## Flowtriq Agent + +* [Flowtriq Agent](/flowtriq) + ## Loki * [Loki](/loki) diff --git a/flowtriq/README.md b/flowtriq/README.md new file mode 100644 index 00000000..2b2cf5d2 --- /dev/null +++ b/flowtriq/README.md @@ -0,0 +1,29 @@ +# Flowtriq Agent + +## From the [Flowtriq](https://flowtriq.com) website + +Real-time network traffic monitoring and DDoS detection agent. Monitors inbound and outbound traffic, detects volumetric attacks, and reports to your Flowtriq dashboard for alerting and incident management. + +## Requirements + +You need a Flowtriq account to use this egg. Sign up at [flowtriq.com](https://flowtriq.com) and create a node in your dashboard to get an API key and Node UUID. + +## Minimum Resources + +| Resource | Minimum | +|----------|-----------| +| CPU | 1 core | +| RAM | 256 MB | +| Disk | 500 MB | + +## Server Ports + +The agent does not require any exposed ports. It connects outbound to the Flowtriq API over HTTPS. + +## Variables + +| Variable | Description | Required | +|-------------------|---------------------------------------------------------------------|----------| +| API Key | Your Flowtriq API key from the dashboard | Yes | +| Node UUID | The UUID for this node, created in your Flowtriq dashboard | Yes | +| API Base URL | API endpoint (only change for self-hosted instances) | Yes | diff --git a/flowtriq/egg-flowtriq.json b/flowtriq/egg-flowtriq.json new file mode 100644 index 00000000..235becdc --- /dev/null +++ b/flowtriq/egg-flowtriq.json @@ -0,0 +1,73 @@ +{ + "_comment": "DO NOT EDIT: FILE GENERATED AUTOMATICALLY BY PANEL", + "meta": { + "version": "PLCN_v2", + "update_url": null + }, + "exported_at": "2026-08-04T19:00:00+00:00", + "name": "Flowtriq Agent", + "author": "jacob@traztech.ca", + "uuid": "210550da-2475-4238-832b-c27840da2c11", + "description": "Real-time network traffic monitoring and DDoS detection agent. Monitors traffic volume, detects attacks, and reports to your Flowtriq dashboard.", + "tags": [], + "features": [], + "docker_images": { + "ghcr.io/parkervcp/yolks:python_3.12": "ghcr.io/parkervcp/yolks:python_3.12" + }, + "file_denylist": [], + "startup": "PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", + "config": { + "files": "{}", + "startup": "{\n \"done\": \"Entering main monitoring loop\"\n}", + "logs": "{}", + "stop": "^C" + }, + "scripts": { + "installation": { + "script": "#!/bin/bash\ncd /mnt/server\npip install --target /mnt/server ftagent\ncat > /mnt/server/config.json << ENDCFG\n{\"api_key\": \"${FTAGENT_API_KEY}\", \"node_uuid\": \"${FTAGENT_NODE_UUID}\", \"api_base\": \"${FTAGENT_API_BASE}\", \"pcap_enabled\": false}\nENDCFG\necho \"Installation complete\"", + "container": "ghcr.io/parkervcp/yolks:python_3.12", + "entrypoint": "bash" + } + }, + "variables": [ + { + "name": "API Key", + "description": "Your Flowtriq API key. Found in your dashboard under Settings.", + "env_variable": "FTAGENT_API_KEY", + "default_value": "", + "user_viewable": true, + "user_editable": true, + "rules": [ + "required", + "string" + ], + "sort": 1 + }, + { + "name": "Node UUID", + "description": "The UUID for this node. Create a node in your Flowtriq dashboard to get one.", + "env_variable": "FTAGENT_NODE_UUID", + "default_value": "", + "user_viewable": true, + "user_editable": true, + "rules": [ + "required", + "string" + ], + "sort": 2 + }, + { + "name": "API Base URL", + "description": "Flowtriq API endpoint. Only change this if you are running a self-hosted instance.", + "env_variable": "FTAGENT_API_BASE", + "default_value": "https://flowtriq.com/api/v1", + "user_viewable": true, + "user_editable": true, + "rules": [ + "required", + "string" + ], + "sort": 3 + } + ] +} \ No newline at end of file From 143280a194057d878106fa8f25236f71fcc47614 Mon Sep 17 00:00:00 2001 From: Jacob Masse Date: Tue, 4 Aug 2026 16:23:33 -0400 Subject: [PATCH 2/4] Switch to flow collector mode, use SERVER_PORT allocation Addresses review feedback: containerized ftagent can only see its own /proc/net/dev, not the host's network stats. Switched to flow collector mode where the agent receives sFlow/NetFlow/IPFIX from network equipment instead of monitoring local traffic. Changes: - Config written at startup using {{SERVER_PORT}} for the flow port - flow_enabled=true, pcap_enabled=false in config - Added flow protocol variable (auto/sflow/netflow_v5/netflow_v9/ipfix) - Removed FTAGENT_FLOW_PORT variable (uses Pelican port allocation) - Updated description and README for flow collector use case --- flowtriq/README.md | 31 ++++++++++++++++++++++++------- flowtriq/egg-flowtriq.json | 24 +++++++++++++++++++----- 2 files changed, 43 insertions(+), 12 deletions(-) diff --git a/flowtriq/README.md b/flowtriq/README.md index 2b2cf5d2..ef135b76 100644 --- a/flowtriq/README.md +++ b/flowtriq/README.md @@ -2,12 +2,16 @@ ## From the [Flowtriq](https://flowtriq.com) website -Real-time network traffic monitoring and DDoS detection agent. Monitors inbound and outbound traffic, detects volumetric attacks, and reports to your Flowtriq dashboard for alerting and incident management. +DDoS detection agent running in flow collector mode. Receives sFlow, NetFlow v5/v9, or IPFIX exports from your router or switch and reports to your Flowtriq dashboard for alerting and incident management. + +This egg runs the agent as a flow collector, not as a local traffic monitor. It listens on the server's primary port for incoming flow data from your network equipment. The agent parses the flows, builds traffic baselines, detects volumetric attacks, and reports to your dashboard. ## Requirements You need a Flowtriq account to use this egg. Sign up at [flowtriq.com](https://flowtriq.com) and create a node in your dashboard to get an API key and Node UUID. +Your router or switch must support sFlow, NetFlow v5/v9, or IPFIX export. Configure it to send flows to this server's IP on the allocated port. + ## Minimum Resources | Resource | Minimum | @@ -18,12 +22,25 @@ You need a Flowtriq account to use this egg. Sign up at [flowtriq.com](https://f ## Server Ports -The agent does not require any exposed ports. It connects outbound to the Flowtriq API over HTTPS. +The flow collector listens on the server's primary allocated port (UDP). Set your allocation port to 2055 for NetFlow, 6343 for sFlow, or 4739 for IPFIX. + +| Port | default | protocol | +|-------------------|---------|----------| +| Flow collector | 2055 | UDP | ## Variables -| Variable | Description | Required | -|-------------------|---------------------------------------------------------------------|----------| -| API Key | Your Flowtriq API key from the dashboard | Yes | -| Node UUID | The UUID for this node, created in your Flowtriq dashboard | Yes | -| API Base URL | API endpoint (only change for self-hosted instances) | Yes | +| Variable | Description | Default | Required | +|-------------------|---------------------------------------------------------------------|----------|----------| +| API Key | Your Flowtriq API key from the dashboard | | Yes | +| Node UUID | The UUID for this node, created in your Flowtriq dashboard | | Yes | +| Flow Protocol | auto, sflow, netflow_v5, netflow_v9, or ipfix | auto | Yes | +| API Base URL | API endpoint (only change for self-hosted instances) | https://flowtriq.com/api/v1 | Yes | + +## How It Works + +1. Pelican allocates a port for this server (e.g. 2055) +2. The agent starts and listens on that port for incoming flow data +3. Configure your router/switch to export flows to this server's IP and port +4. The agent parses flows, learns traffic baselines, and detects attacks +5. Incidents and traffic stats appear in your Flowtriq dashboard diff --git a/flowtriq/egg-flowtriq.json b/flowtriq/egg-flowtriq.json index 235becdc..92f0eb88 100644 --- a/flowtriq/egg-flowtriq.json +++ b/flowtriq/egg-flowtriq.json @@ -8,14 +8,14 @@ "name": "Flowtriq Agent", "author": "jacob@traztech.ca", "uuid": "210550da-2475-4238-832b-c27840da2c11", - "description": "Real-time network traffic monitoring and DDoS detection agent. Monitors traffic volume, detects attacks, and reports to your Flowtriq dashboard.", + "description": "DDoS detection agent running in flow collector mode. Receives sFlow, NetFlow v5/v9, or IPFIX from your router or switch and reports to your Flowtriq dashboard.", "tags": [], "features": [], "docker_images": { "ghcr.io/parkervcp/yolks:python_3.12": "ghcr.io/parkervcp/yolks:python_3.12" }, "file_denylist": [], - "startup": "PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", + "startup": "echo '{\"api_key\":\"{{FTAGENT_API_KEY}}\",\"node_uuid\":\"{{FTAGENT_NODE_UUID}}\",\"api_base\":\"{{FTAGENT_API_BASE}}\",\"pcap_enabled\":false,\"flow_enabled\":true,\"flow_protocol\":\"{{FTAGENT_FLOW_PROTOCOL}}\",\"flow_port\":{{SERVER_PORT}},\"flow_bind\":\"0.0.0.0\"}' > /home/container/config.json && PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", "config": { "files": "{}", "startup": "{\n \"done\": \"Entering main monitoring loop\"\n}", @@ -24,7 +24,7 @@ }, "scripts": { "installation": { - "script": "#!/bin/bash\ncd /mnt/server\npip install --target /mnt/server ftagent\ncat > /mnt/server/config.json << ENDCFG\n{\"api_key\": \"${FTAGENT_API_KEY}\", \"node_uuid\": \"${FTAGENT_NODE_UUID}\", \"api_base\": \"${FTAGENT_API_BASE}\", \"pcap_enabled\": false}\nENDCFG\necho \"Installation complete\"", + "script": "#!/bin/bash\ncd /mnt/server\npip install --target /mnt/server ftagent\necho \"Installation complete\"", "container": "ghcr.io/parkervcp/yolks:python_3.12", "entrypoint": "bash" } @@ -56,6 +56,20 @@ ], "sort": 2 }, + { + "name": "Flow Protocol", + "description": "Which flow protocol to listen for. Set to auto to accept any, or choose sflow, netflow_v5, netflow_v9, or ipfix.", + "env_variable": "FTAGENT_FLOW_PROTOCOL", + "default_value": "auto", + "user_viewable": true, + "user_editable": true, + "rules": [ + "required", + "string", + "in:auto,sflow,netflow_v5,netflow_v9,ipfix" + ], + "sort": 3 + }, { "name": "API Base URL", "description": "Flowtriq API endpoint. Only change this if you are running a self-hosted instance.", @@ -67,7 +81,7 @@ "required", "string" ], - "sort": 3 + "sort": 4 } ] -} \ No newline at end of file +} From c361f82a547f725abd4b2a4cbb4f9278eca40506 Mon Sep 17 00:00:00 2001 From: Jacob Masse Date: Wed, 5 Aug 2026 12:12:33 -0400 Subject: [PATCH 3/4] Move config generation from startup to panel config.files Install script now creates a base config.json, and the panel manages variable injection via the JSON parser on each start. --- flowtriq/egg-flowtriq.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/flowtriq/egg-flowtriq.json b/flowtriq/egg-flowtriq.json index 92f0eb88..e57314cb 100644 --- a/flowtriq/egg-flowtriq.json +++ b/flowtriq/egg-flowtriq.json @@ -15,16 +15,16 @@ "ghcr.io/parkervcp/yolks:python_3.12": "ghcr.io/parkervcp/yolks:python_3.12" }, "file_denylist": [], - "startup": "echo '{\"api_key\":\"{{FTAGENT_API_KEY}}\",\"node_uuid\":\"{{FTAGENT_NODE_UUID}}\",\"api_base\":\"{{FTAGENT_API_BASE}}\",\"pcap_enabled\":false,\"flow_enabled\":true,\"flow_protocol\":\"{{FTAGENT_FLOW_PROTOCOL}}\",\"flow_port\":{{SERVER_PORT}},\"flow_bind\":\"0.0.0.0\"}' > /home/container/config.json && PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", + "startup": "PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", "config": { - "files": "{}", + "files": "{\r\n \"config.json\": {\r\n \"parser\": \"json\",\r\n \"find\": {\r\n \"api_key\": \"{{server.build.env.FTAGENT_API_KEY}}\",\r\n \"node_uuid\": \"{{server.build.env.FTAGENT_NODE_UUID}}\",\r\n \"api_base\": \"{{server.build.env.FTAGENT_API_BASE}}\",\r\n \"flow_protocol\": \"{{server.build.env.FTAGENT_FLOW_PROTOCOL}}\",\r\n \"flow_port\": \"{{server.build.default.port}}\"\r\n }\r\n }\r\n}", "startup": "{\n \"done\": \"Entering main monitoring loop\"\n}", "logs": "{}", "stop": "^C" }, "scripts": { "installation": { - "script": "#!/bin/bash\ncd /mnt/server\npip install --target /mnt/server ftagent\necho \"Installation complete\"", + "script": "#!/bin/bash\ncd /mnt/server\npip install --target /mnt/server ftagent\ncat > /mnt/server/config.json <<'EOF'\n{\"api_key\":\"\",\"node_uuid\":\"\",\"api_base\":\"https://flowtriq.com/api/v1\",\"pcap_enabled\":false,\"flow_enabled\":true,\"flow_protocol\":\"auto\",\"flow_port\":2055,\"flow_bind\":\"0.0.0.0\"}\nEOF\necho \"Installation complete\"", "container": "ghcr.io/parkervcp/yolks:python_3.12", "entrypoint": "bash" } From 25169b193ff52f52080d08079b9aedcde461236c Mon Sep 17 00:00:00 2001 From: Jacob Masse Date: Wed, 5 Aug 2026 12:58:20 -0400 Subject: [PATCH 4/4] Drop PYTHONPATH, cd into container dir instead python -m adds cwd to sys.path, so cd /home/container is enough for Python to find the ftagent package. --- flowtriq/egg-flowtriq.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flowtriq/egg-flowtriq.json b/flowtriq/egg-flowtriq.json index e57314cb..5961570c 100644 --- a/flowtriq/egg-flowtriq.json +++ b/flowtriq/egg-flowtriq.json @@ -15,7 +15,7 @@ "ghcr.io/parkervcp/yolks:python_3.12": "ghcr.io/parkervcp/yolks:python_3.12" }, "file_denylist": [], - "startup": "PYTHONPATH=/home/container /usr/local/bin/python -m ftagent --config /home/container/config.json", + "startup": "cd /home/container && python -m ftagent --config /home/container/config.json", "config": { "files": "{\r\n \"config.json\": {\r\n \"parser\": \"json\",\r\n \"find\": {\r\n \"api_key\": \"{{server.build.env.FTAGENT_API_KEY}}\",\r\n \"node_uuid\": \"{{server.build.env.FTAGENT_NODE_UUID}}\",\r\n \"api_base\": \"{{server.build.env.FTAGENT_API_BASE}}\",\r\n \"flow_protocol\": \"{{server.build.env.FTAGENT_FLOW_PROTOCOL}}\",\r\n \"flow_port\": \"{{server.build.default.port}}\"\r\n }\r\n }\r\n}", "startup": "{\n \"done\": \"Entering main monitoring loop\"\n}",