{"id":20064151,"url":"https://github.com/nyxnor/tor-ctrl","last_synced_at":"2025-05-05T17:33:32.524Z","repository":{"id":43797145,"uuid":"444584452","full_name":"nyxnor/tor-ctrl","owner":"nyxnor","description":"Raw use of tor's controller","archived":false,"fork":false,"pushed_at":"2023-02-20T22:59:12.000Z","size":173,"stargazers_count":5,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T02:13:04.075Z","etag":null,"topics":["authentication","controller","tor","tor-control","tor-control-port","tor-controller"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyxnor.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.upstream","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":"2022-01-04T22:41:03.000Z","updated_at":"2024-05-24T13:37:07.000Z","dependencies_parsed_at":"2024-11-13T13:55:09.362Z","dependency_job_id":null,"html_url":"https://github.com/nyxnor/tor-ctrl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxnor%2Ftor-ctrl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxnor%2Ftor-ctrl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxnor%2Ftor-ctrl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxnor%2Ftor-ctrl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyxnor","download_url":"https://codeload.github.com/nyxnor/tor-ctrl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252542568,"owners_count":21764989,"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":["authentication","controller","tor","tor-control","tor-control-port","tor-controller"],"created_at":"2024-11-13T13:44:59.143Z","updated_at":"2025-05-05T17:33:29.573Z","avatar_url":"https://github.com/nyxnor.png","language":"Shell","readme":"# tor-ctrl - control the tor process on the cli\n\nCommand line tool for setting up stream for communication from the Tor Controller's (client) to a Tor process (server). The client send commands using TCP sockets or Unix-domain sockets and receive replies from the server.\n\nThis package is produced independently of, and carries no guarantee from, The Tor Project.\n\n## Table of contents\n\n* [History](#history)\n* [Features](#features)\n* [Configuration](#configuration)\n  * [Control method](#control-method)\n  * [Authentication method](#authentication-method)\n  * [Apply the changes](#apply-the-changes)\n* [Installation](#installation)\n  * [Requirements](#requirements)\n  * [How to install tor-ctrl on any unix system](#how-to-install-tor-ctrl-on-any-unix-system)\n  * [How to build deb package from source sode](#how-to-build-deb-package-from-source-sode)\n    * [Build the package](#build-the-package)\n    * [Install the package](#install-the-package)\n    * [Clean up](#clean-up)\n* [Usage](#usage)\n  * [Circuits](#circuits)\n  * [Streams](#streams)\n  * [Debugging](#debugging)\n    * [Permission denied](#permission-denied)\n    * [Unkown](#unknown)\n\n## History\n\n**tor-ctrl** was created by Stefan Behte, later developed by Patrick Schleizer and further improved by nyxnor.\n\n## Features\n\n**ControlPort**/**ControlSocket**: the following socket types are accepted to connect to the controller:\n* Unix-domain socket, specified as `[unix:]path`\n* TCP socket, specified as `[addr:]port`\n\nAutodetects the socket by reading the tor configuration.\nIf still unknown, will try TCP socket 127.0.0.1:9051.\n\n**Authentication methods**:\n* ~~SAFECOOKIE~~ (on the work, help wanted)\n* COOKIE - discover it by sending PROTOCOLINFO, so no need to specify the file.\n* HASHEDPASSWORD - needs to be specifiedo on the command line\n\n## Configuration\n\nThe configuration lines below must be set inside your tor configuration file (torrc).\n\n### Control method\n\nThis will be the socket that allows those connections to control the Tor process. Choose between `ControlPort` and `ControlSocket` (setting both means either control can be used).\n\n**TCP socket**:\n```sh\nControlPort 9051\n```\n\n**Unix domain socket**:\n```sh\nControlSocket /var/run/tor/control\n## or\n#ControlPort unix:/var/lib/tor/control\n```\n\n### Authentication method\n\nThis is will be the method you will authenticate to the controller. Choose between `CookieAuthentication` and `HashedControlPassword` (Setting both authentication methods means either method is sufficient to authenticate to Tor)\n\n**Cookie**:\n```sh\nCookieAuthentication 1\n```\n\n**Password**\nChange `YOUR_PASSOWRD`, but maintain it double quoted)\n```\nprintf '%s\\n' \"HashedControlPassword $(tor --hash-password \"YOUR_PASSOWRD\")\"\n```\nthe result of the above operation should be used as the configuration line.\n\n### Apply the changes\n\nIf you have made any changes to the tor run commands file (torrc), you will need to send a HUP signal to tor as root to apply the new configuration:\n```sh\npkill -sighup tor\n## or\n#ps -o user,pid,command -A | grep -E \"/usr/bin/tor|/usr/local/bin/tor\"\n#kill -hup PID_FROM_ABOVE\n```\n\nIf you have tor running with `SandBox 1`, you will need to restart tor.\n\n## Installation\n\n### Requirements\n\nAt least one of each item is necessary:\n\n* Networking tool: **nc**/**socat**/**telnet**\n* Hex converter: **xxd**/**hexdump**/**od**\n\n\n### How to install on any unix system\n\nInstall the script and the manual:\n```sh\nsudo ./configure.sh install\n```\n\n### How to build deb package from source sode\n\n#### Build the package\n\nInstall developer scripts:\n```sh\nsudo apt install -y devscripts\n```\n\nInstall build dependencies.\n```sh\nsudo mk-build-deps --remove --install\n```\nIf that did not work, have a look in `debian/control` file and manually install all packages listed under Build-Depends and Depends.\n\nBuild the package without signing it (not required for personal use) and install it.\n```sh\nsudo dpkg-buildpackage -b --no-sign\n```\n\n#### Install the package\n\nThe package can be found in the parent folder.\nInstall the package:\n```sh\nsudo dpkg -i ../tor-ctrl_*.deb\n```\n\n#### Clean up\n\nDelete temporary debhelper files in package source folder as well as debhelper artifacts:\n```sh\nsudo rm -rf *-build-deps_*.buildinfo *-build-deps_*.changes \\\ndebian/*.debhelper.log debian/*.substvars \\\ndebian/.debhelper debian/files \\\ndebian/debhelper-build-stamp debian/tor-ctrl\n```\n\nDelete debhelper artifacts from the parent folder (including the .deb file):\n```sh\nsudo rm -f ../tor-ctrl_*.deb ../tor-ctrl_*.buildinfo ../tor-ctrl_*.changes\n```\n\n## Usage\n\nIt is required to read the [tor manual](https://gitweb.torproject.org/tor.git/tree/doc/man/tor.1.txt) and the [control-spec](https://gitweb.torproject.org/torspec.git/tree/control-spec.txt).\n\nRead tor-ctrl's manual:\n```sh\nman tor-ctrl\n```\n\nSee usage:\n```sh\ntor-ctrl -h\n```\n\nGet the tor user configured on tor configuration files:\n```sh\ntor-ctrl GETCONF User\n```\n\nGet the username under which the tor process is running:\n```sh\ntor-ctrl GETINFO process/pid\n```\n\nGet process id belonging to the main tor process:\n```sh\ntor-ctrl GETINFO process/pid\n```\n\n### Circuits\n\nSwitch to clean circuits:\n```sh\ntor-ctrl SIGNAL NEWNYM\n```\n\nGet your circuits (raw):\n```sh\ntor-ctrl GETINFO circuit-status\n```\n\nThat is not very clean to read, too much information, so lets organize it:\n```sh\ntor-ctrl-circuit\n```\n\n### Streams\n\nStart listening for streams:\n```sh\ntor-ctrl -w SETEVENTS STREAM\n```\nFrom another terminal, connect via Tor to where you wish\n```sh\ncurl -x socks5h://127.0.0.1:9050 https://check.torproject.org/api/ip\n```\nReturn to the script and and watch the streams. Use the interrupt signal (Ctrl+C) to stop.\n\nAnd if we could see the streams and to which circuit they are attached to and what is their target?\n```sh\ntor-ctrl-stream\n```\nFrom another terminal, connect via Tor to where you wish:\n```sh\ncurl -x socks5h://127.0.0.1:9050 github.com\n```\nReturn to the script and use the interrupt signal (Ctrl+C) to print out the stream events received.\n\n### Tor Browser Bundle\n\ntor-ctrl can connect to any Tor socket, even to the Tor Browser Bundle socket.\n\nOpen Tor Browser but don't connect to the network yet. The default socket is `127.0.0.1:9151`, so specify it when running tor-ctrl:\n```sh\ntor-ctrl-stream -s 9151\n```\nNote: On Whonix-Gateway, there is no need to specify the socket, it will be auto-detected.\n\nConnect to the network, you will watch every stream that is made. Browse to any website you'd like to visit.\n\nIf you plan to share your streams because you saw some unwanted connections being made, don't forget to use the `-z` option, so circuits paths are not shown.\n\n### Debugging\n\n#### Permission denied\n\nIf you receive permission denied, probably you are not running tor-ctrl with the user that can connect to tor's controller socket, which is the tor user in some cases.\n\nOn Tails:\n```sh\nsudo -u debian-tor tor-ctrl GETINFO version\n```\nOn OpenBSD:\n```sh\ndoas -u _tor tor-ctrl GETINFO version\n```\n\n#### Unknown\n\nIf the response is unexpected, run with option `-r` to get the information that will be used to connect to tor's controller. If they are correct, use option `-d` to debug the script and be very verbose.\n\n**Warning: You should review the information before posting on a issue, because it can contain the authentication string (password and cookie hex) and the control host, in the case the host is external (not localhost), anyone with both information will be able to authenticate to your controller. If you haven't set the authentication method and the control host is external and shared, this is far worse as there is no authentication string, so strongly recommended to configure an [authentication method for your controller](#authentication-method).**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxnor%2Ftor-ctrl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyxnor%2Ftor-ctrl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxnor%2Ftor-ctrl/lists"}