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, head over to the Policies page in the Addigy portal, select Catalog at the top of the page, and select the Custom Facts tab within the Catalog. From here, you can create new Custom Facts and view or edit existing Custom Facts.
Select Create Custom Fact + 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.
Currently, the OS(es) Supported is limited to macOS. In future releases, other device OS types will be available here.
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, only Bash and Python are supported, but other languages may be available in the future.
The hashbang textbox contains a path to the binary that will run your fact. By default, it will be the macOS default locations for both languages: #!/bin/bash for Bash scripts or #!/usr/bin/python for Python scripts. 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
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.
For a more detailed look at building Custom Facts, see our article Best Practices and Examples of Custom Facts.