Command line utility

Little Snitch comes with a command line utility, littlesnitch. It’s powerful, and that makes it attractive to malware as well. That’s why most of its commands work only while Little Snitch > Settings > Security > Allow access via Terminal is on. Turn on this setting only if you need the command line utility.

The command line utility is for three kinds of tasks:

Configuration changes for mass deployment, for the administrators of larger organizations.
Internal information that helps you and our support team find the cause of a problem.
Functions for experts, such as capturing traffic or importing backups with user mapping.

Use the built-in help

The command line utility has built-in help. To see the general help, run:

$ 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:
  capture-traffic .... Captures traffic of a particular process or process pair.
  debug-categories ... Sets categories to be logged in more detail.
  export-model ....... Exports the entire data model in JSON format (backup).
  list-preferences ... Lists all preferences.
  log ................ Reads Little Snitch log messages.
  log-traffic ........ Prints data from traffic log.
  profile ............ Activates or deactivates profiles.
  read-preference .... Reads a preference value.
  recrypt-config ..... Copies configuration files changing the encryption key.
  restore-model ...... Restores the current data model from backup.
  restrictions ....... Show restrictions.
  rulegroup .......... Enables or disables rule groups and blocklists.
  update-rule-groups . Updates factory rule groups with rules for currently installed apps.
  write-preference ... Writes a preference value.

For more information about a particular command use

    littlesnitch <command> --help

Requirements

Most commands have two requirements:

You run littlesnitch as the superuser root (sudo littlesnitch).
Allow access via Terminal is on in Settings > Security.

A few commands are exceptions:

log: Has neither requirement.
restrictions: Doesn’t require root.
capture-traffic and debug-categories: Don’t require Allow access via Terminal.
recrypt-config: Doesn’t require Allow access via Terminal if you give the current encryption key with -c.

Some commands act on a particular user, for example when you change a user-specific setting. littlesnitch then changes the value for the user who runs sudo, not for root. To change a value for a different user, use the option --user.

The following sections describe each command.

capture-traffic

$ littlesnitch capture-traffic --help
usage: littlesnitch capture-traffic [-hp] [-v <via process path>] <process path>
     [<output file>]
  -h, --help
        Print a short help and exit.
  -v, --via <via process path>
        Capture only if the connection is made via the given helper process.
  -p, --pcap
        Use pcap output format.

This command captures all network traffic of one executable, and writes it to a file or to the standard output. Give the path of the executable. In some special cases, such as scripts, Java executables, and executables in temporary folders, give the string that log-traffic shows in the columns connectingExecutable and parentAppExecutable instead.

Example

$ sudo littlesnitch capture-traffic -p /System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal -v /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 the option --pcap, the command wraps the captured data in artificial protocol frames (TCP/UDP/ICMP, IP/IPv6, Ethernet) and writes it in PCAP format, which protocol analyzers such as Wireshark can decode.

debug-categories

$ littlesnitch debug-categories --help
usage: littlesnitch debug-categories [-adfhs] [<categoryName>, ...]
  -h, --help
        Print a short help and exit.
  -a, --add
        Add to current set of categories.
  -d, --delete
        Delete from current set of categories.
  -s, --set
        Set current set of categories.
  -f, --factory-reset
        Reset to factory default.

This command is mainly for tracking down bugs and unexpected behavior together with our support team. If you need it, our support team will tell you which options and arguments to use.

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 as File > Create Backup… in the Little Snitch app. Without an output file, it writes the backup in JSON format to the standard output.

For more information about backups, see Backup and restore.

list-preferences

$ littlesnitch list-preferences --help
usage: littlesnitch list-preferences [-ghu]
  -h, --help
        Print a short help and exit.
  -g, --global-only
        Only show preferences affecting all users.
  -u, --user-only
        Only show preferences affecting the current user.

Without options, this command lists all settings of Little Snitch and their values:

$ sudo littlesnitch list-preferences
    activeSilentMode = 0
    allowCommandLineAccess = true
    allowGUIScripting = false
    allowGlobalEditing = true
    ...

With the option -g, the command shows only the global settings. With the option -u, it shows only the user-specific settings.

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 a front end for the macOS command log, with filters set up for Little Snitch. To see older messages, use the option --last with a time interval. To watch messages live, use --stream. Like debug-categories, it’s mainly for tracking down bugs together with our support team, who will tell you which options and arguments to use.

Unlike the other commands, log requires neither root nor Allow access via Terminal.

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 the data behind Network Monitor. To choose a time interval, use --begin-date and --end-date. For live statistics, use --stream, optionally together with --begin-date. The output is in CSV format, and the first row always contains the field names.

Each row contains the statistics for the time since the previous row.

Field Name	Description
date	Start date of the time interval
direction	The string “in” for incoming connections or “out” for outgoing connections
uid	UID of the process
ipAddress	IP address of the server
remoteHostname	Hostname for which the DNS lookup returned the IP address
protocol	Number of the IP protocol, for example 6 for TCP or 17 for UDP
port	Port number of the server for outgoing connections, port number on your Mac for incoming connections
connectCount	Number of new connections in the time interval
denyCount	Number of connection attempts that Little Snitch denied in the time interval
byteCountIn	Number of bytes received in the time interval
byteCountOut	Number of bytes sent in the time interval
connectingExecutable	A string that describes the executable of the process that started the connection
parentAppExecutable	If the connecting executable is not an app, Little Snitch tries to find the app that is responsible for it. If Little Snitch finds this app, this string describes it.

profile

$ littlesnitch profile --help
usage: littlesnitch profile [-dh] [-a <profile name>]
  -h, --help
        Print a short help and exit.
  -a, --activate <profile name>
        Activate the profile.
  -d, --deactivate-all
        Deactivate all profiles.

