Skip to content

Component: Smrt.SupportBundle

Canonical source: SmrtApps/src/Smrt.SupportBundle/README.md (mirrored below)

Smrt.SupportBundle

  • Support Bundle Subsystem (contracts): README.Files/Subsystems/SupportBundle/README.md
  • Support Bundle Capability (end-to-end flow): README.Files/Capabilities/SupportBundle/README.md
  • Support Bundle Reference Guide: README.Files/Reference-Guides/Smrt.SupportBundle.README.md

Overview & Responsibilities

  • Enterprise-grade exporter for SmrtHub diagnostics hand-off. Builds sanitized ZIP bundles that operators can share without leaking sensitive data.
  • SupportBundleExporter orchestrates discovery, sanitization, manifest creation, HTML review reporting, and final packaging.
  • Aligns with README.Files/Reference-Guides/SmrtHub.Logging.README.md for log discovery/HTML export and README.Files/Reference-Guides/Smrt.SupportBundle.README.md for system-wide bundle behavior.

Key Features

  • Comprehensive Data Collection
  • Application logs (JSONL format from Smrt.Logging)
  • Diagnostic artifacts (crash dumps, reports)
  • System information (OS, memory, disk, architecture)
  • Configuration snapshots (optional, sanitized)
  • Storage guard telemetry + signature metadata (BitLocker state, free-space, sync heartbeat) with verification summary for cryptographic proof—even when the service is mid secret rotation

  • Retention evidence (policies, legal holds, verification report + signature, health summary, provider automation logs)

  • Privacy & Security

  • Automatic PII redaction (emails, SSN, credit cards)
  • Credential scrubbing (passwords, API keys, tokens)
  • Path and network info sanitization
  • Configurable data classes for fine-grained control

  • No raw unredacted data in bundles by default

  • Flexible Filtering

  • Time windows (absolute or relative)
  • Severity levels (Information, Warning, Error, Debug, Verbose, Fatal)
  • Component/module filtering

  • Category selection (Logs, Diagnostics, SystemInfo, Config)

  • Manifest & Verification

  • SHA-256 hashes for all files
  • Detailed manifest (v1.1) with metadata and retention verification summary
  • Human-readable HTML review reports (Support, Legal, Compliance) generated every run; legal/compliance views now ingest retention policies, legal holds, worker health, and provider evidence so each stakeholder sees bespoke insights

  • Redaction summary with counts

  • Progress Tracking

  • Real-time progress reporting
  • Cancellation support
  • Non-fatal error collection

Dependencies & Integrations

  • Emits operational telemetry through SmrtHub.Logging; see README.Files/Reference-Guides/SmrtHub.Logging.README.md for sink behavior and HTML export parity.
  • Reads component logs/config snapshots from canonical paths defined in README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md (for example %AppData%/SmrtHub/Logs/<slug>).
  • Optional configuration snapshots use Microsoft.Extensions.Configuration.Abstractions; callers should construct roots via Smrt.Config helpers to guarantee canonical locations.
  • Storage guard evidence comes from the signed snapshot + signature emitted by Smrt.StorageGuard.ServiceHost. The provider copies storage-guard.json, storage-guard.sig, and a verification report generated via StorageGuardSignatureVerifier, iterating across the shared secret set so operators can prove authenticity during and after secret rotations without rerunning disk probes.
  • Retention evidence relies on Smrt.Retention.Storage.RetentionPaths to collect the latest policies, legal holds, verification payload + signature, health summary, and provider automation logs alongside the signed storage guard snapshot.
  • No additional NuGet pins are declared locally. All dependencies are centrally managed in Directory.Packages.props per README.Files/System/Policies/SmrtHub-Central-Package-Version-Policy-v1.0.README.md.

Configuration & Log Paths

  • Runtime behavior is driven entirely through ExportOptions (see table below). There is no separate appsettings file for this library.
  • Bundles are written to ExportOptions.OutputDirectory with filenames <prefix>-YYYYMMDD-HHMMSS.zip. Staging occurs in a temporary child directory and is deleted post-package.
  • Inputs come from component log folders (Logs/<slug>) inside %LocalAppData%/SmrtHub and configuration directories (Config/<slug>) inside %AppData%/SmrtHub.
  • Diagnostic artifacts are collected from %AppData%/SmrtHub/Diagnostics/<slug> per the Operational Data Policy; the exporter will skip the category if the caller disables it or no files exist.
  • Sensitive data never leaves the sanitized staging directory. Raw copies are only retained when IncludeRawUnredactedPreview is explicitly enabled.

