vtk 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6acd180a7e7d3839aebff0617c306c092205492ab3c5ce124f3b5e957970e42b
-  data.tar.gz: c2c5fe18ee04efc2624eb092125c4c738d041e854173d1f934543cb5dbe8dcd2
+  metadata.gz: '0585f00ec9fe122942c5a249fd2733e47baa461960cc9d106e2dfb9ac13dc3aa'
+  data.tar.gz: c23b728a27d519e15812f8b95ffcf7e0aac20981e38cab59dca62c4a62582f21
 SHA512:
-  metadata.gz: 06b298ec4d35bb31e1472913c305377649ef70399cc87eb2818fae5c5f4f6395be90516df1cfb16aa2cdd4ba9ae8bccb9caec475654fa2c98b26e17be5a070fd
-  data.tar.gz: 793f7811c57a9167f17704a14105a4b8d1624974f910295088a3d72c29528e84f2d57921ff073a7d59fee357953b3972d31f5fc5cc19876b66dcd20b2effe5fa
+  metadata.gz: 0d10b96103db87af8754a1a1a3cb0fc6a268255f9c596baccf730f73c8a8ba03598a84cdcc8de35a53114710fe546e572a8f7ca4706efc8c45e7de3ce28aa115
+  data.tar.gz: 9e78a14e489d84f99a81725f7f93c03c3356d7165d7d79c871ade2cb61f2d462f8dae315f8b1f570ae7db4e84f0e9f0b4d7706f4d06dcc2c4622272025edf18d

data/.github/workflows/main.yml

