onion-grater: a Tor Control Port Filter Proxy
Donate
Information about onion-grater.
Introduction[edit]
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.
onion-grater Warning[edit]
The following onion-grater warning is shown for all applications that require it.
This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway™ modifications are therefore necessary for full functionality; see the instructions below.
For better security, consider using Multiple Whonix-Gateway and Multiple Whonix-Workstation™. In any case, Whonix is the safest choice for running it. [1]
Applications that require onion-grater[edit]
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
Add Profile[edit]
Extend the onion-grater whitelist.
On Whonix-Gateway (sys-whonix).
Add onion-grater profile.
sudo onion-grater-add 40_onion_authentication
Remove Profile[edit]
Reduce the onion-grater whitelist in Whonix-Gateway™ (sys-whonix).
On Whonix-Gateway.
Remove onion-grater profile.
sudo onion-grater-remove 40_onion_authentication
List Profile[edit]
List the onion-grater whitelist in Whonix-Gateway™ (sys-whonix).
On Whonix-Gateway.
List available onion-grater profiles:
sudo onion-grater-list --available --show
List used onion-grater profiles: sudo onion-grater-list --used --show
See Also[edit]
Footnotes[edit]
- ↑
Security considerations:
- By using Whonix, additional protections are in place for enhanced 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, it limits 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 this event, Whonix-Workstation cannot determine its own IP address via requests to the Tor Controller, as onion-grater filters the reply.
- In comparison with other operating systems:
- If the application is run on a non-Tor-focused operating system like Debian: The application will have unlimited access to Tor's control protocol (a less secure configuration).
- Whonix: The application's access to Tor's control protocol is limited. Only whitelisted Tor control protocol commands required by the application are allowed.
- Comparison of using Tor as a client versus hosting Tor onion services.
- Using Tor only as a client: More secure.
- When hosting Tor onion services: Users are more vulnerable to attacks against the Tor network. This is elaborated in chapter Onion Services Security.
The most watertight privacy operating system in the world.
At
Whonix we value freedom and trust, supporting Open Source and Freedom Software
2012-
2025 ENCRYPTED SUPPORT LLC
We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!