onion-grater: a Tor Control Port Filter Proxy

From Whonix
Jump to navigation Jump to search

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 ADDRESS using 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 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 in Whonix-Gateway (sys-whonix).

On Whonix-Gateway.

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]


  1. Security considerations:
    • 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.
    In conclusion, Whonix is the safest and correct choice for running this application.

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 12 year success story and maybe DONATE!