commissar 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75fe669345c8c573be9096107effe4a523b2713a7426ff95f4d8e61bd9f0853e
+  data.tar.gz: d221d1a39a1dfb16726c71c5585fdb7e0a814b17cf87787eebb503d6d39eed5f
+SHA512:
+  metadata.gz: 15aefe8a25cb03507a22d01bf932d14c9cac049cde6cb003b20e194e71768366be928ddac39c82967d58437994dc6f045c175b9fc99ad71e68e19c26ba9fe158
+  data.tar.gz: add075296dd9c27830dbfd7484aa9f59ad272f13557b3d9c21ec95d1fc5db656356d12bae63882bc938988522c204f8b267753101c81149c18f427784ba001d0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauro Eldritch
+
+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,141 @@
+# Commissar
+
+Static analysis tool for detecting potential supply chain attacks in RubyGems.
+
+Scans a gem for malicious indicators before you install it: suspicious network calls, credential access, file reads, obfuscated payloads, dangerous gemspec patterns, and more.
+
+## Install
+
+```
+gem install commissar
+```
+
+## Usage
+
+```
+commissar <gem_name> [version] [options]
+commissar --local PATH [options]
+```
+
+Examples:
+
+```
+#Normal use
+commissar rails
+
+#Scan a specific version
+commissar nokogiri 1.16.0
+
+#Scan a local gem
+commissar --local /tmp/my-gemfile.gem
+
+#JSON output to screen or to file
+commissar rails --format json > commissar.json
+commissar rails --format json | jq
+
+#Table format
+commissar rails --format table
+
+#CSV (format is assumed from the output file extension)
+commissar rails --output results.csv
+
+#No colour, please
+commissar rails --no-color
+
+#I just want the score for my automation tool/pipeline
+commissar rails --score-only
+```
+
+Output groups findings by category with severity (`CRIT`, `HIGH`, `MED`, `LOW`, `INFO`), file, and line number. A risk score (0–100) and a final recommendation are printed at the end.
+
+You can use `--score-only` to quickly integrate Commissar with your CI/CD pipelines. You will get a plain integer representing the risk score alone, without banner or any other information.
+
+## Configuration
+
+Pattern lists live in the `conf/` directory of the repo (or the gem's bundled `conf/` when installed). Edit those files directly to add or remove patterns.
+
+Files:
+
+| File | Purpose |
+|---|---|
+| `suspicious_urls.txt` | Domains associated with exfiltration or staging |
+| `suspicious_functions.txt` | Dangerous Ruby methods and classes |
+| `suspicious_shell.txt` | Shell commands used for data exfiltration or staging |
+| `credential_paths.txt` | Filesystem paths and env vars containing secrets and sensitive info |
+| `clipboard_patterns.txt` | System calls and APIs used for clipboard access |
+| `known_bad_wallets.txt` | OFAC-sanctioned and DOJ-documented wallet addresses |
+| `complex_gems.txt` | Known complex gems that receive a contextual note on elevated scores |
+| `severity.txt` | Numeric weights for each severity level |
+| `post_install_patterns.txt` | Suspicious patterns in post-install messages |
+
+Each file is plain text, one entry per line. Lines starting with `#` are ignored.
+
+### Pattern format
+
+```
+SEVERITY:PATTERN
+```
+
+Examples:
+
+```
+HIGH:eval
+CRIT:api.telegram.org
+MED:pastebin.com
+```
+
+### Antipatterns
+
+Any fields after the first pair are treated as antipatterns: if the line matches the pattern but also contains any antipattern, the finding is suppressed. Useful for reducing false positives from legitimate metaprogramming.
+
+```
+SEVERITY:PATTERN:ANTIPATTERN:ANTIPATTERN:...
+```
+
+Examples:
+
+```
+HIGH:eval:&:binding
+HIGH:instance_eval:&
+HIGH:class_eval:&:__FILE__
+```
+
+`::` in Ruby namespace notation is never treated as a separator, so `MED:Net::HTTP` works as expected.
+
+## What it detects
+
+- Version published in the last 72 hours
+- Recent owner changes or new maintainer accounts
+- Missing or broken homepage/source URIs
+- Gemspec `extensions` pointing to `extconf.rb` or `Rakefile` (run on `gem install`)
+- Top-level code in the gemspec
+- `eval`, `system`, backticks, and other dangerous function calls
+- Outbound network calls (Telegram bots, Discord webhooks, paste sites, webhook services)
+- `curl`/`wget` POST commands and Ruby HTTP POST equivalents
+- Base64-encoded or zlib-compressed payloads
+- High Shannon entropy strings (>5.5 bits/char)
+- Lines over 500 characters (common in padding and hiding schemes)
+- Access to credentials via `ENV` or filesystem paths
+- Clipboard hijacking (Web3)
+- Hardcoded wallet addresses: known OFAC/DOJ-sanctioned addresses flagged as `CRIT`, unknown addresses as `HIGH`
+
+## Development
+
+```
+bundle install
+rake test
+```
+
+## Contributing
+
+I appreciate your interest! Feel free to tweak the configuration files and detection expressions and share them with me and the community, always happy to hear back from users of my tools.
+
+If you believe your change deserves a dedicated fork, go for it!
+
+Please report any bugs or false positives, I'll be happy to work on them.
+
+/ ! \ Remember this tool could mistake some constructions for dangerous code or functions, or could even skip real ones, it's not failproof, so always DYOR.
+
+## License
+
+MIT - see [LICENSE](LICENSE).

data/conf/clipboard_patterns.txt

@@ -0,0 +1,5 @@
+HIGH:xclip
+HIGH:pbcopy
+HIGH:pbpaste
+HIGH:xdotool
+HIGH:Clipboard.

data/conf/complex_gems.txt

@@ -0,0 +1,28 @@
+bundler:package manager
+rubygems:package manager
+rake:build tool
+thor:build tool
+pry:debugger
+byebug:debugger
+debug:debugger
+ruby-debug:debugger
+binding_of_caller:debugger
+puma:web server
+thin:web server
+unicorn:web server
+passenger:web server
+falcon:web server
+webrick:web server
+rack:web framework
+rackup:web framework
+sinatra:web framework
+rails:web framework
+rubocop:code analyzer
+reek:code analyzer
+brakeman:security scanner
+flog:code analyzer
+flay:code analyzer
+zip:archive tool
+rubyzip:archive tool
+opal:compiler
+nokogiri:html/xml parser

data/conf/credential_paths.txt

@@ -0,0 +1,48 @@
+HIGH:ENV["AWS_ACCESS_KEY_ID"]
+HIGH:ENV["AWS_SECRET_ACCESS_KEY"]
+HIGH:ENV["AWS_SESSION_TOKEN"]
+HIGH:ENV["GITHUB_TOKEN"]
+HIGH:ENV["GH_TOKEN"]
+HIGH:ENV["RUBYGEMS_API_KEY"]
+HIGH:~/.aws/credentials
+HIGH:~/.ssh/id_rsa
+HIGH:~/.ssh/id_ed25519
+HIGH:~/.ssh/id_ecdsa
+HIGH:~/.gem/credentials
+MED:ENV["NPM_TOKEN"]
+MED:ENV["DATABASE_URL"]
+MED:ENV["SECRET_KEY_BASE"]
+MED:~/.aws/config
+MED:~/.ssh/known_hosts
+MED:~/.npmrc
+MED:~/.bundle/config
+MED:~/.netrc
+MED:.env.local
+MED:.env.production
+MED:.env.development
+CRIT:Login Data
+CRIT:Default/Cookies
+CRIT:Network/Cookies
+CRIT:Default/Web Data
+CRIT:Local Extension Settings
+CRIT:Cookies.binarycookies
+CRIT:login.keychain
+CRIT:System.keychain
+CRIT:Library/Keychains
+CRIT:logins.json
+CRIT:key4.db
+CRIT:cookies.sqlite
+CRIT:Google/Chrome
+CRIT:BraveSoftware/Brave-Browser
+CRIT:Safari/Cookies
+CRIT:Firefox/Profiles
+CRIT:AppData/Local/Google/Chrome
+CRIT:AppData/Roaming/Mozilla/Firefox
+CRIT:AppData/Local/BraveSoftware
+MED:Safari/History.db
+MED:Safari/Bookmarks.plist
+MED:Places.sqlite
+CRIT:wallet.dat
+CRIT:mnemonic
+CRIT:passwords.txt
+CRIT:.kdbx

data/conf/known_bad_wallets.txt

@@ -0,0 +1,25 @@
+0x8589427373D6D84E98730D7795D8f6f8731FDA16:Tornado Cash (OFAC)
+0x722122dF12D4e14e13Ac3b6895a86e84145b6967:Tornado Cash (OFAC)
+0xDD4c48C0B24039969fC16D1cdF626eaB821d3384:Tornado Cash (OFAC)
+0xd90e2f925DA726b50C4Ed8D0Fb90Ad053324F31b:Tornado Cash (OFAC)
+0xd96f2B1c14Db8458374d9Aca76E26c3950113264:Tornado Cash (OFAC)
+0x4736dCf1b7A3d580672CcE6E7c65cd5cc9cFBa9d:Tornado Cash (OFAC)
+0xD4B88Df4D29F5CedD6857912842cff3b20C8Cfa3:Tornado Cash (OFAC)
+0x910Cbd523D972eb0a6f4cAe4618aD62622b39DbF:Tornado Cash (OFAC)
+0xA160cdAB225685dA1d56aa342Ad8841c3b53f291:Tornado Cash (OFAC)
+0xFD8610d20aA15b7B2E3Be39B396a1bC3516c7144:Tornado Cash (OFAC)
+0x07687e702b410Fa43f4cB4Af7FA097918ffD2730:Tornado Cash (OFAC)
+0x23773E65ed146A459667FFaD1d6Ee592c33E1F0e:Tornado Cash (OFAC)
+0x22aaA7720ddd5388A3c0A3333430953C68f1849b:Tornado Cash (OFAC)
+0x03893a7c7463AE47D46bc7f091665f1893656003:Tornado Cash (OFAC)
+0x2717c5e28cf931547B621a5dddb772Ab6A35B701:Tornado Cash (OFAC)
+0xD21be7248e0197Ee08E0c20D4a96DEBdaC3D20Af:Tornado Cash (OFAC)
+0x4F60a160D8C2DDdaAfe16FCC57566dB84D674BD6:Tornado Cash (OFAC)
+0x1E34A77868E19A6647b1f2F47B51ed72dEDE95DD:Tornado Cash (OFAC)
+0x9AD122c22B14202B4490eDAf288FDb3C7cb3ff5E:Tornado Cash (OFAC)
+0x098B716B8Aaf21512996dC57EB0615e2383E2f96:Lazarus Group / Ronin Hack (OFAC)
+0xa0e1c89Ef1a489c9C7dE96311eD5Ce5D32c20E4b:Lazarus Group (OFAC)
+0x3Cffd56B47B7b41c56258D9C7731ABaDc360E073:Lazarus Group (OFAC)
+115p7UMMngoj1pMvkpHijcRdfJNXj6LrLn:WannaCry (DOJ)
+12t9YDPgwueZ9NyMgw519p7AA8isjr6SMw:WannaCry (DOJ)
+13AM4VW2dhxYgXeQepoHkHSQuy6NgaEb94:WannaCry (DOJ)

data/conf/post_install_patterns.txt

@@ -0,0 +1,5 @@
+MED:http
+MED:curl
+MED:wget
+MED:sudo
+MED:chmod

data/conf/severity.txt

@@ -0,0 +1,5 @@
+CRIT:25
+HIGH:10
+MED:5
+LOW:3
+INFO:0

data/conf/suspicious_functions.txt

@@ -0,0 +1,23 @@
+HIGH:eval:&:binding:--eval
+HIGH:instance_eval:&:{: do:__FILE__
+HIGH:class_eval:&:__FILE__:{: do
+HIGH:module_eval:&:__FILE__:{: do:get_file_and_line_from_caller
+HIGH:Kernel.system:(*
+HIGH:Kernel.exec:(*
+HIGH:Kernel.spawn
+HIGH:Process.spawn
+HIGH:IO.popen:%w[
+HIGH:Open3.popen2
+HIGH:Open3.popen3
+HIGH:Open3.capture2
+HIGH:Open3.capture3
+HIGH:Open3.pipeline
+HIGH:Base64.decode64
+HIGH:Base64.strict_decode64
+HIGH:Zlib::Inflate
+MED:Net::HTTP:Gem::Net::HTTP
+MED:URI.open
+MED:open-uri
+MED:TCPSocket:kind_of?
+MED:UDPSocket
+MED:Socket.new: engine

data/conf/suspicious_shell.txt

@@ -0,0 +1,15 @@
+HIGH:curl -X POST
+HIGH:curl --data
+HIGH:curl -d
+HIGH:curl -F
+HIGH:curl -T
+HIGH:wget --post-data
+HIGH:wget --post-file
+HIGH:wget -O-
+MED:Net::HTTP::Post.new
+MED:Net::HTTP.post_form
+MED:RestClient.post
+MED:HTTParty.post
+MED:Faraday.post
+MED:Excon.post
+MED:http.post

data/conf/suspicious_urls.txt

@@ -0,0 +1,19 @@
+CRIT:api.telegram.org
+CRIT:t.me
+CRIT:discord.com/api/webhooks
+CRIT:hooks.slack.com
+MED:pastebin.com
+MED:paste.ee
+MED:hastebin.com
+MED:transfer.sh
+MED:0x0.st
+MED:file.io
+MED:anonfiles.com
+MED:gofile.io
+MED:webhook.site
+MED:requestbin.com
+MED:pipedream.net
+LOW:ngrok.io
+LOW:ngrok-free.app
+LOW:serveo.net
+LOW:localhost.run

data/conf/top_gems.txt

@@ -0,0 +1,133 @@
+rake
+rspec
+bundler
+minitest
+nokogiri
+activesupport
+actionpack
+activerecord
+railties
+actionview
+rack
+actionmailer
+activejob
+activemodel
+activestorage
+actioncable
+actiontext
+actionmailbox
+json
+tzinfo
+concurrent-ruby
+i18n
+thor
+zeitwerk
+rubocop
+yard
+pry
+byebug
+listen
+spring
+faraday
+httparty
+rest-client
+devise
+sidekiq
+resque
+kaminari
+capybara
+selenium-webdriver
+factory_bot
+faker
+webmock
+simplecov
+aws-sdk-s3
+stripe
+redis
+pg
+mysql2
+sqlite3
+jwt
+bcrypt
+dotenv
+colorize
+rainbow
+mechanize
+rubocop-rails
+rubocop-rspec
+rubocop-performance
+rspec-rails
+rails
+sinatra
+puma
+unicorn
+passenger
+capistrano
+whenever
+carrierwave
+paperclip
+geocoder
+ransack
+pundit
+cancancan
+omniauth
+warden
+rolify
+activeadmin
+administrate
+sorbet
+steep
+dry-rb
+hanami
+grape
+fast_jsonapi
+jsonapi-serializer
+grpc
+google-protobuf
+aws-sdk-core
+net-ssh
+net-scp
+sshkit
+mina
+foreman
+rerun
+guard
+rubygems-update
+thin
+eventmachine
+rack
+rack-test
+rack-protection
+pry-rails
+rspec-mocks
+rspec-support
+rspec-expectations
+rspec-core
+webrick
+net-http
+addressable
+excon
+typhoeus
+concurrent-ruby
+activejob
+activerecord
+actiontext
+actionmailbox
+bootsnap
+sprockets
+importmap-rails
+turbo-rails
+stimulus-rails
+tailwindcss-rails
+cssbundling-rails
+jsbundling-rails
+erb_lint
+rubocop-minitest
+debug
+irb
+rdoc
+psych
+ostruct
+logger
+base64
+resolv

data/exe/commissar

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require_relative "../lib/commissar"
+
+options = { format: nil, color: true, output: nil, local: nil, score_only: false }
+
+OptionParser.new do |opts|
+	opts.banner = <<~BANNER
+		Usage:
+		  commissar <gem_name> [version] [options]
+		  commissar --local PATH [options]
+
+		Examples:
+		  commissar rails
+		  commissar nokogiri 1.16.0
+		  commissar --local /tmp/evil.gem
+		  commissar rails --no-color
+		  commissar rails --format table
+		  commissar rails --format json --output results.json
+		  commissar rails --format json | jq
+		  commissar rails --output results.csv
+		  commissar rails --score-only
+		  [ $(commissar rails --score-only) -lt 40 ] && gem install rails
+
+		Options:
+	BANNER
+
+	opts.on("--local PATH", "Scan a local .gem file") do |path|
+		options[:local] = path
+	end
+
+	opts.on("--no-color", "Disable colored output") do
+		options[:color] = false
+	end
+
+	opts.on("--output FILE", "Write output to FILE") do |file|
+		options[:output] = file
+	end
+
+	opts.on("--format FORMAT", %w[text csv json table], "Output format: text, csv, json, table") do |fmt|
+		options[:format] = fmt.to_sym
+	end
+
+	opts.on("--score-only", "Output only the integer risk score (for CI/CD integration)") do
+		options[:score_only] = true
+	end
+
+	opts.on("-h", "--help", "Show this help") do
+		puts opts
+		exit
+	end
+end.tap { |parser| @parser = parser }.parse!
+
+String.disable_colorization = !options[:color]
+
+if options[:local]
+	local_path = File.expand_path(options[:local])
+	unless File.exist?(local_path)
+		warn "File not found: #{local_path}".colorize(:red)
+		exit 1
+	end
+	gem_name = File.basename(local_path, ".gem").sub(/-\d+\.\d+\.\d+.*$/, "")
+	scanner  = Commissar::Scanner.new(gem_name, local_path: local_path)
+elsif ARGV.empty?
+	puts @parser
+	exit 1
+else
+	scanner = Commissar::Scanner.new(ARGV[0], version: ARGV[1])
+end
+
+if options[:score_only]
+	scanner.scan(quiet: true)
+	puts scanner.risk_score
+	exit
+end
+
+quiet = %i[json csv].include?(options[:format])
+scanner.scan(quiet: quiet)
+
+terminal_format = options[:format] || :text
+scanner.report(format: terminal_format)
+
+if options[:output]
+	file_format = options[:format]
+	unless file_format
+		ext = File.extname(options[:output]).downcase
+		file_format = case ext
+			when ".csv"  then :csv
+			when ".json" then :json
+			else              :text
+		end
+	end
+
+	String.disable_colorization = true
+	File.open(options[:output], "w") do |f|
+		scanner.report(format: file_format, io: f)
+	end
+	String.disable_colorization = !options[:color]
+	warn "Output written to #{options[:output]}".colorize(:cyan)
+end

data/lib/commissar.rb

@@ -0,0 +1,673 @@
+require "rubygems"
+require "rubygems/package"
+require "net/http"
+require "uri"
+require "json"
+require "yaml"
+require "tmpdir"
+require "fileutils"
+require "time"
+require "set"
+require "csv"
+require "colorize"
+
+module Commissar
+	VERSION = "0.1.0"
+
+	module Config
+		BUNDLED_DIR = File.expand_path("../../conf", __FILE__)
+
+		def self.load(filename)
+			path = resolve(filename)
+			return [] unless path
+
+			File.readlines(path, chomp: true)
+				.reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+		end
+
+		def self.load_weights
+			path = resolve("severity.txt")
+			return {} unless path
+
+			File.readlines(path, chomp: true)
+				.reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+				.each_with_object({}) do |line, hash|
+					k, v = line.split(":", 2)
+					hash[k.strip] = v.to_i if k && v
+				end
+		end
+
+		def self.load_complex_gems
+			path = resolve("complex_gems.txt")
+			return {} unless path
+
+			File.readlines(path, chomp: true)
+				.reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+				.each_with_object({}) do |line, hash|
+					name, category = line.split(":", 2)
+					hash[name.strip] = category.strip if name && category
+				end
+		end
+
+		def self.load_known_wallets
+			path = resolve("known_bad_wallets.txt")
+			return {} unless path
+
+			File.readlines(path, chomp: true)
+				.reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+				.each_with_object({}) do |line, hash|
+					addr, label = line.split(":", 2)
+					next unless addr && label
+					hash[addr.strip] = label.strip
+				end
+		end
+
+		def self.resolve(filename)
+			candidates = [
+				File.join(Dir.pwd, "conf", filename),
+				File.join(BUNDLED_DIR, filename)
+			]
+			candidates.find { |p| File.exist?(p) }
+		end
+	end
+
+	SEVERITY_WEIGHT = Config.load_weights.freeze
+
+	Finding = Struct.new(:category, :severity, :message, :file, :line, :snippet, keyword_init: true) do
+		def weight
+			SEVERITY_WEIGHT.fetch(severity, 0)
+		end
+
+		def to_s
+			loc = [file, line].compact.join(":")
+			loc_str = loc.empty? ? "" : " => #{loc}"
+			"[#{severity.ljust(4)}] #{message}#{loc_str}"
+		end
+	end
+
+	class Scanner
+		RUBYGEMS_API  = "https://rubygems.org/api/v1"
+		HOMOGLYPH_RE  = /[аеорсхѕіїӏορᴏᴀ]/
+
+		attr_reader :gem_name, :version, :findings
+
+		def initialize(gem_name, version: nil, local_path: nil)
+			@gem_name   = gem_name
+			@version    = version
+			@local_path = local_path
+			@findings   = []
+			@metadata   = {}
+			@files      = {}
+			@spec       = nil
+			@owners     = :pending
+			@suspicious_urls      = Config.load("suspicious_urls.txt")
+			@suspicious_functions = Config.load("suspicious_functions.txt")
+			@suspicious_shell     = Config.load("suspicious_shell.txt")
+			@credential_paths     = Config.load("credential_paths.txt")
+			@clipboard_patterns      = Config.load("clipboard_patterns.txt")
+			@post_install_patterns   = Config.load("post_install_patterns.txt")
+			@known_bad_wallets       = Config.load_known_wallets
+			@complex_gems         = Config.load_complex_gems
+			@top_gems             = Config.load("top_gems.txt")
+		end
+
+		def scan(quiet: false)
+			puts "\n#{"[*] Scanning: #{gem_name}".colorize(:white)} #{version_label}" unless quiet
+			fetch_metadata unless @local_path
+			fetch_and_unpack
+			run_metadata_checks
+			run_diff_checks unless @local_path
+			run_gemspec_checks
+			run_function_checks
+			run_url_checks
+			run_shell_checks
+			run_encoding_checks
+			run_credential_checks
+			run_web3_checks
+			self
+		end
+
+		def risk_score
+			raw = @findings.sum(&:weight)
+			[raw, 100].min
+		end
+
+		def report(format: :text, io: $stdout)
+			case format
+			when :csv   then report_csv(io)
+			when :json  then report_json(io)
+			when :table then report_table(io)
+			else             report_text(io)
+			end
+		end
+
+		private
+
+		def report_text(io)
+			grouped = @findings.group_by(&:category)
+			if grouped.empty?
+				io.puts "  #{"No findings.".colorize(:green)}"
+			else
+				grouped.each do |category, items|
+					io.puts "\n#{category_header(category)} (#{items.size})"
+					items.each do |f|
+						io.puts "  └─ #{colorize_finding(f)}"
+						io.puts "        #{f.snippet.colorize(:light_black)}" if f.snippet
+					end
+				end
+			end
+			io.puts "\n#{score_line}"
+			io.puts complex_gem_note.colorize(:cyan) if complex_gem_note
+		end
+
+		def report_csv(io)
+			io.puts CSV.generate_line(%w[gem version category severity message file line snippet])
+			v = @version || @metadata["version"] || ""
+			@findings.each do |f|
+				io.puts CSV.generate_line([gem_name, v, f.category, f.severity, f.message, f.file, f.line, f.snippet])
+			end
+		end
+
+		def report_json(io)
+			v = @version || @metadata["version"]
+			payload = {
+				gem:        gem_name,
+				version:    v,
+				scanned_at: Time.now.iso8601,
+				risk_score: risk_score,
+				verdict:    verdict_text,
+				findings:   @findings.map { |f|
+					{ category: f.category, severity: f.severity, message: f.message,
+					  file: f.file, line: f.line, snippet: f.snippet }
+				}
+			}
+			payload[:complex_gem_note] = complex_gem_note if complex_gem_note
+			io.puts JSON.pretty_generate(payload)
+		end
+
+		def report_table(io)
+			if @findings.empty?
+				io.puts "No findings."
+				io.puts "\n#{score_line}"
+				return
+			end
+
+			col_defs = [
+				{ header: "SEV",      max: 4  },
+				{ header: "CATEGORY", max: 22 },
+				{ header: "MESSAGE",  max: 40 },
+				{ header: "FILE",     max: 28 },
+				{ header: "LINE",     max: 5  },
+				{ header: "SNIPPET",  max: 50 },
+			]
+			rows = @findings.map { |f|
+				[f.severity.to_s, f.category.to_s, f.message.to_s, f.file.to_s, f.line.to_s, f.snippet.to_s]
+			}
+			widths = col_defs.each_with_index.map do |col, i|
+				content_max = rows.map { |r| r[i].length }.max || 0
+				[col[:header].length, [content_max, col[:max]].min].max
+			end
+
+			sep = "+" + widths.map { |w| "-" * (w + 2) }.join("+") + "+"
+			io.puts sep
+			io.puts "|" + col_defs.each_with_index.map { |c, i| " #{c[:header].ljust(widths[i])} " }.join("|") + "|"
+			io.puts sep
+			rows.each do |row|
+				io.puts "|" + row.each_with_index.map { |cell, i|
+					s = cell.length > widths[i] ? "#{cell[0, widths[i] - 1]}…" : cell
+					" #{s.ljust(widths[i])} "
+				}.join("|") + "|"
+			end
+			io.puts sep
+			io.puts "\n#{score_line}"
+			io.puts complex_gem_note.colorize(:cyan) if complex_gem_note
+		end
+
+		def fetch_metadata
+			uri = URI("#{RUBYGEMS_API}/gems/#{gem_name}.json")
+			response = Net::HTTP.get_response(uri)
+			unless response.is_a?(Net::HTTPSuccess)
+				warn "  Could not fetch metadata for #{gem_name}".colorize(:yellow)
+				return
+			end
+			@metadata = JSON.parse(response.body)
+			@version ||= @metadata["version"]
+		end
+
+		def fetch_and_unpack
+			if @local_path
+				@files, @spec = unpack_gem(@local_path)
+				return
+			end
+
+			Dir.mktmpdir("commissar_") do |tmpdir|
+				gem_path = download_gem(tmpdir)
+				return unless gem_path
+				@files, @spec = unpack_gem(gem_path)
+			end
+		end
+
+		def download_gem(dir, version: nil)
+			ver  = version || @version || @metadata["version"]
+			uri  = URI("https://rubygems.org/gems/#{gem_name}-#{ver}.gem")
+			response = Net::HTTP.get_response(uri)
+			unless response.is_a?(Net::HTTPSuccess)
+				warn "  Could not download .gem for #{gem_name} #{ver}".colorize(:yellow)
+				return nil
+			end
+			path = File.join(dir, "#{gem_name}-#{ver}.gem")
+			File.binwrite(path, response.body)
+			path
+		end
+
+		def unpack_gem(gem_path)
+			extract_dir = nil
+			files = {}
+			extract_dir = Dir.mktmpdir("commissar_x_")
+			pkg  = Gem::Package.new(gem_path)
+			spec = pkg.spec
+			pkg.extract_files(extract_dir)
+			pkg.contents.each do |entry|
+				full_path = File.join(extract_dir, entry)
+				next unless File.file?(full_path)
+				next if File.size(full_path) > 1_048_576
+				files[entry] = safe_read(full_path)
+			end
+			[files, spec]
+		rescue => e
+			warn "  Could not unpack gem: #{e.message}".colorize(:yellow)
+			[{}, nil]
+		ensure
+			FileUtils.rm_rf(extract_dir) if extract_dir
+		end
+
+		def safe_read(path)
+			File.binread(path).encode("UTF-8", "binary", invalid: :replace, undef: :replace, replace: "")
+		rescue
+			nil
+		end
+
+		def run_metadata_checks
+			check_typosquatting
+			return if @metadata.empty?
+			check_version_age
+			check_owner_changes
+			check_missing_uris
+		end
+
+		def check_typosquatting
+			return if @top_gems.empty?
+			closest = @top_gems.min_by { |g| levenshtein(gem_name, g) }
+			dist    = levenshtein(gem_name, closest)
+			return if dist == 0 || dist > 2
+			severity = dist == 1 ? "MED" : "LOW"
+			add_finding(
+				category: "METADATA",
+				severity: severity,
+				message: "Possible typosquat of '#{closest}' (Levenshtein distance: #{dist})"
+			)
+		end
+
+		def run_diff_checks
+			return if @files.empty?
+			versions = fetch_versions
+			return unless versions && versions.size >= 2
+			prev_version_num = versions.map { |v| v["number"] }.reject { |n| n == @version }.first
+			return unless prev_version_num
+			Dir.mktmpdir("commissar_diff_") do |tmpdir|
+				gem_path = download_gem(tmpdir, version: prev_version_num)
+				return unless gem_path
+				prev_files, _prev_spec = unpack_gem(gem_path)
+				check_version_diff(prev_files, prev_version_num)
+			end
+		end
+
+		def check_version_diff(prev_files, prev_version)
+			current_keys = Set.new(@files.keys)
+			prev_keys    = Set.new(prev_files.keys)
+			(current_keys - prev_keys).each do |f|
+				add_finding(category: "DIFF", severity: "INFO", message: "New file vs #{prev_version}: #{f}")
+			end
+			(prev_keys - current_keys).each do |f|
+				add_finding(category: "DIFF", severity: "INFO", message: "Removed vs #{prev_version}: #{f}")
+			end
+			(current_keys & prev_keys).each do |f|
+				next if @files[f] == prev_files[f]
+				add_finding(category: "DIFF", severity: "INFO", message: "Modified vs #{prev_version}: #{f}")
+			end
+		end
+
+		def fetch_versions
+			uri = URI("#{RUBYGEMS_API}/versions/#{gem_name}.json")
+			response = Net::HTTP.get_response(uri)
+			return nil unless response.is_a?(Net::HTTPSuccess)
+			JSON.parse(response.body)
+		rescue
+			nil
+		end
+
+		def check_version_age
+			return unless @metadata["version_created_at"]
+			published_at = Time.parse(@metadata["version_created_at"])
+			age_hours = (Time.now - published_at) / 3600
+			return unless age_hours < 72
+			add_finding(
+				category: "METADATA",
+				severity: "LOW",
+				message: "Version published #{age_hours.round}h ago (threshold: 72h)"
+			)
+		end
+
+		def check_owner_changes
+			@owners = fetch_owners if @owners == :pending
+			return if @owners.nil? || !@owners.is_a?(Array) || @owners.empty?
+			return unless @owners.size == 1
+			handle   = @owners.first["handle"]
+			gem_age  = gem_age_days
+			severity = (gem_age && gem_age < 30) ? "MED" : "LOW"
+			label    = (severity == "MED") ? "new gem with single maintainer" : "single maintainer"
+			add_finding(category: "METADATA", severity: severity, message: "#{label.capitalize}: #{handle}")
+		end
+
+		def fetch_owners
+			uri = URI("#{RUBYGEMS_API}/gems/#{gem_name}/owners.yaml")
+			response = Net::HTTP.get_response(uri)
+			return nil unless response.is_a?(Net::HTTPSuccess)
+			YAML.safe_load(response.body)
+		end
+
+		def gem_age_days
+			return nil unless @metadata["created_at"]
+			(Time.now - Time.parse(@metadata["created_at"])) / 86400
+		end
+
+		def check_missing_uris
+			homepage   = @metadata["homepage_uri"].to_s.strip
+			source_uri = @metadata["source_code_uri"].to_s.strip
+			if homepage.empty? && source_uri.empty?
+				add_finding(category: "METADATA", severity: "MED", message: "No source URIs available (no homepage_uri or source_code_uri)")
+				return
+			end
+			if homepage.empty?
+				add_finding(category: "METADATA", severity: "LOW", message: "Missing homepage_uri")
+			end
+			if source_uri.empty?
+				add_finding(category: "METADATA", severity: "LOW", message: "Missing source_code_uri")
+			end
+		end
+
+		def run_gemspec_checks
+			return unless @spec
+			check_gemspec_extensions
+			check_gemspec_post_install
+		end
+
+		def check_gemspec_extensions
+			return if @spec.extensions.empty?
+			@spec.extensions.each do |ext|
+				if ext.match?(/Rakefile/i)
+					add_finding(
+						category: "GEMSPEC", severity: "HIGH",
+						message: "Native extension executes on gem install: #{ext}"
+					)
+				else
+					add_finding(
+						category: "GEMSPEC", severity: "MED",
+						message: "Native extension declared in gemspec: #{ext}"
+					)
+				end
+			end
+		end
+
+		def check_gemspec_post_install
+			msg = @spec.post_install_message.to_s.strip
+			return if msg.empty?
+			@post_install_patterns.each do |entry|
+				severity, pattern, antipatterns = parse_config_entry(entry)
+				next unless msg.include?(pattern)
+				next if antipatterns.any? { |ap| msg.include?(ap) }
+				add_finding(
+					category: "GEMSPEC", severity: severity,
+					message: "Suspicious post_install_message content",
+					snippet: truncate(msg)
+				)
+				break
+			end
+		end
+
+		def run_function_checks
+			scan_files_for_patterns(@suspicious_functions, "DANGEROUS FUNCTIONS", files: ruby_source_files, word_boundary: true)
+		end
+
+		def run_url_checks
+			scan_files_for_patterns(@suspicious_urls, "SUSPICIOUS URLS", word_boundary: true)
+		end
+
+		def run_shell_checks
+			scan_files_for_patterns(@suspicious_shell, "SHELL/EXFIL")
+		end
+
+		def run_encoding_checks
+			ruby_source_files.each do |filename, content|
+				next if content.nil?
+				scan_lines(content, filename).each do |line, file, lineno|
+					next if line.lstrip.start_with?("#")
+					check_entropy(line, file, lineno)
+					check_line_length(line, file, lineno)
+					check_homoglyphs(line, file, lineno)
+				end
+			end
+		end
+
+		def check_entropy(line, file, lineno)
+			return if line.length < 20
+			e = shannon_entropy(line)
+			return unless e > 5.5
+			add_finding(
+				category: "ENCODING", severity: "HIGH",
+				message: "High entropy line (#{e.round(1)} bits/char, #{line.length} chars)",
+				file: file, line: lineno, snippet: line
+			)
+		end
+
+		def check_line_length(line, file, lineno)
+			return unless line.length > 500
+			add_finding(
+				category: "ENCODING", severity: "MED",
+				message: "Long line (#{line.length} chars)",
+				file: file, line: lineno, snippet: line
+			)
+		end
+
+		def check_homoglyphs(line, file, lineno)
+			return unless line.match?(HOMOGLYPH_RE)
+			add_finding(
+				category: "ENCODING", severity: "HIGH",
+				message: "Homoglyph characters detected",
+				file: file, line: lineno, snippet: line
+			)
+		end
+
+		def shannon_entropy(str)
+			return 0.0 if str.empty?
+			freq = Hash.new(0)
+			str.each_char { |c| freq[c] += 1 }
+			len = str.length.to_f
+			-freq.values.sum { |count| (p = count / len) * Math.log2(p) }
+		end
+
+		def run_credential_checks
+			scan_files_for_patterns(@credential_paths, "CREDENTIALS")
+		end
+
+		def run_web3_checks
+			return if @files.empty?
+			wallet_patterns = [
+				["ETH wallet address", /0x[a-fA-F0-9]{40}\b/],
+				["BTC wallet address", /\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b/],
+				["BTC bech32 address", /\bbc1[a-z0-9]{6,87}\b/i]
+			]
+			scannable_files.each do |filename, content|
+				next if content.nil?
+				scan_lines(content, filename).each do |line, file, lineno|
+					next if line.lstrip.start_with?("#")
+					wallet_patterns.each do |label, re|
+						m = line.match(re)
+						next unless m
+						addr      = m[0]
+						bad_label = @known_bad_wallets[addr] || @known_bad_wallets[addr.downcase]
+						if bad_label
+							add_finding(category: "WEB3", severity: "CRIT", message: "Known malicious wallet (#{bad_label}): #{addr}", file: file, line: lineno, snippet: line)
+						else
+							add_finding(category: "WEB3", severity: "HIGH", message: label, file: file, line: lineno, snippet: line)
+						end
+					end
+					@clipboard_patterns.each do |entry|
+						severity, pattern, antipatterns = parse_config_entry(entry)
+						next unless line.include?(pattern)
+						next if antipatterns.any? { |ap| line.include?(ap) }
+						add_finding(category: "WEB3", severity: severity, message: "Clipboard access: #{pattern}", file: file, line: lineno, snippet: line)
+					end
+				end
+			end
+		end
+
+		def add_finding(category:, severity:, message:, file: nil, line: nil, snippet: nil)
+			@findings << Finding.new(
+				category: category,
+				severity: severity,
+				message:  message,
+				file:     file,
+				line:     line,
+				snippet:  snippet ? truncate(snippet.strip) : nil
+			)
+		end
+
+		def truncate(str, max = 100)
+			str.length > max ? "#{str[0, max]}…" : str
+		end
+
+		def verdict_text
+			score = risk_score
+			if score >= 70    then "DANGEROUS, DO NOT INSTALL"
+			elsif score >= 40 then "REVIEW CAREFULLY"
+			else                   "Looks safe but exercise caution"
+			end
+		end
+
+		def levenshtein(a, b)
+			return b.length if a.empty?
+			return a.length if b.empty?
+			prev = (0..b.length).to_a
+			a.each_char.with_index(1) do |ca, i|
+				curr = [i]
+				b.each_char.with_index(1) do |cb, j|
+					cost = ca == cb ? 0 : 1
+					curr << [prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost].min
+				end
+				prev = curr
+			end
+			prev[b.length]
+		end
+
+		RUBY_EXTENSIONS = %w[.rb .gemspec .rake .ru].freeze
+		RUBY_NAMES      = %w[Rakefile Gemfile].freeze
+
+		SKIP_EXTENSIONS = %w[.md .rdoc .ronn].freeze
+
+		def scannable_files
+			@files.reject { |name, _| SKIP_EXTENSIONS.include?(File.extname(name)) }
+		end
+
+		def ruby_source_files
+			scannable_files.select { |name, _|
+				RUBY_EXTENSIONS.include?(File.extname(name)) ||
+					RUBY_NAMES.include?(File.basename(name))
+			}
+		end
+
+		def scan_files_for_patterns(patterns, category, files: nil, word_boundary: false)
+			target = files || scannable_files
+			return if target.empty?
+			patterns.each do |entry|
+				severity, pattern, antipatterns = parse_config_entry(entry)
+				matcher = word_boundary ? /\b#{Regexp.escape(pattern)}\b/ : nil
+				target.each do |filename, content|
+					scan_lines(content, filename).each do |line, file, lineno|
+						next if line.lstrip.start_with?("#")
+						next unless matcher ? line.match?(matcher) : line.include?(pattern)
+						next if antipatterns.any? { |ap| line.include?(ap) }
+						add_finding(category: category, severity: severity, message: pattern, file: file, line: lineno, snippet: line)
+					end
+				end
+			end
+		end
+
+		def parse_config_entry(entry)
+			parts = entry.split(/(?<!:):(?!:)/, -1)
+			if parts.first =~ /\A(CRIT|HIGH|MED|LOW)\z/
+				severity     = parts.shift
+				pattern      = parts.shift
+				antipatterns = parts.reject(&:empty?)
+				[severity, pattern, antipatterns]
+			else
+				["MED", entry, []]
+			end
+		end
+
+		def scan_lines(content, file_name)
+			return [] if content.nil?
+			content.each_line.with_index(1).map { |line, num| [line.chomp, file_name, num] }
+		end
+
+		def version_label
+			v = @version || @metadata["version"]
+			v ? "(#{v})".colorize(:light_black) : ""
+		end
+
+		def category_header(cat)
+			titles = {
+				"METADATA"            => "[*] METADATA",
+				"GEMSPEC"             => "[*] GEMSPEC",
+				"DANGEROUS FUNCTIONS" => "[*] DANGEROUS FUNCTIONS",
+				"SUSPICIOUS URLS"     => "[*] SUSPICIOUS URLS",
+				"SHELL/EXFIL"         => "[*] SHELL/EXFIL",
+				"ENCODING"            => "[*] ENCODED PAYLOADS",
+				"CREDENTIALS"         => "[*] CREDENTIALS",
+				"WEB3"                => "[*] WEB3",
+				"DIFF"                => "[*] DIFF"
+			}
+			titles.fetch(cat, cat).colorize(:yellow)
+		end
+
+		def colorize_finding(finding)
+			color = case finding.severity
+				when "CRIT" then :magenta
+				when "HIGH" then :red
+				when "MED"  then :yellow
+				when "LOW"  then :light_black
+				when "INFO" then :cyan
+			end
+			finding.to_s.colorize(color)
+		end
+
+		def complex_gem_note
+			category = @complex_gems[gem_name]
+			return nil unless category
+			"[i] #{gem_name} is a known complex gem (#{category}). Elevated scores may reflect legitimate functionality, review findings manually!"
+		end
+
+		def score_line
+			score = risk_score
+			color = if score >= 70    then :red
+				elsif score >= 40 then :yellow
+				else                   :green
+			end
+			icon = if score >= 70    then "[!]"
+				elsif score >= 40 then "[?]"
+				else                   "[*]"
+			end
+			"#{icon} Risk score: #{score}/100 — #{verdict_text}".colorize(color)
+		end
+	end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: commissar
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mauro Eldritch
+bindir: exe
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: 'Static analysis tool that scans RubyGems for indicators of supply chain
+  compromise: malicious gemspecs, suspicious URLs, credential exfiltration, obfuscated
+  payloads, and more.'
+email:
+- mauroeldritch@gmail.com
+executables:
+- commissar
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- conf/clipboard_patterns.txt
+- conf/complex_gems.txt
+- conf/credential_paths.txt
+- conf/known_bad_wallets.txt
+- conf/post_install_patterns.txt
+- conf/severity.txt
+- conf/suspicious_functions.txt
+- conf/suspicious_shell.txt
+- conf/suspicious_urls.txt
+- conf/top_gems.txt
+- exe/commissar
+- lib/commissar.rb
+homepage: https://github.com/mauroeldritch/commissar
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/mauroeldritch/commissar/issues
+  changelog_uri: https://github.com/mauroeldritch/commissar/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/mauroeldritch/commissar
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Supply chain attack detector for RubyGems
+test_files: []