@@ -4,7 +4,7 @@ on: [push,pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v2
     - uses: ruby/setup-ruby@v1

data/.tool-versions

@@ -1 +1 @@
-ruby 3.2.2
+ruby 3.4.7

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [v1.2.0](https://github.com/department-of-veterans-affairs/vtk/tree/v1.2.0) (2026-01-09)
+
+[Full Changelog](https://github.com/department-of-veterans-affairs/vtk/compare/v1.1.0...v1.2.0)
+
+**Merged pull requests:**
+
+- feat(scan): add PowerShell scripts for Windows users [\#69](https://github.com/department-of-veterans-affairs/vtk/pull/69) ([ericboehs](https://github.com/ericboehs))
+- feat(scan): add vtk scan credentials for security incident response [\#68](https://github.com/department-of-veterans-affairs/vtk/pull/68) ([ericboehs](https://github.com/ericboehs))
+- feat(scan): add vtk scan repo for compromised package detection [\#65](https://github.com/department-of-veterans-affairs/vtk/pull/65) ([ericboehs](https://github.com/ericboehs))
+
+## [v1.1.0](https://github.com/department-of-veterans-affairs/vtk/tree/v1.1.0) (2025-12-15)
+
+[Full Changelog](https://github.com/department-of-veterans-affairs/vtk/compare/v1.0.0...v1.1.0)
+
+**Merged pull requests:**
+
+- feat(scan): add vtk scan machine for Shai-Hulud detection [\#64](https://github.com/department-of-veterans-affairs/vtk/pull/64) ([ericboehs](https://github.com/ericboehs))
+- fix: resolve rubocop offenses in socks/setup.rb [\#66](https://github.com/department-of-veterans-affairs/vtk/pull/66) ([ericboehs](https://github.com/ericboehs))
+- Fix rubocop exceptions and update GH to run on Ubuntu Latest [\#63](https://github.com/department-of-veterans-affairs/vtk/pull/63) ([ericboehs](https://github.com/ericboehs))
+
+## [v1.0.0](https://github.com/department-of-veterans-affairs/vtk/tree/v1.0.0) (2024-09-18)
+
+🎉
+
+[Full Changelog](https://github.com/department-of-veterans-affairs/vtk/compare/v0.9.5...v1.0.0)
+
+**Merged pull requests:**
+
+- fix: OpenStruct is no longer auto required in Ruby 3.2 [\#62](https://github.com/department-of-veterans-affairs/vtk/pull/62) ([ericboehs](https://github.com/ericboehs))
+- Update RuboCop w/ corrections [\#53](https://github.com/department-of-veterans-affairs/vtk/pull/53) ([ericboehs](https://github.com/ericboehs))
+
+## [v0.9.5](https://github.com/department-of-veterans-affairs/vtk/tree/v0.9.5) (2023-12-15)
+
+[Full Changelog](https://github.com/department-of-veterans-affairs/vtk/compare/v0.9.4...v0.9.5)
+
+**Merged pull requests:**
+
+- Add sudo to proxy setup command for MacOS. [\#52](https://github.com/department-of-veterans-affairs/vtk/pull/52) ([omahane](https://github.com/omahane))
+
 ## [v0.9.4](https://github.com/department-of-veterans-affairs/vtk/tree/v0.9.4) (2022-04-11)
 
 [Full Changelog](https://github.com/department-of-veterans-affairs/vtk/compare/v0.9.3...v0.9.4)

data/README.md

@@ -67,6 +67,114 @@ $ vtk socks off
 ----> Disconnected from SOCKS.
 ```
     
+### Scan
+
+Security scanning commands for detecting malware and vulnerabilities.
+
+---
+
+```
+$ vtk scan machine
+```
+
+The **machine subcommand** checks your local machine for signs of active Shai-Hulud malware infection. This is a fast (~5 second) check that looks for:
+
+- **Critical indicators**: `~/.dev-env/` persistence folder, malicious processes (Runner.Listener, SHA1HULUD), malware payload files
+- **High-risk indicators**: Exfiltration artifacts, unexpected Bun/Trufflehog installations
+- **Credential inventory**: Lists credential files that should be rotated if infected
+
+**Exit codes:**
+- `0` - Clean (no infection indicators)
+- `1` - Infected (critical indicators found)
+- `2` - Warning (needs investigation)
+
+**Options:**
+- `--verbose` / `-v` - Detailed output with all checks
+- `--quiet` / `-q` - Exit code only, no output
+- `--json` / `-j` - JSON output format
+
+Example:
+```
+$ vtk scan machine --quiet && echo "Clean" || echo "Check machine!"
+```
+
+#### Windows (PowerShell)
+
+For Windows users, standalone PowerShell scripts are available that don't require Ruby or the vtk gem.
+
+**Requirements:** PowerShell 5.1+ (ships with Windows 10/11). PowerShell 7+ recommended for best experience.
+
+**Download and run:**
+
+```powershell
+# Machine scanner - checks for active infection
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/department-of-veterans-affairs/vtk/master/scripts/shai-hulud-machine-check.ps1" -OutFile "shai-hulud-machine-check.ps1"
+
+# Allow script execution (if needed)
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Run the scanner
+.\shai-hulud-machine-check.ps1
+.\shai-hulud-machine-check.ps1 -Verbose  # Detailed output
+.\shai-hulud-machine-check.ps1 -Json     # JSON output
+```
+
+**Repository scanner** - checks lockfiles for compromised packages:
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/department-of-veterans-affairs/vtk/master/scripts/shai-hulud-repo-check.ps1" -OutFile "shai-hulud-repo-check.ps1"
+
+.\shai-hulud-repo-check.ps1                    # Scan current directory
+.\shai-hulud-repo-check.ps1 -Path C:\Code\app  # Scan specific directory
+.\shai-hulud-repo-check.ps1 -Recursive         # Recursive scan
+```
+
+**Credential audit** - lists credentials that may need rotation:
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/department-of-veterans-affairs/vtk/master/scripts/credential-audit.ps1" -OutFile "credential-audit.ps1"
+
+.\credential-audit.ps1
+.\credential-audit.ps1 -Verbose  # Show all checks
+```
+
+---
+
+```
+$ vtk scan credentials
+```
+
+The **credentials subcommand** audits which credentials are present on your machine and provides rotation instructions for each. Run this after a suspected or confirmed security incident.
+
+**What it checks:**
+- **NPM**: `~/.npmrc`, `$NPM_TOKEN`, `$NPM_CONFIG_TOKEN`
+- **AWS**: `~/.aws/credentials`, `~/.aws/config`, `$AWS_ACCESS_KEY_ID`, `$AWS_SECRET_ACCESS_KEY`
+- **GCP**: `~/.config/gcloud/application_default_credentials.json`, `$GOOGLE_APPLICATION_CREDENTIALS`
+- **Azure**: `~/.azure/` directory, `$AZURE_CLIENT_SECRET`
+- **GitHub**: `~/.config/gh/hosts.yml`, `$GITHUB_TOKEN`, `$GH_TOKEN`, `~/.git-credentials`
+- **SSH**: Private keys in `~/.ssh/`
+- **Docker**: `~/.docker/config.json`
+- **Kubernetes**: `~/.kube/config`
+- **Environment**: Sensitive env vars (token, secret, password, etc.)
+
+**Exit codes:**
+- `0` - No credentials found
+- `1` - Credentials found (rotation recommended)
+
+**Options:**
+- `--verbose` / `-v` - Show all checks including clean ones
+- `--json` / `-j` - JSON output format
+
+Example:
+```
+$ vtk scan credentials --json | jq -r '.credentials[].service' | sort -u
+AWS
+GitHub
+SSH
+```
+
+---
+
 ### Help
 
 For helpful information about commands and subcommands run the following:
@@ -74,6 +182,7 @@ For helpful information about commands and subcommands run the following:
     $ vtk -h
     $ vtk module -h
     $ vtk socks -h
+    $ vtk scan -h
 
 ### Docker
 

data/lib/vtk/cli.rb

@@ -23,5 +23,8 @@ module Vtk
 
     require_relative 'commands/module'
     register Vtk::Commands::Module, 'module', 'module [SUBCOMMAND]', 'Command description...'
+
+    require_relative 'commands/scan'
+    register Vtk::Commands::Scan, 'scan', 'scan [SUBCOMMAND]', 'Security scanning for malware and vulnerabilities'
   end
 end

data/lib/vtk/commands/scan/README.md

@@ -0,0 +1,102 @@
+# VTK Scan Commands
+
+Security scanning commands for detecting Shai-Hulud malware and supply chain compromises.
+
+## Commands
+
+### `vtk scan machine`
+
+Quick check for active malware infection on your developer machine.
+
+```bash
+vtk scan machine              # Compact output
+vtk scan machine --verbose    # Detailed checks
+vtk scan machine --json       # JSON output
+vtk scan machine --quiet      # Exit code only
+```
+
+**What it checks:**
+- `~/.dev-env/` persistence folder (critical indicator)
+- Malicious processes (Runner.Listener, SHA1HULUD)
+- Malware files (setup_bun.js, bun_environment.js)
+- Exfiltration artifacts
+- Unexpected Bun/Trufflehog installations
+
+**Exit codes:**
+- `0` - Clean
+- `1` - Infected (critical indicators found)
+- `2` - Warning (needs investigation)
+
+### `vtk scan repo [PATH]`
+
+Scan a repository for compromised npm packages and backdoor workflows.
+
+```bash
+vtk scan repo                      # Scan current directory
+vtk scan repo /path/to/repo        # Scan specific path
+vtk scan repo -r                   # Recursive scan (default depth: 5)
+vtk scan repo -r --depth=10        # Recursive with custom depth
+vtk scan repo -r --depth=0         # Recursive with unlimited depth
+vtk scan repo -v                   # Verbose output (show each lockfile)
+vtk scan repo --refresh            # Force refresh package list
+vtk scan repo --json               # JSON output
+vtk scan repo -r --json            # JSONL output (streaming)
+vtk scan repo --quiet              # Exit code only
+```
+
+**What it checks:**
+- Lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml) against 1,600+ known compromised packages
+- Backdoor workflows (.github/workflows/discussion.yaml)
+- Secrets extraction workflows (.github/workflows/formatter_*.yml)
+
+**Exit codes:**
+- `0` - Clean
+- `1` - Compromised packages found
+- `2` - Backdoor workflow found
+
+**Output formats:**
+
+JSON (`--json`) - Single JSON object for non-recursive scans:
+```json
+{"path":"/repo","status":"CLEAN","packages_scanned":2595,"compromised_packages":[],...}
+```
+
+JSONL (`-r --json`) - One JSON line per lockfile as scanned (streaming):
+```
+{"lockfile":"/repo/yarn.lock","packages_scanned":2595,"status":"CLEAN","compromised_packages":[]}
+{"lockfile":"/repo/app/package-lock.json","packages_scanned":100,"status":"CLEAN","compromised_packages":[]}
+{"type":"summary","status":"CLEAN","total_packages_scanned":2695,...}
+```
+
+## Data Sources
+
+The compromised packages list is fetched from [Cobenian/shai-hulud-detect](https://github.com/Cobenian/shai-hulud-detect) and cached locally for 24 hours.
+
+**Cache location:** `$XDG_CACHE_HOME/vtk/compromised-packages.txt` (defaults to `~/.cache/vtk/`)
+
+## Standalone Scripts
+
+Both scan commands are available as standalone shell scripts that work without vtk installed. These are useful for CI/CD pipelines or machines without Ruby.
+
+```bash
+# Machine scan
+./scripts/shai-hulud-machine-check.sh
+./scripts/shai-hulud-machine-check.sh --json
+
+# Repo scan
+./scripts/shai-hulud-repo-check.sh /path/to/repo
+./scripts/shai-hulud-repo-check.sh -r ~/Code    # Scan all projects
+./scripts/shai-hulud-repo-check.sh -r --json    # JSONL output
+```
+
+## Known Limitations
+
+- **pnpm-lock.yaml** - Parsing tested with pnpm v6/v7/v9; other versions may vary
+- **node_modules** - Not scanned directly; lockfile is the source of truth (by design)
+- **Short flags** - Cannot be combined in shell script (use `-r -j` not `-rj`)
+
+## References
+
+- [Datadog: Shai-Hulud 2.0 npm Worm](https://securitylabs.datadoghq.com/articles/shai-hulud-2.0-npm-worm/)
+- [Cobenian/shai-hulud-detect](https://github.com/Cobenian/shai-hulud-detect)
+- [VA Cleanup Playbook](https://department-of-veterans-affairs.github.io/eert/shai-hulud-dev-machine-cleanup-playbook)

data/lib/vtk/commands/scan/credentials.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative '../../command'
+
+module Vtk
+  module Commands
+    class Scan
+      # Audit credentials that may have been accessed by Shai-Hulud malware
+      class Credentials < Vtk::Command
+        attr_reader :options
+
+        def initialize(options)
+          @options = options
+          super()
+        end
+
+        OPTION_FLAGS = {
+          verbose: '--verbose',
+          json: '--json'
+        }.freeze
+
+        def execute(output: $stdout)
+          @output = output
+
+          script_path, gem_root = find_script
+          return script_not_found(output, gem_root) unless script_path
+
+          run_script(script_path)
+        end
+
+        private
+
+        def script_not_found(output, gem_root)
+          output.puts 'ERROR: Could not find credential-audit.sh script'
+          output.puts "Expected at: #{gem_root}/scripts/credential-audit.sh"
+          1
+        end
+
+        def run_script(script_path)
+          cmd = ['bash', script_path]
+          cmd += OPTION_FLAGS.filter_map { |key, flag| flag if options[key] }
+
+          system(*cmd)
+          $CHILD_STATUS.exitstatus
+        end
+
+        def find_script
+          gem_root = File.expand_path('../../../..', __dir__)
+          script_path = File.join(gem_root, 'scripts', 'credential-audit.sh')
+
+          return [script_path, gem_root] if File.exist?(script_path)
+
+          [nil, gem_root]
+        end
+      end
+    end
+  end
+end

data/lib/vtk/commands/scan/machine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative '../../command'
+
+module Vtk
+  module Commands
+    class Scan
+      # Check for active malware infection indicators (Shai-Hulud)
+      class Machine < Vtk::Command
+        attr_reader :options
+
+        def initialize(options)
+          @options = options
+          super()
+        end
+
+        def execute(output: $stdout)
+          @output = output
+
+          script_path, gem_root = find_script
+          return script_not_found(output, gem_root) unless script_path
+
+          run_script(script_path)
+        end
+
+        private
+
+        def script_not_found(output, gem_root)
+          output.puts 'ERROR: Could not find shai-hulud-machine-check.sh script'
+          output.puts "Expected at: #{gem_root}/scripts/shai-hulud-machine-check.sh"
+          1
+        end
+
+        def run_script(script_path)
+          cmd = ['bash', script_path]
+          cmd << '--verbose' if options[:verbose]
+          cmd << '--json' if options[:json]
+          cmd << '--quiet' if options[:quiet]
+          cmd << "--scan-dirs=#{options[:scan_dirs]}" if options[:scan_dirs]
+
+          system(*cmd)
+          $CHILD_STATUS.exitstatus
+        end
+
+        def find_script
+          # Look for script relative to this gem's location
+          # __dir__ = lib/vtk/commands/scan, so go up 4 levels to get to vtk root
+          gem_root = File.expand_path('../../../..', __dir__)
+          script_path = File.join(gem_root, 'scripts', 'shai-hulud-machine-check.sh')
+
+          # Use explicit bash interpreter, so executable bit not required
+          return [script_path, gem_root] if File.exist?(script_path)
+
+          [nil, gem_root]
+        end
+      end
+    end
+  end
+end

data/lib/vtk/commands/scan/repo.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative '../../command'
+
+module Vtk
+  module Commands
+    class Scan
+      # Scan a repository for compromised packages and backdoor workflows
+      # Shells out to shai-hulud-repo-check.sh for the actual scanning
+      class Repo < Vtk::Command
+        OPTION_FLAGS = {
+          refresh: '--refresh',
+          json: '--json',
+          quiet: '--quiet',
+          verbose: '--verbose',
+          recursive: '--recursive'
+        }.freeze
+
+        attr_reader :options, :path
+
+        def initialize(path, options)
+          @path = path || Dir.pwd
+          @options = options
+          super()
+        end
+
+        def execute(output: $stdout)
+          @output = output
+
+          unless File.directory?(@path)
+            output.puts "ERROR: Directory not found: #{@path}"
+            return 1
+          end
+
+          script_path, gem_root = find_script
+          return script_not_found(output, gem_root) unless script_path
+
+          run_script(script_path)
+        end
+
+        private
+
+        def script_not_found(output, gem_root)
+          output.puts 'ERROR: Could not find shai-hulud-repo-check.sh script'
+          output.puts "Expected at: #{gem_root}/scripts/shai-hulud-repo-check.sh"
+          1
+        end
+
+        def run_script(script_path)
+          cmd = ['bash', script_path] + script_options + [@path]
+          system(*cmd)
+          $CHILD_STATUS.exitstatus
+        end
+
+        def script_options
+          # Use select + map instead of filter_map for Ruby 2.6 compatibility
+          flags = OPTION_FLAGS.select { |key, _flag| options[key] }.values
+          flags << "--depth=#{options[:depth]}" if options[:depth]
+          flags
+        end
+
+        def find_script
+          # Look for script relative to this gem's location
+          # __dir__ = lib/vtk/commands/scan, so go up 4 levels to get to vtk root
+          gem_root = File.expand_path('../../../..', __dir__)
+          script_path = File.join(gem_root, 'scripts', 'shai-hulud-repo-check.sh')
+
+          # Use explicit bash interpreter, so executable bit not required
+          return [script_path, gem_root] if File.exist?(script_path)
+
+          [nil, gem_root]
+        end
+      end
+    end
+  end
+end

data/lib/vtk/commands/scan.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Vtk
+  module Commands
+    # Security scanning commands for developer machines and repositories
+    class Scan < Thor
+      namespace :scan
+
+      desc 'machine', 'Check for active malware infection indicators (Shai-Hulud)'
+      method_option :help, aliases: '-h', type: :boolean,
+                           desc: 'Display usage information'
+      method_option :verbose, aliases: '-v', type: :boolean,
+                              desc: 'Detailed output with all checks'
+      method_option :json, aliases: '-j', type: :boolean,
+                           desc: 'Output results as JSON'
+      method_option :quiet, aliases: '-q', type: :boolean,
+                            desc: 'Exit code only, no output'
+      method_option :scan_dirs, type: :string,
+                                desc: 'Additional directories to scan for backdoor workflows (comma-separated)'
+      def machine
+        if options[:help]
+          invoke :help, ['machine']
+        else
+          require_relative 'scan/machine'
+          exit_status = Vtk::Commands::Scan::Machine.new(options).execute
+          exit exit_status
+        end
+      end
+
+      desc 'repo [PATH]', 'Scan a repository for compromised packages'
+      method_option :help, aliases: '-h', type: :boolean,
+                           desc: 'Display usage information'
+      method_option :refresh, type: :boolean,
+                              desc: 'Force refresh of compromised packages list'
+      method_option :json, aliases: '-j', type: :boolean,
+                           desc: 'Output results as JSON'
+      method_option :quiet, aliases: '-q', type: :boolean,
+                            desc: 'Exit code only, no output'
+      method_option :verbose, aliases: '-v', type: :boolean,
+                              desc: 'Show each lockfile as it is scanned'
+      method_option :recursive, aliases: '-r', type: :boolean,
+                                desc: 'Recursively scan subdirectories (default depth: 5)'
+      method_option :depth, type: :numeric, default: 5,
+                            desc: 'Max directory depth for recursive scan (0=unlimited)'
+      def repo(path = nil)
+        if options[:help]
+          invoke :help, ['repo']
+        else
+          require_relative 'scan/repo'
+          exit_status = Vtk::Commands::Scan::Repo.new(path, options).execute
+          exit exit_status
+        end
+      end
+
+      desc 'credentials', 'Audit credentials that may need rotation after a security incident'
+      method_option :help, aliases: '-h', type: :boolean,
+                           desc: 'Display usage information'
+      method_option :verbose, aliases: '-v', type: :boolean,
+                              desc: 'Show all checks including clean ones'
+      method_option :json, aliases: '-j', type: :boolean,
+                           desc: 'Output results as JSON'
+      def credentials
+        if options[:help]
+          invoke :help, ['credentials']
+        else
+          require_relative 'scan/credentials'
+          exit_status = Vtk::Commands::Scan::Credentials.new(options).execute
+          exit exit_status
+        end
+      end
+    end
+  end
+end

data/lib/vtk/commands/socks/setup.rb

@@ -208,7 +208,7 @@ module Vtk
           @repo_url ||= begin
             keyscan_github_com
 
-            if github_ssh_configured
+            if github_ssh_configured?
               'git@github.com:department-of-veterans-affairs/devops.git'
             else
               'https://github.com/department-of-veterans-affairs/devops.git'
@@ -222,7 +222,7 @@ module Vtk
           `ssh-keyscan -H github.com >> ~/.ssh/known_hosts 2> /dev/null`
         end
 
-        def github_ssh_configured
+        def github_ssh_configured?
           !`ssh -T git@github.com 2>&1`.include?('Permission denied')
         end
 
@@ -460,8 +460,8 @@ module Vtk
           return true if `gsettings get org.gnome.system.proxy mode` == "'auto'\n"
 
           log 'Configuring system proxy to use SOCKS tunnel...' do
-            `gsettings set org.gnome.system.proxy mode 'auto'` &&
-              `gsettings set org.gnome.system.proxy autoconfig-url "#{PROXY_URL}"`
+            system("gsettings set org.gnome.system.proxy mode 'auto'") &&
+              system("gsettings set org.gnome.system.proxy autoconfig-url '#{PROXY_URL}'")
           end
         end
 

data/lib/vtk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vtk
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
 end