Debug Bundle Generation

Overview

The Debug Bundle Builder is a component responsible for assembling a self-contained, compressed diagnostic package for a given traffic capture session. This package, known as a debug bundle, aids in troubleshooting by providing masked API transaction samples, a tokenized system topology, and contextual telemetry in a single ZIP archive.

The builder takes a capture session ID as input and produces the cleartext, compressed bundle as an in-memory byte array. It is designed to be a part of a larger diagnostic workflow; it generates the bundle's content but does not persist or transmit the resulting cleartext archive. A separate component is responsible for encrypting the bundle before storage or delivery.

A key feature of the builder is its security-conscious design. It uses a transient, per-bundle salt to perform irreversible masking of sensitive data in the captured events and system topology. This salt is generated for a single build operation and is securely discarded immediately afterward, ensuring that the tokenized data in the bundle cannot be reversed.

How It Works

The bundle generation process is triggered by a call to buildCleartextBundle with a specific sessionId. The component then executes a series of steps to gather, mask, and package the required diagnostic data.

flowchart TD
    subgraph Bundle Generation Flow
        A[Start: sessionId] --> B{Fetch Session Data};
        B --> C[Generate Per-Bundle Salt];
        C --> D[Fetch & Mask Captured Events];
        C --> E[Extract Tokenized Topology];
        B --> F[Collect Scoped Telemetry];
        D & E & F --> G[Generate Manifest with Hashes];
        G & D & E & F --> H[Assemble ZIP Archive];
        H --> I[Return Cleartext Bundle];
    end
    subgraph Security
        C --> J[Salt is used for masking];
        I --> K[Discard Per-Bundle Salt];
    end

1. Session Retrieval: The process begins by retrieving the specified capture session's metadata from the DebugCaptureRepository using the provided sessionId. If the session does not exist, the process fails.

2. Salt Generation: A new, cryptographically-secure salt is generated specifically for this bundle. This salt is held in memory only for the duration of the build.

3. Data Collection and Masking:

   • Event Samples: The builder fetches the captured event rows associated with the session, up to a hard-coded limit of 500 samples (MAX_SAMPLES). Each event's raw data is processed through a MaskingPipeline using the generated salt. This replaces sensitive values with non-reversible tokens. The gateway_type and captured_at timestamp are added to the masked output.
   • Topology: The system's topology is extracted via the TopologyExtractor. This process also uses the same per-bundle salt to tokenize identifiers, ensuring consistency between the topology data and the event samples. No credentials are included.
   • Telemetry: A snapshot of "Tier-0" diagnostic data is collected via the DiagnosticTelemetryCollector. This information is automatically scoped to the current tenant to prevent data leakage in a multi-tenant environment.

4. Manifest Creation: A manifest.json file is generated. It contains essential metadata about the bundle:

   • A unique bundleId (UUID).
   • The original sessionId.
   • The session's tier and redactionProfile.
   • A summary of the capture scope (e.g., presence of filters, event cap).
   • The total number of events in the session and the number of samples included in the bundle.
   • SHA-256 hashes of every other file in the bundle, ensuring integrity.

5. ZIP Assembly: All generated artifacts—manifest.json, topology/topology.json, telemetry-v2.json, and the individual samples/<n>.json files—are assembled into a single ZIP archive in memory.

6. Cleanup and Return:

   • In a finally block, the per-bundle salt is securely zeroed out and discarded from memory. This is a critical step to guarantee the non-reversibility of the masked data.
   • The final CleartextBundle object, which contains the new bundleId, the ZIP archive bytes, and the manifest map, is returned to the caller.

Bundle Contents

Each generated debug bundle is a ZIP archive containing the following files:

Previewing Bundle Contents

Before generating a full bundle, an API publisher can request a "dry-run" preview. The preview() method provides a partial, uncompressed view of the data that would be included in a bundle. This allows for verification of the masking and redaction rules.

The preview is generated using a temporary, throwaway salt that is immediately discarded. The tokens in a preview are not guaranteed to match the tokens in a subsequently generated bundle.

A call to preview(sessionId, sampleLimit) returns a map containing:

• Session metadata (session_id, redaction_profile, tier).
• Event counts (total_events, preview_sample_count).
• A manifest object similar to the one in a real bundle, but with empty file hashes.
• A list of samples, where each entry is a masked event map.
• A topology_preview object showing the tokenized topology.

The number of samples in a preview is determined by the sampleLimit parameter, which defaults to 3 if the input is 0 or less, and is capped at a maximum of 25.

API Reference

The BundleBuilder component exposes the following public methods.

Configuration

The builder includes an internal constant that defines an operational limit.

Security Considerations

The design of the BundleBuilder incorporates several important security controls.

Transient Masking Salt

To ensure that masked data cannot be reversed, the builder generates a unique salt for each bundle creation operation.

• This salt is used by the MaskingPipeline to tokenize sensitive fields in event samples and the topology.
• The salt exists only in memory for the duration of the buildCleartextBundle or preview method call.
• A finally block ensures the byte array holding the salt is overwritten with zeros before the method returns, securely discarding it.
• The salt is never included in the bundle or persisted anywhere.

Cleartext Data Handling

The output of this component is a CleartextBundle. The raw, unencrypted ZIP archive exists only as an in-memory byte array. The component itself does not write this cleartext data to disk or the database. It is the responsibility of the calling service to handle the encryption of these bytes before any persistence or transmission.

Scoped Telemetry

To prevent unauthorized information disclosure in multi-tenant deployments, the included diagnostic telemetry is strictly scoped. The collectForBoundTenant() method ensures that an operator can only retrieve telemetry relevant to their own tenant, not platform-wide data or data from other tenants.

Troubleshooting

All SOAP-to-REST docs