README

What is this?

A client library which connects a PHP app to a Metaport server using the CycloneDX SBOM standard.

How to use

This library provides single executable metaport which is automatically installed into Composer's vendor/bin directory. It's designed to be invoked on a schedule via cron from within an application's production environment or as part of CI/CD pipelines. In the latter case some of the data - namely hardware related - will not be recorded accurately given that CI environments !== Production. Data sent to a Metaport server during CI runs is automatically flagged in the system until a subsequent cron-based report has been generated and sent.

The library will automatically generate an SBOM for your app, submit it to Metaport and subsequently delete it. Data can be sent using the HTTP or Email transports. See below for example requests.

Install

This package requires PHP ^8. If used as part of a CI/CD setup, it can be installed as a throwaway dependency via Composer's require-dev argument or as a permenant dependency of your PHP application.

composer require-dev dcentrica/metaport-agent-php

If you intend on sending payloads via email, then ensure you have both the MP_MAILER_DSN and MP_MAIL_TRANSPORT_PUBKEY environment variables set. Note: For email transports, the agent only works with SMTP gateways.

You will need to ask your Metaport server administrator to generate a public key for use with your applications, and then set both via suitable environment variables as follows:

MP_MAIL_TRANSPORT_PUBKEY=...

MP_MAILER_DSN=smtp://<user>:<pass>@<host>:<port>

See the "Environment" section below for more detail.

CI

In your pipelines, generate and send your app's SBOM report to a Metaport server using one of the "http" or "email" transports e.g.

php vendor/bin/metaport --transport=http ...

See the "Examples" section below for a complete example.

Cron

Configure cron on your own systems to send data to a Metaport server:

# Send data about your application to Metaport on a weekly basis
# Install into /etc/cron.weekly/ (Debian/Ubuntu) or /etc/periodic/weekly/ (Alpine)
/var/www/html/metaport/vendor/bin/metaport --transport=http ...

See the "Examples" section below, for a complete example.

Environment Variables

Note that some command-line arguments will override a subset of Metaport's environment variables if set:

UUID

Set your application's Metaport UUID (Obtained when the app is first registered with a Metaport server).

If this environment variable is set, you don't need to pass the --uuid command line parameter.

METAPORT_APP_UUID=eeb54e4d-fd12-4910-bfee-f1b5a52fb681

Environment

Set your application's environment e.g. "Production".

If this environment variable is set, you don't need to pass the --env command line parameter.

METAPORT_APP_ENV=Production

Host

Set the host for your Metaport server.

If this environment variable is set, you don't need to pass the --host command line parameter.

METAPORT_HOST=metaport.me.com

Retain SBOM

If the following is set, the generated SBOM file will be retained on the filesystem where it's generated, otherwise it will be deleted.

MP_RETAIN_SBOM=true

Ignore Platform

The logic used to derive the host cloud platform performs DNS lookups and may consult large files of IP lookups. These can take a few seconds to execute and can be disabled via an environment variable if desired, which can speed things up a little.

MP_IGNORE_PLATFORM=true

Examples

HTTP Transport

Note: The --auth switch is a base64 encoded string comprising the team's NotificationEmail and the password. Talk to your Metaport team administrator to obtain these details.

./vendor/bin/metaport \
  --transport=http \
  --name=MyApp \
  --host=example.com \
  --uuid=04b23aee-d9d5-4271-859d-7c476f730cf5 \
  --domain=myapp.com \
  --env=Prod \
  --version=1.0.1 \
  --auth=cnSXc0B0aGVydXNzLLNvbTpiMYdiaXJkvzcuLg==

EMAIL Transport

The EMAIL transport needs both the MP_MAILER_DSN and MP_MAIL_TRANSPORT_PUBKEY environment variables to be available.

./vendor/bin/metaport \
  --transport=email \
  --name=MyApp \
  --host=inbox@my-metaport-server.com \
  --uuid=04b23aee-d9d5-4271-859d-7c476f730cf5 \
  --domain=myapp.com \
  --env=Prod \
  --version=1.0.1

You can also just pass --help to see the above example and a full definition of all available command-line switches is displayed.

Notes

If both Environment variables and CLI arguments are passed, then the latter trump the former
The --host option doubles as an email address with --transport=email, otherwise it should be the IP/domain of your Metaport server
A Metaport server will respond with an HTTP 202 Accepted header on success when using the HTTP transport
When generating your app's SBOM, the JSON file is sent to your Metaport server and subsequently deleted. If you want to retain the file, ensure the MP_RETAIN_SBOM environment variable is set to true. This can be useful if subsequent CI jobs wish to make use of the generated file for any reason. (Note, setting this has no effect when using the "Email" transport)
Metaport labels some app data as "Provisional" within the Metaport Server UI. This indicates that data was provisionally obtained during a CI run. Obviously using a CI agent or runner is going to return non-production values for e.g. hardware components lke RAM and CPU, so adding the MP_IS_CI=true environment variable to your CI jobs ensures this label is displayed correctly. On subsequent runs in normal day to day operation, these values will be updated and the "Provisional" label is removed. Subsequent CI runs will not revert the values of these fields.

Issues

Please see the product's backlog on Gitlab.com
Issues with this package can be reported here

dcentrica / metaport-agent-php

Maintainers

Details