v0.5.0

BoneStack v0.5.0

Highlights

• added in-TUI AI settings with provider selection and saved connectivity
• added AI-assisted forensics for Threat Hunt, Container Diff, and Timeline
• added agentic follow-up so AI can request more BoneStack context and the user can fetch it with x
• added AI loading screens with live animation and backend connectivity checks
• added a safe ai-followup-demo training container for practicing the AI workflow
• added a dedicated AI guide and a real GitHub Pages docs route at /docs/

Included In This Release

• supported AI providers:
  • ollama
  • openai
  • claude
  • grok
  • gemini
  • openai-compatible
• default model presets for supported providers
• AI follow-up context collection for:
  • threat-hunt
  • container-diff
  • timeline
  • logs
  • environment
  • resources
  • processes
  • filesystem
• updated README and docs to surface AI earlier
• Pages docs index to avoid dead docs links

Verification

GOCACHE=/tmp/gocache go test ./...

BoneStack v0.4.1 - Pages And Update UX

BoneStack v0.4.1 - Pages And Update UX

Release Date: April 2, 2026
Status: ✅ Buildable and Tagged
Focus: self-update command, GitHub Pages publishing, and docs/site polish

---

What's New in v0.4.1

BoneStack v0.4.1 packages the follow-up work after v0.4.0: the binary now has a built-in update command, the repository includes a GitHub Pages deployment workflow and landing page, and the Pages site now carries training commands and a visual theme aligned with the project logo.

Included in This Release

1. Built-in update command

• Added bonestack update
• Added bonestack version
• Added bonestack help
• Reused the local installer flow instead of requiring users to rerun the raw install command manually

2. GitHub Pages support

• Added a Pages deployment workflow
• Added a static site landing page for BoneStack
• Added training-container usage instructions to the Pages site
• Restyled the Pages site to match the dark neon look of the BoneStack logo

3. Docs and install UX polish

• Updated the README to point users at bonestack update
• Kept the top-level README short while preserving detailed docs in docs/

Verification

The release was verified with:

GOCACHE=/tmp/gocache go test ./...

Notable Files

• internal/cli/commands.go
• internal/cli/commands_test.go
• .github/workflows/pages.yml
• site/index.html
• README.md

Next Recommended Step

• verify GitHub Pages is set to Source: GitHub Actions
• continue Phase 6 with image comparison and custom YARA rules

BoneStack v0.4.0 - Container Forensics Expansion

BoneStack v0.4.0 - Container Forensics Expansion

Release Date: April 2, 2026
Status: ✅ Buildable and Tagged
Focus: container forensics, YARA-backed hunting, docs, installer, and training images

---

What's New in v0.4.0

BoneStack v0.4.0 expands the container forensics path into a more complete workflow. This release adds dedicated threat-hunt, container-diff, and timeline analysis, optional YARA-backed scanning, combined report export, a simpler install/update script, and safe training containers for learning the tool.

Included in This Release

1. New container forensics views

• Added Threat Hunt
• Added Container Diff
• Added Timeline
• Added combined container forensics export in:
  • forensics.json
  • forensics.csv
  • forensics.html

2. Optional YARA integration

• Added defensive YARA-backed scanning during Threat Hunt
• Bundled default rules for:
  • reverse shell patterns
  • download-and-exec patterns
  • LD_PRELOAD
  • encoded payloads
  • SSH key drops
  • cron persistence
• Falls back cleanly when yara is not installed

3. Installer and docs cleanup

• Replaced the old local-only installer with a clone-or-update installer
• Added docs under docs/
• Shortened the top-level README and moved detailed guidance into the docs

4. Safe training containers

• Added example training containers under training/containers/
• Included suspicious-but-benign scenarios for:
  • cron-style persistence artifacts
  • SSH key and shell-history artifacts
  • badly built, bloated images

Current Phase Status

• Phase 1: complete
• Phase 2: complete
• Phase 3: complete
• Phase 4: implemented
• Phase 5: implemented
• Phase 6: in progress

