A Mac command-line tool that generates kick-ass Jamf Pro reports.

Nindi Gill

Last update: Dec 15, 2022

Related tags

Command Line Kmart

Overview

KMART - Kick-Ass Mac Admin Reporting Tool

A command-line utility generating kick-ass Jamf Pro reports:

Features

Reporting on the following Jamf Pro objects:
- 💻 Mac
  - Advanced Searches
  - Applications
  - Configuration Profiles
  - Devices
  - Directory Bindings
  - Disk Encryptions
  - Dock Items
  - Extension Attributes
  - Packages
  - Policies
  - Printers
  - Restricted Software
  - Scripts
  - Smart Groups
  - Static Groups
- 📱 Mobile
  - Advanced Searches
  - Applications
  - Configuration Profiles
  - Devices
  - Extension Attributes
  - Smart Groups
  - Static Groups
- 🏢 Buildings
- 📂 Categories
- 🏬 Departments
- 📚 eBooks
- 🅱️ iBeacons
- 📶 Network Segments
📒 Customise reporting options via JSON, Property List or YAML configuration files
📋 Output reports as JSON, Property List, YAML, Markdown or HTML files
📤 Email reports to a list of recipients

Usage

OVERVIEW: Kick-Ass Mac Admin Reporting Tool

Generate kick-ass Jamf Pro reports.

USAGE: kmart [--json <json>] [--plist <plist>] [--yaml <yaml>] [--version]

OPTIONS:
  -j, --json <json>       JSON configuration file.
  -p, --plist <plist>     Property List configuration file.
  -y, --yaml <yaml>       YAML configuration file.
  -v, --version           Display the version of kmart.
  -h, --help              Show help information.

Configuration

See Sample Configs for all configuration options.

Note: Use the following command to encode your credentials in the configuration file:

printf 'username:password' | iconv --to-code ISO-8859-1 | base64 --input -

Privileges

kmart requires the following user privileges in order to report correctly.

Recommendations:

Create a separate Jamf Pro User Account
Do not just add these permissions to an existing account
If you are not reporting on everything, only enable the privileges that are required

Privilege	Create	Read	Update	Delete
Advanced Computer Searches	-	✅	-	-
Advanced Mobile Device	-	✅	-	-
Buildings	-	✅	-	-
Categories	-	✅	-	-
Computer Extension Attributes	-	✅	-	-
Computers	-	✅	-	-
Departments	-	✅	-	-
Directory Bindings	-	✅	-	-
Disk Encryption Configurations	-	✅	-	-
Dock Items	-	✅	-	-
eBooks	-	✅	-	-
iBeacons	-	✅	-	-
Mac App Store Apps	-	✅	-	-
macOS Configuration Profiles	-	✅	-	-
Mobile Device Apps	-	✅	-	-
Mobile Device Configuration Profiles	-	✅	-	-
Mobile Device Extension Attributes	-	✅	-	-
Mobile Devices	-	✅	-	-
Network Segments	-	✅	-	-
Packages	-	✅	-	-
Policies	-	✅	-	-
Printers	-	✅	-	-
Restricted Software Records	-	✅	-	-
Scripts	-	✅	-	-
Smart Computer Groups	-	✅	-	-
Smart Mobile Device Groups	-	✅	-	-
Static Computer Groups	-	✅	-	-
Static Mobile Device Groups	-	✅	-	-

Build Requirements

Swift 5.3.
Runs on macOS Catalina 10.15 and later.

Download

Grab the latest version of KMART from the releases page.

Credits / Thank You

Project created and maintained by Nindi Gill (ninxsoft).
Apple (apple) for Swift Argument Parser, used to perform command-line argument and flag operations.
JP Simard (jpsim) for Yams, used to export YAML.
John Sundell (JohnSundell) for Ink, used to generate HTML from Markdown.
Kitura (Kitura) for Swift-SMTP, used to send emails.
Sindre Sorhus (sindresorhus) for github-markdown-css, used to make the HTML output prettier.

Version History

1.1
- Report on one-off Mac Policies that were created via Jamf Remote (mac_policies_jamf_remote)
- Less ambiguous descriptions for Markdown / HTML output
- Better escaping of ASCII characters for Markdown / HTML output
- Fixed false-positive linter errors for Mac Extension Attributes with carriage returns (\r)
- Fixed Mac Directory Bindings reporting as Mac Disk Encryptions
- Fixed emailing report only if enabled is set to true
1.0
- Initial release

