Little Snitch Help

Internet Access Policy – Developer Documentation

This section is for app developers. If you are not a developer, you can safely skip it.

Why you want to bundle an Internet Access Policy

Although many software developers use Little Snitch to protect their own computers, not all of them are happy if their users do the same. That’s because some users tend to deny connections that are essential for applications to work and then complain to the support that the app doesn’t work.

Imagine you could be there when your customer has to answer a connection alert. You would tell your user that this particular connection is essential for your application. Now you can. Not in person, but you can provide a text that is shown to the user in Little Snitch’s connection alert and other places.

Please note that you can only provide information to the user. Little Snitch does not support any way to take the decision about allowing or denying a connection from the user.

Providing information is easy

All you have to do as a first step is to add a file named InternetAccessPolicy.plist to your application bundle’s Resources directory. Here is a short example for what such a file could look like (download this example):

Key Type Value
Root Dictionary (2 items)
ApplicationDescription String EditHelper is part of myCompany’s text editing suite. It provides dictionary and spell checking services to other components.
Connections Array (2 items)
Item 0 Dictionary (7 items)
IsIncoming Boolean NO
Host String dictionary1.mycompany.com, dictionary2.mycompany.com
NetworkProtocol String TCP
Port String 80, 443
Relevance String Essential
Purpose String EditHelper updates its dictionary from this server.
DenyConsequences String If you deny this connection, dictionary and spell checker services may not be available or data may be outdated.
Item 1 Dictionary (6 items)
IsIncoming Boolean NO
Host String software-update.mycompany.com
NetworkProtocol String TCP
Port String 443
Purpose String EditHelper checks for new versions and security updates.
DenyConsequences String If you deny this connection, you will not be notified about new versions and security updates. Security updates are important in order to defend against malware attacks.

File format

Starting in Little Snitch 4.0.5, Little Snitch not only supports Internet Access Policies in Property List format (InternetAccessPolicy.plist), but also in JSON format (InternetAccessPolicy.json). They both have the same logical structure and you can use whichever one you prefer. All information on this page is valid for both formats, even if they only mention one.

You can convert from a Property List IAP to a JSON IAP using the following command:

plutil -convert json -r -e json InternetAccessPolicy.plist

… and back from a JSON IAP to a Property List IAP using this command:

plutil -convert plist -e plist InternetAccessPolicy.json

Localization

The Internet Access Policy contains texts shown to the user. If your application is available in multiple languages, you also want those texts to be available in these languages. There are two ways to localize an Internet Access Policy:

Multiple versions of Internet Access Policy file

Add one InternetAccessPolicy.plist in each language.lproj file:

MyApp.app/Contents/Resources/language.lproj/InternetAccessPolicy.plist

Download example

One Internet Access Policy localized with strings files

Instead of human readable texts for the keys ApplicationDescription, Purpose and DenyConsequences, enter unique keys. Translate these keys to human readable text in localized InternetAccessPolicy.strings files:

MyApp.app/Contents/Resources/InternetAccessPolicy.plist
MyApp.app/Contents/Resources/language.lproj/InternetAccessPolicy.strings

Download example

Specification of keys

Key Type Description
DeveloperName String, optional The human readable name of your company. Presented to the user as the source of the information. Available starting in Little Snitch 4.0.5
ApplicationDescription String, mandatory A general description of the app.
Connections Array, optional An array of connection description dictionaries with the keys defined below
IsIncoming Boolean, optional Whether incoming (YES) or outgoing (NO) connections are matched. If omitted, matches incoming and outgoing connections.
Host String, mandatory A list of host or domain names, separated by comma. A domain name is represented as *.domain.com. See Which connection descriptions are shown for details.
NetworkProtocol String, optional Can be one of TCP, UDP or ICMP. If omitted, matches any protocol.
Port String, optional A comma-separated list of port ranges, e.g. 20-30, 80, 443. Defaults to 0-65535.
Relevance String, optional Indicates how important the connection is for the proper functioning of the application. Values can be Essential or Default. Defaults to Default. Use Essential only if your app is useless without this connection. You can still describe DenyConsequences if you choose default relevance.
Purpose String, mandatory Describes the purpose of the connection. This text is shown to the user as-is, so use easy to understand sentences. Markdown-style links are supported.
DenyConsequences String, optional Describes the consequences of denying the connection. Markdown-style links are supported.

Presentation in Little Snitch

Little Snitch parses the data you provide and presents it in an appropriate format.

In places where users actively look for information on connections, Little Snitch shows everything that is relevant. That is, the ApplicationDescription followed by the Purpose and DenyConsequences for all relevant connection descriptions (see below for an explanation of Which connection descriptions are shown).

When users are about to deny a connection only the short DenyConsequences are shown. This provides a means of last resort to inform your users that they are about to adversely affect your app’s functionality.

The following sections explain how the information from the Internet Access Policy is used in different parts of Little Snitch’s user interface.

Connection alert

If Little Snitch is running in alert mode and no rule matches the connection your app tries to establish, users are presented with a connection alert. Expanding the Research Assistant shows all of the information relevant to this specific connection.

