---
title: "Binary Upload - Workshop Docs"
description: "Binary Upload - 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"
---
# Binary Upload

Workshop can pull a copy of a binary off an enrolled host and store it in your own cloud storage bucket. Use it to grab a sample for analysis, hunt across past activity, or keep a file before it is deleted.

Santa reads the file on the host and uploads it straight to your bucket. The bytes never pass through Workshop.

## Requesting an upload

Request an upload from a binary’s event details or the API. You can target a **path** or a **SHA-256**.

Santa finds binaries by path, so a request always resolves to a path on the host. Uploading by SHA-256 works only when the host already executed that file, which lets Workshop map the hash to a path. If it cannot, upload by absolute path instead.

## Where uploaded files are stored

When Workshop knows the file’s SHA-256, it stores the object under that hash at the root of your bucket. The same file collected from many hosts lands at one key, so you keep a single copy.

When you upload by path and Workshop has no record of that file’s hash on the host, it cannot name the object ahead of time. Workshop stores the file under a unique key beginning with `operator_uploads/`, and Santa reports the SHA-256 it computed during the upload. These objects are not named by content, so the same file collected twice produces two objects.

See [Bucket Setup](https://northpole.security/docs/workshop/binary-upload/bucket-setup) to connect a bucket and run the Test Bucket check.

## Filtering what gets uploaded

Santa can skip an upload on the host before any bytes leave the machine. You write CEL expressions against the binary’s metadata, and a match means the file is not uploaded. Set them with the [`BinaryUploadFilterExpressions`](https://northpole.dev/configuration/keys/#BinaryUploadFilterExpressions) key in the Santa configuration profile (delivered through your MDM).

Goal

Expression

Skip Apple and other platform binaries

`binary.is_platform_binary`

Skip code from a Team ID you trust

`binary.team_id == "ABCDE12345"`

Skip a vendor’s signed apps

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

Skip files over 200 MB

`binary.file_size > 200000000`

Skip dynamic libraries

`binary.macho_type == "dylib"`

See [Filter Expressions](https://northpole.security/docs/workshop/binary-upload/filter-expressions) for every field and the full behavior.

## Setup

1.  Connect an `s3://` or `gs://` bucket in Workshop and run **Test Bucket**. See [Bucket Setup](https://northpole.security/docs/workshop/binary-upload/bucket-setup).
2.  If you restrict Santa’s commands with the [`AllowedSantaCommands`](https://northpole.dev/configuration/keys/#AllowedSantaCommands) key, add `binary_upload` to the list — otherwise those requests are rejected. When the key is not set, every command is allowed and no change is needed.
3.  Optionally add [filter expressions](https://northpole.security/docs/workshop/binary-upload/filter-expressions) to exclude binaries you do not want.

## Results

Disposition

Meaning

`COMPLETED`

The file was uploaded. Its SHA-256 and byte count are returned.

`REFUSED`

The host declined. A filter expression matched, the file is not a Mach-O image, or uploads are turned off locally.

`NOT_FOUND`

No regular file exists at the resolved path.

`HASH_MISMATCH`

The file did not match the expected SHA-256. The upload stopped before anything was stored.

`HTTP_ERROR`

The bucket rejected the upload. The status and a short snippet are in the message, usually a bucket policy problem.

`INTERNAL_ERROR`

Santa could not open, hash, or stream the file.

## See Also

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

## 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)