envameleon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71067c7187ac66066961bb5ae52346bdfa7dd72a11b7506b25f728ac4c81a64d
+  data.tar.gz: d1dc5952b9fb0c501750c0655d905792b9bafe45a31c9a21af7f5ffe0b58cbdf
+SHA512:
+  metadata.gz: b6492dd83fabd4f3d3e261bb4fcfa4fc16ee15c9d0c6f688b282b5a089dc4fff3512480904c32800ef6c9c7115e9c4d739f24ac2195587458b1a9d832feab392
+  data.tar.gz: c98a6dd250a633190cd3326a8f425d62902023e8855982db5430c33b7844a22a9e21e29586b221326a3070345910c84f5a8916ca5879f9149aa2cf1f76b62fef

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,237 @@
+<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)
+- [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 other systems, 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).
+
+## 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
+
+Build the native extension and run the `test/unit` suite:
+
+```console
+ruby -Cext/envameleon extconf.rb
+make -C ext/envameleon
+ruby -Ilib -Iext test/test_envameleon.rb
+```
+
+On Linux, the drop test runs when `CAP_SYS_RESOURCE` is available. Otherwise,
+that one test is omitted.
+
+Build the gem with:
+
+```console
+gem build envameleon.gemspec
+```
+
+## License
+
+Distributed under the MIT License. See `LICENSE.txt`.
+
+[Back to top](#readme-top).

data/ext/envameleon/envameleon.c

@@ -0,0 +1,166 @@
+#include <ruby.h>
+
+#ifdef __linux__
+#include <errno.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <linux/prctl.h>
+
+static void
+read_env_range(unsigned long *env_start, unsigned long *env_end)
+{
+    char stat[4096];
+    char *field;
+    char *end;
+    FILE *file = fopen("/proc/self/stat", "r");
+    int number;
+
+    if (file == NULL)
+        rb_sys_fail("fopen(/proc/self/stat)");
+
+    if (fgets(stat, sizeof(stat), file) == NULL) {
+        int error = errno;
+        fclose(file);
+        if (error != 0) {
+            errno = error;
+            rb_sys_fail("fgets(/proc/self/stat)");
+        }
+        rb_raise(rb_eRuntimeError, "empty /proc/self/stat");
+    }
+    fclose(file);
+
+    field = strrchr(stat, ')');
+    if (field == NULL || field[1] != ' ')
+        rb_raise(rb_eRuntimeError, "invalid /proc/self/stat");
+    field += 2;
+
+    for (number = 3; number < 50; number++) {
+        field = strchr(field, ' ');
+        if (field == NULL)
+            rb_raise(rb_eRuntimeError, "missing env_start in /proc/self/stat");
+        field++;
+    }
+
+    errno = 0;
+    *env_start = strtoul(field, &end, 10);
+    if (errno != 0 || end == field || *env_start == 0)
+        rb_raise(rb_eRuntimeError, "invalid env_start in /proc/self/stat");
+
+    field = end;
+    errno = 0;
+    *env_end = strtoul(field, &end, 10);
+    if (errno != 0 || end == field || *env_end < *env_start)
+        rb_raise(rb_eRuntimeError, "invalid env_end in /proc/self/stat");
+}
+
+static void
+ensure_environment_is_detached(unsigned long env_start, unsigned long env_end)
+{
+    extern char **environ;
+    char **entry;
+
+    for (entry = environ; entry != NULL && *entry != NULL; entry++) {
+        uintptr_t address = (uintptr_t)*entry;
+
+        if (address >= env_start && address < env_end)
+            rb_raise(rb_eRuntimeError, "Ruby ENV overlaps /proc/self/environ");
+    }
+}
+
+static VALUE
+scrub_proc_data(VALUE environment)
+{
+    unsigned long env_start;
+    unsigned long env_end;
+
+    (void)environment;
+    read_env_range(&env_start, &env_end);
+    ensure_environment_is_detached(env_start, env_end);
+    memset((void *)env_start, 0, env_end - env_start);
+    return Qnil;
+}
+
+static VALUE
+mask_proc_data(VALUE environment)
+{
+    unsigned long env_start;
+    unsigned long env_end;
+    char *entry;
+
+    (void)environment;
+    read_env_range(&env_start, &env_end);
+    ensure_environment_is_detached(env_start, env_end);
+
+    for (entry = (char *)env_start; entry < (char *)env_end;) {
+        size_t remaining = (char *)env_end - entry;
+        char *terminator = memchr(entry, '\0', remaining);
+        char *equals;
+        char *value;
+        size_t value_length;
+
+        if (terminator == NULL)
+            rb_raise(rb_eRuntimeError, "invalid environment data");
+
+        equals = memchr(entry, '=', terminator - entry);
+        if (equals != NULL) {
+            value = equals + 1;
+            value_length = terminator - value;
+            if (value_length > 2)
+                memset(value + 1, '*', value_length - 2);
+        }
+
+        entry = terminator + 1;
+    }
+
+    return Qnil;
+}
+
+static VALUE
+drop_proc_data(VALUE environment)
+{
+    unsigned long env_start;
+    unsigned long env_end;
+
+    (void)environment;
+    read_env_range(&env_start, &env_end);
+    if (prctl(PR_SET_MM, PR_SET_MM_ENV_END, env_start, 0L, 0L) == -1)
+        rb_sys_fail("prctl(PR_SET_MM_ENV_END)");
+
+    return Qnil;
+}
+#else
+static VALUE
+scrub_proc_data(VALUE environment)
+{
+    (void)environment;
+    return Qnil;
+}
+
+static VALUE
+mask_proc_data(VALUE environment)
+{
+    (void)environment;
+    return Qnil;
+}
+
+static VALUE
+drop_proc_data(VALUE environment)
+{
+    (void)environment;
+    return Qnil;
+}
+#endif
+
+void
+Init_envameleon(void)
+{
+    ID environment_id = rb_intern2("ENV", 3);
+    VALUE environment = rb_const_get(rb_cObject, environment_id);
+
+    rb_define_singleton_method(environment, "scrub_proc_data", scrub_proc_data, 0);
+    rb_define_singleton_method(environment, "mask_proc_data", mask_proc_data, 0);
+    rb_define_singleton_method(environment, "drop_proc_data", drop_proc_data, 0);
+}

data/ext/envameleon/extconf.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+create_makefile("envameleon/envameleon")

data/lib/envameleon.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ENVameleon
+  VERSION = "0.1.0"
+end
+
+require "envameleon/envameleon"

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: envameleon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dmytro Shteflyuk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Scrub, mask, or drop Linux's /proc/self/environ view without changing
+  Ruby's ENV.
+executables: []
+extensions:
+- ext/envameleon/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- assets/envameleon.png
+- ext/envameleon/envameleon.c
+- ext/envameleon/extconf.rb
+- lib/envameleon.rb
+licenses:
+- MIT
+metadata: {}
+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: 3.6.9
+specification_version: 4
+summary: Leave no ENVidence.
+test_files: []