Verification

The release was verified with:

GOCACHE=/tmp/gocache go test ./...

Notable Files

• internal/forensics/threathunt/scanner.go
• internal/forensics/containerdiff/scanner.go
• internal/forensics/timeline/scanner.go
• internal/forensics/yarascan/scanner.go
• internal/report/exporter.go
• internal/ui/app.go
• install.sh
• docs/
• training/containers/

Next Recommended Step

Phase 6 should continue with:

• image comparison workflows
• custom YARA rule support
• batch analysis
• richer report customization

BoneStack v0.3.1 - Phase 5 Scaffold Deepening

BoneStack v0.3.1 - Phase 5 Scaffold Deepening

Release Date: April 2, 2026
Status: ✅ Buildable and Tagged
Focus: analysis-aware scaffold generation, export flow, and TUI feedback

---

What's New in v0.3.1

BoneStack v0.3.1 deepens the Phase 5 scaffold path so it can use real image tar analysis instead of only image metadata heuristics. This release also makes the optimization and scaffold screens more explicit in the TUI by surfacing tar-analysis status, fallback errors, and file export behavior.

Included in This Release

1. Tar-analysis-backed scaffolding

• Added Docker image archive parsing through ImageSave
• Extracted embedded layer.tar payloads from saved image archives
• Fed file-analysis results into scaffold runtime inference
• Added Rust detection from .rs, Cargo.toml, and Cargo.lock

2. Stronger generated output

• Folded dependency optimization hints directly into generated Dockerfiles
• Added runtime-specific security artifacts for Node, Python, Rust, and Go
• Added export support for generated scaffold files from the TUI
• Preserved metadata-only fallback when tar analysis is unavailable

3. Better TUI behavior

• Fixed o and g routing so optimization and scaffold screens open correctly on first use
• Surfaced tar-analysis status and fallback errors in optimization and scaffold views
• Added per-layer finding summaries and tar-analysis highlights to the UI

4. Documentation and release hygiene

• Updated the README to reflect current Phase 5 status
• Advanced the roadmap to make Phase 6 the next milestone

Current Phase Status

• Phase 1: complete
• Phase 2: complete
• Phase 3: complete
• Phase 4: initial implementation complete
• Phase 5: initial implementation complete
• Phase 6: next milestone

Verification

The release was verified with:

GOCACHE=/tmp/gocache go test ./...

Notable Files

• internal/layers/file_analyzer.go
• internal/layers/tar_extractor.go
• internal/sde/generator.go
• internal/ui/app.go
• internal/models/state.go
• README.md

Next Recommended Step

Phase 6 should focus on user-facing output and scale:

• add JSON, HTML, and CSV report export
• add image comparison workflows
• add batch analysis for multiple images
• add custom policy rule support

BoneStack v0.3.0 - Phase 3 Forensics Stabilization

BoneStack v0.3.0 - Phase 3 Forensics Stabilization

Release Date: April 2, 2026
Status: ✅ Buildable and Tagged
Focus: Container forensics integration, UI wiring, and repo cleanup

---

What's New in v0.3.0

BoneStack v0.3.0 completes the broken Phase 3 handoff and turns the incomplete forensics foundation into a working, testable build. This release does not introduce every planned Phase 3 screen yet, but it restores a coherent backend and TUI path for filesystem, process, volume, and log inspection.

Included in This Release

1. Forensics backend repaired

• Reworked ContainerInspector to match the Docker SDK actually pinned in the repo
• Added working helpers for:
  • container inspect access
  • in-container exec
  • mount lookup
  • log retrieval
• Simplified resource monitoring to a lightweight procfs-based implementation compatible with the current codebase

2. Phase 3 TUI flow enabled

• Added a forensics entry point from container details
• Wired in dedicated screens for:
  • filesystem listing
  • process listing
  • mounted volumes
  • recent logs
