Skip to content

Agent

Agent Library

Quickstart

If you're just evaluating Metaport, follow these instructions to quickly get some dummy app data into Metaport:

  1. Download this example payload.
  2. In the Metaport UI, create an Organisation, a Team and an Application.
  3. From within the application screen: 3.1 Ensure the value of Release Environment is set to PROD. 3.2 Ensure the value of Transport Mode is HTTP. 3.3 Generate the Developer Export (Use the icon).
  4. Open the downloaded example payload file for editing: 4.1 Copy/Paste the value of Application UUID from step 3.3 and modify "serialNumber": "urn:uuid:xxxxxxxx" to become: "serialNumber": "urn:uuid:<value_of_identifier>". 4.2 From the Metaport UI, take the value of the Domain Name(s) field, and make that the value of the value field located directly below "name": "metaport.ssl.domain" so it becomes: "value": "<value_of_domain>". 4.3 Save the file.
  5. Execute curl: 5.1 In the Metaport UI, grab the email address of the relevant application's, team's API User and change the password (and remember both!) 5.2 Run this command: curl -k -u "<api_user_email>:<api_user_password>" -X PUT "https://metaport.dev/api/v1/app" -F 'file=@valid.json' -H 'Content-Type: application/json'.
  6. In the Metaport UI, select the appropriate application and review the newly added data.

Permanent

In order to send data to Metaport, a developer needs to install a software agent 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.

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

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 the MP_CERT_PATH environment variable can be set to a path to the appropriate *.crt file e.g:

MP_CERT_PATH="/path/to/current/dir/metaport.dev.crt"

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

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