dcentrica / metaport-agent-php
Metaport PHP Agent
Requires
- php: ^8
- cyclonedx/cyclonedx-library: ^2.2
- guzzlehttp/guzzle: ^7.7
- linfo/linfo: ^4.0
- paragonie/halite: ^5.1
- symfony/http-foundation: ^6
- symfony/mailer: ^6.4
- symfony/swiftmailer-bundle: ^2.3
- t4web/composer-lock-parser: ^1.2
Requires (Dev)
- phpunit/phpunit: ^10
This package is auto-updated.
Last update: 2024-10-21 08:43:56 UTC
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 totrue
. 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