Command line utility
Due to popular demand, Little Snitch is now scriptable, it comes with a command line tool. Since this
littlesnitch command is very powerful and can potentially be misused by malware, most of its functionality is only available when enabled in Little Snitch > Preferences > Security > Allow access via Terminal. We recommend that you enable access to the command line tool only as long as you need it. When access is enabled, you must take precautions that untrusted processes cannot gain root privileges.
Functions in the command line interface cover the following areas:
- Allowing configuration changes for mass deployment (for sysadmins of big companies).
- Obtaining particular internal information to help debugging problems together with our support team.
- Expert functionality such as filter verification, traffic capturing and importing of backups with user mapping.
The command line utility is a moving target. Experimental features are tested here and the documentation may therefore be out of date.
Using built-in help
The command line tool comes with a built-in help system providing basic usage information. For a general help, use:
$ littlesnitch --help usage: littlesnitch [-hv] [-u <user name or numeric ID>] command [<command args>] -h, --help Print a short list of available commands and options. -u, --user <user name or numeric ID> The command line tool is executed on behalf of a user. You can specify the user here. -v, --version Print the current version of Little Snitch. Commands: list-preferences ... Lists all preferences. read-preference .... Reads a preference value. write-preference ... Writes a preference value. export-model ....... Exports the entire data model in JSON format (backup). restore-model ...... Restores the current data model from backup. debug-topics ....... Sets topics to be logged in more detail. log ................ Reads Little Snitch log messages. log-traffic ........ Prints data from traffic log. recrypt-config ..... Copies configuration files changing encryption password. verify-filter ...... Turns filter verification on/off. capture-traffic .... Captures traffic of a particular process or process pair. For more information about a particular command use littlesnitch <command> --help
There is little to add to this info. Most subcommands require that you run
littlesnitch as root (
sudo littlesnitch). If the command behaves differently for different users (e.g. setting a user specific preference), the the value is changed for the user running
sudo, not for root. If you want to change something on behalf of an other user, use the
$ littlesnitch list-preferences --help usage: littlesnitch list-preferences [-ghu] -h, --help Print a short help and exit. -g, --global-only Show only preferences affecting all users. -u, --user-only Show only preferences affecting the current user.
Without any options, this command lists all Little Snitch preference options and their values:
$ sudo littlesnitch list-preferences activeSilentMode = 0 allowCommandLineAccess = true allowGUIScripting = false allowGlobalEditing = true ...
-o limit output to only global or user-specific preferences.
$ littlesnitch read-preference --help usage: littlesnitch read-preference [-h] <preference key>, ... -h, --help Print a short help and exit.
This command prints a preference value in JSON format, e.g.:
$ sudo littlesnitch read-preference dontShowDenyConsequencesAgain [ "com.DanPristupov.Fork" ]
$ littlesnitch write-preference --help usage: littlesnitch write-preference [-hr] <key> [<new value>] -h, --help Print a short help and exit. -r, --remove Remove the value for the given key.
This command is used to modify preferences. The value argument is converted to the type of the preference. Examples values for types are:
boolean: true, fals unsigned integer: 23, 9953274 integer: -25, 2147483647 floating point: -547.23, 993.13 date: 2021-05-01T13:11:59 string: any text you like data: QmFzZTY0IGVuY29kZWQgZGF0YQo= (base 64 encoded)
Dictionary and array elements can only be set individually. If you want to add an entry to an array, use e.g.:
sudo littlesnitch write-preference dontShowDenyConsequencesAgain.1 at.obdev.launchbar
1 represents the index to be written.
Note that you can disable the command line utility with
sudo littlesnitch write-preference allowCommandLineAccess false. If you do that, you lock yourself out and you must go back to the preferences dialog to enable it.
$ littlesnitch export-model --help usage: littlesnitch export-model [-h] [<output file>] -h, --help Print a short help and exit.
This command does the same thing as the user interface action Little Snitch > File > Create Backup…. If no output file is specified, the backup data (JSON representation) is written to standard output.
$ littlesnitch restore-model --help usage: littlesnitch restore-model [-hl] [-m backupUID > localUID, ...] [-p <password>] [<input file>] -h, --help Print a short help and exit. -l, --list-users Do not actually restore, just list users contained in the file. -m, --map-users backupUID > localUID, ... Provide a mapping between backup and local user-IDs. -p, --password <password> Optional. When importing a configuration.xpl file from a different computer, the "Little Snitch Encryption Key" from the system keychain may be required.
This command imports backups and configuration database files from various versions of Little Snitch. You can use it to import backups in JSON format, backups from Little Snitch 3 and 4 as well as current configurations from other instances of Little Snitch 3, 4 or 5.
Backups and configuration databases usually contain settings for all users on the computer where users are identified by their User Identifier, a small integer number. When you import data from a different computer, users may have different identifiers and you may want to tell Little Snitch which user on the old computer corresponds to which user on the new computer.
If you import data from a different computer, first list the users in the archive:
$ sudo littlesnitch restore-model --list-users ~/LittleSnitch-2019-10-15.xpl uid: short name full name ---------------------------------------------------------------------- 0: - - (86 rules) 248: - - (7 rules) 501: - - (403 rules) 502: - - (55 rules)
The archive in this example has been created by Little Snitch 4 where no user names were stored. User names help you with the mapping. If no user names are available, you can probably distinguish users by the number of rules. User 248 in the example above never really used Little Snitch. And you can see that user 501 was primarily active while 502 probably was a test account.
If you want to import a backup as-is, just use (with the example backup file from above):
sudo littlesnitch restore-model ~/LittleSnitch-2019-10-15.xpl
However, if you have a different User ID on the new computer, you need to set a mapping:
$ id -u 502 $ sudo littlesnitch restore-model --map-users "0 > 0, 501 > 502" ~/LittleSnitch-2019-10-15.xpl
Rules and settings from users which are not mapped are discarded.
If you need to perform any automated changes in the data model (hey, nerdy sysadmins!), you can export a JSON model with
export-model, modify the resulting JSON code in whatever way you like and re-import it with
Note that restoring a backup disables command line access if it was disabled at the time the backup was made!
$ littlesnitch debug-topics --help usage: littlesnitch debug-topics [-adfhls] [<topicName>, ...] -h, --help Print a short help and exit. -a, --add Add to current set of topics. -d, --delete Delete from current set of topics. -s, --set Set current set of topics. -f, --factory-reset Reset to factory default.
This command is primarily made for analyzing bugs and unexpected behavior with guidance from our support. If you need this command, our support team will tell you what options and arguments you should use.
$ littlesnitch log --help usage: littlesnitch log [-adfhjs] [-l <time>[m|h|d]] [-p <log predicate>] -h, --help Print a short help and exit. -l, --last <time>[m|h|d] Show entries not older than the given time. Defaults to 10 minutes. -s, --stream Live stream log messages. -a, --all Also show log messages from frameworks. -f, --frameworks-only Show log messages from frameworks only. -d, --show-debug Show debug messages from frameworks. -p, --predicate <log predicate> Use the given predicate string to filter messages. -j, --json Output in JSON format.
This command is basically a frontend to the macOS
log command, using preconfigured filters suitable for Little Snitch. Use the option
--last to see messages from the past, or
--stream to watch messages live. This command is primarily made for analyzing bugs and unexpected behavior with guidance from our support. If you need this command, our support team will tell you what options and arguments you should use.
Contrary to other commands, the
log command is available to non-root users and does not require the “Allow access via Terminal” preference to be enabled.
$ littlesnitch log-traffic --help usage: littlesnitch log-traffic [-hs] [-b <YYYY-MM-DD HH:MM:SS>] [-e <YYYY-MM-DD HH:MM:SS>] -h, --help Print a short help and exit. -b, --begin-date <YYYY-MM-DD HH:MM:SS> Optional. Where to begin reading logged traffic history. If not specified, no historic data is printed. -e, --end-date <YYYY-MM-DD HH:MM:SS> Optional. Where to stop reading logged traffic history. -s, --stream Optional, incompatible with --end-date. Stream live traffic statistics.
This command gives you access to the underlying data visualized by Network Monitor. You can specify a time range with
--end-date or view live statistics with
--stream (which can be combined with
--begin-date). Output is in CSV format and the first line always represents the field names.
Each line represents statistics over the time interval since the previous line.
|date||Start date of the time interval|
|direction||The string “in” for inbound connections or “out” for outbound|
|uid||UID of the communicating process|
|ipAddress||Remote internet address|
|remoteHostname||Remote computer name used to look up the IP address|
|protocol||Numeric Internet protocol (e.g. 6 for TCP, 17 for UDP)|
|port||Remote port number for outgoing connections, local port number for incoming|
|connectCount||How often new connections were established during the statistics time interval|
|denyCount||How often connection attempts were denied during the statistics time interval|
|byteCountIn||Number of bytes received during statistics time interval|
|byteCountOut||Number of bytes sent during statistics time interval|
|connectingExecutable||A string describing the executable of the process which established the connection|
|parentAppExecutable||If the connecting executable is not an application, Little Snitch tries to find a responsible application. If one is found, this string represents the parent app.|
$ littlesnitch recrypt-config --help usage: littlesnitch recrypt-config [-h] [-c <current encryption key>] [-p <new encryption key>] [<config file path>, ...] -h, --help Print a short help and exit. -c, --current-password <current encryption key> Use this password for decrypting current configuration. Required if the daemon connection not available. -p, --password <new encryption key> Write out configuration files using this encryption key. Defaults to "none".
All files storing configuration data on disk are encrypted with a password stored in the macOS System Keychain. When our support needs a copy of a configuration file, it is useful to decrypt this particular file before transmission instead of sending your password along with the file in plain e-mail.
When run without any arguments, this command copies all configuration files to the current directory, changing their encryption password to “none”. The current password is read from the Keychain. You can customize this behavior by specifying a particular file, password or target password.
$ littlesnitch verify-filter --help usage: littlesnitch verify-filter [-h] [on|off] -h, --help Print a short help and exit.
This command is used to turn filter verification on or off. When run without any arguments, it prints the current status of filter verification.
When filter verification is active, Little Snitch tracks network traffic on the network interface level (via BPF devices) and verifies whether all connections have been presented to the network filter at the Network Extension level. Connections entering the network stack after the Network Extension level are shown in Network Monitor and tagged as “bypassing the filter”.
As far as we can tell from current experience, only network packets originating in Kernel Extensions and Hypervisors (such as VMWare or Parallels) can bypass the Network Extension filter.
$ littlesnitch capture-traffic --help usage: littlesnitch capture-traffic [-ch] [-p <parent app path>] <process path> [<output file>] -h, --help Print a short help and exit. -p, --parent <parent app path> Capture only if the process has been started by the given parent application. -c, --pcap Use pcap output format.
This command captures all network traffic from a particular executable and outputs it to a file or to standard output. The executable is selected by path (or, in special cases such as scripts, Java executables or executables in temporary paths, the string used by
log-traffic in the
$ sudo littlesnitch capture-traffic -p /System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal /sbin/ping Starting Sniffing. Stop by hitting ^C. +++ connect Terminal+ping(9624/501) → 220.127.116.11/ICMP:0: === Terminal+ping(9624/501) → 18.104.22.168/ICMP:0: 08 00 32 da 98 25 00 00 60 91 47 bd 00 07 99 a7 |..2..%..`.G.....| 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 |................| 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 |........ !"#$%&'| 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 36 37 |()*+,-./01234567| === 22.214.171.124/ICMP:0 → Terminal+ping(9624/501): 45 00 40 00 ae 4b 00 00 36 01 72 bd 11 fd 90 0a |E.@..K..6.r.....| c0 a8 00 f1 00 00 3a da 98 25 00 00 60 91 47 bd |......:..%..`.G.| 00 07 99 a7 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 |................| 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 |............ !"#| 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 |$%&'()*+,-./0123| 34 35 36 37 |4567| ...
--pcap, captured data is wrapped into faked protocol frames (TCP/UDP/ICMP, IP/IPv6, Ethernet) and stored in PCAP format. This is the format which can be decoded by powerful protocol analyzers such as Wireshark.
Was this help page useful? Send feedback.
© 2016-2021 by Objective Development Software GmbH