• Extended application state to support scrolling and forensics data

3. Repo and release hygiene

• Updated the README to reflect the real project stage
• Marked bonestack as an ignored local build artifact
• Removed the tracked bonestack binary from version control
• Preserved the logo asset in the repository

Current Phase Status

• Phase 1: complete
• Phase 2: complete
• Phase 3: partially complete
  • implemented: filesystem, processes, volumes, logs
  • still pending: dedicated environment screen, dedicated resources screen
• Phase 4-6: unchanged roadmap

Verification

The release was verified with:

GOCACHE=/tmp/gocache go test ./...

Result:

• cmd/bonestack: builds
• internal/layers: tests passing
• internal/ui: compiles cleanly
• internal/forensics: compiles cleanly

Notable Files

• internal/forensics/container_inspector.go
• internal/forensics/resources.go
• internal/ui/app.go
• internal/models/state.go
• README.md
• .gitignore

Next Recommended Step

The next release should focus on UI and test coverage:

• add Environment and Resources screens
• add targeted unit tests for forensics helpers
• add screen/state tests for the forensics flow
• reduce placeholder behavior in the Phase 3 menu

BoneStack v0.2.5 - Tar-Based Layer Inspection

BoneStack v0.2.5 - Tar-Based Layer Inspection

Release Date: April 2, 2026

Overview

Phase 2.5 introduces real file analysis capabilities by extracting and parsing Docker layer tar files directly. This replaces heuristic-based estimation with actual filesystem data, enabling accurate bloat detection, file type analysis, and optimization recommendations.

Major Features

🔍 Tar Extraction Module

• Real tar parsing from Docker layers (both raw and gzip-compressed)
• File metadata extraction: Name, size, type, permissions
• Whiteout file handling: Proper deletion marker detection
• Path normalization: Clean and consistent file paths
• Type classification: file, directory, symlink, hardlink, char device, block device, fifo

📊 File Analysis Engine

• Real file statistics: Actual file counts (not estimates)
• File type distribution: Breakdown by extension
• Directory analysis: Top N largest directories by size
• Language detection: Python, JavaScript, Java, Go, Ruby, C/C++, PHP, Rust, Shell
• Package manager detection: apt, yum, apk, npm, pip, gem, cargo
• Bloat pattern detection: Cache directories, build artifacts, documentation, logs

🧹 Real Bloat Detection

• Actual file scanning instead of pattern matching
• Cache detection: apt cache, npm cache, pip cache, yum cache, apk cache
• Version control: .git directory detection with real size
• Build artifacts: Makefile, object files, debug symbols
• Documentation bloat: Man pages, documentation files
• Confidence scoring: Per-layer accuracy percentage

📁 File Browser UI Screen

• Interactive file details for selected layers
• File statistics: Total files, directories, symlinks
• Large files listing: Top files by size with paths
• Bloat indicators: Detected bloat patterns per layer
• Package listing: Detected packages and languages

💾 Tar Cache System

• Smart caching of extracted tar analysis results
• Cache location: ~/.bonestack/cache/
• Cache keys: Based on image digest and layer ID
• Staleness detection: Time-based cache invalidation
• Cache statistics: View cache size and entry count
• Clear operations: Clear single entries or entire cache

🎯 Enhanced Bloat Detection

• Hybrid approach: Combine pattern-based and tar-based detection
• Language-aware recommendations: Python, Node.js, Java specific advice
• Package manager recommendations: Apt, yum, apk, npm optimization tips
• Multi-stage build suggestions: Based on detected bloat and file counts
• Savings estimation: Real bloat size calculation from tar analysis

Technical Details

New Modules

• internal/layers/tar_extractor.go (308 lines)

  • TarExtractor: Extract and parse tar files
  • LayerTarData: Extracted layer metadata
  • FileEntry: Individual file metadata
  • Path normalization, type classification

