Skip to main content

Binary Upload Filter Expressions

Binary upload filter expressions are CEL expressions that Santa runs on the host before an upload. A match drops the upload, so the file never leaves the machine. Use them to keep binaries you do not want out of your bucket, such as Apple platform binaries, trusted vendors, or oversized files.

Set them with the BinaryUploadFilterExpressions key in the Santa configuration profile, delivered through your MDM. This key is configured in the configuration profile only, not through Workshop.

How matching works​

Each expression is checked against the binary's metadata. The first one that returns true drops the upload, and the host reports REFUSED with the matched expression in the message. If every expression returns false, the upload proceeds.

An empty or unset list drops nothing, so every requested upload proceeds. There is no built-in default.

Expressions that fail to compile, do not return a boolean, or error while evaluating are logged on the host and skipped. The remaining expressions still apply. A typo disables that one expression rather than blocking uploads, so check the host logs after a change.

The binary variable​

Each expression is evaluated against a single variable named binary, the metadata Santa computed for the file.

FieldTypeDescription
binary.pathstringAbsolute path Santa opened on the host.
binary.signing_idstringSigning ID. Empty when the file is unsigned or the signature could not be read.
binary.team_idstringTeam ID. Empty when there is none or it could not be read.
binary.cdhashstringCode directory hash.
binary.is_platform_binaryboolTrue for Apple platform binaries.
binary.file_sizeintSize in bytes.
binary.macho_typestringOne of executable, dylib, bundle, kext, other, or empty for a non-Mach-O file. For a universal binary this reflects the first slice.

CEL basics​

The most useful pieces of the language for filtering:

  • Logical: &&, ||, !
  • Comparison: ==, !=, <, >, <=, >=
  • String functions: startsWith(), endsWith(), contains(), matches(), size()

Every expression must return a boolean. See celbyexample.com for a full CEL reference.

Examples​

Skip platform binaries​

binary.is_platform_binary

Skip a Team ID you trust​

binary.team_id == "ABCDE12345"

Skip a vendor's signed apps​

binary.signing_id.startsWith("com.microsoft.")

Skip large files​

binary.file_size > 200000000

Skip dynamic libraries and bundles​

binary.macho_type == "dylib" || binary.macho_type == "bundle"

Combine conditions​

binary.is_platform_binary || binary.file_size > 500000000

Testing a change​

Roll changes out narrowly first.

  1. Apply the expression to a small set of test hosts through their configuration profile.
  2. Request an upload of a binary you expect to drop and one you expect to keep.
  3. Confirm the dropped one returns REFUSED with your expression named, and check the host logs for any skipped expressions.
  4. Widen to more hosts once it behaves.

See Also​