santa/docs/introduction/binary-authorization-overview.md

title, parent, redirect_from

title	parent	redirect_from
Binary Authorization	Intro	/introduction/binary-whitelisting-overview

Binary Authorization Overview

Background

santad subscribes to appropriate Endpoint Security (ES) framework events to authorize new executions in its authorizer client. This framework ensures that santad has the opportunity to allow or deny the execution of a binary before any code in that binary is executed.

Flow of a New Execution

1. The santad ES client subscribes to the ES_EVENT_TYPE_AUTH_EXEC to begin receiving and authorizing all new executions on the system.
2. When a binary is executed (e.g., via execve(2) or posix_spawn(2)), the ES framework gathers some information about the execution and holds up the new image until ES either receives a response from santad or a timeout occurs.
   • Note: ES supports authorization result caching that santad attempts to take advantage of when possible. This cache resides within the ES subsystem in the kernel. When a result is already available, ES uses that result immediately without collecting event information or waiting for a new result. This can greatly reduce performance impact.
3. The authorizer client's callback is called by the ES framework with the event information.
4. santad first checks if the event from another ES client on the system and, if configured to do so, immediately allows the event and stops all further processing for this event.
5. Some final checks on the event are made before continuing to handle the event asynchronously on a concurrent dispatch queue.
   • Note: A second asynchronous dispatch block is also submitted to execute immediately before the event's deadline with the configured default response. This helps prevent santad from missing an ES response deadline which would result in the santad process being killed.
6. santad then checks its local authorization cache to determine if full evaluation is necessary.
   • If a cached result already exists, the authorizer client responds to the ES subsystem immediately and no more event processing occurs.
7. When santad has no local cache entry and must perform a full evaluation, it first inserts a placeholder value in its auth cache. If a second event for the same binary is received while the first is being processed, it will wait for the original event to be processed and result placed into the cache instead of performing duplicate processing.
8. Next, santad extracts relevant file and code signing information from the event. It computes the file's hash and verifies the binary's code signature.
   • IMPORTANT: If code signature validation fails, santad will not attempt to lookup rules for any properties validated by the code signature (currently TeamID, SigningID and CDHash). This means only file hash and file scope rules apply.
9. The extracted information is then used to lookup any matching rules and make a decision.
   • There are more details on how these decisions are made in the Rules and Scopes documents.
10. The decision is then posted back to the ES subsystem and local caches are updated.
11. If the binary was blocked, the Santa GUI will display a message, if configured to do so.