Metaport 1.0.0

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./metaport-logo.png" /> <img alt="Metaport Logo" src="metaport-logo.png" /> </picture> </div>

What is this?

A client library which connects any Dotnet app to a Metaport server using the CycloneDX SBOM standard for data interchange.

How to use

Introduction

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 the docs site for example requests.

The library provides a single executable metaport which is automatically installed into the public directory. It's designed to be invoked on a schedule via cron from within an application's production environment or as part of a CI/CD pipeline.

Authentication

The agent uses Basic Authentication for HTTP transport to Metaport servers:

• The --auth parameter accepts a base64 encoded string containing username:password credentials
• The agent decodes this string and splits on : to extract username and password
• These credentials are used in the Authorization: Basic <credentials> HTTP header

Email Transport

For email transport, the agent uses encrypted email attachments:

• Encryption: Uses libsodium PKI encryption (Sodium.Core) compatible with ParagonIE Halite
• Environment Variables: Requires MAILER_DSN and MP_MAIL_TRANSPORT_PUBKEY
• Email Structure:
  • From: MAILER_FROM environment variable or metaport-agent+{uuid}@{domain}
  • To: Email address specified in --host parameter
  • Subject: Application UUID from --uuid parameter
  • Attachment: metaport-bom.json.enc (encrypted SBOM file)
• SMTP Configuration: Parsed from MAILER_DSN environment variable (user, password, host, port)

Fallback Behavior

When system information cannot be determined (hardware specifications, framework detection, OS details, etc.), the agent uses "unknown" as the fallback value in the generated SBOM. This ensures the agent completes successfully even in environments with limited system access or unusual configurations.

Requirements

This package is designed to work for .NET Standard 2.0 applications and supports .NET Core 2+, .NET Framework 4.6.1+, and .NET 5+ runtimes on both Windows and Linux environments.

Platform Requirements

Supported Operating Systems:

• Linux: Ubuntu 20.04+, RHEL 8+, CentOS 8+, Alpine Linux 3.15+
• Windows: Windows Server 2016+, Windows 10+, Windows 11+

Shell Compatibility:

• Linux: bash, zsh, sh (POSIX-compliant shells)
• Windows: PowerShell 5.1+, PowerShell Core 6+, Command Prompt (cmd.exe)
• Cross-Platform: The agent handles command-line parameter parsing differences between PowerShell and DOS prompt internally, requiring no additional configuration from end-users

Runtime Requirements:

• .NET Runtime: .NET 6, 7, or 8 (recommended: .NET 8 for latest features)
• Memory: Minimum 512MB available RAM
• Disk Space: Minimum 100MB free space for temporary files and caching
• Network: Outbound HTTPS access for NuGet API calls and Metaport server communication (when using HTTP transport)

Agent Definitions

The .NET Metaport Agent uses specific definitions for system components:

Framework:

• Definition: Application-level development frameworks and content management systems detected from NuGet package dependencies
• Examples: ASP.NET Core, ASP.NET MVC, Umbraco CMS, Entity Framework, Blazor, WPF
• Detection Method: Analyzes packages.lock.json or *.deps.json files to identify framework-specific packages
• Note: This refers to application frameworks, not the .NET runtime framework itself

Runtime:

• Definition: The .NET runtime environment executing the application
• Examples: ".NET 8", ".NET Framework 4.8", ".NET Core 3.1"
• Detection Method: Uses RuntimeInformation.FrameworkDescription to identify the specific .NET runtime version
• Scope: Represents the underlying .NET execution environment, not application-specific frameworks

Host:

• Definition: The physical or virtual machine environment where the application is deployed
• Components: Operating system, hardware specifications, cloud platform, network configuration
• Examples: "Ubuntu 22.04 on AWS EC2", "Windows Server 2022 on Azure VM"
• Detection Method: Combines OS detection, hardware enumeration, and cloud platform identification via DNS queries
• Fallback: Uses "unknown" for any system information that cannot be determined

Install

1. Nuget

In "disposable" CI pipelines and jobs:

TBC

As part of production apps:

TBC

2. Environment Variables

There are some environment variables which need to be set before the lib will operate correctly. Please see the docs site for more detailed installation and configuration instructions and examples.

Core Environment Variables:

• METAPORT_APP_UUID: Application UUID (alternative to --uuid)
• METAPORT_APP_ENV: Application environment (alternative to --env)
• MP_ENABLE_DOMAIN: Enable SSL certificate monitoring
• MP_IGNORE_CERT: Allow self-signed certificates
• MP_RETAIN_SBOM: Preserve SBOM files after transmission

Email Transport Variables:

• MAILER_DSN: SMTP configuration (user:password@host:port format)
• MP_MAIL_TRANSPORT_PUBKEY: Public key for email encryption
• MAILER_FROM: Email sender address (optional, defaults to metaport-agent+{uuid}@{domain})

Supported Frameworks and CMS's

The agent automatically detects application frameworks and content management systems from NuGet package dependencies. Yours not listed? Contributions are very welcome. Please file an issue and issue a Merge Request, it's a one-line configuration file change!

Development

When incrementing versions, be sure to update the <Version> stanza in MetaportAgent.csproj.