{"id":20538336,"url":"https://github.com/thomasmiz/dust-devil","last_synced_at":"2025-11-03T17:38:06.471Z","repository":{"id":211526181,"uuid":"729289025","full_name":"ThomasMiz/dust-devil","owner":"ThomasMiz","description":"A socks5 proxy server with advanced remote monitoring capabilities","archived":false,"fork":false,"pushed_at":"2024-02-24T18:48:44.000Z","size":7380,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-23T23:04:14.168Z","etag":null,"topics":["monitoring-server","monitoring-tool","network-programming","proxy","proxy-server","socks-protocol","socks-server","socks5","socks5-proxy","terminal-ui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThomasMiz.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}},"created_at":"2023-12-08T20:20:43.000Z","updated_at":"2024-04-04T14:03:19.000Z","dependencies_parsed_at":"2024-01-25T23:26:27.106Z","dependency_job_id":"ed91c8da-9582-4a2b-b2fe-515c56da9c41","html_url":"https://github.com/ThomasMiz/dust-devil","commit_stats":null,"previous_names":["thomasmiz/dust-devil"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasMiz%2Fdust-devil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasMiz%2Fdust-devil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasMiz%2Fdust-devil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasMiz%2Fdust-devil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThomasMiz","download_url":"https://codeload.github.com/ThomasMiz/dust-devil/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844047,"owners_count":21170486,"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":["monitoring-server","monitoring-tool","network-programming","proxy","proxy-server","socks-protocol","socks-server","socks5","socks5-proxy","terminal-ui"],"created_at":"2024-11-16T00:46:20.190Z","updated_at":"2025-11-03T17:38:06.445Z","avatar_url":"https://github.com/ThomasMiz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![monitoring](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/monitoring.gif)\n[![Crates.io](https://img.shields.io/crates/v/dust-devil.svg)](https://crates.io/crates/dust-devil)\n\n# Dust Devil\n\nDust Devil is a SOCKS5 proxy server, the spiritual successor of [TornadoProxy](https://github.com/ThomasMiz/TornadoProxy), written in [Rust](https://www.rust-lang.org/) with the intent of learning said language. The project includes a custom TCP-based monitoring protocol called Sandstorm which allows managing and monitoring the server in real time. This protocol is implemented in the server, and a client application for it is provided too, including an advanced TUI (Terminal User Interface).\n\nDust Devil has the following features:\n\n* Works on both Windows and Linux\n* Support for IPv4 and IPv6 for both SOCKS5 and Sandstorm connections\n* Support for SOCKS5 ([RFC 1928](https://www.rfc-editor.org/rfc/rfc1928)) TCP connections (\"Connect\" command only)\n* Support for connecting to an IPv4/IPv6/Domainname. If a domain name's resolution yields multiple addresses, connection to these will be attempted in said order\n* Support for the \"NO AUTHENTICATION REQUIRED\" and \"USERNAME/PASSWORD\" authentication methods, plus the ability to turn these on or off at any time\n* User persistence to file (by default to `users.txt`) in a human-readable format (that's not intended to be secure)\n* Can choose any arbitrary amount of sockets (address:port) to listen at for incoming SOCKS5 or Sandstorm connections\n* Can choose the buffer size used for SOCKS5 connections (8KB by default)\n* Detailed logging, by default to standard output, but may also output to a file, as well as metrics collection (total connections, bytes sent or received, etc)\n* Extensive remote monitoring capabilities through the custom Sandstorm protocol, including:\n  * Listing/registering/updating/deleting users\n  * Shutting down the server\n  * Listing/adding/removing a listening socket (for both SOCKS5 or Sandstorm)\n  * Listing/enabling/disabling authentication methods\n  * Getting/setting the buffer size\n  * Real time logs/events and metrics\n\n# The Sandstorm Protocol\nThis protocol, partly defined in [sandstorm_protocol.txt](https://github.com/ThomasMiz/dust-devil/blob/main/dust-devil-core/sandstorm_protocol.txt) (but with most of the struct serialization [defined in Rust](https://github.com/ThomasMiz/dust-devil/blob/main/dust-devil-core/src/serialize.rs)).\n\nThe `dust-devil-core` library crate contains the [Rust implementation of this protocol](https://github.com/ThomasMiz/dust-devil/tree/main/dust-devil-core/src/sandstorm) that is used by both the server and the client. This crate is also [available as standalone in crates.io](https://crates.io/crates/dust-devil-core) and [thoroughly documented in docs.rs](https://docs.rs/dust-devil-core/latest/dust_devil_core/).\n\nSandstorm is a TCP-based protocol and is a mix between pipelined request-response and asynchronous streams. The client sends requests to the server and gets responses back, however requests are not guaranteed to be handled nor answered by the server in the same order as they were sent. Multiple requests to add or remove users are guaranteed to be synchronized between themselves, but an open socket request in between those could be answered first, last, or anywhere in between. For more information on Sandstorm's request synchronization rules, check the \"Pipelining\" section of [sandstorm_protocol.txt](https://github.com/ThomasMiz/dust-devil/blob/main/dust-devil-core/sandstorm_protocol.txt).\n\nIn addition to this, the client may enable _event streaming_, which makes the server send an asynchronous stream of real-time events, which are interspersed with the request responses. These events are not simply strings with the log output (even though these events are internally used by the server to also generate the logs), but rather are serialized in a binary format with detailed information.\n\n_Note: events are serialized in an efficient binary format, but still, if a client's connection to the server isn't fast enough to handle the rate at which events are generated, the client's connection will be abruptly terminated._\n\n# Installation and Usage\nThe recommended way to install is with `cargo` from crates.io:\n```\ncargo install dust-devil\n```\n\nOr directly from GitHub:\n```\ncargo install --git https://github.com/ThomasMiz/dust-devil.git dust-devil\n```\n\nEither one of these will download and compile the server's code and all its dependencies. Once this is done, the server's executable will become available under the name `dust-devil`.\n\nThe monitoring client can be installed the same way:\n```\ncargo install dust-devil-sandstorm\n```\n\nOr directly from GitHub:\n```\ncargo install --git https://github.com/ThomasMiz/dust-devil.git sandstorm\n```\n\nEither one of these will download and compile the client's code and all its dependencies. Once this is done, the client's executable will become available under the name `sandstorm`.\n\n## Downloading binaries\nIf you don't have `cargo` installed, pre-compiled binaries are available for x84_64 Windows and Linux [in the releases page](https://github.com/ThomasMiz/dust-devil/releases).\n\n## Server Usage\nThe server can be ran as-is without any setup, using default configuration, and will start outputting logs to standard output immediately:\n```\n$ dust-devil\n[2024-02-23 16:08:39] Loading users from file users.txt\n[2024-02-23 16:08:39] Error while loading users from file users.txt: IO error: The system cannot find the file specified. (os error 2)\n[2024-02-23 16:08:39] Starting up with single default user admin:admin\n[2024-02-23 16:08:39] Listening for socks5 client connections at [::]:1080\n[2024-02-23 16:08:39] Listening for socks5 client connections at 0.0.0.0:1080\n[2024-02-23 16:08:39] Listening for Sandstorm connections at [::]:2222\n[2024-02-23 16:08:39] Listening for Sandstorm connections at 0.0.0.0:2222\n```\n\nThe usage of the server is thoroughly explained in the help menu (`dust-devil --help`):\n```\nUsage: dust-devil [options...]\nOptions:\n  -h, --help                      Display this help menu and exit\n  -V, --version                   Display the version number and exit\n  -v, --verbose                   Display additional information while running\n  -s, --silent                    Do not print logs to stdout\n  -d, --disable-events            Disables events, logs, and all data collection\n  -o, --log-file \u003cpath\u003e           Append logs to the specified file\n  -l, --listen \u003caddress\u003e          Specify a socket address to listen for incoming SOCKS5 clients\n  -m, --management \u003caddress\u003e      Specify a socket address to listen for incoming Sandstorm clients\n  -U, --users-file \u003cpath\u003e         Load and save users to/from this file\n  -u, --user \u003cuser\u003e               Adds a new user\n  -A, --auth-enable \u003cauth_type\u003e   Enables an authentication method\n  -a, --auth-disable \u003cauth_type\u003e  Disables an authentication method\n  -b, --buffer-size \u003csize\u003e        Sets the size of the buffer for client connections\n\nBy default, the server will print logs to stdout, but not to any file. Logging may be enabled to\nboth stdout and to file at the same time. If a log sink is not fast enough to keep up the pace with\nthe server, then messages on said sink may be lost, indicated by an error message printed only to\nsaid sink.\n\nSocket addresses may be specified as an IPv4 or IPv6 address, or a domainname, and may include a\nport number. The -l/--listen and -m/--management parameter may be specified multiple times to\nlisten on many addresses. If no port is specified, then the default port of 1080 will be used for\nsocks5 and 2222 for Sandstorm. If no --listen parameter is specified, then [::]:1080 and\n0.0.0.0:1080 will be used, and if no Sandstorm sockets are specified, then [::]:2222 and\n0.0.0.0:2222 will be used.\n\nUsers are specified in the same format as each line on the users file, but for regular users you\nmay drop the role character. For example, -u \"pedro:1234\" would have the same effect as --user\n\"#pedro:1234\", and admins may be added with, for example \"@admin:secret\".\n\nFor enabling or disabling authentication, the available authentication types are \"noauth\" and\n\"userpass\". All authentication methods are enabled by default.\n\nThe default buffer size is 8KBs. Buffer sizes may be specified in bytes ('-b 8192'), kilobytes\n('-b 8K'), megabytes ('-b 1M') or gigabytes ('-b 1G' if you respect your computer, please don't)\nbut may not be equal to nor larger than 4GBs.\n\n\nExamples:\n\nStarts the server listening for SOCKS5 clients on all IPv4 addresses on port 1080 and Sandstorm\nclients on all IPv6 addresses on port 2222 (the ports are implicit), writing logs to a logs.txt\nfile and creating a new admin user called \"pedro\" with password \"1234\":\n    dust-devil -o logs.txt -l 0.0.0.0 -m [::] -u @pedro:1234\n\nStarts the server with the default sockets listening for incoming SOCKS5 clients, but only allows\nincoming management connections from localhost:3443. The buffer size for clients is set to 4096\nbytes, logging and metrics are disabled:\n    dust-devil -m localhost:3443 -b 4k -d -s\n\nStarts the server with the default listening sockets, diasbles \"noauth\" authentication (to force\nclients to authenticate with a username and password), and creates three users: Admin user\n'Nicolás' with password '#nicorules', regular user 'Greg:orio with password 'holus', and regular\nuser '#tade0' with password 'tadaa':\n    dust-devil -a noauth -u @Nicolás:#nicorules -u Greg\\:orio::holus: -u ##tade0:tadaa\n```\n\n# Client Usage\nThe monitoring client requires at least the credentials parameter to be specified (as monitoring\nclients must authenticate as an admin user with the server). The credentials may be specified via\nparameter or via a `SANDSTORM_USER` environment variable. Unless specified with `-x \u003caddress\u003e`, the\nclient connects to the server at `localhost:2222`.\n\nThe usage of the client is thoroughly explained in the help menu (`sandstorm --help`):\n```\nUsage: sandstorm [options...]\nOptions:\n  -h, --help                      Display this help menu and exit\n  -V, --version                   Display the version number and exit\n  -v, --verbose                   Display additional information while running\n  -s, --silent                    Do not print to stdout\n  -x, --host \u003caddress\u003e            Specify the server to connect to\n  -c, --credentials \u003ccreds\u003e       Specify the user to log in as, in user:password format\n  -S, --shutdown                  Requests the server to shut down\n  -l, --list-socks5               Requests the server sends a list of socks5 sockets\n  -k, --add-socks5 \u003caddress\u003e      Requests the server opens a new socks5 socket\n  -r, --remove-socks5 \u003caddress\u003e   Requests the server removes an existing socks5 socket\n  -L, --list-sandstr              Requests the server sends a list of Sandstorm sockets\n  -K, --add-sandstr \u003caddress\u003e     Requests the server opens a new Sandstorm socket\n  -R, --remove-sandstr \u003caddress\u003e  Requests the server removes an existing Sandstorm socket\n  -t, --list-users                Requests the server adds a new user\n  -u, --add-user \u003cuser\u003e           Requests the server adds a new user\n  -p, --update-user \u003cupdt_user\u003e   Requests the server updates an existing user\n  -d, --delete-user \u003cusername\u003e    Requests the server deletes an existing user\n  -z, --list-auth                 Requests the server sends a list of auth methods\n  -A, --auth-enable \u003cauth_type\u003e   Requests the server enables an authentication method\n  -a, --auth-disable \u003cauth_type\u003e  Requests the server disables an authentication method\n  -m, --get-metrics               Requests the server sends the current metrics\n  -B, --get-buffer-size           Requests the server sends the current buffer size\n  -b, --set-buffer-size \u003csize\u003e    Requests the server changes its buffer size\n  -w, --meow                      Requests a meow ping to the server\n  -o, --output-logs               Remain open and print the server's logs to stdout\n  -i, --interactive               Remains open with an advanced terminal UI interface\n\nSocket addresses may be specified as an IPv4 or IPv6 address, or a domainname, and may include a\nport number. If no port is specified, then the appropriate default will be used (1080 for Socks5\nand 2222 for Sandstorm). If no -x/--host parameter is specified, then localhost:2222 will be used.\n\nCredentials may be specified with the -c/--credentials argument, in username:password format. If no\ncredentials argument is specified, then the credentials will be taken from the SANDSTORM_USER\nenvironment variable, which must follow the same format.\n\nWhen adding a user, it is specified in the (role)?user:password format. For example, \"#carlos:1234\"\nrepresents a regular user with username \"carlos\" and password \"1234\", and \"@josé:4:4:4\" represents\nan admin user with username \"josé\" and password \"4:4:4\". If the role char is omitted, then a\nregular user is assumed. Updating an existing user work much the same way, but the role char or\npassword may be omitted. Only the fields present will be updated, those omitted will not be\nmodified. To specify an username that contains a ':' character, you may escape it like so:\n\"#chi\\:chí:4:3:2:1\" (this produces a regular user \"chi:chí\" with password \"4:3:2:1\"). When deleting\nan user, no escaping is necessary, as only the username is specified.\nFor enabling or disabling authentication, the available authentication types are \"noauth\" and\n\"userpass\".\n\nBuffer sizes may be specified in bytes ('-b 8192'), kilobytes ('-b 8K'), megabytes ('-b 1M') or\ngigabytes ('-b 1G' if you respect your computer, please don't) but may not be equal to nor larger\nthan 4GBs.\n\nThe requests are done in the order in which they're specified and their results printed to stdout\n(unless -s/--silent is specified). Pipelining will be used, so the requests are not guaranteed to\ncome back in the same order. The only ordering guarantees are those defined in the Sandstorm\nprotocol (so, for example, list/add/remove socks5 sockets operations are guaranteed to be handled\nin order and answered in order, but an add user request in the middle of all that may not come back\nin the same order).\n\nThe -o/--output-logs and -i/--interactive modes are mutually exclusive, only one may be enabled.\n\n\nExamples:\n\nConnects to the server at 192.168.1.1:2222 (the port is implicit), logs in with user 'admin'\npassword 'admin', and requests three consecutive meow pings:\n    sandstorm -x 192.168.1.1 -c admin:admin -w -w -w\n\nConnects to the server at 10.4.20.1:8900, logs in with user 'pedro' password '1234', then requests\nadding the admin user 'pedro' with password '1234', updates the role of user 'marcos' to regular\n(the password is not changed), deletes the user 'josé', and finally lists all the users:\n    sandstorm -x 10.4.2.1:8900 -c pedro:1234 -u @pedro:1234 -p #marcos -d josé -t\n\nConnects to the server at localhost:2222 (implicit) with user 'admin' and requests the current\nbuffer size and metrics:\n    sandstorm -c admin:admin -B -m\n\nConnects to the server at localhost:2222 (implicit) with user 'admin' and shuts down the server:\n    sandstorm -c admin:admin -S\n\nConnects to the server at localhost:2222 (implicit) with user 'admin', requests the list of\nlistening SOCKS5 sockets, and then leaves the connection open streaming server events and printing\nthem to stdout until manually closed (with Ctrl-C):\n    sandstorm -c admin:admin -l -o\n\nConnects to the server at localhost:2222 (implicit) with user 'admin', sends three meow pings and\nthen opens the interactive TUI (Terminal User Interface)\n    sandstorm -c admin:admin -w -w -w -i\n```\n\n# Monitoring TUI\nThe aformentioned monitoring client provides an \"interactive\" mode, in which the application takes\nmanual control of the terminal and opens up an advanced interface:\n\n![monitoring_client](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/sandstorm.png)\n\nThis monitoring client provides a more friendly, but still fully featured interface for monitoring\nthe server, displaying real-time metrics, events, and a usage history graph.\n\n# Gallery\n\n![firefox_example](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/firefox.png)\n\n![making_my_isp_hate_me](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/making_my_isp_hate_me.png)\n\n![graph_expanded](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/graph_expanded.png)\n\n![socks5_popup](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/socks5_popup.png)\n\n![users_popup](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/users_popup.png)\n\n![auth_methods_popup](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/auth_methods_popup.png)\n\n![buffer_size_popup](https://raw.githubusercontent.com/ThomasMiz/dust-devil/main/images/buffer_size_popup.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasmiz%2Fdust-devil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasmiz%2Fdust-devil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasmiz%2Fdust-devil/lists"}