{"id":13642008,"url":"https://github.com/stintel/vallumd","last_synced_at":"2025-08-22T00:31:03.923Z","repository":{"id":47596693,"uuid":"78317165","full_name":"stintel/vallumd","owner":"stintel","description":"Centralize or distribute IPset blacklists","archived":false,"fork":false,"pushed_at":"2024-05-29T18:13:08.000Z","size":116,"stargazers_count":116,"open_issues_count":0,"forks_count":17,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-12-17T22:38:32.259Z","etag":null,"topics":["ban-hosts","blacklist","fail2ban","intrusion-prevention","ips","ipset"],"latest_commit_sha":null,"homepage":"https://codeberg.org/stintel/vallumd","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stintel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2017-01-08T02:38:28.000Z","updated_at":"2024-05-29T18:12:05.000Z","dependencies_parsed_at":"2024-10-23T04:02:51.452Z","dependency_job_id":null,"html_url":"https://github.com/stintel/vallumd","commit_stats":{"total_commits":127,"total_committers":2,"mean_commits":63.5,"dds":"0.015748031496062964","last_synced_commit":"e6766b6b7a290bcd8e5e3d01803f25ed68b9574c"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stintel%2Fvallumd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stintel%2Fvallumd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stintel%2Fvallumd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stintel%2Fvallumd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stintel","download_url":"https://codeload.github.com/stintel/vallumd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230542288,"owners_count":18242332,"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":["ban-hosts","blacklist","fail2ban","intrusion-prevention","ips","ipset"],"created_at":"2024-08-02T01:01:26.446Z","updated_at":"2025-08-22T00:31:03.904Z","avatar_url":"https://github.com/stintel.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"vallumd\n=======\n\nThis program allows you to centralize and distribute IP blacklists.\n\nIf you maintain a server on the Internet, it's very likely you encountered\none or more brute force attacks. Not a problem, just install fail2ban. Done.\n\nBut if you're running multiple servers, each of them running their fail2ban\ninstance, they'll all have different IP addresses in the ban list. Wouldn't\nit be nice to have a shared ban list across all your fail2ban instances?\nOr in case all your machines are behind a router or firewall you control\nyourself, wouldn't it be nice to drop malicious traffic at the edge of your\nnetwork?\n\nThat's exactly what vallumd helps to achieve.\n\n\nHow it works\n------------\n\nVallumd connects to an MQTT broker, reads messages containing IP addresses,\nand adds or deletes those IP addresses to or from an ipset. Simple as that.\n\nThis means it is not useful on its own, but it makes vallumd very flexible.\nYou can decide for yourself what kind of iptables rule you want to reference\nthe ipset in. Integrating it with fail2ban is as simple as creating a new\naction that uses mosquitto_pub to send a message to your MQTT broker.\nAnd since there are MQTT libraries out there for most common languages, it\nshouldn't be too hard to integrate with your favorite IDS, IPS or Honeypot.\n\n\nWhy the silly name\n------------------\n\nThe name vallumd comes from the Latin word \"vallum\", which means wall.\nAnd that's what vallumd does: build a wall to protect your digital empire.\n\n\nInstallation\n------------\n\nThe nicest way to install any package, is by using your distribution's\npackage management. However, since this project is very young, it has not been\nincluded in many distributions yet.\n\n### CentOS/RedHat\n\nMake sure you have the EPEL repository enabled.\n\n\n#### CentOS 7 dependencies\n```\nsudo yum -y install cmake ipset-devel mosquitto-devel openssl-devel pkgconfig '@Development Tools'\n```\n\n#### Common\nYou can now generate an RPM package with cpack:\n```\ngit clone https://codeberg.org/stintel/vallumd.git\ncd vallumd\ncmake .\ncpack -G RPM\n\nsudo yum -y localinstall build/*.rpm\n```\nBuild-tested on CentOS 7.\n\n### Debian/Ubuntu\n\nYou can generate a DEB package with cpack:\n```\nsudo apt-get -y install build-essential cmake libipset-dev libmosquitto-dev libssl-dev pkg-config\n\ngit clone https://codeberg.org/stintel/vallumd.git\ncd vallumd\ncmake .\ncpack -G DEB\n\nsudo dpkg -i build/*.deb\n```\nBuild-tested on Debian 10, 11 and Ubuntu 18.04, 20.04, 22.04.\n\n### Gentoo\nYou can find a live ebuild for vallumd in my [Gentoo overlay](https://github.com/stintel/gentoo-overlay)\n\n### OpenWrt/LEDE\n\nIf you're running an OpenWrt DD snapshot or LEDE, vallumd is available\nin the packages feed, and can be installed with opkg:\n```\nopkg update\nopkg install vallumd\n```\n\n### Manual install\nManual installation is very easy.\nRequirements:\n* cmake\n* libipset\n* libmosquitto\n* libssl\n\nInstructions:\n```\ngit clone https://codeberg.org/stintel/vallumd.git\ncd vallumd\ncmake .\nmake\nmake install\n```\n\n\nUsage\n-----\n\nTo use vallumd, you need an MQTT broker, like [Mosquitto](https://mosquitto.org/).\nDepending on your setup, you can run it on the same host that runs vallumd,\nbut that's no requirement.\n\nThe next thing you need is an IPset. To give you full control over the type\nof IPset and its options, vallumd will not create the IPset itself.\nYou can choose between these IPset types:\n* bitmap:ip\n* bitmap:net\n* hash:ip\n* hash:net\n\nIPset creation example:\n`ipset create blacklist hash:ip timeout 3600`\n\nNow you can start vallumd. The following command line options exist:\n```\n -h: MQTT host to connect to\n -p: MQTT port to connect to (1883)\n -u: MQTT username\n -P: MQTT password\n -t: MQTT topic and IPset name\n -V: print version number and exit\n -c: path to CA file\n -T: use TLS\n```\nThe host and topic options are required, the others are optional (default\nvalue). It is possible to specify multiple topics.\n\nStarting vallumd:\n`vallumd -h 192.168.0.1 -t blacklist`\n\nThis will listen for messages on the MQTT broker at 192.168.0.1, in the\nblacklist topic, and when a message is received, the IP address in the message\nwill be added to or remove from the IPset named blacklist.\n\nSo now we have everything in place to start adding IPs to the blacklist.\nAll we have to do is configure our IDS, IPS or Honeypot to send malicious\nIP addresses to our MQTT broker.\n\nFor fail2ban, this could be done with the Mosquitto client `mosquitto_pub`.\nCreate a new action in `/etc/fail2ban/action.d/vallumd.conf`:\n```\n[Definition]\nactionban = mosquitto_pub -h 192.168.0.1 -q 2 -t blacklist/add -m \u003cip\u003e\nactionunban = mosquitto_pub -h 192.168.0.1 -q 2 -t blacklist/del -m \u003cip\u003e\n```\nAnd configure your fail2ban jails to use the vallumd action.\n\n\nRunning as a service\n--------------------\n\nThe packages generated with CPack support OpenRC, Upstart and systemd.\nService configuration files are where you would expect them in your distro:\n* CentOS/RedHat: /etc/sysconfig/vallumd\n* Debian/Ubuntu: /etc/default/vallumd\n* Gentoo: /etc/conf.d/vallumd\n* OpenWrt/LEDE: /etc/config/vallumd\n\nAfter editing the file relevant for your distribution, start the vallumd service\njust like you would start any other service on your system.\n\n\nLogging\n-------\nVallumd uses syslog(3) for logging.\n\n\nGet involved\n------------\n\n* Join the #vallumd IRC channel on irc.oftc.net\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstintel%2Fvallumd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstintel%2Fvallumd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstintel%2Fvallumd/lists"}