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
- func HashBytes(data []byte) string
- func HashFile(path string) (string, int64, error)
- func SuggestOutputPath(session string, format Format) string
- type BundleFilters
- type FileEntry
- type FileRedaction
- type Format
- type Generator
- func (g *Generator) AddDirectory(basePath, relativeTo, contentType string) error
- func (g *Generator) AddFile(relativePath string, data []byte, contentType string, modTime time.Time) error
- func (g *Generator) AddScrollback(paneName string, content string, lines int) error
- func (g *Generator) Generate() (*GeneratorResult, error)
- type GeneratorConfig
- type GeneratorResult
- type HostInfo
- type Manifest
- type RedactionSummary
- type SessionInfo
- type VerifyResult
Constants ¶
const ( ContentTypeScrollback = "scrollback" ContentTypeConfig = "config" ContentTypeLogs = "logs" ContentTypeState = "state" ContentTypeMetadata = "metadata" ContentTypePatch = "patch" ContentTypeUnknown = "unknown" )
ContentTypes for FileEntry.ContentType field.
const DefaultFormat = FormatZip
DefaultFormat is the default bundle format.
const ManifestFileName = "manifest.json"
ManifestFileName is the expected manifest file name in bundles.
const MinSchemaVersion = 1
MinSchemaVersion is the minimum supported manifest schema version.
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 SuggestOutputPath ¶
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.
func DetectFormat ¶
DetectFormat determines the bundle format from the file path.
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 ¶
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 ¶
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 ¶
NewManifest creates a new manifest with default values.
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.