onion-grater: a Tor Control Port Filter Proxy
Information about onion-grater.
onion-grater is a filter proxy that denies every controller command by default and allow specific commands, arguments and events that are explicitly whitelisted. It is a Tails project forked by Whonix™ with some adaptations.
Acts as a proxy between the client application and Tor:
- Filters out Tor control protocol commands that are dangerous for anonymity such as
GETINFO ADDRESSusing a whitelist.
- Allows using Tor Browser's New Identity feature on Anonymity Distribution Workstations.
- Fixes Tor Browser's about:tor default homepage and Tor Button status indicator without exposing commands that are dangerous for anonymity.
The following onion-grater warning is shown for all applications that require it.
Applications that require onion-grater
A list of applications which currently require onion-grater so these can be used in Whonix can be found here: Special:WhatLinksHere/Template:Control_Port_Filter_Python_Profile_Add
Extend the onion-grater whitelist in Whonix-Gateway™ (
Add onion-grater profile.
sudo onion-grater-add 40_onion_authentication
Reduce the onion-grater whitelist in Whonix-Gateway™ (
Remove onion-grater profile.
sudo onion-grater-remove 40_onion_authentication
List the onion-grater whitelist in Whonix-Gateway™ (
List available onion-grater profiles:
sudo onion-grater-list --available --show
List used onion-grater profiles: sudo onion-grater-list --used --show
- By using Whonix, additional protections are in place for greater security.
- This application requires access to Tor's control protocol.
- In the Whonix context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
- Whonix provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
- When this application is run inside Whonix-Gateway with an onion-grater whitelist extension, this will limit Whonix-Workstation application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances. In the event Whonix-Workstation, it can't determine its own IP address via requesting to Tor Controller, as onion-grater filters the reply.
- In comparison, if the application is run on a non-Tor focused operating system like Debian, it will have unlimited access to Tor's control protocol (a less secure configuration).
- If the (non-)Whonix platform is used to host onion services, then running applications are more vulnerable to attacks against the Tor network compared to when Tor is solely used as a client; see also Onion Services Security.