.lsrules rule files

Outbound reads and writes the documented .lsrules JSON format (the format of remote rule groups), so you can bring your rules and the community groups you subscribe to, and take your rules with you if you leave. The converter is strict in one direction only: every rule the format allows that Outbound can express becomes a rule, and everything else is skipped with a reason. An untranslatable remote never becomes “any”, and an untranslatable protocol never becomes “any protocol”.

In the app, the Rules pane’s Import or Export Rules menu imports an .lsrules file and has Export as .lsrules…. On the command line, the same work is outboundctl rules import-lsrules <file> and outboundctl rules export-lsrules <file>. See outboundctl rules.

What a .lsrules file looks like

{
  "name": "Social media",
  "description": "Community blocklist",
  "rules": [
    {
      "action": "deny",
      "process": "any",
      "remote-hosts": "ads.example.com",
      "notes": "Tracks you in every app"
    }
  ],
  "denied-remote-domains": "telemetry.example.net",
  "denied-remote-notes": "Blocked: %REMOTE%"
}

Keys the import reads

Key	Meaning
name	The group’s name. The import sheet is titled “Import Rules from “<name>””.
description	The group’s description.
rules	An array of rule objects, in file order.
denied-remote-domains	Shortcut: one deny rule per domain, for every process, outgoing.
denied-remote-hosts	The same for exact hosts.
denied-remote-addresses	The same for IP addresses and CIDR networks.
denied-remote-notes	A note repeated on every deny rule, with %REMOTE% replaced by the entry.

Unknown keys are ignored (the format may grow). Malformed JSON and wrong JSON types abort the import with an error naming the key; one odd rule never fails a whole group, it is skipped with a reason.

Inside a rule object

Key	Values Outbound accepts	Default
action	allow, deny, ask	ask
direction	outgoing, incoming	outgoing
priority	regular, high	regular
disabled	A boolean; true imports as a disabled rule	false
notes	Any text	empty
ports	any, a port number, a range like 8000-8100, or a comma-separated list of those	any
protocol	tcp or 6, udp or 17, icmp or 1, any	any
process	any, a code ID (identifier.TEAM/IDENTIFIER, team optional), or an executable path	any
via	The same values as process	none

Exactly one remote key is allowed per rule: remote-addresses, remote-hosts, remote-domains or remote. A rule naming several hosts, domains or addresses becomes several rules, one per value. No remote key means every destination.

Remote key	Accepted values
remote-addresses	A single IP address, or a CIDR network. Other range spellings have no Outbound equivalent and are skipped.
remote-hosts	An exact host name.
remote-domains	A domain name; *.example.com is accepted and means the domain.
remote	any or local-net (the local network ranges).

What is skipped, and why

Every skipped rule or entry is reported with its reason, in file order. The common cases:

• An action, direction or priority value the converter does not know, or a protocol with no Outbound equivalent such as GRE or SCTP. Any protocol would widen the rule, so it is never substituted.
• A remote value Outbound has no match for: multicast, broadcast, bonjour, dns-servers and bpf.
• A rule naming several remote keys at once.
• An entry that is not a domain name, host name, address or CIDR network, as the key requires.

Importing: preview first

Nothing changes until you confirm. In the app you choose the file (.lsrules files, and plain .json copies of rule groups), and Outbound opens an import sheet that counts what the file Adds, Changes and what is Already in your rules. It also counts entries Repeated in the file and Entries Outbound can’t read, then lists them under Conflicts with your rules, Added and Not imported, each with its reason. A file the converter cannot read at all is reported as “<file> is not a rule group Outbound can read”, with the detail after it.

When the file and your rules differ chooses how the import settles a conflict:

Choice	What it does
Keep my rules (the default)	Adds the rules you don’t have. Where the file decides a connection differently from one of your rules, yours stays. Importing the same file again adds nothing.
Use the imported rules	Adds the rules you don’t have. Where the file decides a connection differently, your rule takes the file’s decision.
Replace my rules with the file	Your rules that a .lsrules file can hold become exactly the file’s: rules not in it are removed, and the sheet counts them under Removes. Rules from your organization, blocklists and rule groups, and temporary, profile and country rules, stay. The button then reads Import and Remove.

Changes that unblock connections require your usual approval. Edit › Undo reverses the whole import. Imported rules are user rules, created now, with lifetime “forever”.

On the command line, --merge keep-existing (the default), --merge prefer-imported and --merge replace make the same three choices.

What export writes

Export as .lsrules… opens a sheet before anything is written:

• Export: the selected rules, the rules in this view, or all your rules.
• Group Name and Description: written into the file, so it can be hosted and subscribed to as a rule group. The name starts as the active profile’s or the selection’s name, or “Outbound”.
• Each rule carries the keys the format documents, with defaults omitted (outgoing, regular priority, enabled, any port, any protocol).

The sheet lists what stays out of the file, with the reason for each, rather than writing it with a different meaning:

• Rules from your organization, a blocklist or a rule group.
• Temporary or scheduled rules: the format has only permanent rules.
• Rules limited to a profile: the format has no profiles.
• Rules for both directions: the format names one direction.
• Rules for a group of Apple-signed programs: the format has no such group.
• Country rules: the format has no country rules.

It also lists rules that would be Weaker in the file, because the format has no code-signature check or can’t require Apple’s signature, so the rule would match more programs there than it does here. Turn on Strict export to write nothing if any rule would. Rules with a notification or sound are exported without them; they decide the same way in the file.

On the command line, export-lsrules takes --name, --description, --ids for chosen rules and --strict, and tells you how many rules were written and how many of your own were left out.