Without options, this command lists all profiles, and marks the active one with “(active)”:

$ sudo littlesnitch profile
Home
Public Wi-Fi (active)
Work

To activate a profile, give its name, exactly as in Little Snitch, with --activate. Put a name with spaces in quotes:

sudo littlesnitch profile --activate "Public Wi-Fi"

To deactivate all profiles, use --deactivate-all. Then only the rules that aren’t in a profile apply.

read-preference

$ littlesnitch read-preference --help
usage: littlesnitch read-preference [-h] <preference key>, ...
  -h, --help
        Print a short help and exit.

This command prints the value of a setting in JSON format, for example:

$ sudo littlesnitch read-preference dontShowDenyConsequencesAgain
[
  "com.DanPristupov.Fork"
]

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 encryption key to decrypt the current configuration. Required
        if the daemon connection is not available.
  -p, --password <new encryption key>
        Write out configuration files using this encryption key. Defaults to
        "none".

Little Snitch encrypts all configuration files on disk, with an encryption key that it keeps in the System keychain under the name “Little Snitch Encryption Key”. When our support team asks for a copy of a configuration file, decrypt it first with this command. That way, you don’t have to send your encryption key along with the file in a plain email.

Without arguments, the command copies all configuration files to the current directory and changes their encryption key to “none”, reading the current key from the System keychain. To change what it does, give configuration files as arguments, the current encryption key with -c, or the new encryption key with -p.

With the current encryption key given via -c, the command works even if Little Snitch is damaged, and even if Settings > Security > Allow access via Terminal is off.

restore-model

$ littlesnitch restore-model --help
usage: littlesnitch restore-model [-hlt] [-m backupUID > localUID, ...] [-p
     <encryption key>] [<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. Rules and settings
        of users not in the mapping are not restored.
  -p, --password <encryption key>
        Optional. When importing a configuration.xpl file from a different
        computer, the encryption key "Little Snitch Encryption Key" from the
        System keychain may be required.
  -t, --preserve-terminal-access
        If Terminal access is currently enabled, preserve it regardless of
        imported settings.

This command imports these backups and configuration files of Little Snitch:

Backups in JSON format.
Backups of Little Snitch 3 and 4.
Configuration files of Little Snitch 3 to 7.

Without an input file, restore-model reads the backup from the standard input, so you can pipe (|) the output of another command into it.

Backups and configuration databases usually contain the settings of all users of the Mac, identified by their Unix user ID, a small integer. On a different Mac, the same people can have different user IDs. In that case, tell Little Snitch which user on the old Mac is which user on the new one.

When you import data from a different Mac, first list the users in the file:

$ sudo littlesnitch restore-model --list-users ~/configuration6.xpl
   uid: short name       full name
----------------------------------------------------------------------
     0: root             System Administrator             (86 rules)
   248: _mbsetupuser     -                                (7 rules)
   501: user1            First User                       (403 rules)
   502: user2            Second User                      (55 rules)

The user names help you map the users. If the file has no user names, the number of rules can help you tell them apart. In the example above, user 248 hardly used Little Snitch, user 501 used it the most, and user 502 was probably a test account.

To import a backup without changes (using the example file from above):

sudo littlesnitch restore-model ~/configuration6.xpl

If your user ID on the new Mac is different, add a mapping:

$ id -u
502

$ sudo littlesnitch restore-model --map-users "0 > 0, 501 > 502" ~/configuration6.xpl

Little Snitch discards the rules and settings of users who aren’t in the mapping.

To change the data model with a script, export it in JSON format with export-model, change the JSON as needed, and import it again with restore-model.

Use the option --preserve-terminal-access to keep command line access. If command line access was off when the backup was made, restoring the backup turns it off, and you lose access to the command line utility.

restrictions

$ littlesnitch restrictions --help
usage: littlesnitch restrictions [-h]
  -h, --help
        Print a short help and exit.

This command shows the restrictions of your license, for example whether you have a license key and whether it expires. Without a license key, it also shows the limits of demo mode for the network filter and for Network Monitor.

This command doesn’t require root.

rulegroup

$ littlesnitch rulegroup --help
usage: littlesnitch rulegroup [-h] [-e <group name>] [-d <group name>]
  -h, --help
        Print a short help and exit.
  -e, --enable <group name>
        Enable the rule group or blocklist.
  -d, --disable <group name>
        Disable the rule group or blocklist.

Without options, this command lists all rule groups and blocklists, and whether each is enabled:

$ sudo littlesnitch rulegroup
My Blocklist (disabled)
iCloud Services (enabled)
macOS Services (enabled)

To enable or disable a rule group or a blocklist, give its name with --enable or --disable:

sudo littlesnitch rulegroup --enable "My Blocklist"

update-rule-groups

$ littlesnitch update-rule-groups --help
usage: littlesnitch update-rule-groups [-aht]
  -h, --help
        Print a short help and exit.
  -a, --apple-apps
        Update Apple Apps group only
  -t, --third-party-apps
        Update Third Party Apps group only

This command creates or updates app rule groups, just like adding the rule group in the Little Snitch app.

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 changes a setting, converting the value that you give to the type of the setting. Here are examples for each type:

         boolean: true, false
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= (Base64-encoded)

You can set the elements of dictionaries and arrays only one at a time. For example, to add an entry to an array:

sudo littlesnitch write-preference dontShowDenyConsequencesAgain.1 at.obdev.launchbar

Here, 1 is the index of the element that the command writes.

Don’t turn off command line access by mistake: after sudo littlesnitch write-preference allowCommandLineAccess false, the command line utility stops working. To turn command line access on again, you need the settings of the Little Snitch app.