Clicking the “Deny…” button shows only the DenyConsequences. Note that what is shown here depends on the options the user has selected in the connection alert. For example, if they are about to deny “Any Connection”, more DenyConsequences may be shown than if they only deny connections to the specific domain.

Network Monitor

In the inspector of the Network Monitor, Little Snitch shows information about the connections selected in the connection list. Expanding the Research Assistant shows all of the relevant information.

Clicking the “X” button in a connection line to create a deny rule shows only the DenyConsequences. Note that what is shown here depends on what line the user clicked on. For example, if they clicked on the line next to an app’s name to deny any connection, more DenyConsequences may be shown than if they only deny connections of that app to a specific domain.

Configuration

The Research Assistant in Little Snitch Configuration is located at the bottom of the right-hand info sidebar and shows information about the selected rules.

Which connection descriptions are shown

This section describes the behavior in Little Snitch 4.0.6 and later. Earlier versions are less precise and may also show descriptions that are less relevant.

Hosts and domains

The Host field of a connection description is a comma-separated list of host names and domain names. The basic format and meaning is as follows:

It is possible to create connection descriptions with overlapping Host values. For example, you could have a description for Host: sw-update.example.com (one specific host) and another, more general one for Host: *.example.com (the whole domain). Because the specific host is in the domain, both descriptions match when looking up information for sw-update.obdev.at.

Also, multple descriptions can match because Little Snitch shows IAP information relevant to what the user has currently selected in the connection alert or other places. For example, you could have descriptions for Host: www.example.com and Host: sw-update.example.com that do not overlap, but when the user creates a rule for the domain example.com, both descriptions are relevant.

In these situations, Little Snitch uses a set of criteria to determine which descriptions to show. These are designed to keep the information shown to the user as concise as possible to avoid information overload, while giving you as the developer precise control over what should be shown for a particular connection. In short, if there’s an exact match with one of the descriptions, only that description is shown. Otherwise, all relevant descriptions are shown.

Example 1

As an example, assume there are two connection descriptions (the Purpose fields are overly terse for illustration purposes):

What Little Snitch shows depends on what the user selects:

While all these are technically correct, it may not be very useful to show both descriptions in the latter two cases because their Purpose texts overlap in what they say. There’s no value in telling the user twice that the app checks for software updates.

Exact matches for domains and “any connection”

To handle these cases better, there is a way to specify a Host description that is an exact match for domains and “any connection”:

These descriptions match only when the user selects exactly the respective connection.

Example 2

To improve over Example 1 above, we can use the following three IAP connection descriptions:

Again, what Little Snitch shows depends on what the user selects:

To summarize: If a description’s Host is an exact match, only that single connection description’s Purpose and DenyConsequences will be shown. Otherwise, multiple matching descriptions may be shown.

Matching everything else

There’s one more case that the examples above do not handle: What should be shown if your app connects to arbitrary servers that you don’t know about in advance? For example, if you develop a web browser or file transfer app, it will connect to whatever servers the user enters and you couldn’t possibly know them when writing your app’s IAP. To show a connection description for these connections anyway, you can provide a fallback connection description:

Example 3

If you add the following description to Example 2 above…

… it will be shown whenever a connection is established to a server that is not covered by another connection description, e.g. www.apple.com. Without this description, no information from your app’s IAP would be shown for that connection.

Summary

Information from only one single connection description is shown in the following cases:

Otherwise, if one or more Domain connection descriptions match, information from all of them are shown, ordered by their relevance. Example: Host: *.example.com

Otherwise, if a connection description with the Fallback Wildcard exists, its information is shown, i.e. Host: *

Otherwise, no connection descriptions match and no connection-specific IAP information is shown.

Support for XPC services

This feature is available starting in Little Snitch 4.0.5

Using XPC services allows you to separate your app’s functionality into multiple processes for stability and privilege separation reasons.

Little Snitch treats connections established by an XPC service on behalf of an app as if the connection were established by the app itself. In fact, in most places Little Snitch doesn’t even prominently show to the user that an XPC service is in use. Also, rules are automatically created for just the app itself, instead of via-rules for “App via XPCService” (see Anatomy of a rule, paragraph process for more information about via rules).

Apps that bundle XPC services

If you are developing an app that bundles XPC services, there’s nothing special you have to do in regard to the Internet Access Policy.

Third-party XPC services

If you are developing an XPC service that other developers incorporate into their apps (e.g. as part of a third-party framework), you can provide an Internet Access Policy that describes only the connections of the XPC service. In this case, the files go into the XPC service bundle’s Resources directory.

If the developers who bundle your XPC service in their apps do not include an Internet Access Policy of their own, at least the connections established by your XPC service will be described.

But if the developers who bundle your XPC service in their apps do include their own Internet Access Policy in their app bundle, only that information will be used – the XPC service’s IAP will be ignored. This allows the developers who actually ship an app to have the last say over what information the Internet Access Policy shows to the user.

Because Little Snitch rules usually do not contain information about XPC services, Little Snitch Configuration cannot show an IAP that is contained inside an XPC service. This information will only be shown in the connection alert and Network Monitor where more information about the connecting processes is available.

Writing guidelines

Troubleshooting

If you bundled an Internet Access Policy with your app, but it does not seem to be used by Little Snitch, here are a few hints that can help you track down the problem.


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