README
¶
cert-payload
Support for managing embedded JSON payloads generated by a plugin from the atc0005/check-cert project
Table of contents
Overview
This package provides support and functionality for managing embedded JSON
payloads generated by a plugin from the atc0005/check-cert project.
Status
While attempts are made to provide stability, this codebase is subject to change without notice and may break client code that depends on it. You are encouraged to vendor this package if you find it useful until such time that the API is considered stable.
Features
- placeholder
Changelog
See the CHANGELOG.md file for the changes associated with
each release of this application. Changes that have been merged to master,
but not yet an official release may also be noted in the file under the
Unreleased section. A helpful link to the Git commit history since the last
official release is also provided for further review.
Examples
Add this line to your imports like so:
package main
import (
"fmt"
"log"
"os"
payload "github.com/atc0005/cert-payload"
)
and pull in a specific version of this library that you'd like to use.
go get github.com/atc0005/cert-payload@v0.1.0
Alternatively, you can use the latest stable tag available to get started:
go get github.com/atc0005/cert-payload@latest
See https://pkg.go.dev/github.com/atc0005/cert-payload for specific examples.
See https://pkg.go.dev/github.com/atc0005/cert-payload?tab=importedby for projects that are using this library.
License
From the LICENSE file:
MIT License
Copyright (c) 2024 Adam Chalkley
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.
Used by
See the Known importers lists below for a dynamically updated list of projects using either this library or the original project.
References
See also the Used by section for projects known to be using this package. Please report any additional projects that we've missed!
Documentation
¶
Overview ¶
Package payload provides support for managing embedded JSON payloads generated by the `check_cert` plugin within this project.
See our GitHub repo:
- to review documentation (including examples)
- for the latest code
- to file an issue or submit improvements for review and potential inclusion into the project
Index ¶
Constants ¶
const ( StateOKLabel string = "OK" StateWARNINGLabel string = "WARNING" StateCRITICALLabel string = "CRITICAL" StateUNKNOWNLabel string = "UNKNOWN" StateDEPENDENTLabel string = "DEPENDENT" )
Nagios plugin/service check state "labels". These values are used (where applicable) by the CertChainPayload `ServiceState` field.
const ( ValidityPeriod1Year string = "1 year" ValidityPeriod90Days string = "90 days" ValidityPeriod45Days string = "45 days" ValidityPeriodUNKNOWN string = "UNKNOWN" )
Validity period keywords intended as human readable output.
Common historical certificate lifetimes:
- 5 year (1825 days, 60 months) - 3 year (1185 days, 39 months) - 2 year (825 days, 27 months) - 1 year (398 days, 13 months)
See also:
- https://www.sectigo.com/knowledge-base/detail/TLS-SSL-Certificate-Lifespan-History-2-3-and-5-year-validity/kA01N000000zFKp - https://support.sectigo.com/Com_KnowledgeDetailPage?Id=kA03l000000o6cv - https://www.digicert.com/faq/public-trust-and-certificates/how-long-are-tls-ssl-certificate-validity-periods - https://docs.digicert.com/en/whats-new/change-log/older-changes/change-log--2023.html#certcentral--changes-to-multi-year-plan-coverage - https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/maximum-validity-changes-for-tls-ssl-to-drop-to-825-days-in-q1-2018 - https://chromium.googlesource.com/chromium/src/+/666712ff6c7ba7aa5da380bc0a617b637c9232b3/net/docs/certificate_lifetimes.md - https://www.entrust.com/blog/2017/03/maximum-certificate-lifetime-drops-to-825-days-in-2018
Variables ¶
var ( // ErrMissingValue indicates that an expected value was missing. ErrMissingValue = errors.New("missing expected value") )
Functions ¶
func CertChainToJSON ¶
func CertChainToJSON(certChain []*x509.Certificate) ([]byte, error)
CertChainToJSON encodes the certificate chain in PEM format and then marshals the PEM-encoded certificates to JSON. An error is returned if an invalid cert chain is provided or if the marshaling process fails.
func CertChainToPEM ¶
func CertChainToPEM(certChain []*x509.Certificate) ([]string, error)
CertChainToPEM encodes the certificate chain in PEM format as a slice of string values. An error is returned if an invalid cert chain is provided.
Types ¶
type CertChainPayload ¶
type CertChainPayload struct {
// CertChainOriginal is the original certificate chain entries encoded in
// PEM format.
//
// Due to size constraints this field may not be populated if the user did
// not explicitly opt into bundling the full certificate chain.
CertChainOriginal []string `json:"cert_chain_original"`
// CertChainSubset is a customized subset of the original certificate
// chain metadata. This field should always be populated.
CertChainSubset []Certificate `json:"cert_chain_subset"`
// Server is the FQDN or IP Address specified to the plugin which was used
// to retrieve the certificate chain.
//
// TODO: Considering making this a struct with fields for resolved IP
// Address and original CLI flag value (often a FQDN, but just as often a
// fixed IP Address).
Server string `json:"server"`
// A fully-qualified domain name or IP Address in the Subject Alternate
// Names (SANs) list for the leaf certificate.
//
// Depending on how the check_cert plugin was called this value may not be
// set (e.g., the `server` flag is sufficient if specifying a valid FQDN
// associated with the leaf certificate).
DNSName string `json:"dns_name"`
// TCPPort is the TCP port of the remote certificate-enabled service. This
// is usually 443 (HTTPS) or 636 (LDAPS).
TCPPort int `json:"tcp_port"`
// Issues is an aggregated collection of problems detected for the
// certificate chain.
Issues CertificateChainIssues `json:"cert_chain_issues"`
// ServiceState is the monitoring system's evaluated state for the service
// check performed against a given certificate chain (e.g., OK, CRITICAL,
// WARNING, UNKNOWN).
ServiceState string `json:"service_state"`
}
CertChainPayload is the "parent" data structure which represents the information to be encoded as a payload and later decoded for use in reporting (and other) tools.
type Certificate ¶
type Certificate struct {
// Subject is the full subject value for a certificate. This is intended
// for (non-cryptographic) comparison purposes.
Subject string `json:"subject"`
// CommonName is the short subject value of a certificate. This is
// intended for display purposes.
CommonName string `json:"common_name"`
// SANsEntries is the full list of Subject Alternate Names for a
// certificate.
SANsEntries []string `json:"sans_entries"`
// SANsEntriesCount is the number of Subject Alternate Names for a
// certificate.
//
// This field allows the payload creator to omit SANs entries to conserve
// plugin output size and still indicate the number of SANs entries
// present for a certificate for use in display or for metrics purposes.
SANsEntriesCount int `json:"sans_entries_count"`
// Issuer is the full CommonName of the signing certificate. This is
// intended for (non-cryptographic) comparison purposes.
Issuer string `json:"issuer"`
// IssuerShort is the short CommonName of the signing certificate. This is
// intended for display purposes.
IssuerShort string `json:"issuer_short"`
// SerialNumber is the serial number for a certificate in hex format with
// a colon inserted after each two digits.
//
// For example, `77:BD:0D:6C:DB:36:F9:1A:EA:21:0F:C4:F0:58:D3:0D`.
SerialNumber string `json:"serial_number"`
// IssuedOn is a RFC3389 time value for when a certificate is first
// valid or usable.
IssuedOn time.Time `json:"not_before"`
// ExpiresOn is a RFC3389 time value for when the certificate expires.
ExpiresOn time.Time `json:"not_after"`
// DaysRemaining is the number of days remaining for a certificate in two
// digit decimal precision.
DaysRemaining float64 `json:"days_remaining"`
// DaysRemainingTruncated is the number of days remaining for a
// certificate as a whole number rounded down.
//
// For example, if five and a half days remain then this value would be
// `5`.
DaysRemainingTruncated int `json:"days_remaining_truncated"`
// LifetimePercent is percentage of life remaining for a certificate.
//
// For example, if 43% life is remaining for a cert (a rounded value) this
// field would be set to `43`.
LifetimePercent int `json:"lifetime_remaining_percent"`
// ValidityPeriodDescription is the human readable value such as "90 days"
// or "1 year".
ValidityPeriodDescription string `json:"validity_period_description"`
// ValidityPeriodDays is the number of total days a certificate is valid
// for using `Not Before` & `Not After` as the starting & ending range.
ValidityPeriodDays int `json:"validity_period_days"`
// human readable summary such as, `[OK] 1199d 2h remaining (43%)`
Summary string `json:"summary"`
// Status is the overall status of the certificate.
Status CertificateStatus `json:"status"`
// SignatureAlgorithm indicates what certificate signature algorithm was
// used by a certification authority (CA)'s private key to sign a checksum
// calculated by a signature hash algorithm (i.e., what algorithm was used
// to sign the certificate). The verifying party must use the same
// algorithm to decrypt and verify the checksum using the CA's public key.
//
// A cryptographically weak hashing algorithm (e.g. MD2, MD4, MD5, SHA1)
// used to sign a certificate is considered to be a vulnerability.
SignatureAlgorithm string `json:"signature_algorithm"`
// Type indicates the type of certificate (leaf, intermediate or root).
Type string `json:"type"`
}
Certificate is a subset of the metadata for an evaluated certificate.
type CertificateChainIssues ¶
type CertificateChainIssues struct {
// MissingIntermediateCerts indicates that intermediate certificates are
// missing from the certificate chain.
MissingIntermediateCerts bool `json:"missing_intermediate_certs"`
// MissingSANsEntries indicates that SANs entries are missing from a leaf
// certificate within the certificates chain.
MissingSANsEntries bool `json:"missing_sans_entries"`
// DuplicateCerts indicates that there are one or more duplicate copies of
// a certificate in the certificate chain.
DuplicateCerts bool `json:"duplicate_certs"`
// ExpiredCerts indicates that there are one or more expired certificates
// in the certificate chain.
ExpiredCerts bool `json:"expired_certs"`
// HostnameMismatch indicates that the name or IP Address used to
// establish a connection to a certificate-enabled service does not match
// the list of valid host names honored by the leaf certificate.
//
// Historically the Common Name (CN) field was searched in addition to the
// Subject Alternate Names (SANs) field for a match, but this practice is
// deprecated and many clients (e.g., web browsers) no longer support
// this.
HostnameMismatch bool `json:"hostname_mismatch"`
// SelfSignedLeafCert indicates that the leaf certificate is self-signed.
// This is fairly common for development/test environments but is not best
// practice for certificates used outside of temporary / lab environments.
SelfSignedLeafCert bool `json:"self_signed_leaf_cert"`
// WeakSignatureAlgorithm indicates that the certificate chain has been
// signed using a cryptographically weak hashing algorithm (e.g. MD2, MD4,
// MD5, or SHA1). These signature algorithms are known to be vulnerable to
// collision attacks. An attacker can exploit this to generate another
// certificate with the same digital signature, allowing an attacker to
// masquerade as the affected service.
//
// NOTE: This does not apply to trusted root certificates; TLS clients
// trust them by their identity instead of the signature of their hash;
// client code setting this field would need to exclude root certificates
// from the determination whether the chain is vulnerable to weak
// signature algorithms.
//
// - https://security.googleblog.com/2014/09/gradually-sunsetting-sha-1.html
// - https://security.googleblog.com/2015/12/an-update-on-sha-1-certificates-in.html
// - https://superuser.com/questions/1122069/why-are-root-cas-with-sha1-signatures-not-a-risk
// - https://developer.mozilla.org/en-US/docs/Web/Security/Weak_Signature_Algorithm
// - https://www.tenable.com/plugins/nessus/35291
// - https://docs.ostorlab.co/kb/WEAK_HASHING_ALGO/index.html
WeakSignatureAlgorithm bool `json:"weak_signature_algorithm"`
}
CertificateChainIssues is an aggregated collection of problems detected for the certificate chain.
type CertificateStatus ¶
type CertificateStatus struct {
OK bool `json:"status_ok"` // No observed issues; shouldn't this be calculated?
Expiring bool `json:"status_expiring"` // Based on given monitoring thresholds
Expired bool `json:"status_expired"` // Based on certificate NotAfter field
}
CertificateStatus is the overall status of a certificate.
- no problems (ok) - expired - expiring (based on given threshold values) - revoked (not yet supported)
TODO: Any useful status values to borrow here? They have `Active`, `Revoked` and then a `Pending*` variation for both. https://developers.cloudflare.com/ssl/reference/certificate-statuses/#client-certificates
Source Files