Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for embedding an encoded JSON payload at tail end of LongServiceOutput content #960

Closed
atc0005 opened this issue Oct 3, 2024 · 3 comments · Fixed by #1017
Closed
Assignees
Labels
config enhancement New feature or request output/extended Long Service Output (aka, "extended" or "detailed") plugin/check_cert
Milestone

Comments

@atc0005
Copy link
Owner

atc0005 commented Oct 3, 2024

Overview

There may be better ways to handle this, but I want to make sure that the certificate chain captured by the monitoring plugin is exposed to the monitoring system.

The current plugin API permits passing human readable information back for display in a web UI or notifications and metrics for calculations & other data manipulation purposes, but AFAIK does not permit passing something like a JSON payload between plugin and the monitoring system.

My particular use case is accessing this information via the Nagios XI API, but I'd like to see this implemented in a way that's usable to others using the plugin from other monitoring systems.

I'd also like to see this implemented in an opt-in manner so that it's off by default.

While ideally the additional info would be available via a dedicated field of some kind, I'm considering whether it's a workable solution to provide a small, customized JSON payload in an encoded format (able to safely pass default sanitization requirements) that can be accessed later from the LongServiceOutput field.

I've not yet checked to confirm that the base64 encoding format would pass the illegal_macro_output_chars requirements, but assuming that it would, we'd still be limited by the default 4K plugin output requirements.

References

See also:

@atc0005 atc0005 added enhancement New feature or request question Further information is requested config plugin/check_cert output/extended Long Service Output (aka, "extended" or "detailed") labels Oct 3, 2024
@atc0005 atc0005 added this to the Future milestone Oct 3, 2024
@atc0005 atc0005 self-assigned this Oct 3, 2024
@atc0005
Copy link
Owner Author

atc0005 commented Oct 4, 2024

May need to also update the atc0005/go-nagios project to provide some helper functionality.

@atc0005 atc0005 modified the milestones: Future, v0.20.0 Oct 5, 2024
atc0005 added a commit to atc0005/go-nagios that referenced this issue Oct 15, 2024
OVERVIEW

Add support for embedding an encoded payload within and later
extracting the payload from plugin output.

The current Nagios plugin API permits returning human readable
information to Nagios for display in a web UI or notifications and
metrics for calculations & other data manipulation purposes. As far as
I know, Nagios does not permit passing something like a JSON payload
directly between the plugin and the monitoring system.

This new (optional) support provides a way for plugins to safely &
reliably embed content (e.g., JSON data) within the generated output
which can later be extracted by other tools.

Due to current Nagios plugin output length restrictions (8192 bytes),
the use of encoded payloads should be used sparingly.

CHANGES

- add standalone functions for encoding/decoding payload content
- add new `Plugin` methods for adding (append or overwrite behavior)
  content to be encoded and embedded as a payload
- add new `Plugin` methods to override behavior
  - opt out of using delimiters (NOT RECOMMENDED)
  - use custom delimiters
  - set custom payload section label
- minor README updates
  - note new functionality
  - refresh overview & status sections
- add test coverage for new functionality
- add numerous testdata input files
- add basic examples
  - extract and decode an embedded payload from (previous) plugin
    output
  - add encoded payload

CREDIT

I consulted ChatGPT when planning the implementation. While later
iterations of the code differed significantly, ChatGPT provided
code samples that acted as a starting point for the initial
encoding/decoding functionality.

Discussions with ChatGPT proved very helpful when deciding between
using the base64 encoding format (more common, but less efficient) and
the base85 (aka, "Ascii85") encoding format (more efficient). Those
discussions also covered concerns such as adhering to the default
`illegal_macro_output_chars` requirements that Nagios imposes for
plugin output.

REFERENCES

- refs #251
- refs atc0005/check-cert#960
atc0005 added a commit that referenced this issue Oct 15, 2024
Prepare for testing latest pre-release changes.

- refs atc0005/go-nagios#251
- refs #960
@atc0005
Copy link
Owner Author

atc0005 commented Nov 4, 2024

May need to also update the atc0005/go-nagios project to provide some helper functionality.

The v0.17.0 release of that project will provide the necessary support for encoding/decoding embedded payloads.

The https://github.com/atc0005/cert-payload project will provide a cert payload type for encoding/decoding the JSON data.

