Skip to main content

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.

info

Binary upload is off until you set it up. You need a storage bucket connected to Workshop, and — if you restrict Santa's commands — binary_upload allowed for your hosts. See Setup.

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 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 key in the Santa configuration profile (delivered through your MDM).

GoalExpression
Skip Apple and other platform binariesbinary.is_platform_binary
Skip code from a Team ID you trustbinary.team_id == "ABCDE12345"
Skip a vendor's signed appsbinary.signing_id.startsWith("com.microsoft.")
Skip files over 200 MBbinary.file_size > 200000000
Skip dynamic librariesbinary.macho_type == "dylib"

See 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.
  2. If you restrict Santa's commands with the 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 to exclude binaries you do not want.
note

Binary upload uses the same push channel as Santa's other host commands, so hosts need push notifications enabled to receive requests.

Results​

DispositionMeaning
COMPLETEDThe file was uploaded. Its SHA-256 and byte count are returned.
REFUSEDThe host declined. A filter expression matched, the file is not a Mach-O image, or uploads are turned off locally.
NOT_FOUNDNo regular file exists at the resolved path.
HASH_MISMATCHThe file did not match the expected SHA-256. The upload stopped before anything was stored.
HTTP_ERRORThe bucket rejected the upload. The status and a short snippet are in the message, usually a bucket policy problem.
INTERNAL_ERRORSanta could not open, hash, or stream the file.

See Also​