bootprint 0.2.0

data/ROADMAP.md

@@ -0,0 +1,15 @@
+# Roadmap
+
+## 0.2 — Environment Intelligence Engine
+
+Schema v2, structured diagnosis, policy, Rails profiling, Docker inspection, CI reports, plugins, and privacy auditing.
+
+## Next
+
+- Validate rule behavior across more real JRuby and TruffleRuby applications.
+- Add opt-in offline advisory metadata bundles for unavailable/yanked gems.
+- Improve libc and native-client precision without adding capture-time network access.
+- Publish companion plugins for PostgreSQL, Redis, Sidekiq, and Nokogiri.
+- Stabilize schema migration guarantees before 1.0.
+
+Bootprint will remain a CLI/library—not a hosted dashboard, deployment platform, observability agent, or secret manager.

data/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Security fixes |
+|---|---|
+| 0.2.x | Supported |
+| 0.1.x | Upgrade to 0.2.x |
+
+Until 1.0, security fixes are released on the latest minor line. Older snapshots remain readable when the documented in-memory migration path supports them.
+
+## Data model
+
+Bootprint never reads or stores environment-variable values. It records only selected names with boolean presence. It avoids dumping Rails credentials, database configuration values, authorization headers, command output, complete application files, or arbitrary process memory. Known application-root and home-directory prefixes are replaced with `<APP_ROOT>` and `<HOME>`.
+
+Recursive sanitization detects secret-like field names, credential-bearing URLs, private keys, JWT-like strings, authorization fields, and high-entropy token-like values. Digest and checksum fields are safely distinguished from secrets. Strict privacy mode additionally anonymizes hostname-like strings.
+
+Snapshots can still reveal operational metadata, including:
+
+- gem and native-library versions
+- platform and operating-system details
+- selected environment-variable names
+- Rails adapter and load-path information
+
+Treat `bootprint.lock` as ordinary internal project metadata and review it before making it public. Use `ignored_environment_names` for a name that should never appear:
+
+```ruby
+Bootprint.configure do |config|
+  config.ignored_environment_names << "INTERNAL_CUSTOMER_CODENAME"
+end
+```
+
+## Trust boundaries
+
+- Snapshot files are parsed strictly as JSON and never evaluated.
+- Policy files use safe YAML loading with aliases and arbitrary classes disabled.
+- Rule plugins are executable Ruby code. Install and register them only from trusted gems.
+- Bootprint does not upload snapshots, enable telemetry, open ports, or execute Docker commands.
+- Capability detection examines executable file presence on `PATH`; it does not run those executables.
+
+Docker commands are the explicit exception to the last point: they invoke only Docker, verify that the requested image exists locally, and create a fixed-script `--rm --read-only --network none` temporary container. Bootprint never inspects unrelated running containers.
+
+Run `bootprint security audit bootprint.lock` before sharing a snapshot outside your organization.
+
+## Reporting vulnerabilities
+
+Please use [GitHub private vulnerability reporting](https://github.com/theworker02/bootprint/security/advisories/new) or email `security@magnexis.com`. Do not open a public issue or include real credentials or production snapshots. Include the affected Bootprint version, operating system, Ruby engine, sanitized reproduction, and expected impact. Expect acknowledgement within seven days.

data/assets/branding/README.md

@@ -0,0 +1,24 @@
+# Bootprint brand assets
+
+The Bootprint mark combines a fingerprint with a letter `B`. The interrupted blue path represents an environment difference being isolated from a reproducible runtime fingerprint.
+
+## Files
+
+| File | Intended use |
+|---|---|
+| `bootprint-logo.png` | 1024 px transparent master for documentation and release artwork |
+| `bootprint-logo-512.png` | README, repository, and package artwork |
+| `bootprint-logo-128.png` | Example packages and compact documentation headers |
+| `bootprint-logo-64.png` | Small UI and documentation placements |
+
+## Palette
+
+| Role | Color |
+|---|---|
+| Ruby/runtime signal | `#CC342D` |
+| Diagnostic/drift signal | `#3977F6` |
+| Structure | `#171A21` |
+
+Keep the mark's aspect ratio, preserve clear space around it, and use the transparent PNG on a plain light or dark surface. Do not recolor individual paths, add effects, or place the mark over visually noisy imagery.
+
+These assets are distributed with Bootprint under the repository license.

data/docs/capturing.md

@@ -0,0 +1,9 @@
+# Capturing environments
+
+`bootprint capture` writes `bootprint.lock`; `bootprint capture local` writes `.bootprint/local.json`. Use `--output`, `--env NAME`, `--required-env NAME`, and `--privacy strict` to control the capture.
+
+The snapshot includes runtime, dependency, native-library, configuration, filesystem, and OS facts. Values of environment variables are never read into the snapshot. `--all-env` records all names and should be used deliberately because names reveal infrastructure vocabulary.
+
+Capture performs no network requests and modifies no application files. It may create only the requested output file. Docker capture is a separate, explicit command.
+
+Strict privacy removes application/home path prefixes and anonymizes hostname-like strings. Run `bootprint security audit PATH` before external sharing.

data/docs/ci.md

@@ -0,0 +1,21 @@
+# CI integration
+
+Use the same committed `bootprint.lock` in generic POSIX CI, GitLab CI, CircleCI, or GitHub Actions:
+
+```yaml
+name: Bootprint
+on: [pull_request, push]
+jobs:
+  environment-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: bundle exec bootprint ci verify --against bootprint.lock
+```
+
+GitHub Actions receives workflow annotations and Markdown appended to `GITHUB_STEP_SUMMARY`. SARIF output is compatible with GitHub code scanning when uploaded by the workflow. Bootprint does not upload reports itself.
+
+GitLab, CircleCI, and generic CI receive stable console output and exit codes. CI provider detection uses standard environment-variable presence, not secret values.

data/docs/comparing.md

@@ -0,0 +1,22 @@
+# Comparing environments and understanding findings
+
+Use `bootprint diff SOURCE TARGET` for a complete raw comparison. Use `bootprint diagnose SOURCE TARGET` for compatibility intelligence.
+
+Findings have four severities:
+
+- `info`: useful context with negligible direct risk
+- `warning`: likely drift that deserves review
+- `error`: behavior or installation is likely to fail
+- `critical`: boot, security, or binary compatibility is at immediate risk
+
+Each finding contains a stable rule ID, category, cause, impact, evidence, remediation, optional commands/files, references, and suppression status. `--minimum-severity` controls presentation; policy `fail_on` controls exit code.
+
+## macOS Rails to Linux container
+
+```console
+bootprint capture macos-development
+bootprint docker capture registry.example/myapp:latest --output .bootprint/linux-production.json
+bootprint diagnose macos-development linux-production --only runtime,dependencies,native,configuration
+```
+
+A native `nokogiri` Darwin variant produces a critical platform finding with `bundle lock --add-platform x86_64-linux`. A local-only `REDIS_URL` produces an error without revealing its value. Case sensitivity appears as a warning.

data/docs/custom-rules.md

@@ -0,0 +1,7 @@
+# Writing custom rules
+
+Define rules after requiring `bootprint`. Rules receive source and target schema-v2 `environment` objects; a third argument receives the active policy.
+
+Detection returns `false`/`nil` for no finding, `true` for a finding without custom evidence, or a hash containing evidence. Explanation returns `summary`, `cause`, `impact`, `evidence`, and optional `source_location`. Remediation is always structured and preview-only.
+
+Rule IDs are global and later definitions replace earlier rules with the same ID, allowing an application to intentionally customize built-ins. Prefer namespaced IDs for third-party packages. Test rules against fixture snapshots without requiring Rails.

data/docs/docker.md

@@ -0,0 +1,7 @@
+# Docker support
+
+`bootprint docker capture IMAGE` and `bootprint docker diagnose IMAGE --against SNAPSHOT` inspect an image already present locally. Bootprint never pulls an absent image.
+
+The temporary container uses `--rm`, `--read-only`, `--network none`, and a fixed Ruby inspection script. No port is required. The container reports Ruby/gem/platform data, native libraries, installed dpkg/apk package names when available, working-directory permissions, and image entrypoint/command metadata.
+
+The image must contain a working `ruby` executable. Docker errors are returned as exit code 4 with sanitized stderr. Bootprint never lists or inspects unrelated running containers.

data/docs/findings.md

@@ -0,0 +1,7 @@
+# Understanding findings
+
+Human reports prioritize critical findings, then errors, warnings, and information. JSON and SARIF preserve the same order and stable IDs.
+
+Evidence contains captured metadata only. Remediation commands use placeholders such as `<target-platform>` when Bootprint cannot safely infer an exact command. Commands are preview text and are never passed to a shell.
+
+Suppressed findings remain in machine-readable output with `suppressed: true` and a reason. They do not block CI. Prefer narrow rule suppression over raising the global minimum severity.

data/docs/installation.md

@@ -0,0 +1,7 @@
+# Installation
+
+Bootprint supports MRI Ruby 3.1+ and is designed to degrade safely on JRuby. Install globally with `gem install bootprint`, or add `gem "bootprint", require: false` to development and test groups and run `bundle install`.
+
+The core gem has no runtime dependencies. Docker support requires a local Docker CLI and running daemon. Rails inspection requires Rails to load Bootprint during application boot.
+
+Verify the installation with `bootprint version` and `bootprint doctor`.

data/docs/maintainer-setup.md

@@ -0,0 +1,54 @@
+# GitHub and RubyGems maintainer setup
+
+This checklist covers settings that cannot be represented completely by committed files. Apply it after creating `theworker02/bootprint` and before publishing the first gem.
+
+## Repository profile
+
+- Description: `Diagnose why Ruby environments work locally but fail in CI, Docker, staging, or production.`
+- Website: `https://rubygems.org/gems/bootprint`
+- Topics: `ruby`, `rails`, `bundler`, `rubygems`, `docker`, `ci`, `diagnostics`, `reproducibility`, `developer-tools`
+- Default branch: `main`
+- Social preview: `assets/branding/bootprint-logo-512.png`
+- Enable Issues and Discussions; disable the wiki unless maintainers intend to support it.
+
+## Ruleset for `main`
+
+- Require pull requests and at least one approving review.
+- Dismiss stale approvals when new commits are pushed.
+- Require conversation resolution.
+- Require the four focused CI compatibility checks.
+- Require branches to be up to date before merging.
+- Block force pushes and branch deletion.
+- Restrict bypass permission to release maintainers.
+- Add a tag ruleset protecting `v*` from deletion or update.
+
+CodeQL runs weekly or on explicit maintainer request rather than adding another check to every pull request.
+
+## Actions and security
+
+- Allow GitHub-authored actions plus `ruby/setup-ruby` and `rubygems/release-gem`.
+- Keep the default workflow token read-only; grant write permissions only inside the release job.
+- Enable the dependency graph, Dependabot alerts, Dependabot security updates, secret scanning, and push protection.
+- Review and merge Dependabot updates rather than enabling unattended auto-merge.
+- Enable private vulnerability reporting and repository security advisories.
+- Retain Actions logs long enough to investigate releases, without treating logs as a secret store.
+
+## Release environment
+
+Create an environment named `release`:
+
+- Require approval from a release maintainer.
+- Allow deployment only from tags matching `v*`.
+- Do not add `RUBYGEMS_API_KEY`; trusted publishing uses OIDC.
+- Do not expose unrelated organization secrets to the workflow.
+
+Then create the RubyGems trusted publisher described in [RELEASE.md](../RELEASE.md). The repository owner, repository name, workflow filename, and environment must match exactly.
+
+## First-publication checklist
+
+- Confirm `gem search --remote --exact bootprint` still returns no existing gem.
+- Confirm the repository URLs and `hello@magnexis.com`, `security@magnexis.com`, and `conduct@magnexis.com` mailboxes are controlled and monitored.
+- Confirm the name and copyright holder in `LICENSE` are intentional.
+- Run `bundle exec rake release_check` from a clean checkout.
+- Review the packaged file list and installed CLI behavior.
+- Push `main`, wait for every required check, then create the signed `v0.2.0` tag.

data/docs/plugins.md

@@ -0,0 +1,7 @@
+# Creating plugins
+
+Plugin gems should use names such as `bootprint-sidekiq` or `bootprint-redis`, call `Bootprint::Plugin.api_version "1"`, and register a stable plugin name.
+
+Collectors return JSON-safe data and must not return secrets. Bootprint applies recursive sanitization regardless. Rules modules respond to `.install` or `.register` and use the ordinary rule DSL.
+
+One plugin exception becomes a warning stored in `capture.warnings`; other collectors continue. Strict policy converts plugin failures into capture failures. Plugins are executable Ruby code and must be installed only from trusted sources.

data/docs/policy.md

@@ -0,0 +1,9 @@
+# Policy configuration
+
+`.bootprint.yml` uses policy schema version 1. Validate it with `bootprint policy validate` and explain effective controls with `bootprint policy explain`.
+
+`mode: permissive` reports information and blocks errors/critical findings by default. `mode: strict` reports warnings and blocks warnings/errors/critical findings. Explicit `minimum_severity` and `fail_on` override these defaults.
+
+Rules accept `enabled: false` and `severity`. `ignore` suppresses known rule IDs. `allow.environment_variables` declares optional names. `expected_platforms` drives lockfile-platform checks. `redaction.patterns` extends built-in secret-name patterns, while `redaction.safe_list` narrowly exempts known non-secret field names. Plugin failures block only in strict mode or when `plugins.strict: true`.
+
+YAML is safe-loaded with aliases and arbitrary Ruby classes disabled. Syntax and semantic errors include absolute file paths and line numbers when identifiable.

data/docs/privacy.md

@@ -0,0 +1,7 @@
+# Privacy and redaction
+
+Bootprint uses data minimization first: it does not collect environment-variable values, Rails credentials, full URLs, cookies, sessions, request data, or arbitrary files.
+
+Recursive defense-in-depth redaction handles secret field names, authorization fields, private-key markers, JWT-like strings, high-entropy token-like strings, database/URL credentials, application roots, and user-home paths. Checksum fields are explicitly safe-listed. Strict privacy anonymizes hostname-like values.
+
+Project redaction patterns add organization-specific secret vocabulary. A narrow `redaction.safe_list` can exempt a known non-secret field name; values still pass value-based sanitization. Use `bootprint security audit` to inspect a stored snapshot.

data/docs/quick-start.md

@@ -0,0 +1,9 @@
+# Five-minute quick start
+
+1. Run `bundle exec bootprint capture local` on the working environment.
+2. Run `bundle exec bootprint capture production` in the failing environment, or copy the local capture into CI and run `bootprint diagnose --against bootprint.lock` there.
+3. Run `bundle exec bootprint diagnose local production`.
+4. Review each finding's evidence and suggested command. Bootprint never executes remediation.
+5. Copy `.bootprint.yml.example` to `.bootprint.yml`, declare intentional differences, and use `bootprint ci verify`.
+
+Named captures resolve from `.bootprint/NAME.json`, so `local` and `production` can be used instead of full paths.

data/docs/rails.md

@@ -0,0 +1,13 @@
+# Rails integration
+
+Load Bootprint during Rails boot to register `bootprint:capture` and `bootprint:doctor` tasks. Set `BOOTPRINT_INSPECT=1` to observe configuration initializer order without full profiling.
+
+```console
+BOOTPRINT_INSPECT=1 bin/rails bootprint:capture
+BOOTPRINT_OUTPUT=.bootprint/staging.json bin/rails bootprint:capture
+bin/rails bootprint:doctor
+```
+
+Set `BOOTPRINT_PROFILE_BOOT=1` for initializer duration, start/completion order, exception metadata, newly loaded constant names, and heuristic network-call observation. The heuristic is intentionally conservative and can report false positives; it does not intercept or block calls.
+
+Bootprint captures adapter names and boolean/presence metadata. It never serializes credentials, database passwords, URLs, cookies, sessions, message contents, or application user data.

data/docs/snapshot-schema.md

@@ -0,0 +1,9 @@
+# Snapshot schema v2
+
+Every snapshot contains `schema_version`, `generated_at`, `bootprint_version`, `environment`, and optional `capture`/`extensions` metadata. `environment` contains `name`, `runtime`, `dependencies`, `native_libraries`, `configuration`, `filesystem`, and `operating_system` objects.
+
+Keys are recursively sorted. Scalar arrays are sorted; ordered object arrays such as Rails initializers retain capture order. `generated_at`, Bootprint version, capture duration, warnings, and environment labels do not participate in raw environment equality.
+
+Schema v1 is migrated in memory. Unknown v1 top-level fields move to `extensions`. Future schemas fail with an instruction to upgrade. `snapshot migrate` always writes a new file unless an explicit output path is selected; it does not overwrite the source by default.
+
+Diagnosis JSON uses its own report schema version 1 so snapshot and report evolution remain independent.

data/docs/troubleshooting.md

@@ -0,0 +1,8 @@
+# Troubleshooting
+
+- **Docker unavailable:** verify `docker version` succeeds and that the requested image exists locally. Bootprint does not pull it.
+- **Initializer list empty:** load Bootprint before Rails initializes and set `BOOTPRINT_INSPECT=1` or `BOOTPRINT_PROFILE_BOOT=1`.
+- **Missing environment-variable finding absent:** declare the name with `--required-env`, application configuration, or policy context. Bootprint cannot infer an absent arbitrary name.
+- **Unexpected lockfile platform error:** declare actual deployment targets under `expected_platforms` and run `bundle lock --add-platform` deliberately.
+- **Policy error:** run `bootprint policy validate`; the error includes the policy path and best-known line.
+- **Internal details needed:** set `BOOTPRINT_DEBUG=1` for a stack trace. Review output before sharing because diagnostics may contain local metadata.

data/exe/bootprint

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bootprint/cli"
+
+exit Bootprint::CLI.start

data/lib/bootprint/analysis.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Backward-compatible facade for the 0.1 API.
+module Bootprint
+  class Analysis
+    def initialize(source, target, allowed_paths: [])
+      policy_data = allowed_paths.empty? ? {} : { "allow" => { "paths" => allowed_paths } }
+      @diagnosis = Diagnosis.new(source, target, policy: Policy.new(nil, policy_data))
+    end
+
+    def results = @diagnosis.run.findings
+  end
+end