This python3
script leverages the Kandji and Snipe-IT APIs to accomplish two things:
- Sync device details from Kandji to Snipe-IT
- Sync asset tags from Snipe-IT to Kandji.
kandji2snipe is designed to sync assets between your Kandji and Snipe-IT instances. The tool searches for assets based on the serial number, not the existing asset tag. If assets exist in Kandji and are not in Snipe-IT, the tool will create an asset and try to match it with an existing Snipe-IT model. This match is based on the device's model identifier (ex. MacBookAir7,1) being entered as the model number in Snipe-IT, rather than the model name. If a matching model isn't found, it will create one.
When an asset is first created, it will fill out only the most basic information. If the asset already exists in your Snipe-IT inventory, the tool will sync the information you specify in the settings.conf file and make sure that the asset tag in Kandji matches the asset tag in Snipe-IT, where Snipe-IT's asset tag for that device is considered the authority.
If the asset tag field is blank in Kandji when the record is being created in Snipe-IT, the script will create an asset tag with KANDJI-$SERIAL_NUMBER
unless you enable use_custom_pattern
in your settings.conf
file.
- Python3
- Python dependencies - Can be installed using the included
requirements.txt
using the commandpython3 -m pip install -r requirements.txt
or individually using the commandspython3 -m pip install requests
andpython3 -m pip install pytz
. - A Kandji API token with the following permissions:
- Devices
- Update a device
- Device details
- Device list
- Device ID
- Devices
- A Snipe-IT API key for a user with the following permissions:
- Assets
- View
- Create
- Edit
- Checkin
- Checkout
- Users
- View
- Models
- View
- Create
- Edit
- Self
- Two-Factor Authentication (recommended, but not required)
- Create API Keys
- Assets
All of the keys highlighted in bold below are required in your settings.conf
file. Please review the settings.conf.example file for example settings and additional details.
Note: do not add ""
or ''
around any values.
[kandji]
tenant
: Your tenant name, for example accuhive.kandji.io would be accuhiveregion
: us or euapitoken
: Your Kandji API token
[snipe-it]
url
: The base URL for your Snipe-IT instance (ie https://snipeit.example.com)apikey
: Your Snipe-IT API keytime_zone
: The time zone that your Snipe-IT instance is set to. Refer toAPP_TIMEZONE=
in your Snipe-IT .env file.manufacturer_id
: The manufacturer database field id for Apple in your Snipe-IT instance.defaultStatus
: The status database field id to assign to new assets created in Snipe-IT from Kandji. Typically you will want to pick a status like "Ready To Deploy".mac_model_category_id
: The ID of the category you want to assign to Mac computers. You will have to create this in Snipe-IT and note the Category ID.iphone_model_category_id
: The ID of the category you want to assign to iPhones. You will have to create this in Snipe-IT and note the Category ID.ipad_model_category_id
: The ID of the category you want to assign to iPads. You will have to create this in Snipe-IT and note the Category ID.appletv_model_category_id
: The ID of the category you want to assign to Apple TVs. You will have to create this in Snipe-IT and note the Category ID.mac_custom_fieldset_id
: The ID of the category you want to assign to Mac computers. You will have to create this in Snipe-IT and note the Category ID.iphone_custom_fieldset_id
: The ID of the category you want to assign to iPhones. You will have to create this in Snipe-IT and note the Category ID.ipad_custom_fieldset_id
: The ID of the category you want to assign to iPads. You will have to create this in Snipe-IT and note the Category ID.appletv_custom_fieldset_id
: The ID of the category you want to assign to Apple TVs. You will have to create this in Snipe-IT and note the Category ID.
[asset-tag]
use_custom_pattern
: Set to yes to set your own patterns, if set to no, devices with no existing asset tag in Kandji will default toKANDJI-$SERIAL_NUMBER
.pattern_mac
: The pattern to use when creating new Macs in Snipe-IT that do not have an asset tag in Kandji.pattern_iphone
: The pattern to use when creating new iPhones in Snipe-IT that do not have an asset tag in Kandji.pattern_ipad
: The pattern to use when creating new iPads in Snipe-IT that do not have an asset tag in Kandji.pattern_appletv
: The pattern to use when creating new Apple TVs in Snipe-IT that do not have an asset tag in Kandji.
Note:
The following sections require custom fields to be created in Snipe-IT. Please see the API Mapping section for details.
[mac-api-mapping]
[iphone-api-mapping]
[ipad-api-mapping]
[appletv-api-mapping]
To get the database fields for Snipe-IT Custom Fields, go to Settings and then Custom Fields inside of your Snipe-IT instance, scroll down past Fieldsets to Custom Fields, click the column selection button and make sure the 'DB Field' checkbox is checked. Copy and paste the DB Field name for Snipe-IT under platform-api-mapping sections in your settings.conf
file.
To get the API mapping fields for Kandji, refer to Kandji's Device Details API example response.
Some example API mappings can be found below:
- MAC Address:
_snipeit_<your_mac_address_custom_field_id> = general mac_address
- IPv4 Address:
_snipeit_<your_IPv4_custom_field_id> = general ip_address
- Blueprint Name:
_snipeit_<your_blueprint_custom_field_id>_ = general blueprint_name
- FileVault Status:
_snipeit_<your_filevault_enabled_custom_field_id> = filevault filevault_enabled
- Kandji Device ID:
_snipeit_<your_device_id_custom_field_id> = general device_id
You need to set the manufacturer_id
for Apple devices in the settings.conf
file. You can grab the manufacturer_id
in Snipe-IT by going to Manufacturers > click the column selection button > select the ID
checkbox.
usage: kandji2snipe [-h] [-l] [-v] [-d] [--dryrun] [--version] [--auto_incrementing] [--do_not_update_kandji] [--do_not_verify_ssl] [-r] [-f] [-u] [-uns] [--mac | --iphone | --ipad | --appletv]
optional arguments:
-h, --help Shows this help message and exits.
-l, --logfile Saves logging messages to kandji2snipe.log instead of displaying on screen.
-v, --verbose Sets the logging level to INFO and gives you a better idea of what the script is doing.
-d, --debug Sets logging to include additional DEBUG messages.
--dryrun This checks your config and tries to contact both the Kandji and Snipe-IT instances, but exits before updating or syncing any assets.
--version Shows the version of this script and exits.
--auto_incrementing You can use this if you have auto-incrementing enabled in your Snipe-IT instance to utilize that instead of using KANDJI-<SERIAL NUMBER> for the asset tag.
--do_not_update_kandji Does not update Kandji with the asset tags stored in Snipe-IT.
--do_not_verify_ssl Skips SSL verification for all Snipe-IT requests. Helpful when you use self-signed certificate.
-r, --ratelimited Puts a half second delay between Snipe-IT API calls to adhere to the standard 120/minute rate limit
-f, --force Updates the Snipe-IT asset with information from Kandji every time, despite what the timestamps indicate.
-u, --users Checks in/out assets based on the user assignment in Kandji.
-uns, --users_no_search Doesn't search for any users if the specified fields in Kandji and Snipe-IT don't match. (case insensitive)
--mac Runs against Kandji Mac computers only.
--iphone Runs against Kandji iPhones only.
--ipad Runs against Kandji iPads only.
--appletv Runs against Kandji Apple TVs only.
It is recommended that you use a test/dev Snipe-IT instance for testing and that your backups are up to date. You can spin up a Snipe-IT instance in Docker pretty quickly (see the Snipe-IT docs).
If you do not have a test/dev Kandji tenant, you can test kandji2snipe using the --do_not_update_kandji
argument to prevent data being written back to Kandji.
kandji2snipe is inspired by and forked from jamf2snipe, created by Brian Monroe. Thank you for your contributions to the Mac Admin and Open Source communities!
If you have something you'd like to add please help by forking this project then creating a pull request to the develop
branch. When working on new features, please try to keep existing configs running in the same manner with no changes. When possible, open up an issue and reference it when you make your pull request.