onion-grater: a Tor Control Port Filter Proxy

From Whonix



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.

Ambox notice.png 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.