Rule group subscriptions

Rule groups are sets of rules that anyone can create and publish on their web server for others to subscribe to. Whenever changes to the rules are made by the publisher, subscribers receive these changes.

This is useful for providing automatically updating block lists, distributing rules on multiple computers, or for app developers who want to provide a set of rules to their customers to make it work seamlessly with Little Snitch.

If you want to try out a sample rule group subscription, we are hosting an example blocklist that you can subscribe to.

Limitations of rule group subscriptions

• Global — Rules from a subscription are global by design, so any changes you make to them (subscribe, unsubscribe, activate, deactivate, etc.) will affect all users on the computer and therefore require the Allow Global Rule Editing option to be turned on in Preferences > Security. Otherwise you will have to enter an administrator password whenever you make changes to a rule group subscription.
• Protected — Because rules from a subscription are maintained by someone else and are updated via the Internet, they are protected and cannot be edited by subscribers. However, these rules can be disabled, either individually or all at once by disabling the entire group.
• Effective in all profiles — Rules from a subscription are always effective in all profiles (unless they are disabled). They cannot be added to individual profiles.
• HTTPS — For security reasons, Little Snitch requires that rule groups are published via HTTPS. Unencrypted HTTP connections are not supported.

Subscribing to rule groups

To subscribe to a rule group that someone else has published, open Little Snitch Configuration and choose File > New Rule Group Subscription. In the dialog, enter the URL of the rule group. Only HTTPS URLs are supported.

Rule groups can contain rules with any action, e.g. allow, deny, or ask. By default, rules that allow connections are added as disabled rules until you review them and enable them yourself. This is to make sure that no rules that allow connections are added without your consent. If you do not want this additional protection, you can uncheck Disable new Allow-rules.

You can choose the update interval at which Little Snitch will connect to the publisher’s server and check for updates to the rule group.

Whenever new rules are added or existing rules are modified in an update in a way that affects what connections it allows or denies, Little Snitch will show a notification in the top-right corner of the screen and mark these rules as unapproved for you to review.

Editing rule group subscriptions

After subscribing to a rule group, the group is shown in the Rule Groups section in the left sidebar of Little Snitch Configuration. By double-clicking the group, you can view and edit settings and change the group’s name.

You can enable or disable individual rules in a rule group by clicking the checkboxes in the list. You can also enable and disable a whole group using the checkbox next to the group name in the left sidebar.

The rules themselves cannot be edited, though, as indicated by the lock symbol to the right of the rules. However, you can disable them and then add a copy to your ruleset by duplicating it. This copy can then be edited like any other rule you created. Note that any updates to that rule made by the publisher of the rule group will not affect the copy you created.

Unsubscribing from a rule group

Unsubscribing from rule groups will stop checking for updates and will also delete the rules in that group from your ruleset. If you want to keep some or all of the rules, you can duplicate them before unsubscribing, as described above.

To unsubscribe, right-click on the rule group in the left sidebar and choose Unsubscribe from the menu.

Publishing rule groups

To publish a rule group you need two things: First, the rules you want to publish in a .lsrules file. Second, a web server that is accessible via HTTPS.

As a publisher of a rule group, keep a few things in mind:

• Provide a meaningful description to your rule group. Subscribers have to trust you to only add rules that match what the description says.
• Subscribers may choose to disable automatic updates for your rule groups. Don’t expect that modifications you make are guaranteed to reach all subscribers.
• By default, subscribers will need to manually enable Allow-rules you add.

Creating a rule group file

The easiest way to create a rule group file is by selecting the rules to publish in Little Snitch Configuration and choosing File > Export Selected Rules….

Alternatively, you can create the .lsrules file using a text editor or a script. The latter option allows you to dynamically create the JSON depending on parameters passed in the URL used for subscribing. The chapter The .lsrules file format specifies the JSON structure that Little Snitch expects for subscribing to rule groups.

Providing a URL

Please refer to your web server’s documentation on how to serve a static file or how to run a script to dynamically create responses to incoming requests.

Regardless of how you serve the rule group, you will want to send the URL to others for subscribing. For convenience, you can provide an x-littlesnitch: URL on a website that users of Little Snitch can click on to automatically open Little Snitch Configuration with the URL filled in already. Because you’ll pass a URL as a parameter in an x-littlesnitch:subscribe-rules?url= URL, you will need to percent encode your URL.

For example:

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