License

Copyright © 2021 Nindi Gill

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Comments

Nested Smart Groups

Smart Groups that are nested in other Smart groups show up as not being linked to any Policies.

Jamf (depending on your version) will prohibit the deletion of groups that have other Smart Groups dependent on them. For these reports though, it makes it seem like certain smart groups are unused or not scoped when in actuality they can be by association with the parent Smart Group

opened by slaneycoursera 5

Timeouts when running kmart

When attempting to run kmart I am getting "The Request Timed Out" messages when it appears to parsing larger groups of info from jamf. I did not have the issue with the dev environment, which is significantly smaller.

✅ [2021-06-16 12:47:47 +0000] - Performing lookups for Buildings: 8.9 seconds
✅ [2021-06-16 12:47:56 +0000] - Performing lookups for Categories: 122.7 seconds
✅ [2021-06-16 12:49:59 +0000] - Performing lookups for Departments: 1.3 seconds
✅ [2021-06-16 12:50:00 +0000] - Performing lookups for eBooks: 1.3 seconds
✅ [2021-06-16 12:50:01 +0000] - Performing lookups for Mac Advanced Searches:⛔️ [2021-06-16 12:53:15 +0000] - The request timed out.
⛔️ [2021-06-16 12:54:34 +0000] - The request timed out.
⛔️ [2021-06-16 12:59:15 +0000] - The request timed out.

opened by rthaley 4

Feature request: Slack webhook support

Hi, it'd be really handy if there was an export that could post results via a Slack webhook into a channel (with flags for webhook URL, username, icon/emoji icon, etc.).

opened by smashism 4
Consideration of Patch Management EAs

First of all, great tool you have created here! 💯

May Extension attributes created automatically by patch management appear here incorrectly: mac_extension_attributes_not_linked

But I think this is a limitation of Jamf Pro, as I haven't found a way to retrieve this info via Classic API or the newer Universal API.

opened by aduffner 3
Linting of Python scripts

Kmart currently only supports linting sh/bash/dash/ksh scripts via Shellcheck.

Look into adding support for Python linter(s), possibly (preferably?) flake8

opened by ninxsoft 2
Dock items with same name missing on report

I have multiple dock items with the same name that are not linked to anything, but only one of them came out on the report. The report picks up the first id number, but nothing after.

opened by redshirtdave 2
Mac Extension Attributes

Wonderful piece of software, thank you so much! I am seeing an issue with the Mac Extension Attributes.

Error for all items:

Literal carriage return. Run script through tr -d 'r' .

Thanks

opened by danielnovello 2
URL changes in Jamf 10.42

With the Jamf settings page changes, some of the URLs in Kmart reports are now incorrect. There may be others but the two I'm finding are:

Scripts: old url- https://mydomain.jamfcloud.com/view/settings/computer/scripts, new url- https://mydomain.jamfcloud.com/view/settings/computer-management/scripts.

Departments: old url- https://mydomain.jamfcloud.com//view/settings/network/departments, new url- https://mydomain.jamfcloud.com/view/settings/network-organization/departments

opened by thomasrmartin 1
Mac Policies No Payload

I'm trying to get a report of mac policies with no payload but despite marking it as true in the json config, it never reports anything.

"mac_policies_no_payload": true,

I have several other items enabled and they report ok but just not the 'mac policies no payload'.

opened by monodata 1
Option to Disable SMTP Auth

Currently I don't see an option to send an E-mail via an SMTP that doesn't require authentication. Would it be possible to add a key for "require_auth" and accept a true/false value? Or just ignore auth if the username and password fields are left blank?

This is what I get when using an SMTP that doesn't require auth.

├─ Sending Report(s) via Email ├─ The operation couldn’t be completed. (Socket.Socket.Error error 1.) └─ Total Email Time: 10.1 seconds

opened by TheFritz01 1
Teams support?

This is another great ninxsoft tool, thank you. My org uses Teams, not Slack - would it be difficult to create an integration for it along the same lines? Happy to help in any way I can.

opened by dhcav 1

Errors when Retrieving Jamf Pro API Endpoints

I run the kmart --json /Users/Shared/Kmart/config/config.json

┌───────────────────────────────────┐
 │ RETRIEVING JAMF PRO API ENDPOINTS │
