bundle

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 2, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package bundle provides support bundle generation and manifest handling. Support bundles are archives containing diagnostic information for debugging and support purposes, with built-in redaction for sensitive content.

Index

Constants

View Source
const (
	ContentTypeScrollback = "scrollback"
	ContentTypeConfig     = "config"
	ContentTypeLogs       = "logs"
	ContentTypeState      = "state"
	ContentTypeMetadata   = "metadata"
	ContentTypePatch      = "patch"
	ContentTypeUnknown    = "unknown"
)

ContentTypes for FileEntry.ContentType field.

View Source
const DefaultFormat = FormatZip

DefaultFormat is the default bundle format.

View Source
const ManifestFileName = "manifest.json"

ManifestFileName is the expected manifest file name in bundles.

View Source
const MinSchemaVersion = 1

MinSchemaVersion is the minimum supported manifest schema version.

View Source
const SchemaVersion = 1

SchemaVersion is the current manifest schema version. Increment when making breaking changes to the manifest format.

Variables

This section is empty.

Functions

func HashBytes

func HashBytes(data []byte) string

HashBytes computes the SHA256 hash of a byte slice.

func HashFile

func HashFile(path string) (string, int64, error)

HashFile computes the SHA256 hash of a file.

func SuggestOutputPath

func SuggestOutputPath(session string, format Format) string

SuggestOutputPath generates a default output path.

Types

type BundleFilters

type BundleFilters struct {
	// Since is the earliest timestamp for included content (RFC3339).
	Since string `json:"since,omitempty"`

	// Lines is the maximum lines of scrollback per pane.
	Lines int `json:"lines,omitempty"`

	// MaxSizeBytes is the maximum bundle size limit.
	MaxSizeBytes int64 `json:"max_size_bytes,omitempty"`
}

BundleFilters contains the constraints used during bundle generation.

type FileEntry

type FileEntry struct {
	// Path is the relative path within the bundle.
	Path string `json:"path"`

	// SHA256 is the hex-encoded SHA256 hash of the file content.
	SHA256 string `json:"sha256"`

	// SizeBytes is the file size in bytes.
	SizeBytes int64 `json:"size_bytes"`

	// ContentType describes the file content (e.g., "scrollback", "config", "logs").
	ContentType string `json:"content_type,omitempty"`

	// Redaction contains redaction details for this file.
	Redaction *FileRedaction `json:"redaction,omitempty"`

	// SourcePath is the original file path (may be redacted or omitted).
	SourcePath string `json:"source_path,omitempty"`

	// ModTime is the original file modification time (RFC3339).
	ModTime string `json:"mod_time,omitempty"`
}

FileEntry describes a single file in the bundle.

type FileRedaction

type FileRedaction struct {
	// WasRedacted indicates if any content was redacted.
	WasRedacted bool `json:"was_redacted"`

	// FindingCount is the number of secrets detected.
	FindingCount int `json:"finding_count"`

	// Categories lists the types of secrets found.
	Categories []string `json:"categories,omitempty"`

	// OriginalSize is the file size before redaction.
	OriginalSize int64 `json:"original_size,omitempty"`
}

FileRedaction describes redaction actions for a single file.

type Format

type Format string

Format represents a bundle archive format.

const (
	FormatZip     Format = "zip"
	FormatTarGz   Format = "tar.gz"
	FormatUnknown Format = "unknown"
)

func DetectFormat

func DetectFormat(path string) Format

DetectFormat determines the bundle format from the file path.

func (Format) Extension

func (f Format) Extension() string

Extension returns the file extension for a format.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator creates support bundles.

func NewGenerator

func NewGenerator(config GeneratorConfig) *Generator

NewGenerator creates a new bundle generator.

func (*Generator) AddDirectory

func (g *Generator) AddDirectory(basePath, relativeTo, contentType string) error

AddDirectory adds all files from a directory recursively.

func (*Generator) AddFile

func (g *Generator) AddFile(relativePath string, data []byte, contentType string, modTime time.Time) error

AddFile adds a file to the bundle with optional redaction.

func (*Generator) AddScrollback

func (g *Generator) AddScrollback(paneName string, content string, lines int) error

AddScrollback adds pane scrollback with optional line limit.

func (*Generator) Generate

func (g *Generator) Generate() (*GeneratorResult, error)

Generate creates the bundle archive.

type GeneratorConfig

type GeneratorConfig struct {
	// Session is the target session name (optional).
	Session string

	// OutputPath is the destination file path.
	OutputPath string

	// Format specifies the archive format (zip or tar.gz).
	Format Format

	// NTMVersion is included in the manifest.
	NTMVersion string

	// Since filters content to entries after this time (optional).
	Since *time.Time

	// Lines limits scrollback capture per pane (0 = unlimited).
	Lines int

	// MaxSizeBytes is the maximum bundle size (0 = unlimited).
	MaxSizeBytes int64

	// RedactionConfig configures secret redaction.
	RedactionConfig redaction.Config

	// WorkDir is the working directory for relative paths.
	WorkDir string
}

GeneratorConfig configures support bundle generation.

type GeneratorResult

