lockfile_audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f02ad30c5d73027023967b15462cf39489383751cd89acb440fb0c6eb993e70
+  data.tar.gz: a4d6a9fbd40231af0c64935759faf225f5891bb93a617723cc540bd1adacd2c2
+SHA512:
+  metadata.gz: 7c0fc2776fe8bc32ae760225ac8d76ed805dc8e839fb85fb27d60aae31894608a41b6f341eecdef0e396149a7bc4bd8da7cf136ea79a782e53e73b018c73bbb9
+  data.tar.gz: 6b62f3b0e60043aa76e4bc771adb14082df5f36f6a2afe34f621dbc299b7f1bdc59852666e855f0c1bf6548e1442cd3468b5065cbbc80a2558b6b5b96f2ca03b

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- `LockfileAudit.report` returns a JSON-ready Hash with `generated_at`,
+  `packages` (from `Gemfile.lock`), and `audit.vulnerabilities`
+  (from `bundler-audit`).
+- `LockfileAudit::PackageCollector` parses every `specs:` block in a
+  `Gemfile.lock`, collecting top-level gems with their resolved versions.
+- `LockfileAudit::VulnerabilityCollector` normalizes `bundle-audit
+  check --format json` output, tolerating both the Array and
+  Hash-with-`results` schema shapes.
+- `LockfileAudit::Report` assembles the final payload and stamps
+  `generated_at` in ISO 8601 UTC.
+- Support for passing pre-computed audit JSON via the `audit_json:`
+  keyword, so `bundler-audit` need not be installed or invoked.
+- `LockfileAudit::Errors` namespace with `LockfileNotFound`,
+  `BundlerAuditNotInstalled`, and `InvalidAuditJson`.
+
+[Unreleased]: https://github.com/Behnam1369/lockfile_audit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Behnam1369/lockfile_audit/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 behnam1369
+
+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,132 @@
+# LockfileAudit
+
+Returns a JSON package inventory plus vulnerability audit data for a Ruby
+project, in a single payload.
+
+`lockfile_audit` parses a `Gemfile.lock` for the resolved gem list and pairs it
+with findings from [bundler-audit](https://github.com/rubysec/bundler-audit).
+The result is a plain, JSON-ready Hash you can expose from a Rails endpoint,
+feed into a dashboard, or archive for compliance.
+
+## Installation
+
+Add it to your Gemfile:
+
+    gem "lockfile_audit"
+
+Then run `bundle install`.
+
+To collect vulnerability data, `bundler-audit` must be available on your
+PATH:
+
+    gem install bundler-audit
+    bundle-audit update   # fetch the advisory database
+
+If you would rather manage that step yourself, you can pass pre-computed
+audit JSON instead — see Usage.
+
+## Usage
+
+### Basic
+
+    require "lockfile_audit"
+
+    LockfileAudit.report(gemfile_lock_path: "Gemfile.lock")
+
+This returns:
+
+    {
+      "generated_at": "2026-09-26T11:09:28Z",
+      "packages": [
+        { "name": "rails", "version": "7.1.3" },
+        { "name": "nokogiri", "version": "1.16.2" },
+        { "name": "pg", "version": "1.5.6" }
+      ],
+      "audit": {
+        "vulnerabilities": [
+          {
+            "gem": "nokogiri",
+            "version": "1.16.2",
+            "criticality": "High",
+            "description": "Nokogiri Command Injection Vulnerability"
+          }
+        ]
+      }
+    }
+
+### Passing pre-computed audit JSON
+
+If you already run `bundle-audit` in your own CI pipeline, or want to avoid
+shelling out at request time, pass its JSON output directly:
+
+    audit_json = File.read("tmp/bundle-audit.json")
+
+    LockfileAudit.report(
+      gemfile_lock_path: "Gemfile.lock",
+      audit_json: audit_json
+    )
+
+When `audit_json:` is provided, `lockfile_audit` does not invoke
+`bundler-audit` at all.
+
+### From a Rails controller
+
+    class PackageAuditController < ApplicationController
+      def show
+        render json: LockfileAudit.report(
+          gemfile_lock_path: Rails.root.join("Gemfile.lock").to_s
+        )
+      end
+    end
+
+## Payload schema
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `generated_at` | String | ISO 8601 UTC timestamp, e.g. `"2026-09-26T11:09:28Z"` |
+| `packages` | Array | Sorted by `name`; each entry has `name` and `version` |
+| `audit` | Hash | Contains a single `vulnerabilities` key |
+| `audit.vulnerabilities` | Array | Each entry has `gem`, `version`, `criticality`, and `description` |
+
+All keys are symbols when you consume the Hash in Ruby, and strings when
+serialized to JSON. `description` falls back to the advisory title when no
+longer description is available.
+
+## Errors
+
+All errors inherit from `LockfileAudit::Errors::Error`.
+
+| Error | Raised when |
+|-------|-------------|
+| `LockfileNotFound` | The `Gemfile.lock` file does not exist at the given path |
+| `BundlerAuditNotInstalled` | `bundle-audit` is not on `PATH` and no `audit_json:` was passed |
+| `InvalidAuditJson` | The supplied audit JSON cannot be parsed |
+
+## How it works
+
+- Packages are read from the `specs:` blocks of `Gemfile.lock`. Only
+  top-level specs are collected; transitive dependency lines (which carry a
+  version constraint rather than a resolved version) are ignored.
+- Vulnerabilities come from `bundle-audit check --format json`. The output
+  is normalized to tolerate both known schema shapes: a bare Array of
+  findings, or a Hash with a `results` key.
+- The `bundle-audit` subprocess runs with a scrubbed environment, so the
+  parent process's Bundler state (`BUNDLE_*`, `RUBYOPT`) does not leak into
+  it. This makes the collector safe to call from inside a running Rails app.
+
+## Development
+
+    bundle install
+    bundle exec rspec
+    bundle exec standardrb
+
+To release a new version:
+
+1. Bump `lib/lockfile_audit/version.rb`.
+2. Update `CHANGELOG.md`.
+3. `gem build lockfile_audit.gemspec`
+4. `gem push lockfile_audit-<version>.gem`
+
+## License
+
+MIT. See LICENSE.txt.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/lockfile_audit/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LockfileAudit
+  # Namespace for all errors raised by LockfileAudit.
+  module Errors
+    # Base class for every LockfileAudit error.
+    class Error < StandardError; end
+
+    # Raised when the Gemfile.lock file does not exist at the given path.
+    class LockfileNotFound < Error
+      def initialize(path)
+        super("Gemfile.lock not found at: #{path}")
+      end
+    end
+
+    # Raised when the `bundle-audit` executable cannot be found on PATH.
+    class BundlerAuditNotInstalled < Error
+      def initialize(message = nil)
+        super(message || "bundler-audit is not installed or not on PATH")
+      end
+    end
+
+    # Raised when `bundle-audit` runs but exits with a non-zero status
+    # other than 1 (which conventionally means "vulnerabilities found").
+    class BundlerAuditFailed < Error; end
+
+    # Raised when the supplied audit JSON cannot be parsed.
+    class InvalidAuditJson < Error
+      def initialize(message = nil)
+        super("Could not parse bundler-audit JSON: #{message}")
+      end
+    end
+  end
+end

data/lib/lockfile_audit/package_collector.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module LockfileAudit
+  # Parses a Gemfile.lock and returns the resolved gem list.
+  #
+  # Only top-level specs from `specs:` blocks are collected. Transitive
+  # dependency lines are skipped because they:
+  #   - are indented further (6 spaces instead of 4), and
+  #   - carry a version constraint (e.g. "= 7.1.3.2") rather than a
+  #     resolved version.
+  #
+  # A Gemfile.lock may contain multiple specs blocks (e.g. PATH, GEM, GIT),
+  # and all are collected.
+  class PackageCollector
+    # Matches a top-level spec line such as:
+    #   "    rails (7.1.3)"
+    # Exactly four leading spaces, then the gem name, then a version in
+    # parentheses. The version itself must not start with a comparator
+    # operator (=, <, >, ~), which would indicate a transitive dependency.
+    SPEC_LINE = /\A {4}([^\s(]+) \(([^)=<>~!]+)\)\z/
+
+    # Matches a "specs:" header line at any indentation depth.
+    SPECS_HEADER = /\A\s*specs:\s*\z/
+
+    # @param gemfile_lock_path [String, Pathname] path to the Gemfile.lock file
+    def initialize(gemfile_lock_path:)
+      @gemfile_lock_path = gemfile_lock_path
+    end
+
+    # @return [Array<Hash>] array of `{ name:, version: }` sorted by name
+    # @raise [Errors::LockfileNotFound] if the lockfile does not exist
+    def call
+      unless File.exist?(@gemfile_lock_path)
+        raise Errors::LockfileNotFound, @gemfile_lock_path
+      end
+
+      in_specs = false
+      packages = []
+
+      File.foreach(@gemfile_lock_path) do |raw_line|
+        line = raw_line.chomp
+
+        if line.match?(SPECS_HEADER)
+          in_specs = true
+          next
+        end
+
+        # A non-indented, non-empty line (e.g. "PLATFORMS" or "GEM")
+        # ends the current specs block.
+        in_specs = false if in_specs && !line.start_with?(" ")
+
+        next unless in_specs
+
+        match = line.match(SPEC_LINE)
+        next unless match
+
+        packages << {name: match[1], version: match[2]}
+      end
+
+      packages
+        .uniq { |pkg| pkg[:name] }
+        .sort_by { |pkg| pkg[:name] }
+    end
+  end
+end

data/lib/lockfile_audit/report.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "time"
+
+module LockfileAudit
+  # Assembles the final payload by combining packages and vulnerabilities.
+  class Report
+    # @param gemfile_lock_path [String, Pathname] path to the Gemfile.lock file
+    # @param audit_json [String, nil] pre-computed bundler-audit JSON; if nil,
+    #   bundler-audit is invoked directly
+    def initialize(gemfile_lock_path: "Gemfile.lock", audit_json: nil)
+      @gemfile_lock_path = gemfile_lock_path
+      @audit_json = audit_json
+    end
+
+    # @return [Hash] payload with `:generated_at`, `:packages`, and `:audit`
+    def call
+      {
+        generated_at: Time.now.utc.iso8601,
+        packages: packages,
+        audit: {
+          vulnerabilities: vulnerabilities
+        }
+      }
+    end
+
+    private
+
+    def packages
+      PackageCollector.new(gemfile_lock_path: @gemfile_lock_path).call
+    end
+
+    def vulnerabilities
+      VulnerabilityCollector.new(
+        audit_json: @audit_json,
+        lockfile_path: @gemfile_lock_path
+      ).call
+    end
+  end
+end

data/lib/lockfile_audit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LockfileAudit
+  VERSION = "0.1.0"
+end

data/lib/lockfile_audit/vulnerability_collector.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module LockfileAudit
+  # Collects vulnerability findings from bundler-audit.
+  #
+  # Either accepts pre-computed JSON (via +audit_json:+) or shells out to
+  # `bundle-audit check --format json` when no JSON is supplied.
+  #
+  # The normalizer tolerates both known shapes of bundler-audit output:
+  #   - a bare Array of findings (newer versions)
+  #   - a Hash with a "results" key holding the Array (older versions)
+  #
+  # When invoking the CLI, the collector runs with a scrubbed environment so
+  # the parent process's Bundler state (BUNDLE_*, RUBYOPT, etc.) does not leak
+  # into the subprocess. Without this, running from inside a Rails console
+  # causes Bundler to re-validate the Ruby version in the subprocess and abort
+  # with Bundler::RubyVersionMismatch.
+  #
+  # The CLI is invoked directly (never via `bundle exec` or `gem exec`) so the
+  # subprocess stays independent of the parent's Bundler context and does not
+  # trigger dependency installation or RDoc generation as a side effect.
+  class VulnerabilityCollector
+    # Environment variables that must not leak into the bundler-audit
+    # subprocess. These are set by Bundler when the parent process is a
+    # bundled Ruby app, and their presence forces Bundler to re-initialize
+    # inside the subprocess.
+    BUNDLER_ENV_KEYS = %w[
+      BUNDLE_GEMFILE
+      BUNDLE_BIN_PATH
+      BUNDLE_PATH
+      BUNDLE_APP_CONFIG
+      BUNDLE_FROZEN
+      BUNDLE_WITHOUT
+      BUNDLE_WITH
+      BUNDLE_JOBS
+      BUNDLE_RETRY
+      BUNDLER_VERSION
+      BUNDLER_ORIG_BUNDLE_BIN_PATH
+      BUNDLER_ORIG_BUNDLE_GEMFILE
+      BUNDLER_ORIG_BUNDLE_PATH
+      BUNDLER_ORIG_MANPATH
+      BUNDLER_ORIG_RUBYLIB
+      BUNDLER_ORIG_RUBYOPT
+      RUBYOPT
+      RUBYLIB
+    ].freeze
+
+    # @param audit_json [String, nil] raw JSON from bundler-audit; if nil,
+    #   bundler-audit is invoked directly
+    # @param lockfile_path [String, Pathname] path to Gemfile.lock; used to
+    #   derive the working directory for the CLI invocation
+    def initialize(audit_json: nil, lockfile_path: "Gemfile.lock")
+      @audit_json = audit_json
+      @lockfile_path = lockfile_path
+    end
+
+    # @return [Array<Hash>] normalized findings, each with keys
+    #   `:gem`, `:version`, `:criticality`, `:description`
+    # @raise [Errors::InvalidAuditJson] if the JSON cannot be parsed
+    # @raise [Errors::BundlerAuditNotInstalled] if bundler-audit is missing
+    def call
+      raw = @audit_json || run_bundler_audit
+      return [] if raw.nil? || raw.strip.empty?
+
+      parsed = JSON.parse(raw)
+      results = parsed.is_a?(Hash) ? parsed.fetch("results", []) : parsed
+
+      Array(results).map { |finding| normalize(finding) }
+    rescue JSON::ParserError => e
+      raise Errors::InvalidAuditJson, e.message
+    end
+
+    private
+
+    def run_bundler_audit
+      stdout, stderr, status = invoke(["bundle-audit"])
+      return stdout if usable?(stdout, status)
+
+      raise Errors::BundlerAuditNotInstalled,
+        "bundle-audit could not be invoked. " \
+        "Ensure the `bundler-audit` gem is installed and on your PATH " \
+        "(e.g. `gem install bundler-audit`). " \
+        "stderr: #{stderr.to_s.strip}"
+    rescue Errno::ENOENT
+      raise Errors::BundlerAuditNotInstalled,
+        "bundle-audit is not installed or not on PATH. " \
+        "Install it with `gem install bundler-audit`."
+    end
+
+    def invoke(command)
+      Open3.capture3(
+        clean_env,
+        *command, "check", "--format", "json",
+        chdir: File.dirname(File.expand_path(@lockfile_path))
+      )
+    end
+
+    # Builds an environment hash that removes the inherited Bundler state.
+    # Passing nil as the value to Open3 unsets the variable in the child.
+    def clean_env
+      BUNDLER_ENV_KEYS.each_with_object({}) do |key, acc|
+        acc[key] = nil
+      end
+    end
+
+    # bundler-audit exits 1 when it finds vulnerabilities (that's success for
+    # us), and 0 when the lockfile is clean. Any other exit code, or empty
+    # stdout, means the invocation didn't produce usable output.
+    def usable?(stdout, status)
+      return false if stdout.nil? || stdout.strip.empty?
+      return true if [0, 1].include?(status.exitstatus)
+
+      false
+    end
+
+    # Maps a single bundler-audit finding onto the public schema.
+    #
+    # bundler-audit has used slightly different key names across versions, so
+    # we fall back to nested "advisory" keys when the top-level ones are absent.
+    def normalize(finding)
+      advisory = finding["advisory"] || {}
+
+      {
+        gem: finding["gem"] || advisory["package"],
+        version: finding["version"] || advisory["affected_versions"],
+        criticality: finding["criticality"] || advisory["criticality"],
+        description: finding["title"] || advisory["title"] || finding["description"]
+      }
+    end
+  end
+end

data/lib/lockfile_audit.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lockfile_audit/version"
+require_relative "lockfile_audit/errors"
+require_relative "lockfile_audit/package_collector"
+require_relative "lockfile_audit/vulnerability_collector"
+require_relative "lockfile_audit/report"
+
+# LockfileAudit parses a Gemfile.lock for resolved gems and reports
+# vulnerabilities from bundler-audit as a single JSON-ready hash.
+#
+# @example
+#   LockfileAudit.report(gemfile_lock_path: "Gemfile.lock")
+#   # => {
+#   #      generated_at: "2026-09-26T12:00:00Z",
+#   #      packages: [{ name: "rails", version: "7.1.3" }, ...],
+#   #      audit: { vulnerabilities: [{ gem: "nokogiri", ... }] }
+#   #    }
+module LockfileAudit
+  # Builds the full report payload.
+  #
+  # @param gemfile_lock_path [String, Pathname] path to the Gemfile.lock file
+  # @param audit_json [String, nil] pre-computed JSON from
+  #   `bundle-audit check --format json`. When nil, bundler-audit is invoked
+  #   directly.
+  # @return [Hash] a JSON-ready hash matching the documented payload shape
+  def self.report(gemfile_lock_path: "Gemfile.lock", audit_json: nil)
+    Report.new(
+      gemfile_lock_path: gemfile_lock_path,
+      audit_json: audit_json
+    ).call
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: lockfile_audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- behnam1369
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Parses Gemfile.lock for resolved gems and reports vulnerabilities from
+  bundler-audit as a single JSON-ready hash.
+email:
+- behnam.aghaali@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/lockfile_audit.rb
+- lib/lockfile_audit/errors.rb
+- lib/lockfile_audit/package_collector.rb
+- lib/lockfile_audit/report.rb
+- lib/lockfile_audit/version.rb
+- lib/lockfile_audit/vulnerability_collector.rb
+homepage: https://github.com/Behnam1369/lockfile_audit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Behnam1369/lockfile_audit
+  changelog_uri: https://github.com/Behnam1369/lockfile_audit/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: JSON package inventory plus vulnerability audit from a Gemfile.lock.
+test_files: []