santactl
This may be the most complex part of Santa. It does two types of work:
- It contains all of the code and functionality for syncing with a sync-server.
- 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 Syncing Overview. 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
santad | 0.9.19
santactl | 0.9.19
SantaGUI | 0.9.19
Again, a JSON version is available santactl version --json
⇒ santactl version --json
{
"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 document.
sync
The sync command is covered in the Syncing Overview 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.