type GeneratorResult struct {
	// Path is the generated bundle file path.
	Path string `json:"path"`

	// Format is the archive format used.
	Format Format `json:"format"`

	// FileCount is the number of files in the bundle.
	FileCount int `json:"file_count"`

	// TotalSize is the total size in bytes.
	TotalSize int64 `json:"total_size"`

	// RedactionSummary contains aggregate redaction stats.
	RedactionSummary *RedactionSummary `json:"redaction_summary,omitempty"`

	// Manifest is the generated manifest.
	Manifest *Manifest `json:"manifest,omitempty"`

	// Errors contains any non-fatal errors during generation.
	Errors []string `json:"errors,omitempty"`

	// Warnings contains any warnings.
	Warnings []string `json:"warnings,omitempty"`
}

GeneratorResult contains the outcome of bundle generation.

type HostInfo

type HostInfo struct {
	// OS is the operating system (e.g., "linux", "darwin", "windows").
	OS string `json:"os"`

	// Arch is the CPU architecture (e.g., "amd64", "arm64").
	Arch string `json:"arch"`

	// Hostname is the machine hostname (may be redacted).
	Hostname string `json:"hostname,omitempty"`

	// Username is the current user (may be redacted).
	Username string `json:"username,omitempty"`
}

HostInfo contains information about the machine that generated the bundle.

type Manifest

type Manifest struct {
	// SchemaVersion is the manifest format version.
	SchemaVersion int `json:"schema_version"`

	// GeneratedAt is when the bundle was created (RFC3339).
	GeneratedAt string `json:"generated_at"`

	// NTMVersion is the version of NTM that created the bundle.
	NTMVersion string `json:"ntm_version"`

	// Host contains information about the generating machine.
	Host HostInfo `json:"host"`

	// Session contains optional session context.
	Session *SessionInfo `json:"session,omitempty"`

	// Files lists all files included in the bundle.
	Files []FileEntry `json:"files"`

	// RedactionSummary provides an aggregate view of redaction actions.
	RedactionSummary *RedactionSummary `json:"redaction_summary,omitempty"`

	// Filters contains the time/size constraints used during generation.
	Filters *BundleFilters `json:"filters,omitempty"`

	// Errors lists any non-fatal errors during bundle generation.
	Errors []string `json:"errors,omitempty"`
}

Manifest represents the metadata for a support bundle. It provides integrity verification and content inventory.

func NewManifest

func NewManifest(ntmVersion string) *Manifest

NewManifest creates a new manifest with default values.

func (*Manifest) AddError

func (m *Manifest) AddError(msg string)

AddError records a non-fatal error during bundle generation.

func (*Manifest) AddFile

func (m *Manifest) AddFile(entry FileEntry)

AddFile adds a file entry to the manifest.

func (*Manifest) FileCount

func (m *Manifest) FileCount() int

FileCount returns the number of files in the bundle.

func (*Manifest) TotalSize

func (m *Manifest) TotalSize() int64

TotalSize returns the total size of all files in the bundle.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks if the manifest is valid.

type RedactionSummary

type RedactionSummary struct {
	// Mode is the redaction mode used (off, warn, redact, block).
	Mode string `json:"mode"`

	// TotalFindings is the total number of secrets detected.
	TotalFindings int `json:"total_findings"`

	// FilesScanned is the number of files scanned.
	FilesScanned int `json:"files_scanned"`

	// FilesRedacted is the number of files with redactions.
	FilesRedacted int `json:"files_redacted"`

	// CategoryCounts maps category to occurrence count.
	CategoryCounts map[string]int `json:"category_counts,omitempty"`
}

RedactionSummary provides aggregate redaction statistics.

type SessionInfo

type SessionInfo struct {
	// Name is the tmux session name.
	Name string `json:"name"`

	// Directory is the working directory.
	Directory string `json:"directory,omitempty"`

	// PaneCount is the number of panes in the session.
	PaneCount int `json:"pane_count,omitempty"`

	// AgentCounts maps agent type to count.
	AgentCounts map[string]int `json:"agent_counts,omitempty"`
}

SessionInfo contains optional session context for the bundle.

type VerifyResult

type VerifyResult struct {
	// Valid is true if all checks passed.
	Valid bool `json:"valid"`

	// ManifestValid indicates if the manifest was found and parseable.
	ManifestValid bool `json:"manifest_valid"`

	// SchemaValid indicates if the schema version is supported.
	SchemaValid bool `json:"schema_valid"`

	// FilesPresent indicates if all manifest files exist in the bundle.
	FilesPresent bool `json:"files_present"`

	// ChecksumsValid indicates if all checksums match.
	ChecksumsValid bool `json:"checksums_valid"`

	// Errors contains any validation errors.
	Errors []string `json:"errors,omitempty"`

	// Warnings contains non-fatal issues.
	Warnings []string `json:"warnings,omitempty"`

	// Details contains additional verification details.
	Details map[string]string `json:"details,omitempty"`

	// Manifest is the parsed manifest (nil if not found/invalid).
	Manifest *Manifest `json:"manifest,omitempty"`
}

VerifyResult contains the results of bundle verification.

func Verify

func Verify(bundlePath string) (*VerifyResult, error)

Verify validates a support bundle archive.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL