{"id":31136735,"url":"https://github.com/vmxdev/xenoeye","last_synced_at":"2026-01-30T23:02:47.714Z","repository":{"id":41606239,"uuid":"160399783","full_name":"vmxdev/xenoeye","owner":"vmxdev","description":"Lightweight Netflow/IPFIX/sFlow collector and analyzer","archived":false,"fork":false,"pushed_at":"2026-01-23T07:16:29.000Z","size":4477,"stargazers_count":131,"open_issues_count":4,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-01-24T00:36:47.891Z","etag":null,"topics":["clickhouse","grafana","ipfix","netflow","netflow-analyzer","netflow-collector","postgresql","sflow"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-12-04T18:14:22.000Z","updated_at":"2026-01-23T07:16:33.000Z","dependencies_parsed_at":"2024-03-22T20:27:27.888Z","dependency_job_id":"7ef6e2ce-df6c-4e2b-8062-4171c6741f0f","html_url":"https://github.com/vmxdev/xenoeye","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vmxdev/xenoeye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmxdev%2Fxenoeye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmxdev%2Fxenoeye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmxdev%2Fxenoeye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmxdev%2Fxenoeye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmxdev","download_url":"https://codeload.github.com/vmxdev/xenoeye/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmxdev%2Fxenoeye/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28922232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T22:32:35.345Z","status":"ssl_error","status_checked_at":"2026-01-30T22:32:31.927Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","grafana","ipfix","netflow","netflow-analyzer","netflow-collector","postgresql","sflow"],"created_at":"2025-09-18T08:01:50.810Z","updated_at":"2026-01-30T23:02:47.694Z","avatar_url":"https://github.com/vmxdev.png","language":"C++","funding_links":[],"categories":["Integrations"],"sub_categories":["Metrics and Monitoring"],"readme":"# xenoeye\nLightweight Netflow/IPFIX/sFlow collector and analyzer\n\n[`README.ru.md`](README.ru.md) - документация на русском\n\nThe documentation is mostly translated automatically using Google translator, so if you see something weird - feel free to let us know.\n\nWith this collector you can\n\n  * Monitor traffic of IP networks, individual IP addresses or services\n  * React quickly to traffic spikes or traffic drops below thresholds\n  * Monitor traffic patterns and distribution of network packets using data from Netflow/IPFIX/sFlow\n\n\n## Key Features\n\n  * The collector was developed for medium and large networks, with different user groups that need different reports. For this purpose, \"monitoring objects\" are used. A monitoring object can be a network, a set of networks, an autonomous system, a geo-object or arbitrary network traffic that can be extracted from Netflow/IPFIX/sFlow.\n  * Using the collector, you can generate various reports, build charts, dashboards in Grafana, perform some actions when the traffic speed exceeds thresholds or falls below thresholds.\n  * We use the collector to monitor our networks. We are using Netflow v9 and IPFIX, so the collector supports them.\n  * Netflow v5 and sFlow are also supported.\n  * The documentation contains examples of building simple reports. To build more complex ones, you need at least basic knowledge of SQL.\n  * The collector uses text configuration files. This allows you to write simple configs manually, and for complex configurations with a large number of objects, you can generate configs using scripts.\n  * The collector processes data in two ways: it aggregates it over periods (fixed-size time windows to produce reports and graphs), and it uses moving averages to quickly react to spikes.\n  * Both methods can be used individually or together. For example, if a moving average detects a threshold being exceeded, you can run a custom script and immediately enable extended statistics collection.\n  * We use moving averages to detect volumetric DoS/DDoS attacks. When thresholds are reached, BGP announcements are created (FlowSpec filtering, rate-limit, redirection to cleaning servers or Blackhole) and users receive a notification in the messenger.\n  * Collector is not very demanding on resources. It can process data and build reports even on Orange Pi (analogous to Raspberry Pi) with 4 GB of memory. On small networks it can run in a VM with one CPU and 1GB of RAM.\n  * The collector has only been tested under 64-bit Linux (x64, AArch64 and [Elbrus](https://en.wikipedia.org/wiki/Elbrus_2000)).\n  * We use PostgreSQL as a storage for time series data. Aggregated data by selected Netflow fields is exported there. The collector can export **not all** data to the DBMS, it can aggregate and export only top-N entities, and aggregate the rest into one row. This is a useful feature for large monitoring objects - you can regulate the amount of data that is written to the DBMS and use cheaper, slower disks.\n  * In addition to PostgreSQL, the collector has experimental support for storing data in ClickHouse\n  * A basic set of Netflow/IPFIX fields are supported out of the box, but you can add almost any field you need.\n  * The project has a very liberal ISC license. We have no plans to make commercial or semi-commercial versions. This means that we cannot make any predictions about the future of the project. But on the other hand:\n  * There are no hidden or artificial restrictions\n\n\n## Performance\n\nUsers are usually interested in at least a rough performance estimate, so we made several tests: we recorded real Netflow traffic from different routers in pcap files and played them on the loopback interface using tcpreplay at different speeds.\n\nTests were run on i3-2120 CPU @ 3.30GHz.\n\nVery roughly, you can rely on following numbers:\n\nIn debug mode, when the contents of each flow are printed to a file, it turned out about 100K flow per second per one CPU.\n\nIn a slightly closer to production mode, with two monitoring objects, two sliding windows - about 700K fps per single CPU.\n\nThese numbers are best read in a pessimistic mood:\n  1. if you load the collector with many monitoring objects with a bunch of reports and debug printing, it can choke on 100K fps/CPU or less\n  2. most likely 700K fps and more cannot be processed on one CPU\n\nScaling to multiple cores is described below in the documentation\n\n\n## LXC container\n\nThe v25.02 release comes with an LXC container image [xe2502.tar.xz](https://github.com/vmxdev/xenoeye/releases/download/v25.02-Novokuznetsk/xe2502.tar.xz). This is a **privileged** container and is configured to use the **host network**, use this configuration with extreme caution. The container contains a collector with several pre-configured monitoring objects, PostgreSQL and Grafana.\n\nBrief usage instructions:\n``` sh\n# install lxc\n$ sudo apt install lxc\n\n# unpack the container image\n$ sudo tar Jxf xe2502.tar.xz -C /var/lib/lxc\n\n# run container\n$ sudo lxc-start --name xe2502\n\n# run container shell\n$ sudo lxc-attach --name xe2502\n```\n\nInside the container, edit the file `/etc/xenoeye/xenoeye.conf`\n\nIf you are capturing `*flow` with pcap, add capabilities:\n``` sh\n# setcap \"cap_net_admin,cap_net_raw,cap_dac_read_search,cap_sys_ptrace+pe\" /usr/local/bin/xenoeye\n```\n\nEdit the file `/var/lib/xenoeye/iplists/mynet`, write your networks there (IPv4 and IPv6), and delete unnecessary ones.\n\nRestart the service\n``` sh\n# service xenoeye restart\n```\n\nNavigate your browser to `http://server-address:3000`, Grafana should open. Login/password admin/admin.\n\nGrafana comes with several pre-configured dashboards (Overview, AS/GeoIP, Routers, DoS/DDoS) separately for IPv4 and IPv6 addresses. The documentation below describes how to add other reports and configure moving averages.\n\n\n## Proxmox-template\n\nA template for Proxmox is also available: [proxmox-xe2502.tar.xz](https://github.com/vmxdev/xenoeye/releases/download/v25.02-Novokuznetsk/proxmox-xe2502.tar.xz)\n\n\n## Documentation\n\n  * [Step-by-step instructions for installing and configuring the collector](STEP-BY-STEP.md)\n    * [Build and install](STEP-BY-STEP.md#build-and-install)\n    * [Checking Netflow packets receiving](STEP-BY-STEP.md#checking-netflow-packets-receiving)\n    * [Load-balancing across multiple CPUs](STEP-BY-STEP.md#load-balancing-across-multiple-cpus)\n    * [Sampling rate](STEP-BY-STEP.md#sampling-rate)\n    * [Monitoring objects](STEP-BY-STEP.md#monitoring-objects)\n    * [IP lists](STEP-BY-STEP.md#ip-lists)\n    * [Configure what data should be exported to the DBMS](STEP-BY-STEP.md#configure-what-data-should-be-exported-to-the-dbms)\n    * [Export to DBMS](STEP-BY-STEP.md#export-to-dbms)\n    * [Simple Reporting by IP Addresses](STEP-BY-STEP.md#simple-reporting-by-ip-addresses)\n    * [Detect spam-bots and ssh-scanners](STEP-BY-STEP.md#detect-spam-bots-and-ssh-scanners)\n    * [Plotting with gnuplot](STEP-BY-STEP.md#plotting-with-gnuplot)\n    * [Plots with Python Matplotlib](STEP-BY-STEP.md#plots-with-python-matplotlib)\n    * [Traffic visualization with Grafana](STEP-BY-STEP.md#traffic-visualization-with-grafana)\n    * [Moving Averages](STEP-BY-STEP.md#moving-averages)\n    * [Configure and set thresholds](STEP-BY-STEP.md#configure-and-set-thresholds)\n    * [Scripts and their options](STEP-BY-STEP.md#scripts-and-their-options)\n    * [Extended stats](STEP-BY-STEP.md#extended-stats)\n    * [Anomaly alerts using Telegram-bot](STEP-BY-STEP.md#anomaly-alerts-using-telegram-bot)\n\n  * [Additional features](EXTRA.md)\n    * [GeoIP](EXTRA.md#geoip)\n    * [Autonomous systems](EXTRA.md#autonomous-systems)\n    * [Updating databases without restarting the collector](EXTRA.md#updating-databases-without-restarting-the-collector)\n    * [xegeoq utility](EXTRA.md#xegeoq-utility)\n    * [Visualizing GeoIP data and AS names with Grafana](EXTRA.md#visualizing-geoip-data-and-as-names-with-grafana)\n    * [Traffic classification](EXTRA.md#traffic-classification)\n    * [sFlow](EXTRA.md#sflow)\n    * [Additional data analysis using sFlow: DNS and SNI](EXTRA.md#additional-data-analysis-using-sflow-dns-and-sni)\n    * [Nested/Hierarchical Monitoring Objects](EXTRA.md#nestedhierarchical-monitoring-objects)\n    * [Interfaces classification](EXTRA.md#interfaces-classification)\n    * [Traffic drops below threshold](EXTRA.md#traffic-drops-below-threshold)\n    * [Changing moving average thresholds without restarting the collector](EXTRA.md#changing-moving-average-thresholds-without-restarting-the-collector)\n    * [Exporting data to ClickHouse](EXTRA.md#exporting-data-to-clickhouse)\n\n  * [Full description of configuration files](CONFIG.md)\n    * [Main configuration file `xenoeye.conf`](CONFIG.md#main-configuration-file-xenoeyeconf)\n    * [Device configuration (sampling rate and interface classification) `devices.conf`](CONFIG.md#device-configuration-sampling-rate-and-interface-classification-devicesconf)\n    * [Description of the monitoring object `mo.conf`](CONFIG.md#description-of-the-monitoring-object-moconf)\n    * [Files with thresholds](CONFIG.md#files-with-thresholds)\n    * [IP Lists](CONFIG.md#ip-lists)\n\n  * [Internals](INTERNALS.md)\n    * [General remarks](INTERNALS.md#general-remarks)\n    * [Worker and auxiliary threads](INTERNALS.md#worker-and-auxiliary-threads)\n    * [Monitoring objects and filters](INTERNALS.md#monitoring-objects-and-filters)\n    * [How to add a new Netflow field to the collector](INTERNALS.md#how-to-add-a-new-netflow-field-to-the-collector)\n    * [Time source](INTERNALS.md#time-source)\n    * [Fixed time windows](INTERNALS.md#fixed-time-windows)\n    * [Moving averages](INTERNALS.md#moving-averages)\n    * [IP lists](INTERNALS.md#ip-lists)\n    * [GeoIP and AS databases](#geoip-and-as-databases)\n\n\n## Plans for the future\n\nRight now we don't plan to add new features. We look at stability, work results, try to fix bugs and make the code simpler and more understandable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmxdev%2Fxenoeye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmxdev%2Fxenoeye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmxdev%2Fxenoeye/lists"}