Little Snitch Help

The .lsrules file format

Rule group subscriptions use a .lsrules file, which is a JSON format specified in this chapter. Such files can be exported using Little Snitch Configuration or using a text editor or a script.

A simple example

Let’s start with a simple example that specifies a single rule for allowing software updates for LaunchBar:

{
  "name": "LaunchBar Software Update",
  "description": "This rule allows LaunchBar to check for updates.",
  "rules": [
    {
      "action": "allow",
      "process": "/Applications/LaunchBar.app/Contents/MacOS/LaunchBar",
      "remote-hosts": "sw-update.obdev.at"
    }
  ]
}

Blocklists

A common use case for rule group subscriptions are blocklists that contain a lot of domains, hosts, or IP addresses for which access should be flat out denied. Using the above syntax, you’d have to repeat "process": "any" and "action": "deny" for each domain, host, or IP address. For thousands of rules, that can lead to unnecessarily large files that in turn lead to unnecessarily large downloads for every single subscriber.

Starting in Little Snitch 4.2, you can use a more compact format that looks like this:

{
    "name": "Social Media Block List",
    "description": "Blocks access to popular social media sites.",
    "denied-remote-domains": ["facebook.com", "twitter.com", "youtube.com"]
}

Top-level keys

The top level of an .lsrules file is a JSON dictionary with the following keys:

Key Type Description
name String The name of the group.
description String A description of the rule grouop.
rules Array of Dictionaries The list of rules. See below for rule-level keys.

To efficiently support blocklists, the following keys were added in Little Snitch 4.2:

Key Type Description
denied-remote-domains Array of Strings A list of domain names.
denied-remote-hosts Array of Strings A list of hostnames.
denied-remote-addresses Array of Strings A list of IP addresses. See Anatomy of a rule > Server (remote computer) for supported syntax.
denied-remote-notes String The notes that should be repeated for each rule. The placeholder %REMOTE% will be replaced with the respective domain, host, or IP-address for each rule.

You can mix all of these keys in a single .lsrules file, i.e. you can define arbitrary rules in a rules array next to a list of domains in denied-remote-domains and a list of IP addresses in denied-remote-addresses.

Rule keys

Each rule defined in the file is a JSON dictionary with the following keys:

Specifying the process

To define which processes a rule should match, you specify the executable of the process using the following keys:

Specifying the remote

The remote for the rule can be specified in multiple ways. You can only provide one of the following keys:

Other keys

Key Type Description
direction String, optional The connection direction. "incoming" or "outgoing", defaults to "outgoing".
action String, optional The rule action. "allow", "deny", or "ask". Defaults to "ask".
priority String, optional The rule priority. "regular" or "high". Defaults to "regular".
disabled Boolean, optional Whether or not the rule is disabled by default. Defaults to false.
ports String, optional The ports the rule matches. Can be "any" for any port (the default), a single port (e.g. "443"), or a range of ports (e.g. "123-456").
protocol String, optional The protocol the rule matches. Can be a numeric value as defined in /etc/protocols, like "6" for TCP, or the actual protocol name, like "tcp". Defaults to any protocol.
notes String, optional The notes for the rule.

Was this help page useful? Send feedback.
© 2016-2019 by Objective Development Software GmbH