Skip to content

Agent

Agent Library

In order to send data to Metaport, a developer needs to first install a small software library into each application you wish to see data for. The library generates a standardised JSON file and sends it to Metaport.

Libraries exist for the following languages which framework developers and maintainers should base their implementations on:

  • PHP
  • Python (Planned)
  • NodeJS (Planned)
  • Ruby (Planned)

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.

Mail

Warning

Only SMTP is supported out of the box with Mailgun configuration included by default. If there's a need to support a greater range of SMTP transport backends, the module will be modified to suit. Please file a support request.

Note

If you intend on sending payloads via email as opposed to HTTP, then ensure you have both the MAILER_DSN and MP_MAIL_TRANSPORT_PUBKEY environment variables set in the sending environment. The public key is generated automatically whenever a new team is created for use with your applications:

MP_MAIL_TRANSPORT_PUBKEY=...

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

See the "Environment" section below for more detail.

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. "PROD".

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

METAPORT_APP_ENV=PROD

Tip

Acceptable environments to pass are: DEV, TEST, UAT, STAGE or PROD (In all caps!)

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

Examples

HTTP Transport

Note

The --auth switch is a base64 encoded string comprising the team's NotificationEmail and the password, ensure it's wrapped in quotes.

./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=='
  --classic=1

A successful transaction looks something like this:

{
    "success": true,
    "code": 202,
    "message": "OK"
}

A failed transaction looks something like this:

{
  "success": false,
  "code": 400,
  "message": "Invalid payload according to Metaport specification"
}

Limited error context is also available in the system log /var/log/metaport.log.

EMAIL Transport

The EMAIL transport needs both the 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
  --classic=1

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

Classic Mode

When the --classic parameter exists, the agent will attempt to invoke the appropriate command which produces dependency and security vulnerability data.

For example, using the PHP agent, both the Composer audit and show commands are executed to generated and send dependency and security audit data to Metaport Server via the generated SBOM. If you're already using a third party Dependency Managerment System like DependencyTrack then it's recommened not to mix data-sources and not set this parameter.

Tips

Tip

If both Environment variables and CLI arguments are passed, then the latter trumps the former.

Tip

The --host option doubles as an email address when using --transport=email, otherwise it should be the IP/domain of your Metaport server.

Tip

A Metaport server will respond with an HTTP 202 Accepted header on success when using the HTTP transport.

Tip

To retain generated SBOM files, set the MP_RETAIN_SBOM environment variable to true. This is useful if subsequent CI jobs wish to make use of the generated file for any reason.

Note

Metaport will label some app data as "Provisional" within the UI, which indicates the data is provisionally obtained during e.g. a CI job. Obviously using a CI agent or runner will return non-production data so add the MP_IS_CI=true environment variable to your CI jobs, to ensure this label is displayed correctly. On subsequent runs values are updated and the "Provisional" label is removed.

Issues