• internal/layers/file_analyzer.go (356 lines)

  • FileAnalyzer: Comprehensive file analysis
  • FileAnalysisResult: Complete analysis output
  • Language detection: 8 languages
  • Package manager detection: 7 managers
  • Bloat detection: Cache dirs, build artifacts

• internal/layers/cache.go (196 lines)

  • TarCache: Cache management system
  • CacheEntry: Serializable cache entry
  • JSON-based persistence
  • Cache statistics and staleness detection

• internal/models/state.go (Enhanced)

  • Added LayerTarData[]
  • Added FileAnalysis[]
  • Support for file browser screen

• internal/ui/app.go (Enhanced)

  • File browser screen: renderFileBrowser()
  • Navigation handlers for file browser
  • Integration with tar data

Test Coverage

• 39 total tests (up from 28)
• New tests: 11 cache tests + 28 tar/file analyzer tests
• 100% pass rate: All tests passing
• Coverage areas:
  • Tar extraction (gzip and raw)
  • File type detection
  • File filtering and searching
  • Directory size calculation
  • Extension analysis
  • Language/PM detection
  • Bloat pattern matching
  • Cache operations (set/get/clear)
  • Cache staleness
  • Multi-layer caching

Performance

• Tar parsing: < 1 second for typical layers
• File analysis: < 500ms for large layers
• Cache lookup: < 10ms (instant hits)
• Memory efficient: Only stores essential metadata

Files Changed

• Created: 5 new files (2,183 lines)
  • tar_extractor.go, tar_extractor_test.go
  • file_analyzer.go
  • cache.go, cache_test.go
• Modified: 2 files
  • app.go (added file browser screen and handlers)
  • state.go (extended with tar data fields)

Usage Examples

View Layer File Browser

bonestack
→ Select Image
→ View Layers
→ Select Layer
→ Press 'f' to open File Browser

Shows:

• Real file counts
• Large files list
• Detected bloat patterns
• Installed packages
• Detected languages

Cache Management

Clear a specific layer's cache:

cache, _ := NewTarCache(DefaultCachePath())
cache.Clear(imageDigest, layerID)

Clear all cache:

cache.ClearAll()

Get cache statistics:

stats := cache.GetCacheStats()
// Returns: entries count, total size, cache location

Real Bloat Detection

analyzer := NewFileAnalyzer()
result := analyzer.AnalyzeTarData(tarData)

// Get bloat findings with real sizes
for _, bloat := range result.PotentialBloat {
    fmt.Printf("%s: %d bytes\n", bloat.Path, bloat.Size)
}

// Get optimization recommendations
recommendations := analyzer.GenerateOptimizationRecommendationsFromAnalysis(result)

Improvements Over Phase 2

Aspect	Phase 2	Phase 2.5
File Counting	~5KB heuristic	Real tar extraction
Bloat Detection	Pattern-based	Real file scanning
Accuracy	Estimated	Actual data
Language Detection	None	8 languages
Package Managers	None	7 managers
Cache System	None	Full caching system
File Browser	Size breakdown	File details view

Breaking Changes

None. Phase 2.5 is backward compatible with Phase 2.

Known Limitations

• Docker layer extraction requires local tar files (future: full Docker API integration)
• Cache is local (future: distributed caching option)
• File browser is text-based (future: interactive navigation)
• No real-time layer modification tracking (future: live container monitoring)

Next Steps (Phase 3)

• Container forensics and live inspection
• Network analysis
• Process introspection
• Log streaming and filtering
• Resource usage tracking

Quality Metrics

• Tests: 39/39 passing (100%)
• Build: Clean (0 warnings)
• Binary Size: 11 MB (unchanged)
• Compiler: Go 1.21+
• Architecture: ARM64 (macOS), x86_64

Contributors

• Built with Go + Bubble Tea
• Docker SDK for image inspection
• Tar library for archive parsing

---

BoneStack v0.2.5 - Real file analysis for Docker containers
GitHub: https://github.com/khbarkar/BoneStack