Skip to content

Agent

Metaport Agents

Note

Substitute the command-line values given below, with those provided to you by the evaluation setup script, or the "Developer Export". It is good practice to wrap quotes around values, to prevent shells from mis-interpolating them.

Send data from a PHP app:

    ./vendor/bin/metaport \
    --transport=http \
    --name=app-toaster-butterfly \
    --host=metaport.dev \
    --uuid=6bb56dd2-4eb1-4162-943e-78b22ecc72b5 \
    --domain=1757431591.com \
    --env=PROD \
    --version=1.0.0 \
    --classic=1 \
    --auth='Mzk0NDg3MzExQG1ldGFwb3J0LnNoOjU4NDhjNDY2MTUzNzI1ZTYxMzY0OTllOTRiZDU1NWE2MDM2ZTA0NjNhMWU1Y2EwZjlkNDJiZDA3M2ZjMjJlNzc='

Send data from a Python app:

Assumes the metaport executable is accessible in a Python virtual environent, or by some other means.

    metaport \
    --transport=http \
    --name=app-toaster-butterfly \
    --host=metaport.dev \
    --uuid=6bb90dd2-4eb1-4162-9x3e-78b22ecc72b5 \
    --domain=1757411591.com \
    --env=PROD \
    --version=1.2.3 \
    --classic=1 \
    --auth='Mzk0MDg3MzExQG1ldGFwb3J1LnNoOjU4NlhjNDY2MTUzNPI1ZTYxMzYTTTllOTRiZDU1NWE2MDM2ZTA0NjNhMWU1Y2EwZjlkNDJiZDA3M2ZjMjJlNz=='

Send data from a React app:

    npm run metaport \
    -- \
    --transport=http \
    --name=app-karamba-interrupt \
    --host=metaport.dev \
    --uuid=7486e0d8-8ab8-4987-9ea1-95f19835791c \
    --domain=1057433521.com \
    --env=PROD \
    --version=1.0.0 \
    --classic=1 \
    --auth='Mzk0NDg3MzExQG1ldGFwb3J0LnNoOjU4NDhjNDY2MTUzNzI1ZTYxMzY0OTllOTRiZDU1NWE2MDM2ZTA0NjNhMWU1Y2EwZjlkNDJiZDA3M2ZjMjJlNzc='

Agents

In order to send data to Metaport, an agent is required to be installed into each "real world" application. Each agent generates a standardised JSON file and sends it securely to Metaport.

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

  • PHP
  • [NodeJS(https://gitlab.com/dcentrica/metaport/metaport-agent-nodejs)
  • [Python] (https://gitlab.com/dcentrica/metaport/metaport-agent-python) (Works in Poetry and Pip managed environments)
  • C# .Net (Planned)
  • Ruby/Gems (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.

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

See the "Examples" section below for a complete command examples.

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 command examples.

Environment Variables

The following environment variables are designed to be set in each application's running environment - the same environment in which the agent is running.

Note that some command-line arguments are capable of overriding a subset of Metaport's environment variables when set, as follows:

Mail

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. If you're having problems with SMTP relay errors, try setting the MAILER_FROM environment variable to the same domain that Metaport is operating on.

Note

The public key is generated automatically whenever a new team is created for use with your applications.

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

MP_MAIL_TRANSPORT_PUBKEY=...

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!)

SSL Certificate

When using the HTTP transport, the agent is hard-coded to transact over https and to verify SSL certificates. If your certificates are in a non-standard location, or you're evaluating Metaport and need to use self-signed certificates, then set the MP_IGNORE_CERT environment variable to a truthy value.

CI Pipelines

Metaport will display the "Provisional" label in the UI if it thinks data has been sent from a CI pipeline. To ensure this works correctly, ensure the following environment variable is set in CI environments:

MP_IS_CI=true

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.dev

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

Note

For simplicity, the following examples have assumed a PHP scenario, but every language agent accepts the same arguments in the same format, only the executable name differs. E.g. for the NodeJS Agent substitute metaport for metaport.js.

HTTP Transport

Note

The --auth switch is a base64 encoded string comprising the team's NotificationEmail and the password. You can get this from the Metaport UI from your team's Owner or Manager. 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 Management System like DependencyTrack then it's recommended 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 being "Provisional" within the UI. This indicates that data is provisionally obtained during a CI pipeline (sending data from a CI environment returns "bogus" non-production data). So ensure to add the MP_IS_CI=true environment variable to your CI jobs, to ensure this label is displayed correctly. On subsequent, non-CI runs, data is updated and the "Provisional" label is removed.

Issues

  • Please see the product's backlog on Gitlab.com
  • Issues with this package can be reported here
  • Issues with a specific agent, should be reported to that agent's backlog (See the bullet list of agents above).