Horizon lookup plugin

Note

This lookup plugin is part of the evertrust.horizon collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install evertrust.horizon.

To use it in a playbook, specify: evertrust.horizon.horizon_lookup.

Synopsis

  • Retrieve certificate’s information from Horizon.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('evertrust.horizon.horizon_lookup', key1=value1, key2=value2, ...) and query('evertrust.horizon.horizon_lookup', key1=value1, key2=value2, ...)

Parameter

Comments

ca_bundle

path

Path of a CA bundle used to validate the Horizon instance SSL certificate.

certificate_pem

string

A certificate in PEM format, or the path to the certificate PEM file.

src

path

The path to a certificate PEM file

client_cert

path

Path of a client certificate.

Required if you use certificate based authentication

client_key

path

Path to the private key used for client-certificate authentication.

Required if you use certificate based authentication.

Restrict access to the key and inventory configuration files.

connect_timeout

float

Maximum number of seconds to wait for the controller to establish a connection to Horizon.

Default: 10.0

endpoint

string / required

Your Horizon instance base endpoint.

It must include the protocol (https://) and no trailing slash nor path.

fields

list / elements=string

Fields to be retrieved from Horizon.

If omitted, all fields will be returned.

Choices:

  • "_id"

  • "certificate"

  • "discoveredTrusted"

  • "dn"

  • "holderId"

  • "issuer"

  • "keyType"

  • "labels"

  • "metadata"

  • "module"

  • "notAfter"

  • "notBefore"

  • "owner"

  • "profile"

  • "revocationDate"

  • "revocationReason"

  • "serial"

  • "signingAlgorithm"

  • "subjectAlternateNames"

  • "thirdPartyData"

read_timeout

float

Maximum number of seconds to wait between response reads by the controller after connecting to Horizon.

Default: 60.0

x_api_id

string

Horizon identifier

Required if you use credentials authentication

x_api_key

string

Secret API key used for Horizon credential authentication.

Required if you use credentials authentication.

Store this value with Ansible Vault.

Tasks containing lookup expressions with this value should use no_log=true.

Examples

vars:
  endpoint: "https://<horizon-endpoint>"
  x_api_id: "<horizon-id>"
  x_api_key: "<horizon-password>"
  # Send the certificate by specifying its content (string)
  my_pem: <a_webra_pem_file>
  # Send the certificate by specifying its file path
  pem_path:
    src: /pem/file/path

  # Sets a variable containing only one field (module)
  with_one: >-
    {{ lookup('evertrust.horizon.horizon_lookup', x_api_id=x_api_id,
              x_api_key=x_api_key, certificate_pem=my_pem, fields='module',
              endpoint=horizon_endpoint, wantlist=True) }}

  # Sets a variable containing a list of fields (module, _id)
  with_list: >-
    {{ lookup('evertrust.horizon.horizon_lookup', x_api_id=x_api_id,
              x_api_key=x_api_key, certificate_pem=my_pem,
              fields=['module', '_id'], endpoint=horizon_endpoint,
              wantlist=True) }}

  # Sets a variable containing every certificate field.
  without: >-
    {{ lookup('evertrust.horizon.horizon_lookup', x_api_id=x_api_id,
              x_api_key=x_api_key, certificate_pem=pem_path,
              endpoint=horizon_endpoint, wantlist=True) }}

Return Value

Key

Description

_id

string

Horizon internal certificate ID.

Returned: If specifically requested.

certificate

string

Certificate in PEM format.

Returned: If specifically requested.

crlSynchronized

boolean

True if the revocation status was reconciled from the CRL

Returned: If present and specifically requested.

discoveredTrusted

boolean

True if the certificate was discovered and trusted.

False if the certificate was discovered.

Absent if the certificate was not discovered.

Returned: If present and specifically requested.

discoveryData

list / elements=dictionary

Certificate discovery data.

Returned: Only if the certificate was discovered.

hostnames

list / elements=string

Host hostnames.

Returned: If present.

ip

string

Host IP address

Returned: Always.

operatingSystems

list / elements=string

Host operating systems

Returned: If present.

paths

list / elements=string

Host paths.

Returned: If present.

tlsPorts

list / elements=dictionary

Host TLS ports.

Returned: If present.

port

integer

Port number.

Returned: Always.

version

string

TLS version.

Returned: Always.

usages

list / elements=string

Certificate usages.

Returned: If present.

discoveryInfo

list / elements=dictionary

Certificate’s discovery info

Returned: If present and specifically requested

campaign

string

Campaign name.

Returned: Always.

identifier

string

Horizon user that discovered the certificate.

Returned: If present.

lastDiscoveryDate

integer

Last discovery date (UNIX timestamp in millis).

Returned: Always.

dn

string

Certificate DN.

Returned: If specifically requested.

holderId

string

Certificate holder ID.

Returned: If specifically requested.

issuer

string

Certificate issuer DN.

Returned: If specifically requested.

keyType

string

Certificate key type.

Returned: If specifically requested.

labels

list / elements=dictionary

Certificate labels.

Returned: If present and specifically requested.

key

string

Label key

Returned: Always.

value

string

Label value

Returned: Always.

metadata

list / elements=dictionary

Certificate metadata.

Returned: If specifically requested.

key

string

Metadata key

Returned: Always.

value

string

Metadata value

Returned: Always.

module

string

Certificate module.

Returned: If specifically requested.

notAfter

integer

Certificate expiration date (UNIX timestamp in millis).

Returned: If specifically requested.

notBefore

integer

Certificate issuance date (UNIX timestamp in millis).

Returned: If specifically requested.

owner

string

Certificate’s owner.

Returned: If specifically requested.

profile

string

Certificate profile.

Returned: If present and specifically requested.

publicKeyThumbprint

string

Certificate public key thumbprint.

Returned: If specifically requested.

revocationDate

integer

Certificate revocation date (UNIX timestamp in millis).

Returned: If present and specifically requested.

revocationReason

string

Certificate revocation reason.

Returned: If specifically requested.

selfSigned

boolean

True if the certificate is self-signed.

Returned: If specifically requested.

serial

string

Certificate serial number (hexadecimal format).

Returned: If specifically requested.

signingAlgorithm

string

Certificate signing algorithm.

Returned: If specifically requested.

subjectAlternateNames

list / elements=dictionary

Certificate subject alternate names (SANs).

Returned: If specifically requested.

sanType

string

SAN type

Returned: Always

value

string

SAN value

Returned: Always

thirdPartyData

list / elements=dictionary

Certificate third-party data.

Returned: If present and specifically requested.

connector

string

Third party connector name.

Returned: Always.

fingerprint

string

Third party object fingerprint.

Returned: If present.

id

string

Third party object ID.

Returned: Always.

pushDate

integer

Certificate’s push date in the third party (UNIX timestamp in millis).

Returned: If present.

removeDate

integer

Certificate’s remove date in the third party (UNIX timestamp in millis).

Returned: If present.

thumbprint

string

Certificate public key thumbprint.

Returned: If specifically requested.

triggerResults

list / elements=dictionary

Certificate trigger results.

Returned: If present and specifically requested.

detail

string

Execution details.

Returned: If present.

event

string

Trigger event type.

Returned: Always.

lastExecutionDate

integer

Last trigger execution date (UNIX timestamp in millis).

Returned: Always.

name

string

Trigger name.

Returned: Always.

nextDelay

string

Duration until next try.

Returned: If present.

nextExecutionDate

integer

Next trigger execution date (UNIX timestamp in millis).

Returned: If present.

retries

integer

Trigger retries count.

Returned: If present.

status

string

Trigger type.

Returned: Always.

Authors

  • Evertrust R&D (@EverTrust)