santactl

This may be the most complex part of Santa. It does two types of work:

  1. It contains all of the code and functionality for syncing with a sync-server.
  2. It can be used to view the state and configuration of Santa as a whole. It can also inspect individual files. When running without a sync server it also a supported method of managing the rules database.

The details of santactl’s syncing functionality are covered in the syncing.md document. This document will cover the status work that santactl performs.

status

To view the status of Santa run santactl status

⇒  santactl status
>>> Daemon Info
  Mode                      | Monitor
  File Logging              | Yes
  Watchdog CPU Events       | 0  (Peak: 2.19%)
  Watchdog RAM Events       | 0  (Peak: 29.45MB)
>>> Kernel Info
  Kernel cache count        | 123
>>> Database Info
  Binary Rules              | 321
  Certificate Rules         | 123
  Events Pending Upload     | 0
>>> Sync Info
  Sync Server               | https://sync-server.com/santa/
  Clean Sync Required       | No
  Last Successful Full Sync | 2017/08/10 15:05:32 -0400
  Last Successful Rule Sync | 2017/08/10 15:29:21 -0400
  Push Notifications        | Connected
  Bundle Scanning           | Yes

The status command also has the ability to print JSON output santactl status --json

⇒  santactl status --json
{
  "kernel" : {
    "cache_count" : 123
  },
  "daemon" : {
    "watchdog_ram_events" : 0,
    "watchdog_ram_peak" : 29.44921875,
    "watchdog_cpu_events" : 0,
    "file_logging" : true,
    "mode" : "Monitor",
    "watchdog_cpu_peak" : 2.188006666666666
  },
  "database" : {
    "events_pending_upload" : 0,
    "certificate_rules" : 123,
    "binary_rules" : 321
  },
  "sync" : {
    "last_successful_rule" : "2017\/08\/10 15:29:21 -0400",
    "push_notifications" : "Connected",
    "bundle_scanning" : true,
    "clean_required" : false,
    "server" : "https:\/\//sync-server.com\/santa\/",
    "last_successful_full" : "2017\/08\/10 15:05:32 -0400"
  }
}
version

To view all of the component versions santactl version

⇒  santactl version
santa-driver    | 0.9.19
santad          | 0.9.19
santactl        | 0.9.19
SantaGUI        | 0.9.19

Again, a JSON version is available santactl version --json

⇒  santactl version --json
{
  "santa-driver" : "0.9.19",
  "santad" : "0.9.19",
  "SantaGUI" : "0.9.19",
  "santactl" : "0.9.19"
}
fileinfo

The fileinfo verb is very powerful and can be used to tease out just about anything you wish to know about a file, with respect to the domain of Santa.

Here is an example of using santactl fileinfo to inspect the main executable within /Applications/Hex Fiend.app.

⇒  santactl fileinfo /Applications/Hex\ Fiend.app
Path                 : /Applications/Hex Fiend.app/Contents/MacOS/Hex Fiend
SHA-256              : efaf88db065beae61615f6f176c11c751555d2bad3c5da6cdad71635896014f1
SHA-1                : 5585e6fb94eace1bd37da9a0a2f928e992d7c60c
Bundle Name          : Hex Fiend
Bundle Version       : 170205
Bundle Version Str   : 2.5
Download Referrer URL: http://ridiculousfish.com/hexfiend/
Download URL         : http://ridiculousfish.com/hexfiend/files/Hex_Fiend_2.5.dmg
Download Timestamp   : 2017/06/29 12:52:16 -0400
Download Agent       : com.google.Chrome
Type                 : Executable (x86-64)
Code-signed          : Yes
Rule                 : Allowed (Unknown)
Signing Chain:
     1. SHA-256             : ba1be5d2d60a43658a0c6ebf61b577e428439b53ef2e0b96ba90285e2c82a1b2
        SHA-1               : 8fdbf6d6c22a97c472fb4961b7733ab0d8830ff7
        Common Name         : Developer ID Application: Kevin Wojniak
        Organization        : Kevin Wojniak
        Organizational Unit : QK92QP33YN
        Valid From          : 2012/10/30 01:07:40 -0400
        Valid Until         : 2017/10/31 01:07:40 -0400

     2. SHA-256             : 7afc9d01a62f03a2de9637936d4afe68090d2de18d03f29c88cfb0b1ba63587f
        SHA-1               : 3b166c3b7dc4b751c9fe2afab9135641e388e186
        Common Name         : Developer ID Certification Authority
        Organization        : Apple Inc.
        Organizational Unit : Apple Certification Authority
        Valid From          : 2012/02/01 17:12:15 -0500
        Valid Until         : 2027/02/01 17:12:15 -0500

     3. SHA-256             : b0b1730ecbc7ff4505142c49f1295e6eda6bcaed7e2c68c5be91b5a11001f024
        SHA-1               : 611e5b662c593a08ff58d14ae22452d198df6c60
        Common Name         : Apple Root CA
        Organization        : Apple Inc.
        Organizational Unit : Apple Certification Authority
        Valid From          : 2006/04/25 17:40:36 -0400
        Valid Until         : 2035/02/09 16:40:36 -0500

