metadata subsection to track changes in customized rules #298

New Issue

michael · 2026-01-19T18:29:59Z

michael commented

2026-01-19 18:29:59 +00:00

Originally created by @jamierrichardson on GitHub.

Problem to solve

Make it easier to track SPECIFIC changes to yaml files in the custom folder. Custom tags are a needed feature, but they introduce the issue that it becomes difficult to track changes to fixes, changes in results, changes in checks, changes in discussions, or changes in tags in the custom folder, when every file is tagged. By including some metadata of whether a file is changed, it is easy to track what has actually been changed in the yaml files

I'm proposing a set of metadata tags inside the yaml file:

customDiscussion
customCheck
customResult
customFix
customTags

These are binary settings, true or false

By default, all the tags in the project would have these set to false. When edited, the metadata could be set to true, to allow for quick queries of different customizations in a mdm or security tool. The SOP would be copy a file and edit it in the Custom folder, where the tags would then be set.

additional tags could be

requiresCustomization ( for yaml rules like timeserver or any other item needing organizational personalization)

and

requiresAdminReview (for yaml rules like mandatory smartcard enforcement, which can impact system usability if not properly understood)

Intended users

This should make it easier for mdm vendors to present files that require changes or have been changed. It should also make it easier for admins who have changed files to track what files have what type of changes, to accelerate yearly organizational customizations

Further details

While this could be done with tags in macOS's Finder easily, placing the metadata in the yaml files keeps each rule truly portable, and gives a means for the tool builder or admin to track changes by adjusting a set of defined metadata tags.

Proposal

Simply add a metadata section to the yaml files used to track changes of specific sections

Documentation

none

Testing

Customize yaml files and edit the metadata tags. query on the types of changes.

What does success look like, and how can we measure that?

Adding some additional metadata is a lightweight way to keep track of customized yaml files, and specifically what section has been customized- this is very useful visualizing needed changes during yearly OS updates.
A mdm vendor has the ability to allow customizations in the gui, and then has the ability to organize and track changes, so an admin can review customizations by type. If a sysadmin can query files by types of changes, we can accelerate yearly change management

Links / references

none

Originally created by @jamierrichardson on GitHub. ### Problem to solve Make it easier to track SPECIFIC changes to yaml files in the custom folder. Custom tags are a needed feature, but they introduce the issue that it becomes difficult to track changes to fixes, changes in results, changes in checks, changes in discussions, or changes in tags in the custom folder, when every file is tagged. By including some metadata of whether a file is changed, it is easy to track what has actually been changed in the yaml files I'm proposing a set of metadata tags inside the yaml file: customDiscussion customCheck customResult customFix customTags These are binary settings, true or false By default, all the tags in the project would have these set to false. When edited, the metadata could be set to true, to allow for quick queries of different customizations in a mdm or security tool. The SOP would be copy a file and edit it in the Custom folder, where the tags would then be set. additional tags could be requiresCustomization ( for yaml rules like timeserver or any other item needing organizational personalization) and requiresAdminReview (for yaml rules like mandatory smartcard enforcement, which can impact system usability if not properly understood) ### Intended users This should make it easier for mdm vendors to present files that require changes or have been changed. It should also make it easier for admins who have changed files to track what files have what type of changes, to accelerate yearly organizational customizations ### Further details While this could be done with tags in macOS's Finder easily, placing the metadata in the yaml files keeps each rule truly portable, and gives a means for the tool builder or admin to track changes by adjusting a set of defined metadata tags. ### Proposal Simply add a metadata section to the yaml files used to track changes of specific sections ### Documentation none ### Testing Customize yaml files and edit the metadata tags. query on the types of changes. ### What does success look like, and how can we measure that? Adding some additional metadata is a lightweight way to keep track of customized yaml files, and specifically what section has been customized- this is very useful visualizing needed changes during yearly OS updates. A mdm vendor has the ability to allow customizations in the gui, and then has the ability to organize and track changes, so an admin can review customizations by type. If a sysadmin can query files by types of changes, we can accelerate yearly change management ### Links / references none

michael closed this issue

2026-01-19 18:29:59 +00:00

michael commented

2026-01-19 18:29:59 +00:00

@golbiga commented on GitHub:

This is now in main as we record what custom changes are made in the csv.

@golbiga commented on GitHub: This is now in `main` as we record what custom changes are made in the csv.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: usnistgov/macos_security#298