@atc0005
Copy link
Owner Author

atc0005 commented Nov 4, 2024

Current prototyping efforts are going well enough with most evaluated certificate chains falling below the 8K plugin output cutoff. However, there is one certificate chain I'm testing against which has 73 SANs entries. Listing all of them in the plugin output exceeds the 8k "budget".

Some debug output generated by the prototype:

[go-nagios] 2024/11/04 04:33:04 222 bytes plugin ServiceOutput content written to buffer
[go-nagios] 2024/11/04 04:33:04 3914 bytes plugin LongServiceOutput content written to buffer
[go-nagios] 2024/11/04 04:33:04 6251 bytes plugin EncodedPayload content written to buffer
[go-nagios] 2024/11/04 04:33:04 273 bytes plugin performance data content written to buffer
[go-nagios] 2024/11/04 04:33:04 10660 bytes total plugin output to write

For contrast, here is the debug output when evaluating the certificate used by www.google.com:

[go-nagios] 2024/11/04 04:43:16 217 bytes plugin ServiceOutput content written to buffer
[go-nagios] 2024/11/04 04:43:16 1602 bytes plugin LongServiceOutput content written to buffer
[go-nagios] 2024/11/04 04:43:16 272 bytes plugin performance data content written to buffer
[go-nagios] 2024/11/04 04:43:16 2091 bytes total plugin output to write

For the former cert chain, we'll need this flag to be implemented to bring the content down below the 8k plugin output limit:

atc0005 added a commit that referenced this issue Nov 6, 2024
Primary changes:

- add optional support for embedding an encoded certificate metadata
  payload
  - disabled by default to retain existing plugin behavior
  - the intent is to "shuttle" a payload of certificate metadata in
    structured format from the plugin, to the monitoring system and to
    downstream tools (e.g., via API call) so that the payload can be
    retrieved, decoded, & unmarshalled to a supported data structure
    for further certificate evaluation
    - see also the <https://github.com/atc0005/cert-payload> and
      <https://github.com/atc0005/go-nagios> projects for the data
      structures and supporting logic used in the encoding/decoding
      process
- add optional support for embedding an encoded certificate metadata
    payload *with the original certificate chain included* in PEM
    encoded format
  - this is not enabled by default due to the significant increase in
    plugin output size
- add logging of plugin output size calculations when debug logging is
  enabled
- update README with new features

Related/indirect changes:

- doc comments cleanup
  - e.g., `ExpirationValidationResult.ageWarningThreshold` field
- add `ExpirationValidationResult.AgeWarningThreshold` method
- add `ExpirationValidationResult.AgeCriticalThreshold` method
- add `atc0005/cert-payload` dependency
- extend `Config` type, constants, flags, etc. to handle new flags
- add `certs.ExpiresInDaysPrecise` function
- add `certs.ExpiresInHours` function
- add `certs.SANsEntriesLine` function

refs GH-960
atc0005 added a commit that referenced this issue Nov 6, 2024
Primary changes:

- add optional support for embedding an encoded certificate metadata
  payload
  - disabled by default to retain existing plugin behavior
  - the intent is to "shuttle" a payload of certificate metadata in
    structured format from the plugin, to the monitoring system and to
    downstream tools (e.g., via API call) so that the payload can be
    retrieved, decoded, & unmarshalled to a supported data structure
    for further certificate evaluation
    - see also the <https://github.com/atc0005/cert-payload> and
      <https://github.com/atc0005/go-nagios> projects for the data
      structures and supporting logic used in the encoding/decoding
      process
- add optional support for embedding an encoded certificate metadata
    payload *with the original certificate chain included* in PEM
    encoded format
  - this is not enabled by default due to the significant increase in
    plugin output size
- add logging of plugin output size calculations when debug logging is
  enabled
- update README with new features

Related/indirect changes:

- doc comments cleanup
  - e.g., `ExpirationValidationResult.ageWarningThreshold` field
- add `ExpirationValidationResult.AgeWarningThreshold` method
- add `ExpirationValidationResult.AgeCriticalThreshold` method
- add `atc0005/cert-payload` dependency
- extend `Config` type, constants, flags, etc. to handle new flags
- add `certs.ExpiresInDaysPrecise` function
- add `certs.ExpiresInHours` function
- add `certs.SANsEntriesLine` function

