Skip to main content

Dependency decisions

AGENTS.md requires written justification for new dependencies.

The disposable lab/aws harness uses Python 3.9+ standard library, AWS CLI v2, OpenSSL and nginx on the Amazon Linux control host, and the AWS-provided AWSPowerShell module on Windows Server 2022. These are lab-only tools: AWS CLI and AWSPowerShell use instance roles to fetch ephemeral secrets without embedding credentials in command text; OpenSSL creates the isolated TLS/signing material; nginx restricts development administration to loopback while collectors use TLS. The resolved AMI IDs and artifact hashes are recorded for each run. No product runtime or Python package dependency is added. The wecfix profiler report (lab/aws/wecfix/etlstacks, lab-only, never shipped or run in CI) uses Microsoft.Diagnostics.Tracing.TraceEvent 3.1.23 (MIT, Microsoft) to read the in-box Windows Performance Recorder trace and resolve frames against the build's PDBs; the alternative (Windows Performance Analyzer) is not on Windows Server and has no scriptable report. CI reuses its existing pinned cfn-lint for generated infrastructure. Alternatives are custom SigV4 clients, hand-written TLS provisioning or exposing development admin remotely, each with more security-sensitive code or weaker isolation.

The offline tools/queue-migration-check project references Bower.Persistence to reuse canonical EventIdentity and the existing SQLite/contract dependencies; it adds no NuGet packages. Unit tests reference the tool to exercise the exact command and read-only checker without duplicating identity logic in a script or adding a native CLI command.

Bower.Pipeline references Bower.Redaction so the custom-log parser preview reuses the built-in privacy detectors for its server-owned masking floor rather than duplicating detector patterns. It adds no NuGet packages.

Bower.Management.Api references Bower.Evidence and Bower.Dcr so the onboarding wizard runs the unchanged evidence runner and DCR drift checks instead of duplicating proof semantics. This brings Azure.Identity (already pinned and AOT clean for the CLI) into the management API for the optional read-only verifier identity; no new package is added to the repository.

The parser transform language (Bower.Pipeline.Transforms) adds no packages. Its regex engine is Bower's own, so captures and step counts are deterministic; see the decision record.

PackageUsed byWhyAlternatives considered
OpenTelemetry.Extensions.Hosting, OpenTelemetry.Exporter.OpenTelemetryProtocol 1.21, Microsoft.Extensions.Http.Resilience, Microsoft.Extensions.ServiceDiscovery 11.0Bower.ServiceDefaults (so also Bower.Collector, Bower.Management.Api, Bower.Functions.Collector)OpenTelemetry logs, metrics and traces to the Aspire dashboard during local development. Inert in production: AddBowerServiceDefaults registers nothing unless OTEL_EXPORTER_OTLP_ENDPOINT is set, which no shipped deployment (Compose, Bicep, packages) sets; a unit test pins this. It exports framework metadata only (routes, status codes, runtime and HTTP client metrics, log records without scopes), never bodies, headers or query strings. Resilience and service discovery are referenced only for the opt-in AddBowerHttpClientDefaults, which no Bower client uses: Bower retries through the durable queue, and the management client's single-use enrolment token must not be retried by a generic handler. Apache-2.0 (OpenTelemetry, CNCF) and MIT (Microsoft), AOT compatible; the AOT collector publish stays warning-free.Hand-rolled OTLP export (protocol code to own); no telemetry in the harness (the dashboard would show console logs only).
Aspire.Hosting.AppHost, Aspire.Hosting.Dotnet, Aspire.Hosting.Testing 17.0Bower.AppHost, Bower.AppHost.Tests (development and test only; never published, packaged or deployed)Local development and integration-test harness: starts the collectors, management API, Functions collector and local stand-in destinations with a dashboard. Supports the pinned SDK (11.0.100, rollForward: disable); the libraries target net10.0 and are consumed by net11.0. Building the AppHost fetches the paired Aspire CLI bundle (DCP and dashboard, about 170 MB) through dnx from nuget.org on first build; CI builds it but runs the AppHost test only with BOWER_ASPIRE_TESTS=1. Container image adobe/s3mock 5.2.3 (Apache-2.0, pinned by digest) is the S3 stand-in; tools/Bower.DevSinks is the HTTP and syslog stand-in. MIT, first-party.The existing Compose files (kept as the production path; no dashboard, telemetry or one-command multi-output run); bespoke scripts like tests/e2e/aws-emulator.sh (kept for AWS-fidelity CI).
AWSSDK.SQS, AWSSDK.S3 4.0Bower.Agent.Cloud; Bower.Output.S3 (S3 only, so also Bower.Collector)SigV4-signed SQS receive/delete/visibility and bounded S3 GetObject with ExpectedBucketOwner, using the AWS default credential chain (EC2 instance profile with IMDSv2, ECS task role, EKS IRSA). Apache-2.0, first-party. Only these two service clients are referenced. The S3 output reuses the already-pinned AWSSDK.S3 for conditional PutObject (If-None-Match, x-amz-checksum-sha256, SSE, ExpectedBucketOwner) with the same chain; it adds no package to the central pins, but the collector now ships AWSSDK.Core and AWSSDK.S3.Hand-written SigV4 over HttpClient (security-sensitive code to own and audit); AWS CLI sidecar (shell, extra image surface); a presigned-URL or HTTP output (needs a separate signer anyway).
AWSSDK.SecurityToken 4.0Bower.Agent.Cloud; Bower.Output.S3Loaded by AWSSDK.Core to exchange an IRSA or Workload Identity web token for temporary credentials (AssumeRoleWithWebIdentity). Without it IRSA silently fails.None for IRSA in .NET.
Vecc.YamlDotNet.Analyzers.StaticGenerator 18.1 (build-time only, PrivateAssets=all)Bower.PolicyEngine, Bower.Redaction, Bower.Pipeline, Bower.PacksRoslyn source generator that emits YamlDotNet's StaticContext for policy, privacy profile, pipeline and pack YAML, so YAML binding needs no reflection under Native AOT. Published by the YamlDotNet maintainers at the same version as YamlDotNet. Nothing ships at run time.Hand-written YAML-to-model mapping over YamlDotNet's parser (more code to keep in step with the models); YamlDotNet reflection deserializer (IL2026/IL3050 under AOT).
Microsoft.Azure.Functions.Worker 2.52, Microsoft.Azure.Functions.Worker.Extensions.Http 3.3, Azure.Functions.Sdk 1.0.2 (MSBuild project SDK, build-time, pinned in global.json)Bower.Functions.CollectorThe supported Azure Functions isolated worker model for .NET 11 (the in-process model ended in November 2026 and never supported .NET 10 or later). .NET 11 requires Azure.Functions.Sdk 1.0.1 or later as the project SDK, which replaces the Microsoft.Azure.Functions.Worker.Sdk package. Worker hosts the HTTP triggers over the host's gRPC channel (pulls Grpc.Net.Client, Google.Protobuf, Microsoft.Extensions.Hosting); Extensions.Http provides HttpRequestData; the Sdk generates function metadata and the host extension bundle at build time. MIT, first-party. Only the plain HTTP extension is used, not ASP.NET Core integration, Application Insights worker packages or storage bindings.Custom handler hosting a native binary or a minimal ASP.NET app (custom handlers lose the native .NET worker model and its tooling); ASP.NET Core integration (Worker.Extensions.Http.AspNetCore, more surface for three routes).
Microsoft.IdentityModel.JsonWebTokens, Microsoft.IdentityModel.Protocols.OpenIdConnect 8.23.0Bower.Functions.CollectorIn-code Entra v2 token validation (RS256 signature against OIDC signing keys with refresh on rollover, issuer, audience, lifetime) with the Microsoft-maintained validator. The central pin also lifts Microsoft.AspNetCore.Authentication.JwtBearer (which needs 8.19.2 or later) to the same version for the management API. Central pins also align Bower.Source.SqlServer (Microsoft.Data.SqlClient's IdentityModel 8.16.0 → 8.23.0, Microsoft.Bcl.Cryptography 9.0.18 → 10.0.2); no API change.JwtBearer (needs the ASP.NET Core pipeline, which the plain HTTP worker does not have); Functions Easy Auth alone (configuration outside the code, no role/tenant checks testable offline).
Microsoft.Extensions.Hosting.WindowsServices 11.0.0Bower.CollectorRuns the collector under the Windows service control manager for the MSI (#112): start, stop and shutdown reporting, and warnings and errors to the Application event log. Microsoft-owned, same release train as the shared framework, AOT clean, and a no-op unless the process is a Windows service (Linux, containers and tests are unchanged). Pulls System.ServiceProcess.ServiceController and Microsoft.Extensions.Logging.EventLog (Windows-only code paths).A third-party service wrapper (WinSW, NSSM: another binary to ship, sign and trust); hand-written StartServiceCtrlDispatcher P/Invoke (security-relevant lifecycle code to own); a scheduled task at boot (no SCM recovery, no service SID for the folder ACLs).
Microsoft.Extensions.DependencyInjection.Abstractions 10.0.15Bower.Sdk (net10.0 build only)AddBower registers into IServiceCollection. .NET 11 includes it in the shared framework, so only the .NET 10 LTS build references the package (restore reports NU1510 for it on net11.0).Dropping the net10.0 target (applications on .NET 10 LTS could no longer reference the SDK).
Microsoft.AspNetCore.TestHostTests onlyRuns the collector and management API in-process for HTTP, authentication and rate-limit tests.Microsoft.AspNetCore.Mvc.Testing (needs a single Program entry point per test assembly).

| nginxinc/nginx-unprivileged (container base image) | Dockerfile.web | Serves the static console as a non-root user on a read-only filesystem, with runtime config. Official NGINX image. | Serving from the management API only (still supported); Caddy (no official unprivileged image). |

Build and test tools for the native installers (#112)​

The build tools do not run on collector hosts. The WiX Util extension embeds a native custom action in the MSI that runs only during installation, repair or upgrade.

ToolUsed byWhyAlternatives considered
nfpm 2.48.0 (MIT), static binary downloaded in CI and checked against a pinned SHA-256package-linux jobBuilds the deb and the rpm from one manifest (deploy/installers/linux/nfpm.yaml) with the same files, modes and maintainer scripts, and signs both with one GPG key when configured.dpkg-deb plus rpmbuild (preinstalled and installable on the runner, but two manifests to keep in step, and an rpm spec that rebuilds nothing); fpm (Ruby gem tree).
WiX Toolset 5.0.2 (wix .NET tool from nuget.org, MS-RL)package-windows jobAuthors the MSI declaratively: service install as a virtual account, folder ACLs from SDDL, remembered properties, upgrade rules. Pinned to v5 deliberately: WiX v6 and later are under the Open Source Maintenance Fee EULA, which v7 enforces and which a person, not CI, must accept for the organisation. Upgrading needs that decision first.WiX v3 (.NET Framework, end of life); msitools wixl (subset of WiX, no service ACLs); MSIX (no Windows service support for this model).
ansible-core 2.21.5 (via uvx, GPL-3.0)install-linux jobRuns the example role (deploy/ansible) against the runner to prove it installs, enrols, is idempotent and uninstalls cleanly. The role uses ansible.builtin modules only, so no collection is installed.Testing the role only with --syntax-check (does not prove it works).
WixToolset.Util.wixext 5.0.2 (MS-RL)Windows MSI service recoveryConfigures restart actions with the required service access rights and rollback support. Pinned to the same version as WiX; adds no collector runtime dependency.The native MSI failure-actions table fails with error 5 on the Windows install runner; a shell custom action would require our own upgrade and rollback implementation.
rockylinux/rockylinux:9-ubi-init (container image, pinned by digest)install-linux jobA RHEL 9 family host with systemd as PID 1, so the rpm install test exercises the real unit, account and maintainer scripts on a GitHub runner.AlmaLinux init images (equivalent; one is enough); a RHEL VM (not available on GitHub runners).
actions/download-artifact v8.0.2 (pinned SHA)packaging and install jobsConsumes the existing publish artefacts so packages contain exactly the binaries CI built and tested, and passes packages to the install tests.Rebuilding the binaries in each packaging job (slower, and no longer the same artefacts).

Bower.Agent.Docker uses the ASP.NET Core shared framework (FrameworkReference) for the generic host, logging and IHttpClientFactory, so it adds no NuGet packages. Bower.Agent.Cloud does the same; its only packages are the AWS SDKs above. Google credentials are handled in-house (see "Removed for Native AOT" below), so no Google package is referenced. Bower.Source.WindowsEventLog uses the same shared framework for System.Diagnostics.Eventing.Reader (EvtQuery, EvtNext, EvtRender over the local event log service), which the collector already ships; it adds no NuGet packages. The reader is Windows only ([SupportedOSPlatform("windows")]); event XML parsing uses System.Xml with DTDs prohibited and no resolver. Bower.Source.Gcp and the AWS queue parser in Bower.Source.Aws have no dependencies: parsing stays pure and testable without cloud access.

Review these when upgrading: AWS SDK for .NET 5.x. Review Bower.Agent.Cloud/Gcp/Auth when Google changes AIP-4110/4117 (new external_account credential sources, a new aws environment version or new credential file types).

Removed for Native AOT​

PackageReplaced byNotes
Hangfire.Core, Hangfire.NetCore, Hangfire.InMemoryBower.Jobs in-process cron scheduler (RecurringJobRegistry, PeriodicTimer)Hangfire serializes jobs with reflection-based Newtonsoft.Json and builds calls from expression trees. Same job ids, UTC cron schedules, retry counts and no-overlap rule; state stays in memory. See background jobs.
Newtonsoft.Json (direct pin)—Only pinned for Hangfire. Its last transitive use (Google.Apis.Auth) is removed too, so no Bower project resolves Newtonsoft.Json.
Google.Apis.Auth (Google.Apis, Google.Apis.Core, Newtonsoft.Json, System.Management, System.CodeDom)Bower.Agent.Cloud/Gcp/Auth: in-house Application Default Credentials with System.Text.Json source generationGoogle.Apis.Core reads credential files and token responses with reflection-based Newtonsoft.Json (IL2026/IL3050/IL2070). The replacement covers exactly what the agent used: ADC discovery (GOOGLE_APPLICATION_CREDENTIALS, the gcloud well-known file, then the metadata server), metadata server tokens (Metadata-Flavor: Google, probe on 169.254.169.254, tokens from metadata.google.internal, GCE_METADATA_HOST/GCE_METADATA_IP), and Workload Identity Federation per AIP-4117: file- and URL-sourced subject tokens (text or JSON), AWS-sourced tokens (SigV4-signed GetCallerIdentity, IMDSv2 session token, region and role credentials from IMDS or the AWS environment variables), the RFC 8693 STS exchange (optional client authentication, workforce userProject) and service account impersonation through IAM Credentials generateAccessToken (token_lifetime_seconds 600–43200). Tokens are cached in memory until five minutes before expiry. The key-file refusal is unchanged; gcloud user credentials (authorized_user, a long-lived refresh token) now need BOWER_GCP_ALLOW_KEY_FILE=true too. Executable-sourced credentials are refused (configuration must not run code), as are X.509 workload certificates, impersonated_service_account and other credential types. Hardening beyond the AIP: token and IAM endpoints must be HTTPS on the universe domain (googleapis.com), AWS metadata URLs must be 169.254.169.254 or fd00:ec2::254 (as AIP-4117 requires), plain HTTP only to metadata or loopback hosts, no redirects, metadata calls bypass proxies, responses capped at 64 KiB (subject tokens 256 KiB), and error bodies are never surfaced beyond the OAuth error code. SigV4 is pinned by AWS's published SigV4 test suite.
Microsoft.EntityFrameworkCore, Microsoft.EntityFrameworkCore.Sqlite (Bower.Persistence)Microsoft.Data.Sqlite (already referenced)EF Core's runtime model building needs reflection and dynamic code. EfSourceCursorStore keeps the exact table, column order (SourceId, Value, Version, UpdatedAt) and timestamp text EF Core created, so existing cursor files keep working. Bower.Source.SqlServer still uses EF Core (SQL Server) by design and is not referenced by any AOT executable.

Native AOT status​

All product libraries set IsAotCompatible (trim, AOT and single-file analysers run on every build; warnings are errors). bower, the collector, the management API, the Docker sidecar and the cloud agent publish as Native AOT with zero IL2xxx/IL3xxx warnings. JSON uses System.Text.Json source generation with the same options as before, so wire bytes, policy hashes and pack signatures are unchanged.

DependencyStatus
Microsoft.AspNetCore.Authentication.JwtBearer / Microsoft.IdentityModel.*AOT clean.
Azure.Identity, Azure.CoreAOT clean.
Microsoft.Azure.Functions.Worker*Not published as Native AOT. The Azure Functions host starts the isolated worker as a framework-dependent .NET app; Bower.Functions.Collector keeps the trim/AOT analysers on for its own code and the Bower libraries it reuses.
Azure.Monitor.IngestionLogsIngestionClient.UploadAsync<T> carries RequiresUnreferencedCode/RequiresDynamicCode because its default serializer is reflection-based. AzureLogsIngestionOutput always passes JsonRecordSerializer (writes JsonObject nodes directly), behind a guard, and suppresses IL2026/IL3050 on that one call with a written justification. Uploaded bytes are unchanged (pinned by AzureLogsIngestionOutputTests).
AWSSDK.Core, AWSSDK.SQS, AWSSDK.S3, AWSSDK.SecurityToken 4.0AOT clean (no warnings under ILC).

HTTP output (BOWER_OUTPUT=http)​

src/Bower.Output.Http adds no NuGet packages: it uses HttpClient (SocketsHttpHandler), GZipStream and System.Text.Json from the runtime, and references only Bower.Abstractions. Alternatives considered: a Splunk SDK (adds a dependency for a single documented POST) and a generic log shipper (out of scope: Bower is not a log forwarder).

Local syslog output (BOWER_OUTPUT=ama-syslog)​

src/Bower.Output.AmaSyslog adds no NuGet packages: it sends datagrams on a Unix socket with System.Net.Sockets. It references Bower.Abstractions and Bower.Dcr, the second for the same record checks the Logs Ingestion output runs (IngestionPreflight, SentinelSchema) before a record reaches BowerSecurity_CL, and Bower.Dcr has no package references of its own. Bower.Cli references this project for the bower doctor --syslog-socket check. Alternatives considered: a syslog client library (a dependency for one message format on one local socket) and calling syslog(3) through P/Invoke (process-wide state, no error per message, so a full socket would be silent).

Signed pack runtime activation​

Bower.Packs reuses its existing Detection, Pipeline, PolicyEngine and Redaction references for bounded raw mapping and post-redaction detection enrichment. The collector composes that wrapper around its existing redactor; no external runtime package is added. Detection's internal scalar/condition encoding uses a generated System.Text.Json context (DetectionJsonContext) and evidence uses DetectionEvidenceJson, preserving Native AOT analysis without suppressions.

PowerShell modules (powershell/)​

The Bower PowerShell modules bundle no third-party code and declare no RequiredModules. Optional modules are imported only by the commands that need them, with a clear error when absent:

Module / toolUsed byWhyAlternatives considered
Az.Accounts (optional)Connect-BowerManagement, Send-BowerSecurityEvent -Target AzureFunction -AudienceFirst-party Entra token acquisition (Get-AzAccessToken, SecureString tokens) reusing the operator's existing Azure sign-in. -AccessToken and -TokenProvider work without it.Bundling MSAL.PS (third-party, unmaintained); device-code flow in-module (token handling code to own).
Microsoft.Graph.Applications (optional)New-BowerEntraApplication -ApplyFirst-party Graph cmdlets for app registrations and service principals.Raw Graph REST calls (token handling and paging to own).
az, aws, terraform, bower CLIs (optional)Bower.Deployment, Test-BowerPrivacyProfile, Bower.PolicyThe deployment commands wrap the existing templates with the tools those templates already require. Invoked with argument arrays through one mockable function.Re-implementing what-if, change sets or plans.
Pester 5.9, PSScriptAnalyzer 1.25 (development only)powershell/build.ps1, CIStandard PowerShell test framework and linter, both Microsoft/PowerShell-community maintained. Pinned in CI.None comparable.

Collector settings trust: operating-system APIs​

The C# settings loader uses the operating system's existing native libraries, with no additional package or runtime service. Linux uses libc openat/statx to verify and read the same objects. Windows uses kernel32 handle APIs, advapi32 security-descriptor queries, and ntdll NtCreateFile for directory-handle-relative opens with OBJ_DONT_REPARSE. Path-based ACL checks followed by another open permit substitution; rejecting every ancestor metadata-write grant also rejects normal ProgramData ACLs. Native calls are limited to read-only handles, bounded descriptors and fixed structures, and failures refuse startup. Dedicated native platform tests gate release qualification.

The C# file tail source (Bower.Source.File) uses the same libc approach on Linux to open a tailed file with O_NOFOLLOW | O_NONBLOCK and to compare statx device and inode of the handle and the path (FileTailHandles.cs), so a link or another file swapped in after the path checks is refused. .NET has no no-follow open or inode API; other platforms only re-check that the path is not a link after opening.

AWS Emulator end-to-end test​

DependencyScopeReason and alternatives
AWS Emulator 1.0.322 (CC0-1.0), on public.ecr.aws/amazonlinux/amazonlinux:2023-minimalCI and local tests only (tests/e2e/aws-emulator/Dockerfile); never in a Bower image or packageFirst-party AWS emulator that runs the shipped CloudFormation templates and serves SQS, S3, STS and EventBridge to the unmodified cloud agent and S3 output, with no AWS account or stored keys. Version and base image digest are pinned; the package signature is verified against the AWS publishing key fingerprint before install; telemetry is off. LocalStack and moto (third-party emulators and mocks) were the alternatives; a first-party emulator that AWS tracks against its own fidelity tests is preferred. Unit tests keep using fakes; this does not replace the AWS lab.
public.ecr.aws/aws-cli/aws-cli 2.34.32 and curlimages/curl 8.11.1, digest-pinnedSame test onlyDrive the emulator and read collector status from inside its network namespace, so the emulator never publishes a port. curlimages/curl is already used by the compose e2e tests.

Documentation website​

DependencyScopeReason and alternatives
Docusaurus 3.10 (@docusaurus/core, preset-classic, theme-mermaid), React 19Build time only, exact versions in website/package-lock.jsonPublish the existing Markdown from docs/ as searchable, responsive static HTML on GitHub Pages, with a React homepage, a light and dark console gallery and themed screenshots. Replaced MkDocs Material, which announced end of life for 5 May 2027. Built static, with no runtime service, analytics or remote fonts. Mermaid diagrams are drawn in the browser from the bundled library, not a CDN.
@easyops-cn/docusaurus-search-local 0.55Build time and browserSearch built with the site; no query leaves the browser. Algolia DocSearch was not used because it sends queries to a hosted service.
npm overrides in website/package.jsonBuild time onlyserialize-javascript 7.1.4, tinypool 2.2.0 and uuid 11.1.1 replace older transitive versions with known advisories (GHSA for prototype pollution, worker pool and buffer bounds). Each is loaded the same way as before (CommonJS require or dynamic import), checked by a full build. deepmerge (via @svgr/plugin-svgo, SVG imports at build time only) has no fixed release; the site imports no untrusted SVG. Remove each override once Docusaurus depends on a fixed version.

The site self-hosts the existing console's OFL-licensed Geist variable font. The license accompanies the font in website/static/fonts/. Browser checks reuse the console's Playwright version in a separate locked test package. @axe-core/playwright is a development-only accessibility check for the documentation; it is never included in the published site. Lighthouse is a development-only performance/accessibility audit, also excluded from the site.

The docs test package temporarily overrides only @sentry/bundler-plugins's glob to 14.0.3. Lighthouse's current Sentry dependency requests glob 13, whose minimatch dependency and cancellation handling have moderate denial-of-service advisories. Glob 14.0.3 uses a patched minimatch. This crosses Sentry's declared major-version range, so the docs checks must exercise compatibility; remove the override when Sentry or Lighthouse supports a patched dependency chain.

Windows lab queue identity evidence: inbox SQLite API​

lab/aws/monitoring/wec-qualification.ps1 uses winsqlite3.dll, the Windows Server 2016+ inbox SQLite API, through PS5.1-compatible P/Invoke. This is a lab-only read-only projection of event_id and received_at needed to reconcile native WEC identities with actual durable queue acceptance. It avoids exporting queue payloads or installing a separate SQLite executable/runtime package. Input rows and field lengths are bounded; unsupported APIs and read errors fail the qualification. The production collector retains its existing SQLite dependency. The API must be exercised on the owned Windows host; cross-platform compilation and mocked tests do not establish native compatibility.