{"id":13530142,"url":"https://github.com/DCSO/slinkwatch","last_synced_at":"2025-04-01T17:32:05.351Z","repository":{"id":128725994,"uuid":"155190473","full_name":"DCSO/slinkwatch","owner":"DCSO","description":"automatic enumeration and maintenance of Suricata monitoring interfaces","archived":false,"fork":false,"pushed_at":"2019-12-10T16:18:23.000Z","size":32,"stargazers_count":10,"open_issues_count":7,"forks_count":5,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-02T07:11:16.115Z","etag":null,"topics":["automation","ifplugd","interfaces","intrusion-detection","network","network-monitoring","sensor-management","suricata"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DCSO.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}},"created_at":"2018-10-29T10:07:23.000Z","updated_at":"2024-03-28T11:49:35.000Z","dependencies_parsed_at":"2023-03-22T12:16:54.873Z","dependency_job_id":null,"html_url":"https://github.com/DCSO/slinkwatch","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCSO%2Fslinkwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCSO%2Fslinkwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCSO%2Fslinkwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCSO%2Fslinkwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DCSO","download_url":"https://codeload.github.com/DCSO/slinkwatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222748281,"owners_count":17031898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automation","ifplugd","interfaces","intrusion-detection","network","network-monitoring","sensor-management","suricata"],"created_at":"2024-08-01T07:00:44.513Z","updated_at":"2024-11-02T16:31:46.304Z","avatar_url":"https://github.com/DCSO.png","language":"Go","readme":"# 🔃 slinkwatch [![CircleCI](https://circleci.com/gh/DCSO/slinkwatch.svg?style=svg)](https://circleci.com/gh/DCSO/slinkwatch)\n\nslinkwatch is the *Suricata Link Watcher*, a tool to dynamically maintain `interface` entries in Suricata's configuration file, depending on what network interfaces are connected. It is meant to ease deployment of identical sensor installations at many heterogenous sites, allowing to make full use of the sensor resources in the light of varying monitoring volume.\n\n## Interaction with Suricata\n\nIn order to propagate changed interface configuration to Suricata, one would need to configure Suricata in such a way that the\nsection of the configuration YAML created by the slinkwatch template is included from a separate file, e.g. via\n\n```yaml\n...\n\ninclude: interfaces.yaml\n\n...\n```\n\nin, for example, `/etc/suricata/suricata.yaml` and then specifying `/etc/suricata/interfaces.yaml` as the `--target-file` in the slinkwatch call. Note that it must be writable by the slinkwatch process!\n\nAfter modifying this file whenever a status change occurs, slinkwatch will attempt to restart Suricata. For systems that run [systemd](https://www.freedesktop.org/wiki/Software/systemd/), slinkwatch will always try to restart the service given by the `--service-name` option (default is `suricata.service`). On non-systemd systems, it will run a simple command to restart Suricata (default is `/etc/init.d/suricata restart`). Whether systemd is available will be checked at runtime.\n\n## Resource assignment\n\nSupport for interfaces going online and offline at runtime obviously raises the question of how to assign computing resources (i.e. detection threads) to the individual interfaces. Unless all interfaces on a sensor are completely  identical in terms of supported bandwidth and traffic, it is not sufficient to simply assign equal amounts of threads to all interfaces that are connected at a given point in time. For example, one might have a 10Gbit interface `eth1` and a 1Gbit interface `eth2` on such a machine, and most certainly one would want more threads  assigned to the former than to the latter. Even more importantly, how would an existing assignment be changed to be most efficient when another 10Gbit interface, say `eth3` gets a link?\n\nWe address this issue using _thread weights_. That is, each interface _i_ is assigned a integer value _w\u003csub\u003ei\u003c/sub\u003e_ to denote its resource allocation importance. For example, in the case above we could assign _w\u003csub\u003eeth1\u003c/sub\u003e_ = _w\u003csub\u003eeth3\u003c/sub\u003e_ = 10 and _w\u003csub\u003eeth2\u003c/sub\u003e_ = 2. We also consider the _active set_ of interfaces _A_ as the set of all interfaces that have an active link. On a machine with _n_ threads available for detection, we can then assign to each interface _i_ the value \n\n![t_i=\\lceil n \\frac{w_i}{\\sum_{j \\in A}w_j} \\rceil](https://latex.codecogs.com/png.latex?t_i%3D%5Clceil%20n%20%5Cfrac%7Bw_i%7D%7B%5Csum_%7Bj%20%5Cin%20A%7Dw_j%7D%20%5Crceil)\n\nas the number of threads allocated to detection for traffic on interface _i_. For example, for _n_ = 40 we would then set\n\n![t_{\\textup{eth1}} = t_{\\textup{eth3}} = \\lceil 40 \\frac{10}{22} \\rceil = 19](https://latex.codecogs.com/png.latex?t_%7B%5Ctextup%7Beth1%7D%7D%20%3D%20t_%7B%5Ctextup%7Beth3%7D%7D%20%3D%20%5Clceil%2040%20%5Cfrac%7B10%7D%7B22%7D%20%5Crceil%20%3D%2019)\n\nand\n\n![t_{\\textup{eth2}} = \\lceil 40 \\frac{2}{22} \\rceil = 4](https://latex.codecogs.com/png.latex?t_%7B%5Ctextup%7Beth2%7D%7D%20%3D%20%5Clceil%2040%20%5Cfrac%7B2%7D%7B22%7D%20%5Crceil%20%3D%204)\n\nWe aim for slight overcommitment of CPU hyperthreads to avoid idling CPUs as much as possible.\n\n## Installing dependencies via `dep`\n\nThe component of slinkwatch talking to systemd requires a specific godbus version. Please make sure to run\n\n```\n$ dep ensure\n```\n\nbefore building to make sure the correct version constraints apply.\n\n## Usage\n\nDefine the interfaces that are available to assign in a YAML file, together with their weights:\n\n```yaml\n# Interfaces available for Suricata\n--- \nifaces:\n  eth1: \n    clusterid: 98\n    threadweight: 10\n  eth2: \n    clusterid: 97\n    threadweight: 2\n  eth3: \n    clusterid: 96\n    threadweight: 10\n```\n\nAdjust the template to fit the desired configuration format:\n\n```\n%YAML 1.1\n---\naf-packet:{{ range $iface, $vals := . }}\n  - interface: {{ $iface }}\n    threads: {{ $vals.Threads }}\n    cluster-id: {{ $vals.ClusterID }}\n    cluster-type: cluster_flow\n    defrag: yes\n    rollover: yes\n    use-mmap: yes\n    tpacket-v3: yes\n    use-emergency-flush: yes\n    buffer-size: 128000\n{{ else }}\n  - interface: default\n    threads: auto\n    use-mmap: yes\n    rollover: yes\n    tpacket-v3: yes\n{{ end }}\n\n```\n\nFinally, run slinkwatch, preferably in the background (there's also a systemd service unit file in the repo).\n\n```\n$ slinkwatch run \n```\n\nIt is possible to specify the locations of the template and config file using the command line parameters:\n\n```\n$ slinkwatch run --help\nRun the slinkwatch service\n\nUsage:\n  slinkwatch run [flags]\n\nFlags:\n  -c, --config string            Configuration file (default \"config.yaml\")\n  -d, --delta-bytes uint         threshold of bytes to be exceeded on interface to be marked as up (default 100)\n  -h, --help                     help for run\n  -i, --interfaces string        Template file for interfaces (default \"interfaces.tmpl\")\n  -p, --poll-interval duration   poll time for interface changes (default 5s)\n  -r, --restart-command string   Suricata restart command (default \"/etc/init.d/suricata restart\")\n  -s, --service-name string      systemd service name for Suricata service (default \"suricata.service\")\n  -t, --target-file string       Target YAML file with interface information (default \"/etc/suricata/interfaces.yaml\")\n```\n\n## Other commands\n\n - `slinkwatch make-config` creates an initial YAML file with skeleton config entries for local interfaces (or a subset defined by a regular expression)\n - `slinkwatch makeman` creates a set of man pages for the tool\n - `slinkwatch show-active` lists the currently active set of interfaces (useful for debugging)\n\n## Dependencies/requirements\n\nNeeds [ifplugo](http://github.com/satta/ifplugo) for network change notifications. This introduces a runtime dependency on libdaemon.\nIt is also highly recommended to use systemd.\n\n## Authors\n\nSascha Steinbiss\n\n## License\n\nGPL2 (due to ifplugo being GPL2).\n","funding_links":[],"categories":["Operations, Monitoring and Troubleshooting"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDCSO%2Fslinkwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDCSO%2Fslinkwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDCSO%2Fslinkwatch/lists"}