Code identity (Code ID)

A rule that allows Safari to connect should match Safari, and nothing that only pretends to be Safari. To make sure of that, Little Snitch needs a way to tell programs apart reliably: the identity of a program. It’s a small set of data that securely distinguishes a program from all others, and it usually comes from the program’s code signature.

On this page, “program” means both apps, such as Safari, and plain executables, such as /sbin/ping. A running program is a “process”. Little Snitch usually deals with running processes, not with executables on disk.

Little Snitch uses the identity of a program in two ways:

To recognize a program, wherever it is. For this, Little Snitch uses the Code ID, for example in rules that identify the process by its Code ID.
To verify a program at a particular path. For this, Little Snitch uses a Code Requirement, for example in rules that identify the process by its path. See Identity checks.

Both contain mostly the same data.

A rule that identifies the process by its Code ID has two advantages:

If the program moves to a different place on disk, the rule still matches.
If you install a new version of the program, the Code ID usually stays the same, wherever you install it, so the rule still matches.

Which data identifies a program?

If the program has a code signature, its Code ID consists of two parts of this signature: the Team Identifier and the Identifier.

The Team Identifier is a string of 10 characters that Apple assigns to each developer. Code from Apple often has none, and Little Snitch then uses the string “APPLE”.
The Identifier is chosen by the developer and distinguishes the program from the developer’s other programs. By convention, it’s in reverse DNS notation, for example at.obdev.littlesnitch.

So the Code ID of Little Snitch is MLZF7K7B5R/at.obdev.littlesnitch, and the Code ID of Safari is APPLE/com.apple.Safari.

The simulators in Xcode’s Device Hub are a special case. Many macOS programs also exist in these simulators, even with the same Code ID. To tell them apart, Little Snitch adds /simulator to the Code ID of processes that run in a simulator. Safari in a simulator, for example, has the Code ID APPLE/com.apple.Safari/simulator.

If a program has no code signature with a certificate from Apple, Little Snitch builds the Code ID from other data. Such a Code ID lacks most of the advantages described above:

In rare cases, code is signed, but not with a certificate from Apple. Little Snitch then can’t rely on a Team Identifier and uses a hash of the signer’s public key instead. The Code ID is KEY/<hash over signer’s key>.
If a program has an ad-hoc signature, the Code ID is ADHOC/<code directory hash>.
If a program has no signature at all, not even an ad-hoc one, Little Snitch falls back on a hash of the executable. The Code ID is SHA256/<sha256 over executable on disk>.

Identity checks

A rule can also identify a program by its path in the file system. But a path alone isn’t secure. A popular, trusted program, such as a web browser, usually has generous allow-rules. If malware replaced it with itself, it could use these rules. To prevent this, Little Snitch verifies the identity of the program at the path, with a Code Requirement.

The name says what it does: it requires the program to have particular properties. A Code Requirement isn’t a Code ID, but it contains mostly the same information, and in most cases, Little Snitch can convert one into the other. A Code Requirement can also list alternatives, though, for example more than one code directory checksum for a universal binary.