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..ef135b76 --- /dev/null +++ b/flowtriq/README.md @@ -0,0 +1,46 @@ +# Flowtriq Agent + +## From the [Flowtriq](https://flowtriq.com) website + +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 | +|----------|-----------| +| CPU | 1 core | +| RAM | 256 MB | +| Disk | 500 MB | + +## Server Ports + +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 | 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 new file mode 100644 index 00000000..5961570c --- /dev/null +++ b/flowtriq/egg-flowtriq.json @@ -0,0 +1,87 @@ +{ + "_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": "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": "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}", + "logs": "{}", + "stop": "^C" + }, + "scripts": { + "installation": { + "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" + } + }, + "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": "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.", + "env_variable": "FTAGENT_API_BASE", + "default_value": "https://flowtriq.com/api/v1", + "user_viewable": true, + "user_editable": true, + "rules": [ + "required", + "string" + ], + "sort": 4 + } + ] +}