vtk 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c41b577facc94e32eb15aeea7f5817a49f54c31a568654c5dfe5da082d0775f9
-  data.tar.gz: 87820698519528ff97594bf9e148a0a20ca700026079a0fc2b65ede3bee84b19
+  metadata.gz: '0585f00ec9fe122942c5a249fd2733e47baa461960cc9d106e2dfb9ac13dc3aa'
+  data.tar.gz: c23b728a27d519e15812f8b95ffcf7e0aac20981e38cab59dca62c4a62582f21
 SHA512:
-  metadata.gz: 729f7b3a93dd61661ad557d471796a059ada830970afe16bbeef7bdf84e0e92887a321249c5ffc025db051fe71dfffb00fdec836382e3041392ae3ddcc9e5b59
-  data.tar.gz: eb5411ac4f245210470d310767fabd2e877759a5dcb023b00ae4925e8dcb4dec16f7637441433ca978d809d807734b18e4e51d901f69107e8291d186309d2ba3
+  metadata.gz: 0d10b96103db87af8754a1a1a3cb0fc6a268255f9c596baccf730f73c8a8ba03598a84cdcc8de35a53114710fe546e572a8f7ca4706efc8c45e7de3ce28aa115
+  data.tar.gz: 9e78a14e489d84f99a81725f7f93c03c3356d7165d7d79c871ade2cb61f2d462f8dae315f8b1f570ae7db4e84f0e9f0b4d7706f4d06dcc2c4622272025edf18d

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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)

data/README.md

@@ -98,6 +98,81 @@ 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

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/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

@@ -29,9 +29,47 @@ module Vtk
         end
       end
 
-      # Future subcommands:
-      # desc 'repos', 'Scan lockfiles for compromised packages'
-      # desc 'credentials', 'Inventory credentials that may need rotation'
+      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/version.rb

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