refs GH-960
@atc0005 atc0005 removed the question Further information is requested label Nov 6, 2024
@atc0005 atc0005 changed the title Test embedding an encoded JSON payload at tail end of LongServiceOutput content Add support for embedding an encoded JSON payload at tail end of LongServiceOutput content Nov 6, 2024
atc0005 added a commit to atc0005/go-nagios that referenced this issue Nov 6, 2024
OVERVIEW

Add support for embedding an encoded payload within and later
extracting the payload from plugin output.

The current Nagios plugin API permits returning human readable
information to Nagios for display in a web UI or notifications and
metrics for calculations & other data manipulation purposes. As far as
I know, Nagios does not permit passing something like a JSON payload
directly between the plugin and the monitoring system.

This new (optional) support provides a way for plugins to safely &
reliably embed content (e.g., JSON data) within the generated output
which can later be extracted by other tools.

Due to current Nagios plugin output length restrictions (8192 bytes),
the use of encoded payloads should be used sparingly.

CHANGES

- add standalone functions for encoding/decoding payload content
- add new `Plugin` methods for adding (append or overwrite behavior)
  content to be encoded and embedded as a payload
- add new `Plugin` methods to override behavior
  - opt out of using delimiters (NOT RECOMMENDED)
  - use custom delimiters
  - set custom payload section label
- minor README updates
  - note new functionality
  - refresh overview & status sections
- add test coverage for new functionality
- add numerous testdata input files
- add basic examples
  - extract and decode an embedded payload from (previous) plugin
    output
  - add encoded payload

CREDIT

I consulted ChatGPT when planning the implementation. While later
iterations of the code differed significantly, ChatGPT provided
code samples that acted as a starting point for the initial
encoding/decoding functionality.

Discussions with ChatGPT proved very helpful when deciding between
using the base64 encoding format (more common, but less efficient) and
the base85 (aka, "Ascii85") encoding format (more efficient). Those
discussions also covered concerns such as adhering to the default
`illegal_macro_output_chars` requirements that Nagios imposes for
plugin output.

REFERENCES

- refs #251
- refs atc0005/check-cert#960
atc0005 added a commit that referenced this issue Nov 7, 2024
Primary changes:

- add optional support for embedding an encoded certificate metadata
  payload
  - disabled by default to retain existing plugin behavior
  - the intent is to "shuttle" a payload of certificate metadata in
    structured format from the plugin, to the monitoring system and to
    downstream tools (e.g., via API call) so that the payload can be
    retrieved, decoded, & unmarshalled to a supported data structure
    for further certificate evaluation
    - see also the <https://github.com/atc0005/cert-payload> and
      <https://github.com/atc0005/go-nagios> projects for the data
      structures and supporting logic used in the encoding/decoding
      process
- add optional support for embedding an encoded certificate metadata
    payload *with the original certificate chain included* in PEM
    encoded format
  - this is not enabled by default due to the significant increase in
    plugin output size
- add logging of plugin output size calculations when debug logging is
  enabled
- update README with new features

Related/indirect changes:

- doc comments cleanup
  - e.g., `ExpirationValidationResult.ageWarningThreshold` field
- add `ExpirationValidationResult.AgeWarningThreshold` method
- add `ExpirationValidationResult.AgeCriticalThreshold` method
- add `atc0005/cert-payload` dependency
- extend `Config` type, constants, flags, etc. to handle new flags
- add `certs.ExpiresInDaysPrecise` function
- add `certs.ExpiresInHours` function
- add `certs.SANsEntriesLine` function

refs GH-960
atc0005 added a commit that referenced this issue Dec 1, 2024
Switch from using unstable/development format 0 by default to
using recently updated "stable" format 1.

Any further changes to format 1 will be applied as part of
preparing for release v0.7.0 of the cert-payload library.

refs GH-960
atc0005 added a commit that referenced this issue Dec 2, 2024
Switch from using unstable/development format 0 by default to
using recently updated "stable" format 1.

Any further changes to format 1 will be applied as part of
preparing for release v0.7.0 of the cert-payload library.

refs GH-960
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
config enhancement New feature or request output/extended Long Service Output (aka, "extended" or "detailed") plugin/check_cert
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant