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 backups with user mapping.

The command line utility is still under active development. 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.
  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 value is changed for the user running sudo, not for root. If you want to change something on behalf of another user, use the --user option.

list-preferences

$ 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
    ...

The options -g and -o limit output to only global or user-specific preferences.

read-preference

$ 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"
]

write-preference

$ 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. Example 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

where 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.

export-model

$ 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.

restore-model

$ 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, you can export a JSON model with export-model, modify the resulting JSON code in whatever way you like and re-import it with restore-model.

Note that restoring a backup disables command line access if it was disabled at the time the backup was made!

debug-topics

$ 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.

log

$ 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.

log-traffic

$ 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 --begin-date and --end-date or view live statistics with --stream (which can be combined with --begin-date). Output is in CSV format and the first row always represents the field names.

Each row represents statistics over the time interval since the previous row.

Field Name	Description
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.

recrypt-config

$ 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.

capture-traffic

$ 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 connectingExecutable and parentAppExecutable columns).

Example:

$ 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) → 17.253.144.10/ICMP:0:
=== Terminal+ping(9624/501) → 17.253.144.10/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|
=== 17.253.144.10/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|
...

With option --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.