└───────────────────────────────────┘
  ├─ Unable to find 'token' and 'expires' keys in URL response
  ├─ Buildings - The operation couldn’t be completed. (KMART.KmartError error 4.)
  ├─ 
  ├─ Unable to find 'token' and 'expires' keys in URL response
  ├─ Departments - The operation couldn’t be completed. (KMART.KmartError error 4.)
  ├─ 
  ├─ Unable to find 'token' and 'expires' keys in URL response
  ├─ eBooks - The operation couldn’t be completed. (KMART.KmartError error 4.)```

I have added the credentials correctly to the config.json would this happen if SSO is in place even if we have a username/password account in jamfcloud?

opened by cpeonepeloton 1

Mac Scoping ignores Users and User Groups Targets

It appears the Jamf Pro Classic API does not provide the scoped User and User Groups Targets on Mac Policies.

This causes a Mac Policy to report as "No Scope", even if a User or User Group is scoped as a Target.

Further investigation required.

opened by ninxsoft 0

Releases(v1.3.2)

v1.3.2(Dec 25, 2022)
Fixed an issue where mac_policies_no_payload was not reporting correctly (thanks monodata)

URL slugs have been updated to match recent Jamf Pro changes (thanks thomasrmartin)

Source code(tar.gz)
Source code(zip)
Kmart.1.3.2.pkg(2.59 MB)
v1.3.1(Aug 7, 2022)
Nested Smart Groups are now also detected when generating reports

Source code(tar.gz)
Source code(zip)
Kmart.1.3.1.pkg(2.56 MB)
v1.3(May 29, 2022)
Added support for linting Python scripts via flake8

Added support for reporting on Patch Management Software Titles:

New report types: mac_patch_policies_no_scope and mac_patch_policies_disabled

Existing reports now factor in Patch Management Software Titles and Patch Policies

Progress output is now dynamic, updating in-place

Basic Authentication has been replaced with Bearer Token Authentication

Option to send reports via Email has been removed

Fixed the missing Serial Number column header for Unmanaged Mac/Mobile Device reports in Markdown and HTML

General cosmetic bugfixes

Note: Kmart now uses Swift concurrency (async await), which significantly reduces the amount and complexity of HTTP code. Concurrency requires macOS Monterey 12, therefore support for macOS Catalina 10.15 and macOS Big Sur 11 has been dropped.
Source code(tar.gz)
Source code(zip)
KMART.1.3.pkg(2.53 MB)
v1.2(Aug 25, 2021)
Added support for sending reports via Slack

Read Basic app setup to create a Slack app with a Bot token

Note: The Bot token will require the chat:write and files:write permission scopes

See Sample Configs for more information

Added mac_devices_unmanaged and mobile_devices_unmanaged report types

Mac and Mobile device reports now exclude unmanaged devices

Added support for custom api_timeout value (default: 10)

Mac Packages now also display Categories in Markdown / HTML reports

Improved file handling for Mac Extension Attributes and Mac Scripts over 64KB

Fixed escaping of \ in JSON reports

Fixed escaping of _ in Markdown / HTML reports

Reduced verbosity of output messaging (reads much nicer)

Source code(tar.gz)
Source code(zip)
KMART.1.2.pkg(1.82 MB)
v1.1(Apr 12, 2021)
Report on one-off Mac Policies that were created via Jamf Remote (mac_policies_jamf_remote)

Less ambiguous descriptions for Markdown / HTML output

Better escaping of ASCII characters for Markdown / HTML output

Fixed false-positive linter errors for Mac Extension Attributes with carriage returns (\r)

Fixed Mac Directory Bindings reporting as Mac Disk Encryptions

Fixed emailing report only if enabled is set to true

Source code(tar.gz)
Source code(zip)
KMART.1.1.pkg(1.31 MB)
v1.0(Apr 4, 2021)
Initial Release

Source code(tar.gz)
Source code(zip)
KMART.1.0.pkg(1.31 MB)

Owner

Nindi Gill

Senior Apple & Linux Engineer @ University of Melbourne

GitHub

A Mac command-line tool that automatically downloads macOS Installers / Firmwares.

MIST - macOS Installer Super Tool A Mac command-line tool that automatically downloads macOS Installers / Firmwares: Features List all available macOS

483 Jan 8, 2023

Mac App Store: Embedding a Command Line tool using paths as arguments

Mac App Store: Embedding a Command Line tool using paths as arguments Code snippets to embed a Command Line tool using paths as arguments on the Mac A