Observability & diagnostics

  • The exporter emits structured logs through SmrtHub.Logging describing planning decisions, skipped artifacts, redaction counts, and final output paths.
  • Not documented yet: standardized event names and correlation IDs for bundle export runs.

Support bundle

This component is the canonical support bundle exporter. Other components should invoke it (or approved wrappers) rather than inventing ad-hoc diagnostic packagers.

Runtime Workflow

  1. SupportBundleExporter validates the supplied options (output folder, prefix, sanitization intent) and ensures the logger is initialized.
  2. ExportPlanner aggregates artifacts from provider implementations (logs, diagnostics, system info, configuration, storage guard evidence, retention evidence).
  3. Sanitizer copies artifacts into a staging directory, applying redaction rules defined by DataClassFlags while tracking counts.
  4. ManifestBuilder produces manifest.json v1.1 with SHA-256 hashes, error summaries, and a retentionEvidence block (when retention artifacts were staged); optional signing writes manifest.sig.
  5. ReviewReportBuilder crafts the review/ HTML trio (Support, Legal, Compliance) so operators, counsel, and compliance reviewers each get tailored insights without reopening the manifest manually.
  6. Packager compresses staged content into the final ZIP (deterministic when requested), and the exporter cleans up staging + temporary provider files.

API Quick Start

Basic Usage

using Smrt.SupportBundle;
using Smrt.SupportBundle.Models;

var exporter = new SupportBundleExporter();

var options = new ExportOptions
{
  OutputDirectory = @"C:\\Support Bundles",
  FileNamePrefix = "smrthub-support",
  Categories = ExportCategories.All,
  RelativeWindowHours = 24, // Last 24 hours
  DataClasses = DataClassFlags.All
};

var result = await exporter.ExportAsync(options);

SmrtHub.Logging.Logger.Info($"Bundle created: {result.BundlePath}");
SmrtHub.Logging.Logger.Info($"Files: {result.TotalFiles}, Size: {result.TotalSizeBytes / (1024.0 * 1024):F2} MB");

With Progress Tracking

var progress = new Progress<ExportProgress>(p =>
{
  SmrtHub.Logging.Logger.Info($"[{p.Percent}%] {p.Stage}");
});

var result = await exporter.ExportAsync(options, progress);

With Cancellation Support

var cts = new CancellationTokenSource();
// Cancel after 30 seconds
cts.CancelAfter(TimeSpan.FromSeconds(30));

try
{
    var result = await exporter.ExportAsync(options, progress, cts.Token);
}
catch (OperationCanceledException)
{
  SmrtHub.Logging.Logger.Warning("Support bundle export was canceled");
}

Selective Categories

var options = new ExportOptions
{
    OutputDirectory = @"C:\Support Bundles",
    Categories = ExportCategories.Logs | ExportCategories.SystemInfo,
    // Only collect logs and system info, skip diagnostics and config
};

Custom Time Window

var options = new ExportOptions
{
    OutputDirectory = @"C:\Support Bundles",
    TimeStartUtc = DateTimeOffset.UtcNow.AddDays(-7),
    TimeEndUtc = DateTimeOffset.UtcNow,
    Severities = new HashSet<string> { "Warning", "Error", "Fatal" }
};

Module Filtering

var options = new ExportOptions
{
    OutputDirectory = @"C:\Support Bundles",
    Modules = new HashSet<string> { "hub-window" },
    // Only include logs from these components
};

Testing & Validation

Automated Tests

dotnet test SmrtApps/tests/Smrt.SupportBundle.Tests/Smrt.SupportBundle.Tests.csproj -c Debug

The automated suite covers: - Happy-path exports with full sanitization - Empty result handling when no artifacts match filters - Invalid option validation - Cancellation behavior mid-export - Deterministic packaging toggles

Manual Smoke Harness

A CLI harness is available for exploratory testing:

cd SmrtApps\tests\Smrt.SupportBundle.TestHarness
dotnet run

Or run the compiled executable:

dotnet run --project SmrtApps\tests\Smrt.SupportBundle.TestHarness\Smrt.SupportBundle.TestHarness.csproj

The harness: 1. Prompts for an output directory (defaults to Desktop) 2. Emits sample log entries via SmrtHub.Logging 3. Runs an export with all categories enabled 4. Displays the resulting bundle path and can open the output folder

Bundle Structure

smrthub-support-20251018-143022.zip
├── manifest.json              # Metadata, file list, hashes, retentionEvidence summary
├── review/
│   └── report.html           # Human-readable summary
├── logs/
│   ├── hub-window/
│   │   └── hub-window-log20251018.json
├── diagnostics/              # If any crash dumps exist
├── system-info/
│   ├── system-info.json          # OS, memory, disk info
│   ├── storage-guard.json        # BitLocker/free-space/sync snapshot
│   ├── storage-guard.sig         # SHA-512 + HMAC signature document
│   ├── storage-guard-verification.json # Verification result emitted during export
│   └── retention/
│       ├── retention-policy.json         # Active retention policies at capture time
│       ├── legal-holds.json              # Active legal holds
│       ├── retention-verification.json   # Most recent verification run output
│       ├── retention-verification.sig    # Signature for the verification payload
│       ├── retention-health.json         # Rolling health summary
│       └── providers/                    # Provider automation logs (sharepoint, smb, etc.)
└── config/
    └── config-snapshot.json  # If InjectedConfiguration provided

Manifest retention evidence summary

