envameleon 0.2.0-universal-mingw

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76320666462ab75a0de8ccec9a4f51f2a0bf5d25342fa798a647c6e53f7c2b66
+  data.tar.gz: b31c3bc6f236daf24c859f43450a794cd6fbcb7d2d42ce44e9eb6f683e0512b5
+SHA512:
+  metadata.gz: 06f34cc1a6b2d3143e56b474d3e5aab7e368259f211dc9db459cf2d60bcdda1d4022ddef2e1df21b87f76bfe0e7b0cb186fa90a264de264a6fbcdeb9944563d1
+  data.tar.gz: ef6f91088ba51fe266904665a77cef33f2b2d54de2773867017a509399a719638f412d3969ae2495bad1e5210a20938a55eb1b45b69488f450fd5c49ee0b9f1d

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmytro Shteflyuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,279 @@
+<a id="readme-top"></a>
+
+<div align="center">
+  <img src="assets/envameleon.png" alt="ENVameleon — Leave no ENVidence." width="800">
+
+  <h1>ENVameleon</h1>
+  <p><strong>Leave no ENVidence.</strong></p>
+  <p>Hide the first process environment shown by Linux without changing Ruby's <code>ENV</code>.</p>
+  <p>
+    <a href="#about">About</a> ·
+    <a href="#getting-started">Get started</a> ·
+    <a href="#usage">Usage</a> ·
+    <a href="#how-it-works">How it works</a> ·
+    <a href="#development">Development</a>
+  </p>
+</div>
+
+## Table of Contents
+
+- [About](#about)
+- [Getting Started](#getting-started)
+- [Native Gems](#native-gems)
+- [Usage](#usage)
+- [How It Works](#how-it-works)
+- [Process Inheritance](#process-inheritance)
+- [Security Limits](#security-limits)
+- [Development](#development)
+- [License](#license)
+
+## About
+
+Linux exposes the environment passed at process start through
+`/proc/self/environ`. ENVameleon lets a Ruby process mask, scrub, or drop that
+view after boot. Ruby's live `ENV` stays intact.
+
+### Why this matters
+
+Suppose your app keeps its credentials in an encrypted file. Your container
+runner passes the unlock key through the process environment. The encrypted
+file may seem safe even if an attacker can read any file that the app can
+access.
+
+Guess again. Linux also exposes `/proc/self/environ` as a file. It may hold the
+unlock key passed at process launch. An attacker who reads both files can
+decrypt the credentials, recover a session signing key, and forge sessions.
+
+ENVameleon removes this copy of the key from the proc view after app boot.
+
+The gem has no runtime dependencies. Loading it does not change anything. Your
+app chooses when to call one of its three methods.
+
+## Getting Started
+
+### Requirements
+
+- CRuby 3.2 or newer
+- Linux for changes to `/proc/self/environ`
+- The Linux `CAP_SYS_RESOURCE` right only for `ENV.drop_proc_data`
+
+On macOS and Windows, all three methods are safe no-ops.
+
+### Installation
+
+Install the gem:
+
+```console
+gem install envameleon
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "envameleon"
+```
+
+Then load it:
+
+```ruby
+require "envameleon"
+```
+
+[Back to top](#readme-top).
+
+## Native Gems
+
+ENVameleon publishes precompiled native gems for its supported CRuby minors on:
+
+- GNU/Linux and musl Linux on x86-64 and AArch64
+
+The macOS and Windows gems contain the documented pure-Ruby no-ops. There is no
+native code to compile on those systems. Linux is split into `-linux-gnu` and
+`-linux-musl` gems so a glibc binary is never mistaken for a musl binary. These
+native gems require RubyGems 3.3.22 or newer; musl users should use Bundler
+2.5.6 or newer.
+
+Each precompiled Linux gem contains a separate binary for every supported Ruby
+minor and has no extension build hook. When Linux runs a newer Ruby API,
+RubyGems or Bundler selects the generic source gem instead. That gem runs
+`extconf.rb` and requires a C compiler, Make, and the Ruby headers. macOS and
+Windows continue to select their compiler-free no-op gems. If neither a native
+nor source fallback applies on Linux, `require "envameleon"` fails closed
+instead of silently exposing the process environment.
+
+Every GitHub release includes the gems and `SHA256SUMS`. Release gems also have
+GitHub build-provenance attestations, which can be checked with:
+
+```console
+gh attestation verify envameleon-0.2.0-x86_64-linux-gnu.gem --repo kpumuk/envameleon
+```
+
+[Back to top](#readme-top).
+
+## Usage
+
+```ruby
+require "envameleon"
+
+ENV.mask_proc_data
+# SECRET=example becomes SECRET=e*****e in /proc/self/environ
+
+ENV.scrub_proc_data
+# /proc/self/environ now holds only NUL bytes
+
+ENV.drop_proc_data
+# /proc/self/environ is now zero bytes long
+```
+
+| Method | Result in `/proc/self/environ` | File length | Permissions |
+| --- | --- | --- | --- |
+| `ENV.mask_proc_data` | Names plus the first and last value byte | Unchanged | None |
+| `ENV.scrub_proc_data` | NUL bytes | Unchanged | None |
+| `ENV.drop_proc_data` | Empty | Zero | `CAP_SYS_RESOURCE` |
+
+Choose the least power you need.
+
+> [!IMPORTANT]
+> `ENV.drop_proc_data` requires `CAP_SYS_RESOURCE` on Linux. Without it, the
+> method raises `Errno::EPERM`.
+
+Masking works on raw bytes, not characters. It replaces all value bytes except
+the first and last with `*`. Values shorter than three bytes stay unchanged.
+
+[Back to top](#readme-top).
+
+## How It Works
+
+CRuby moves its active environment during startup. Linux still keeps the old
+range used by `/proc/self/environ`. ENVameleon reads that range from
+`/proc/self/stat`.
+
+Masking and scrubbing first check that Ruby no longer uses the old range. They
+then change those bytes in place. If Ruby still uses any of them, the method
+raises an error and changes nothing.
+
+Dropping uses `PR_SET_MM_ENV_END` to move the end of the kernel's view to its
+start. This makes `/proc/self/environ` truly zero-length. Linux requires the
+`CAP_SYS_RESOURCE` right for that call.
+
+## Process Inheritance
+
+Call a method before `fork` and each child inherits the changed proc view. Ruby
+`ENV` remains available in the parent and children. The test suite checks this
+with a second fork for all three methods.
+
+`spawn`, `system`, and `exec` are different. They give the new program a fresh
+proc environment. That program must load ENVameleon and call a method itself.
+
+### Forking servers
+
+You may call a method in the parent before it forks. You may also call it from a
+worker boot hook. These examples use scrubbing, which needs no extra right.
+
+#### Unicorn
+
+```ruby
+require "envameleon"
+
+after_fork do |_server, _worker|
+  ENV.scrub_proc_data
+end
+```
+
+#### Puma
+
+Use `before_worker_boot` for cluster workers. In single mode, call the method
+during app boot.
+
+```ruby
+require "envameleon"
+
+before_worker_boot do
+  ENV.scrub_proc_data
+end
+```
+
+#### Sidekiq
+
+Standard Sidekiq uses threads. Its startup hook runs before work begins. Sidekiq
+Enterprise Swarm runs the hook in each child.
+
+```ruby
+require "envameleon"
+
+Sidekiq.configure_server do |config|
+  config.on(:startup) { ENV.scrub_proc_data }
+end
+```
+
+#### Karafka
+
+The `app.running` event runs in the server process. In Swarm mode, it runs in
+each forked node.
+
+```ruby
+require "envameleon"
+
+Karafka::App.monitor.subscribe("app.running") do
+  ENV.scrub_proc_data
+end
+```
+
+If a child calls `ENV.drop_proc_data`, it must still have the needed Linux right.
+
+[Back to top](#readme-top).
+
+## Security Limits
+
+> [!WARNING]
+> **`CAP_SYS_RESOURCE` grants broad powers outside ENVameleon.**
+>
+> `ENV.drop_proc_data` needs this Linux capability. Grant it only if you accept
+> its wider access. Masking and scrubbing do not need it.
+
+ENVameleon changes only what `/proc/self/environ` shows. It does not erase every
+copy of a secret. It gives no protection from memory disclosure, debuggers, or
+core dumps.
+
+Dropping leaves the old bytes in memory. Masking keeps variable names and the
+outer bytes of each value. Short values remain fully visible. Scrubbing
+overwrites the old proc range, but a secret may still exist elsewhere.
+
+[Back to top](#readme-top).
+
+## Development
+
+Install the checksum-locked development bundle and run the `test/unit` suite.
+The test task compiles the extension on Linux and exercises the pure-Ruby no-ops
+elsewhere:
+
+```console
+bundle install
+bundle exec rake test
+```
+
+On Linux, the drop test runs when `CAP_SYS_RESOURCE` is available. Otherwise,
+that one test is omitted.
+
+Build the macOS and Windows no-op gems and the Linux source fallback with:
+
+```console
+bundle exec rake gem
+```
+
+Native builds run inside the versioned image selected by the
+checksum-locked `rake-compiler-dock` gem. The image installs the exact Bundler
+version recorded in `Gemfile.lock`; Bundler then validates its own locked
+checksum and installs every other dependency from the prepared local cache:
+
+```console
+bundle cache --all-platforms
+bundle exec rake gem:x86_64-linux-gnu
+ruby .github/scripts/verify_native_gem.rb pkg/envameleon-0.2.0-x86_64-linux-gnu.gem x86_64-linux-gnu
+```
+
+## License
+
+Distributed under the MIT License. See `LICENSE.txt`.
+
+[Back to top](#readme-top).

data/lib/envameleon/noop.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+ENV.define_singleton_method(:scrub_proc_data) { nil }
+ENV.define_singleton_method(:mask_proc_data) { nil }
+ENV.define_singleton_method(:drop_proc_data) { nil }

data/lib/envameleon.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+ruby_api_version = RUBY_VERSION[/\A\d+\.\d+/]
+native_extension = File.expand_path(
+  "envameleon/#{ruby_api_version}/envameleon.#{RbConfig::CONFIG.fetch("DLEXT")}",
+  __dir__
+)
+development_extension = File.expand_path(
+  "envameleon/envameleon.#{RbConfig::CONFIG.fetch("DLEXT")}",
+  __dir__
+)
+
+if RbConfig::CONFIG.fetch("host_os").include?("linux")
+  extension = [native_extension, development_extension].find { |path| File.file?(path) }
+  if extension
+    require extension
+  else
+    begin
+      require "envameleon/envameleon"
+    rescue LoadError => error
+      raise unless error.path == "envameleon/envameleon"
+
+      raise LoadError, "ENVameleon has no native extension for Ruby #{ruby_api_version} on #{RUBY_PLATFORM}"
+    end
+  end
+else
+  require_relative "envameleon/noop"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: envameleon
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: universal-mingw
+authors:
+- Dmytro Shteflyuk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+- !ruby/object:Gem::Dependency
+  name: rake-compiler-dock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+description: Scrub, mask, or drop Linux's /proc/self/environ view without changing
+  Ruby's ENV.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/envameleon.rb
+- lib/envameleon/noop.rb
+homepage: https://github.com/kpumuk/envameleon
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/kpumuk/envameleon/issues
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kpumuk/envameleon
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Leave no ENVidence.
+test_files: []