Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
.platforms
CMakeLists.txt
README.md

README.md

Santa osquery Extension

Santa is an open-source application whitelist/blacklist enforcement solution for macOS. This extension for osquery enables the osquery user to read the log of DENY events from the Santa generated log file on the host, with a table called santa_denied. It also adds a table called santa_allowed, to read the log of ALLOW events. Finally, it allows the user to remotely view and create new rules for Santa with a table called santa_rules.

Note: this extension can complement the use of a Santa sync server or Upvote server, but if Santa is configured to use a server then the server will take precedence, and osquery will not be able to create or delete rules.

Schema

santa_allowed and santa_denied tables (same schema for each table)

Column Type Description
timestamp TEXT Event timestamp
path TEXT The executable path
shasum TEXT Object hash
reason TEXT Either BINARY or CERT for certificates

The value in the reason column determines the meaning of the shasum field:

reason value shasum value
CERT This is a reference to the certificate used to sign the application
BINARY Raw hash of the executable (i.e.: openssl sha256 /path/to/application)

santa_rules table

Column Type Description
shasum TEXT The certificate or binary hash
state TEXT Either whitelist or blacklist
type TEXT Either binary or certificate
custom_message TEXT User-definable message for a rule entry (justification, etc.)

Usage

Listing allow and deny events

SELECT * FROM santa_denied;
SELECT * FROM santa_allowed;  -- note: this table will normally have hundreds of thousands of entries

The santa_denied table is intended for supporting security alerts via osquery, whereas the santa_allowed table is to support forensic investigations, as a way to search a record of process execution history on the host.

Listing system rules

SELECT * FROM santa_rules;

Adding and removing rules

The Santa extension edits the Santa rules database by invoking santactl (the standard Santa executable); this means that adding and removing rules will generate process events.

It is also important to remember that adding and removing rules only works when Santa has not been configured to use a sync server. Read-only access (as with a SELECT statement), however, works regardless of how Santa is configured.

Creating a new binary rule

Calculate the hash of the binary you want to allow: openssl sha256 /path/to/application. You can also use santactl fileinfo /path/to/application and use the first sha256 hash.

INSERT INTO santa_rules
  (shasum, state, type, custom_message)

VALUES
  (
    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "whitelist",
    "binary",
    "We know and trust this executable"
  );

Note: the custom_message field is a free-form string, but if you're not using it then you can set it to "".

Creating a new certificate rule

Print the certificates that validate the application: santactl fileinfo /path/to/application. Look at the chain and take the sha256 value of the certificate you want to add to the configuration.

INSERT INTO santa_rules
  (shasum, state, type, custom_message)

VALUES
  (
    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "blacklist",
    "certificate",
    "This certificate has been stolen and cannot be trusted."
  );

Removing rules

DELETE FROM santa_rules
WHERE shasum = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";

License

The code in this repository is licensed under the Apache 2.0 license.