manifest.json now emits a retentionEvidence block whenever system-info/retention/* artifacts were staged. The block contains:

  • verificationId, generatedUtc, and SHA-256 hashes of the policy/legal-hold JSON that fed the run.
  • Aggregate warningCount, errorCount, signatureIncluded, signatureVerified, signatureVerifiedAtUtc, signatureIssuedAtUtc, and signatureError/keyIds so operators can see whether the detached signature was validated with local trust roots.
  • providers[] entries (one per retention provider) with status, outside/inside counts, legal-hold matches, free-space percentage, and optional notes.

This enables downstream tooling to reason about retention health without re-parsing the raw verification payload and keeps phase-3 retention reporting centralized in the manifest.

ExportOptions Reference

Property Type Description Default
OutputDirectory string Where to save the bundle Required
FileNamePrefix string Prefix for bundle filename "smrthub-support"
Categories ExportCategories What to include All
DataClasses DataClassFlags Sanitization level All
TimeStartUtc DateTimeOffset? Start of time window null (no limit)
TimeEndUtc DateTimeOffset? End of time window null (defaults to Now)
RelativeWindowHours int? Override with relative window null
Severities HashSet<string> Log levels to include All levels
Modules HashSet<string> Components to include All components
MaxBundleSizeMB int? Soft size cap in MB null (no limit)
IncludeRawUnredactedPreview bool Include raw unredacted preview (DANGEROUS) false
IncludeRetentionWindowDays int? Pre-filter to last N days null
ZipPassword string? ZIP password (not implemented yet) null
SignWithCertThumbprint string? Cert for signing (not implemented yet) null
InjectedConfiguration IConfiguration? Config to snapshot null
IncludeHtmlLog bool Include exported HTML log viewers when present false
DeterministicZip bool Forces sorted entries + fixed timestamps true
SignManifest bool Emits manifest.sig containing the SHA-256 hash true
ReportKinds HashSet<ReportKind> Which HTML reports to emit (Support, Legal, Compliance) All kinds

Data Classes

Control what gets redacted via DataClassFlags:

  • PII: Personally Identifiable Information (email, SSN, credit cards)
  • Credentials: Passwords, API keys, secrets
  • Tokens: Bearer tokens, JWTs, generic tokens
  • Paths: File system paths (Windows and Unix)
  • HostInfo: Machine names, hostnames
  • NetInfo: IP addresses (IPv4, IPv6)

Compliance report generator

Phase 4 adds a one-click compliance workflow powered by ComplianceReportGenerator. It wraps the existing SupportBundleExporter pipeline with a hardened preset:

  • Collects system-info/* evidence plus the storage-guard-service, retention-verifier, and smrt-hub-supervisor logs.
  • Enforces deterministic zips, manifest signatures, and emits a .sha256 hash file beside the bundle for downstream verification.
  • Produces a machine-readable *.compliance.json summary with bundle/manifest hashes, retention health, and the hashed artifact list so auditors can validate evidence without cracking open the ZIP.
using Smrt.SupportBundle.Compliance;

var generator = new ComplianceReportGenerator();
var options = new ComplianceReportOptions
{
  OutputDirectory = @"C:\\Evidence\\Compliance",
  FileNamePrefix = "smrthub-compliance",
  RelativeWindowHours = 168 // last 7 days
};

var result = await generator.GenerateAsync(options);

Console.WriteLine($"Bundle: {result.BundlePath}");
Console.WriteLine($"Bundle SHA-256: {result.BundleSha256}");
Console.WriteLine($"Summary: {result.SummaryPath}");

ComplianceReportSummary (stored in the JSON output) surfaces:

  • Bundle + manifest hashes, log window, severity/module filters.
  • Latest retention verification metadata (ID, signature flags, per-provider status).
  • Hashes for the Storage Guard snapshot/signature, retention policy/hold files, verification payloads, and the targeted component logs.
  • Storage Guard ACL inspection results, open issues, current quota forecasts, plus the aggregated aclDriftCount and retentionConfigHash so compliance reviewers can reason about disk posture (and prove which retention payloads were present) without unpacking the ZIP.

Supervisor’s new --compliance-report verb consumes the generator so operators can capture a signed evidence pack directly from the CLI without touching raw folders.

Integration Points

  • HubWindow tray: Export menu item invokes ISupportBundleExporter with user-selected filters.
  • Supervisor & services: On critical faults, supervisors can trigger automated exports scoped to the failing component for post-mortem analysis.
  • CLI tooling: Operators can wrap the exporter in scripted workflows (for example, capturing a support bundle after running automated diagnostics).
  • Future MKDocs ingest: Docstrings and README content here will feed future SDK-style reference pages.

Apps Staging Notes

  • The central Apps/<Configuration>/<RuntimeIdentifier>/ staging (see README.Files/System/Policies/SmrtHub-Architecture_Platform_Policy.README.md) does not change log/config locations. The exporter always reads from %AppData%/SmrtHub/... per Operational Data Policy.
  • Bundles typically exclude binaries. Only include executables when explicitly requested for forensic review.

Architecture (Internal Layout)

  • Providers (Internal/Providers) discover artifacts for logs, diagnostics, system info, configuration, storage guard evidence, and retention evidence.
  • Planner (Internal/Planning) aggregates provider output into a cohesive plan and surfaces warnings.
  • Sanitizer (Internal/Sanitization) applies redaction rules and writes sanitized copies to staging.
  • Manifest & Reporting (Internal/Models, Internal/Reporting) generate the manifest JSON, signature, and HTML review report.
  • Packaging (Internal/Packaging) compresses artifacts into the final bundle using deterministic ordering when requested.
  • Utilities (Internal/Utilities) contains shared helpers such as the SHA-256 hash computer.

Directory Map

  • SupportBundleExporter.cs — public orchestrator and primary entry point.
  • ISupportBundleExporter.cs — contract used by callers.
  • Models/ — public data contracts (ExportOptions, ExportResult, enums, progress updates).
  • Internal/ — implementation details (providers, planner, sanitizer, manifest/report builders, packager, utilities). Each subdirectory has its own README describing responsibilities.
  • Smrt.SupportBundle.csproj — .NET 8 class library configuration with XML doc output enabled.
  • bin/, obj/ — generated artifacts; purge via repository build scripts.

Policy References

  • Logging & HTML export parity: README.Files/Reference-Guides/SmrtHub.Logging.README.md
  • Operational paths & naming: README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md
  • Documentation standards: README.Files/System/Policies/SmrtHub-Documentation-Policy-v1.0.README.md
  • NuGet version governance: README.Files/System/Policies/SmrtHub-Central-Package-Version-Policy-v1.0.README.md
  • Architecture & staging: README.Files/System/Policies/SmrtHub-Architecture_Platform_Policy.README.md