From 4386ed4fca7bc6d1a02c3325fd1a3ae0dba1da9c Mon Sep 17 00:00:00 2001 From: Rich Megginson Date: Mon, 27 Apr 2026 10:52:34 -0600 Subject: [PATCH] feat: add role fingerprints to syslog Feature: Add a fingerprint string to the system log to indicate when the role began successfully, and when the role finished successfully. The fingerprint string indicates the role name, a timestamp, and the platform. Reason: Users can see when the role was used and if it was used successfully. This information from the system log can be collected by log scanners and aggregators for further analysis. Result: The role logs fingerprints to the system log. This also adds a test to check if the fingerprints were written upon a successful role invocation. Signed-off-by: Rich Megginson --- .sanity-ansible-ignore-2.14.txt | 1 + .sanity-ansible-ignore-2.16.txt | 1 + .sanity-ansible-ignore-2.17.txt | 1 + .sanity-ansible-ignore-2.18.txt | 1 + .sanity-ansible-ignore-2.19.txt | 1 + .sanity-ansible-ignore-2.20.txt | 1 + .sanity-ansible-ignore-2.21.txt | 1 + .sanity-ansible-ignore-2.22.txt | 1 + library/sr_fingerprint.py | 88 ++++++++++++++++++++++ tasks/main.yml | 6 ++ tasks/set_vars.yml | 6 ++ tests/roles/linux-system-roles.ssh/library | 1 + tests/tests_default.yml | 25 ++++++ 13 files changed, 134 insertions(+) create mode 100644 .sanity-ansible-ignore-2.14.txt create mode 100644 .sanity-ansible-ignore-2.16.txt create mode 100644 .sanity-ansible-ignore-2.17.txt create mode 100644 .sanity-ansible-ignore-2.18.txt create mode 100644 .sanity-ansible-ignore-2.19.txt create mode 100644 .sanity-ansible-ignore-2.20.txt create mode 100644 .sanity-ansible-ignore-2.21.txt create mode 100644 .sanity-ansible-ignore-2.22.txt create mode 100644 library/sr_fingerprint.py create mode 120000 tests/roles/linux-system-roles.ssh/library diff --git a/.sanity-ansible-ignore-2.14.txt b/.sanity-ansible-ignore-2.14.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.14.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.16.txt b/.sanity-ansible-ignore-2.16.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.16.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.17.txt b/.sanity-ansible-ignore-2.17.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.17.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.18.txt b/.sanity-ansible-ignore-2.18.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.18.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.19.txt b/.sanity-ansible-ignore-2.19.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.19.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.20.txt b/.sanity-ansible-ignore-2.20.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.20.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.21.txt b/.sanity-ansible-ignore-2.21.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.21.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/.sanity-ansible-ignore-2.22.txt b/.sanity-ansible-ignore-2.22.txt new file mode 100644 index 00000000..fae055c2 --- /dev/null +++ b/.sanity-ansible-ignore-2.22.txt @@ -0,0 +1 @@ +plugins/modules/sr_fingerprint.py validate-modules:missing-gplv3-license diff --git a/library/sr_fingerprint.py b/library/sr_fingerprint.py new file mode 100644 index 00000000..593dd39f --- /dev/null +++ b/library/sr_fingerprint.py @@ -0,0 +1,88 @@ +#!/usr/bin/python + +from __future__ import absolute_import, division, print_function + +__metaclass__ = type + +DOCUMENTATION = """ +--- +module: sr_fingerprint +short_description: Write a message string to syslog using Ansible C(module.log) function. +description: + - Writes the given string to the system log using Ansible C(module.log) function. + - Intended for role-internal or diagnostic use. +author: Rich Megginson (@richm) +options: + sr_message: + description: Text to record in syslog. + type: str + required: true +""" + +EXAMPLES = """ +- name: Record a fingerprint message in syslog + sr_fingerprint: + sr_message: "system_role:ROLENAME" +""" + +RETURN = r""" # """ + +from ansible.module_utils.basic import AnsibleModule + +import datetime + + +def _local_iso8601_no_microseconds(): + """System local wall clock with local tz offset, ISO 8601, seconds only.""" + try: + utc = datetime.timezone.utc + except AttributeError: + import time + + return time.strftime("%Y-%m-%dT%H:%M:%S%z", time.localtime()) + # Prefer the local clock interpreted in the system timezone (not UTC displayed). + now = datetime.datetime.now() + astimezone = getattr(now, "astimezone", None) + if astimezone is not None: + try: + return astimezone().replace(microsecond=0).isoformat() + except (OSError, TypeError, ValueError): + pass + return datetime.datetime.now(utc).astimezone().replace(microsecond=0).isoformat() + + +def run_module(): + module_args = dict( + sr_message=dict(type="str", required=True), + ) + + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True, + ) + + log_message = "%s %s" % ( + module.params["sr_message"], + _local_iso8601_no_microseconds(), + ) + + if module.check_mode: + module.exit_json( + changed=False, + message="Check mode: message not logged - [%s]" % log_message, + ) + + module.log(log_message) + + # we don't actually change anything, so we're not changed - writing a log message + # is not considered a change + # also, we don't want to report changed every time the role runs + module.exit_json(changed=False) + + +def main(): + run_module() + + +if __name__ == "__main__": + main() diff --git a/tasks/main.yml b/tasks/main.yml index 7cbe5a65..4e3d3bc9 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -82,3 +82,9 @@ __ssh_config_mode: "{{ ssh_config_mode if ssh_config_mode is not none else '0600' if ssh_user is not none else '0644' }}" + +- name: Record role success fingerprint + sr_fingerprint: + sr_message: >- + success system_role:ssh ansible_version={{ ansible_version.full }} + {{ ansible_facts['distribution'] }}-{{ ansible_facts['distribution_version'] }} diff --git a/tasks/set_vars.yml b/tasks/set_vars.yml index 36969f28..6de4f08d 100644 --- a/tasks/set_vars.yml +++ b/tasks/set_vars.yml @@ -5,6 +5,12 @@ when: __ssh_required_facts | difference(ansible_facts.keys() | list) | length > 0 +- name: Record role begin fingerprint + sr_fingerprint: + sr_message: >- + begin system_role:ssh ansible_version={{ ansible_version.full }} + {{ ansible_facts['distribution'] }}-{{ ansible_facts['distribution_version'] }} + - name: Determine if system is ostree and set flag when: not __ssh_is_ostree is defined block: diff --git a/tests/roles/linux-system-roles.ssh/library b/tests/roles/linux-system-roles.ssh/library new file mode 120000 index 00000000..ba40d2f5 --- /dev/null +++ b/tests/roles/linux-system-roles.ssh/library @@ -0,0 +1 @@ +../../../library \ No newline at end of file diff --git a/tests/tests_default.yml b/tests/tests_default.yml index b1f457d2..8b3fc9a7 100644 --- a/tests/tests_default.yml +++ b/tests/tests_default.yml @@ -12,11 +12,36 @@ - name: Ensure that the role runs with default parameters hosts: all tasks: + - name: See if /dev/log exists for the fingerprint check + ansible.builtin.stat: + path: /dev/log + register: __register_dev_log + + - name: Set the start time for the journal search + ansible.builtin.set_fact: + __journal_start_time: "{{ ansible_facts['date_time']['date'] ~ ' ' ~ ansible_facts['date_time']['time'] }}" + when: __register_dev_log.stat.exists + - name: Run role include_tasks: tasks/run_role_with_clear_facts.yml vars: __sr_public: true + # look for the exact module invocation, not some other message that might contain the string + - name: Check system journal contains role fingerprints + ansible.builtin.shell: + executable: /bin/bash + cmd: >- + set -eo pipefail; + journalctl --since "{{ __journal_start_time }}" --no-pager | + grep -v " Invoked with" | grep "sr_fingerprint.*begin system_role:ssh" || + { echo ERROR: BEGIN fingerprint not found; exit 1; }; + journalctl --since "{{ __journal_start_time }}" --no-pager | + grep -v " Invoked with" | grep "sr_fingerprint.*success system_role:ssh" || + { echo ERROR: SUCCESS fingerprint not found; exit 1; } + changed_when: false + when: __register_dev_log.stat.exists + - name: Restore configuration files hosts: all vars: