The Addigy agent software installed on your Mac devices collects loads of meaningful data about the Mac and uploads that data to the Addigy platform in the form of facts. Facts are great for reporting on your machines and receiving alerts when a machine needs maintenance or leaves compliance. But, what happens if you need to collect information about your Macs that isn't contained in the default facts available to you?
With Custom Facts, you can extend the power of the Addigy agent beyond the default set of facts by building your own fact based on a script of your choice. Just like the default facts, Custom Facts can be listed on the Devices page and can be used to trigger Alerts and Remediation. In this article, we'll review how to build a Custom Fact and deploy a Custom Fact to one of your policies.
Creating a Custom Fact
To create a new Custom Fact, navigate to the Catalog and select the Custom Facts. From here, you can create new Custom Facts and view or edit existing Custom Facts.
Select New to begin. Your new Custom Fact will have a few components. Let's go through them one at a time.
Name should a good descriptor for your fact. It will be used as the header for this fact if you add it to a Devices Table View.
Return Type will be one of four options: string, number, boolean, or list. These types represent how the Addigy agent will collect output from your script and how it will appear in the rest of the system.
We currently support macOS and Raspberry Pi operation systems.
The Description field should contain a description of the fact. Use the description as a way to communicate with other Addigy users how to understand and leverage your fact. Consider adding information like: what the different results of the fact mean, how the result is collected, what versions of the OS it has been tested on, and if there are any special considerations or dependencies for your fact.
The dropdown menu allows you to select the scripting language you will be using. Currently, Z-Shell, Bash, and Python are supported.
The hashbang textbox contains a path to the binary that will run your fact. You can use this textbox to call a different interpreter for your script (a Python3 binary, for example). We recommend that you stick to the default hashbangs unless you understand how to call other interpreters or shells and know that the path will be available on your machines.
Finally, the scripting window provides a place for you to enter the script that will be run to collect your fact. All standard output and standard error from the script will be collected and parsed by the Addigy agent auditor for the specified return type.
For each return type, a specific type of output will be looked for:
- A string can be any set of Unicode characters. Newline characters will be removed from the output for formatting purposes.
- A number should be a single integer
- A boolean should be one of the following: "true", "false", "True", "False", "TRUE", or "FALSE"
- A list can be any number of strings delimited by newline characters
Copying a Device Fact
If you want to duplicate or clone a fact, click the Edit button next to the fact name, and press Clone.
This will open up the Creation view for Custom Facts with all the information prefilled. Its recommends you change the name to distinguish it from the original fact that was cloned.
Deploying a Custom Fact
Choose the policy where you would like to deploy your Custom Fact from the policy tree on the left-hand side of the Policies page and select Custom Facts.
From here, you can see all the Custom Facts in your organization and choose which facts should be deployed to these machines. Click Add to queue a fact for deployment, then go to Deploy Changes for the policy to confirm the deployment of the fact.
Some Custom Facts may contain sensitive scripts that you don't want to deploy to all the devices you manage. Don't worry. Custom Facts will only be deployed to the policies that you have added them to.
Once your Custom Fact has been created and deployed, it will be available just like the default facts in the Devices table and when creating alerts.
Custom facts will report "N/A" until the device has run an audit with the custom fact. The auditor will run every ~5 minutes, however, this can manually be pushed to a device by selecting "Refresh Data" within the device's GoLive page.
For a more detailed look at building Custom Facts, see our article Best Practices and Examples of Custom Facts.