Any of the desired information can be targeted with the --key flag

⇒  santactl fileinfo /Applications/Hex\ Fiend.app --key SHA-256
efaf88db065beae61615f6f176c11c751555d2bad3c5da6cdad71635896014f1

Multiple --key flags are allowed

⇒  santactl fileinfo /Applications/Hex\ Fiend.app --key SHA-256 --key Rule
efaf88db065beae61615f6f176c11c751555d2bad3c5da6cdad71635896014f1
Allowed (Unknown)

The --json flag can also be used at any point

⇒  santactl fileinfo /Applications/Hex\ Fiend.app --key SHA-256 --key Rule --json
{
  "SHA-256" : "efaf88db065beae61615f6f176c11c751555d2bad3c5da6cdad71635896014f1",
  "Rule" : "Allowed (Unknown)"
}

Multiple files are also supported as input

⇒  santactl fileinfo /bin/* --key SHA-256 --key Rule --json
[
{
  "SHA-256" : "5d8e161c21fc1a43374c4cf21be05360dbe2ecea0165fd4725ae7a958f2a0b02",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "295fbc2356e8605e804f95cb6d6f992335e247dbf11767fe8781e2a7f889978a",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "9f9b36ec79b9fcaf649e17f2f94c544dd408c2ab630e73d7c62a7a43f1bc7b1d",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "08a09d2d9bade16872acdf5da1c4e9d29582ed985480a9e73fd389e98293c40d",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "48e4b938b363201ec11d06a13d8080c1bd77187d286780259b9304c96edc5324",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "7dff6291a29fdaf97dad64c0671dc5d1ecc42189bc5daf8ca08e2a3ae06aff95",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "7cbba457df4c02d6a7fb93046fea0e869732c65a2225bee6f2e8ec290d38c57b",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "39e894d1705656451f592884a56bcc76e7ffbb9ed2a8b81d5f2878e1c0e68dbe",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "8555ed4622410aa7b4379041acabf80fe452a90efe3be2697406935ff0d6822e",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "cee3e29089f8919ee904328904a7492995cfa398b027857fbf8b3e601397b308",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "da2cfa9fc2cabd41907f9d0931cea79000a19520fe0b3d73fc40537408730e40",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "73aee02c4761e5501b1fdfa51ccd316bf735017a5cc0a09d5bcc46f4e7112be9",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "3a1c4ca5a038b42b1fbfca6f9bec25d307a8af40afbe9c48b307372fe8167a2f",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "9dc8e1c5b6ec49602dd968eb88286e330220233f7cfa6e73fd37fc983a365084",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "78fd9b8749c2a216ca76ff4541754d4cf5a5e2e8c00710a85c3fdab171486f92",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "c4daaf12bd42adee60549872126e15186c75d89e760f078bfa6a45a861f6400f",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "9dba1cbb01bce47a9610a40cbcbc27704a754e31a889503eb0670c3a25f7ad72",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "a5ae86cd413589d9661fc604349fb153c0d6f5dfa3d9e95e01b8bc5e09bc1da1",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "a5ae86cd413589d9661fc604349fb153c0d6f5dfa3d9e95e01b8bc5e09bc1da1",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "c4c5517ff40a33006028853a19734d8cda8e2942cb9ba27b8310e07f18677487",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "a944b104742db59204b45f1dae657bd6a845ff2374e1ade3cf9f09cc428154cf",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "09e143cf3b6c4dcc98676cc45543613b83b6527b502d4dacb42b3f6c7036ef5a",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "47cea771e93aff464f1060a6a1a2c3855401e6cd22c3971b2b76fae92e8c33b4",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "5682f15628ae15e5c29aa37f19ec421bbe4aca47734864b6363b73a16f891888",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "83c29a2445d84daf51eebd51668753fb39600a136efc20aba7298a812b44974c",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "83929910d3cd2c401636337fadc747a9a8ea6c174bfd80f1e96b99d877ddfa6e",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "cccd818698aa802b116586a773643d0b951067dea8284304acaae62ac97b362b",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "2bf2d10a7529a88d340ce0255da52dbef9873ccb44e46d23af03abf70b8e54ca",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "956f2dc7ba31663dd3a9b70e84e6a2491980165426b90cacd10db4bd010c3353",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "da1a3ae959751b211928f175f6c8987408a976be44690022c92d45ef5a8cb6e5",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "1e51209ae4549a72432ad504341c0731a282b33ba99c5f7f4e2abc9993e09b0a",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "7dff6291a29fdaf97dad64c0671dc5d1ecc42189bc5daf8ca08e2a3ae06aff95",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "5d8e161c21fc1a43374c4cf21be05360dbe2ecea0165fd4725ae7a958f2a0b02",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "83929910d3cd2c401636337fadc747a9a8ea6c174bfd80f1e96b99d877ddfa6e",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "17372eafbe9e920d5715a9cffa59f881ef4ed949785c1e2adf9c067d550dbde6",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "b1834d55b76c65d57cef1219a30331452301e84b6e315f2a17e5b5b295ce1648",
  "Rule" : "Allowed (Certificate)"
}
]

Recursive lookups of an application or directory is a soon to be added feature

⇒  santactl fileinfo --recursive /Applications/Santa.app --key SHA-256 --key Rule --key Type --json
[
{
  "SHA-256" : "c149c10c83abaf6b602401106f098b68d47a1a433ab02455cef2ca8057cf4a82",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
},
{
  "SHA-256" : "c339c3e5e04c732ae493dbc4a26d18fccc8bb48cea0cc0762ccd8754ef318a0b",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
},
{
  "SHA-256" : "6ee757ab65d7c93e8b6a467b44cd2f0d10b6db7da8b6200e778c3ca279ea5619",
  "Type" : "Executable (x86-64)",
  "Rule" : "Allowed (Certificate)"
},
{
  "SHA-256" : "82502191c9484b04d685374f9879a0066069c49b8acae7a04b01d38d07e8eca0",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
},
{
  "SHA-256" : "9814019f865a540d3635012a75db932eaefc9a62468750f2294350690430aadf",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
},
{
  "SHA-256" : "05a9c9dbbf0a7a30f083e3dccd8db3d96845e0644930977b4e284c65083b89ac",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
},
{
  "SHA-256" : "e1db8fdffc5017684f962c51fad059dcaa06ab5d551186aa85711f80b727d23d",
  "Type" : "Unknown",
  "Rule" : "Allowed (Scope)"
}
]
rule

The rule command is covered in the rules.md document.

sync

The sync command is covered in the syncing.md document.

Debug Commands

There are a few commands that are not included in the release versions of Santa. They are mainly used during development and only accessible with a debug build of Santa.

bundleinfo

This prints info about all of the executable Mach-O files within a bundle. It also prints the calculated bundle hash for that particular bundle. A bundle hash is a notion used by Santa to represent a set of binaries.

⇒  santactl bundleinfo /Applications/Hex\ Fiend.app
Hashing time: 12 ms
4 events found
BundleHash: 33da3e2d5e2ccbdb9d34fb9753c2c18805e6325853d2fb4eb947915c90113efc
BundleID: com.ridiculousfish.HexFiend
    SHA-256: e592a7c65f803675c0b7d55ab7d2a1a2696c9f097a99dc28a4083d7387e53d95
    Path: /Applications/Hex Fiend.app/Contents/Library/LaunchServices/com.ridiculousfish.HexFiend.PrivilegedHelper
BundleID: com.ridiculousfish.HexFiend
    SHA-256: ce23d39a1a8ff2b42baad5a0204b24b57590bb7ff74c9552b3ba10d9c1517279
    Path: /Applications/Hex Fiend.app/Contents/Frameworks/Sparkle.framework/Versions/A/Resources/Autoupdate.app/Contents/MacOS/Autoupdate
BundleID: com.ridiculousfish.HexFiend
    SHA-256: efaf88db065beae61615f6f176c11c751555d2bad3c5da6cdad71635896014f1
    Path: /Applications/Hex Fiend.app/Contents/MacOS/Hex Fiend
BundleID: com.ridiculousfish.HexFiend
    SHA-256: 148d6ae55176b619e5eb9f5000922b3ca4c126206fc5782f925d112027f9db3c
    Path: /Applications/Hex Fiend.app/Contents/Frameworks/Sparkle.framework/Versions/A/Resources/Autoupdate.app/Contents/MacOS/fileop

See the santabs.md document for more information on bundles and bundle hashes.

checkcache

This is used to check if a particular file is apart of santa-driver’s kernel cache. Mainly for debugging purposes.

⇒  santactl checkcache /usr/bin/yes
File does not exist in cache
⇒  /usr/bin/yes
y
y
y
y
y
^C
⇒  santactl checkcache /usr/bin/yes
File exists in [allowlist] kernel cache
flushcache

This can be used to flush santa-driver’s kernel cache, as shown here.

⇒  santactl checkcache /usr/bin/yes
File exists in [allowlist] kernel cache
⇒  sudo santactl flushcache
Cache flush requested
⇒  santactl checkcache /usr/bin/yes
File does not exist in cache