{"id":17310501,"url":"https://github.com/kpcyrd/snail","last_synced_at":"2025-04-14T14:31:05.685Z","repository":{"id":47673927,"uuid":"138343304","full_name":"kpcyrd/snail","owner":"kpcyrd","description":"Parasitic network manager","archived":true,"fork":false,"pushed_at":"2019-05-27T16:28:05.000Z","size":599,"stargazers_count":15,"open_issues_count":13,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T05:17:35.321Z","etag":null,"topics":["lua","network-manager","parasitic","rust","sandboxed","scriptable","security"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/snail","language":"Rust","has_issues":true,"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/kpcyrd.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}},"created_at":"2018-06-22T20:00:04.000Z","updated_at":"2025-01-28T09:44:41.000Z","dependencies_parsed_at":"2022-08-21T16:40:33.685Z","dependency_job_id":null,"html_url":"https://github.com/kpcyrd/snail","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpcyrd%2Fsnail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpcyrd%2Fsnail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpcyrd%2Fsnail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpcyrd%2Fsnail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpcyrd","download_url":"https://codeload.github.com/kpcyrd/snail/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248897073,"owners_count":21179533,"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":["lua","network-manager","parasitic","rust","sandboxed","scriptable","security"],"created_at":"2024-10-15T12:37:24.991Z","updated_at":"2025-04-14T14:31:05.328Z","avatar_url":"https://github.com/kpcyrd.png","language":"Rust","readme":"# snail [![Build Status][travis-img]][travis] [![Crates.io][crates-img]][crates]\n\n[travis-img]:   https://travis-ci.org/kpcyrd/snail.svg?branch=master\n[travis]:       https://travis-ci.org/kpcyrd/snail\n[crates-img]:   https://img.shields.io/crates/v/snail.svg\n[crates]:       https://crates.io/crates/snail\n\n**Disclaimer:** The project is in a very early state, you're very likely to\nexperience bugs. I'm using it as my daily driver, but you should expect a very\nbare bone experience if you're considering doing the same.\n\nParasitic network manager. snail is trying to fill the gap of a metasploit-like\nnetwork manager. Its core feature is a scripting engine that can be used to\nmatch known networks and also interact with captive portals if one is\ndiscovered. Have a look at the [scripts/](scripts/) folder for examples. The\nbasic idea is that you're trying to get connectivity, but you don't really care\nwhere it's actually coming from. Please remain seated and keep your arms and\nlegs inside the firewall at all times.\n\n![logo](docs/logo.png)\n\n## Installation\n\nIf possible, use the [snail-git] package for archlinux. For a manual setup on a\ndebian based system, install the dependency libraries `libseccomp-dev`,\n`libdbus-1-dev` and `libzmq3-dev`.\n\n[snail-git]: https://aur.archlinux.org/packages/snail-git/\n\nNext, build the binary:\n```\ncargo build --release\n```\n\nAnd install it:\n```\ninstall -Dm755 target/release/snail{d,ctl} /usr/bin\ninstall -Dm644 scripts/* -t /usr/lib/snaild/scripts\n\ninstall -d /etc/snail/scripts\ninstall -Dm644 contrib/snail.conf -t /etc/snail\ninstall -Dm644 contrib/snail@.service -t /usr/lib/systemd/system\ninstall -Dm644 contrib/snail-tmpfiles.conf /usr/lib/tmpfiles.d/snail.conf\ninstall -Dm644 contrib/snail-sysuser.conf /usr/lib/sysusers.d/snail.conf\n\nsystemd-tmpfiles --create\nsystemd-sysusers\nsystemctl daemon-reload\nsystemctl enable --now snail@wlp3s0\n```\n\nYou can monitor your network status with snailctl. Make sure your user is in\nthe correct group which is specified in /etc/snail/snail.conf.\n```\nsnailctl status\n```\n\nTo add yourself to the correct group, run\n```\nusermod -aG snail user\n```\n\n## snailctl decap\n\nThe captive portal engine should run automatically as part of snaild, but it's\nalso possible to invoke it manually.\n\nTo execute the engine in verbose mode, run:\n```\nsnailctl decap -v\n```\n\nSome portals also hijack the android captive portal probe, in that case you can\nbypass the captive portal test and execute the scripts directly by running:\n```\nsnailctl decap -vf\n```\n\nIf you are developing a new script, you can provide the path to that script\nusing:\n```\nsnailctl decap -v ~/scripts/foo.lua\n```\n\nBy default, custom scripts are loaded from `/etc/snail/scripts/*.lua`, but you\ncan also add additional folders to `/etc/snail/snail.conf`:\n```\n[scripts.paths.\"/home/user/snail/scripts\"]\n[scripts.paths.\"/opt/snail/scripts\"]\n```\n\nTo ensure your script is properly being picked up, run snailctl without any\narguments:\n```\nsnailctl\n```\n\nIf you wrote a new script for a captive portal, please submit a pull request.\n\n## snaild dns\n\nsnaild contains a dns server that listens for dns queries on localhost and\nforwards them to a dns-over-https recursor. You can also configure your own\nzones that get forwarded to a different dns recursor, or hardcode static dns\nrecords.\n\n```toml\n[dns]\nbind = \"127.0.0.1:53\"\n\n# cloudflare\nservers = [\"1.1.1.1\",\n           \"1.0.0.1\",\n           \"2606:4700:4700::1111\",\n           \"2606:4700:4700::1001\"]\nport = 443\nsni = \"cloudflare-dns.com\"\n\n[dns.records]\n\"foo.example.com\" = [\"192.0.2.10\", \"2001:DB8::10\"]\n\"bar.example.com\" = [\"192.0.2.20\", \"2001:DB8::20\"]\n\n[dns.zones]\n\"example.com\" = [\"192.0.2.2\", \"2001:DB8::2\"]\n\"corp.example.com\" = [\"192.0.2.3\", \"2001:DB8::3\"]\n```\n\n## snaild vpn\n\n:fire::fire::fire: **Highly experimental, use at your own risk** :fire::fire::fire:\n\nsnaild contains a vpn server and client that can be used to setup an encrypted\ntunnel to a remote server. It features forward secrecy, identity hiding for the\nclient and is going to support various transport channels in the future to\nevade egress firewalls.\n\nThe encrypted tunnel is setup using the noise protocol with\n`Noise_XK_25519_ChaChaPoly_BLAKE2s`. Unlike some traditional vpn clients, we do\nnot leak any metadata during the handshake.\n\nTo setup the server, run `snaild vpn-keygen` to generate a keypair for the\nserver. You also need to specify a range for the client ip pool and list the\npublic keys of all clients that are authorized to connect to the server.\n\n```toml\n[vpn.server]\nbind = \"0.0.0.0:443\"\n\nserver_pubkey = \"s0c8xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4D0=\"\nserver_privkey = \"a0zxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQg5o=\"\n\ngateway_ip = \"192.168.100.1/24\"\npool_start = \"192.168.100.5\"\npool_end = \"192.168.100.200\"\n\nclients = [\n    \"cn66xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxaXY=\",\n]\n```\n\nNext, use `snaild vpn-keygen` again and generate a key for the client. Copy the\nprivate key you generated into the client section together with the public key\nyou generated for the server.\n\n```toml\n[vpn.client]\nremote = \"192.0.2.13:443\"\n\nserver_pubkey = \"s0c8xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4D0=\"\nclient_privkey = \"te4Pxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4Qx8=\"\n```\n\nStarting the vpn on both the server and client should give you an encrypted\ntunnel between both:\n\n```\nserver# snaild vpnd snail0\nclient# snaild vpn snail1\n```\n\n## Trivia\n\nThe name snailctl is inspired by [Leucochloridium], a parasite that lives\ninside a snail and is able to control its host. In the long term, `snaild` is\nthe process that interfaces with the snails brain and `snailctl` is the utility\nto control the snail through `snaild`.\n\nThe logo has been created by Baudon in 1879.\n\n[Leucochloridium]: https://en.wikipedia.org/wiki/Leucochloridium\n\n## License\n\nGPLv3+\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpcyrd%2Fsnail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpcyrd%2Fsnail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpcyrd%2Fsnail/lists"}