Security

By default, all Fix Inventory components communicate with each other via HTTPS using Transport Layer Security (TLS).

The trust between components is established using a PSK that is used to derive a key used to sign JWTs.

Fix Inventory Core runs a Public Key Infrastructure (PKI) including a Certificate Authority (CA). Upon start, all components will request a certificate from the CA.

Pre-Shared Key (PSK)

Each Fix Inventory component accepts a --psk flag (which can alternatively be supplied using the environment variables FIXCORE_PSK, FIXWORKER_PSK, FIXMETRICS_PSK and FIXSHELL_PSK).

The value of the flag is a pre-shared key—a common passphrase that all components know about.

From this passphrase, a 256 bit key is derived using PKCS#5 password-based key derivation function 2 with HMAC as its pseudo-random function (PBKDF2-HMAC) and a random salt. This derived key is then used to sign JWTs.

JSON Web Token (JWT)

If a PSK is provided, every request that a component makes to Fix Inventory Core must provide a valid Authentication header with a JWT signed using the PSK.

This is true for encrypted HTTPS and unencrypted HTTP requests, meaning that if TLS is turned off (--no-tls) but a PSK was specified, the request will still be authenticated (just not encrypted!).

Certificate Authority (CA)

By default, Fix Inventory's built-in CA will be used.

Alternatively, a custom CA cert and key can be provided to Fix Inventory Core using the --ca-cert and --ca-cert-key flags.

Or, if you are already running a CA or have externally signed certificates (e.g., Let's Encrypt) they can be used using the --ca-cert, --cert and --cert-key flags for all components. If the key is protected by a passphrase, --cert-key-pass can also be specified.

The following sections explain the steps Fix Inventory automatically performs when using the built-in CA.

Establishing Trust

Fix Inventory Core has two API endpoints, /ca/cert and /ca/sign.

The former serves the core's public CA root certificate. Upon startup, all other components will request this root certificate from Fix Inventory Core without validating the TLS connection.

However, Fix Inventory Core encodes the certificate's SHA256 fingerprint into a JWT which is signed with the previously mentioned PSK.

When a component downloads untrusted root certificate, it compares its fingerprint with the one the core has encoded into the JWT. If the fingerprints match the CA's root certificate is stored as a valid root certificate and from then on trusted.

Any HTTPS requests between components and Fix Inventory Core from this point forward are validated against the CA root certificate.

Component Certificates

Once trust is established, each component requests a certificate from the CA by creating a private RSA key in memory and a Certificate Signing Request (CSR) using that key.

The CSR is then sent to /ca/sign, which returns a signed certificate.

Like any other request, this one includes a JWT signed with the PSK. This way, the CA knows it can trust the requesting component before returning a signed certificate.

Components will automatically renew certificates one day before their expiration.

Custom Certificates

Fix Inventory Shell can be used to create custom certificates. This is useful for securing the connection to other components like ArangoDB or Prometheus.

To create a certificate, open Fix Inventory Shell and execute:

> certificate create --common-name arangodb.local --dns-names arangodb.local localhost --ip-addresses 127.0.0.1
​Received a file arangodb.key, which is stored to ./arangodb.key.
​Received a file arangodb.crt, which is stored to ./arangodb.crt.

info

See certificate Command for more information.

Securing ArangoDB

1. Create a certificate and combine the two outputted files into a single PEM file:

   $ cat arangodb.crt arangodb.key > arangodb.pem
   $ chmod 600 arangodb.pem

2. Copy the PEM certificate file to your directory of choice and start ArangoDB using the following flags:

   --server.endpoint ssl://localhost:8530 --ssl.keyfile /path/to/arangodb.pem

3. Set the value of fixcore's --graphdb-server startup flag to https://localhost:8530.

Advanced

When interfacing with Fix Inventory's API endpoints, it is possible to integrate with Fix Inventory Core using the same transport encryption and authentication utilized by Fix Inventory's components.

Retrieving and Validating the CA Certificate

The Fix Inventory CA certificate can be retrieved at https://localhost:8900/ca/cert (replace localhost with the hostname or IP where Fix Inventory Core is running).

In a Python 3 REPL with fixlib installed, execute the following:

>>> from fixlib.core.ca import get_ca_cert
>>> from fixlib.x509 import write_cert_to_file
>>> ca_cert = get_ca_cert(fixcore_uri="https://localhost:8900", psk="changeme")
>>> write_cert_to_file(cert=ca_cert, cert_path="./fixinventory_ca.crt")

Alternatively, the CA cert can be retrieved without verifying it.

$ curl -k https://localhost:8900/ca/cert > fixinventory_ca.crt

Generating a JSON Web Token

The following will return http headers that contain a valid JWT for the provided PSK:

>>> from fixlib.jwt import encode_jwt_to_headers
>>> encode_jwt_to_headers(http_headers={}, payload={}, key="changeme", expire_in=3600)
​{'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInNhbHQiOiJuSVEzU3M5TGVNS1JHYUNQUEJxMnlBPT0ifQ.eyJleHAiOjE2NDkzNzI1MTR9.KXAmijfSsV-taO3890qJNzXKXng1u38eU6PTrDYTgVs'}

Executing Fix Inventory CLI Commands with curl

Use the retrieved CA cert and generated http headers with curl in a shell to talk to the Fix Inventory API:

$ auth_header="Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInNhbHQiOiJuSVEzU3M5TGVNS1JHYUNQUEJxMnlBPT0ifQ.eyJleHAiOjE2NDkzNzI1MTR9.KXAmijfSsV-taO3890qJNzXKXng1u38eU6PTrDYTgVs"
$ fixinventory_command="search is(resource) | count"
$ curl --cacert fixinventory_ca.crt -H "$auth_header" -H "Content-Type: text/plain" -H "Accept: application/json" -X POST -d "$fixinventory_command" https://localhost:8900/cli/execute

Disabling Security Features

Fix Inventory installations are secure by default, but it is possible to disable some of the security features.

danger

Disabling security features is not recommended and should only be done in a trusted environment.

Disabling Authentication

Fix Inventory's authentication infrastructure is based on the PSK provided to Fix Inventory Core on startup.

If a PSK is not provided, authentication is not required to access Fix Inventory's API endpoints.

Disabling TLS

Fix Inventory Core can be started without TLS using the --no-tls flag.

note

This change also needs to be reflected in the startup parameters of all other components because it affects the Fix Inventory Core URL.