README

这是什么？

这是一个客户端库，它使用CycloneDX SBOM标准将PHP应用程序连接到Metaport服务器。

如何使用

此库提供单个可执行的metaport，它将自动安装到Composer的vendor/bin目录。它旨在通过cron从应用程序的生产环境或作为CI/CD管道的一部分进行调用。在后一种情况下，由于CI环境 !== 生产环境，因此某些数据（即硬件相关数据）将无法准确记录。在CI运行期间发送到Metaport服务器的数据将在生成并发送后续基于cron的报告之前自动在系统中标记。

库将自动为您应用程序生成SBOM，将其提交到Metaport，然后删除它。数据可以使用HTTP或Email传输发送。下面是示例请求。

安装

此包需要PHP ^8。如果作为CI/CD设置的一部分使用，则可以通过Composer的require-dev参数将其安装为临时依赖项，或者将其安装为PHP应用程序的永久依赖项。

composer require-dev dcentrica/metaport-agent-php

如果您打算通过电子邮件发送有效载荷，则确保您已经设置了两个环境变量：MP_MAILER_DSN和MP_MAIL_TRANSPORT_PUBKEY。注意：对于电子邮件传输，代理仅支持SMTP网关。

您需要要求您的Metaport服务器管理员为您应用程序生成一个公钥，然后通过以下方式设置这两个环境变量：

MP_MAIL_TRANSPORT_PUBKEY=...

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

有关更多详细信息，请参阅下面的“环境”部分。

CI

在您的管道中，使用“http”或“email”传输之一生成并发送您的应用程序SBOM报告到Metaport服务器，例如：

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

请参阅下面的“示例”部分以获取完整示例。

Cron

配置您的系统上的cron以将数据发送到Metaport服务器

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

请参阅下面的“示例”部分以获取完整示例。

环境变量

请注意，如果设置了某些命令行参数，则将覆盖Metaport环境变量的一部分

UUID

设置您应用程序的Metaport UUID（在应用程序首次与Metaport服务器注册时获取）。

如果设置了此环境变量，则不需要传递--uuid命令行参数。

METAPORT_APP_UUID=eeb54e4d-fd12-4910-bfee-f1b5a52fb681

环境

设置您应用程序的环境，例如“生产”。

如果设置了此环境变量，则不需要传递--env命令行参数。

METAPORT_APP_ENV=Production

主机

设置您的Metaport服务器的主机。

如果设置了此环境变量，则不需要传递--host命令行参数。

METAPORT_HOST=metaport.me.com

保留SBOM

如果设置了以下项，则生成的SBOM文件将在生成它的文件系统中保留，否则将删除。

MP_RETAIN_SBOM=true

忽略平台

用于推导主机云平台的逻辑执行DNS查找，并可能咨询大型IP查找文件。这些操作可能需要几秒钟才能执行，如果需要，可以通过环境变量禁用这些操作，这可以略微加快速度。

MP_IGNORE_PLATFORM=true

示例

HTTP传输

注意：--auth开关是一个包含团队的NotificationEmail和密码的base64编码字符串。与您的Metaport团队管理员交谈以获取这些详细信息。

./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 传输方式需要同时设置环境变量 MP_MAILER_DSN 和 MP_MAIL_TRANSPORT_PUBKEY。

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

您也可以直接输入 --help 来查看上述示例，并显示所有可用的命令行选项的完整定义。

注意事项

如果同时传递了环境变量和 CLI 参数，则后者将覆盖前者。
当使用 --transport=email 时，--host 选项可以作为电子邮件地址，否则它应该是您的 Metaport 服务器 IP 地址或域名。
当使用 HTTP 传输时，Metaport 服务器在成功时将以 HTTP 202 Accepted 状态响应。
在生成您应用的 SBOM 时，JSON 文件将被发送到您的 Metaport 服务器，然后被删除。如果您想保留该文件，请确保环境变量 MP_RETAIN_SBOM 设置为 true。这在后续的 CI 作业需要使用生成的文件时非常有用。（注意：使用 "Email" 传输时设置此选项没有效果）
Metaport 将一些应用数据标记为 "Provisional"（临时）在 Metaport 服务器 UI 中。这表明数据是在 CI 运行期间临时获取的。显然，使用 CI 代理或运行器将返回非生产值，例如 RAM 和 CPU 等硬件组件，因此将环境变量 MP_IS_CI=true 添加到您的 CI 作业中可以确保正确显示此标签。在日常运营中的后续运行中，这些值将被更新，并移除 "Provisional" 标签。后续的 CI 运行不会撤销这些字段的值。

问题

请参阅产品在 Gitlab.com 的待办事项列表。
关于此软件包的问题可以在此处报告。

dcentrica / metaport-agent-php

维护者

详情