---
title: "Filter Expressions - Workshop Docs"
description: "Filter Expressions - Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet."
doc_version: "1"
last_updated: "2026-06-23"
canonical: "https://northpole.security/docs/workshop/binary-upload/filter-expressions"
---
# 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`](https://northpole.dev/configuration/keys/#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.

Field

Type

Description

`binary.path`

string

Absolute path Santa opened on the host.

`binary.signing_id`

string

Signing ID. Empty when the file is unsigned or the signature could not be read.

`binary.team_id`

string

Team ID. Empty when there is none or it could not be read.

`binary.cdhash`

string

Code directory hash.

`binary.is_platform_binary`

bool

True for Apple platform binaries.

`binary.file_size`

int

Size in bytes.

`binary.macho_type`

string

One 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](https://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

-   [Binary Upload](https://northpole.security/docs/workshop/binary-upload)
-   [Bucket Setup](https://northpole.security/docs/workshop/binary-upload/bucket-setup)
-   [Telemetry Filter Expressions](https://northpole.security/docs/workshop/telemetry/filter-expressions)

## Sitemap

- [Home](https://northpole.security/index.md)
- [Workshop](https://northpole.security/workshop.md)
- [Santa](https://northpole.security/santa.md)
- [Features](https://northpole.security/features.md)
- [Cookbook](https://northpole.security/cookbook.md)
- [Docs](https://northpole.security/docs.md)
- [Blog](https://northpole.security/blog.md)
- [Glossary](https://northpole.security/glossary.md)
- [About](https://northpole.security/about.md)
- [Contact](https://northpole.security/contact.md)