claws-scan 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06dc58b6a6cca01d4a26c696c0ad84ee026a850ecb154e5363ac87fe056c132
-  data.tar.gz: '006479039bafbefb2c33c15324c645b48a8dc36a607a6ac78c1922de273621f4'
+  metadata.gz: 5f4c3263217e12165f1f7c89c402a4e9cf1085ccfca4d4ab8316d9693569a8bb
+  data.tar.gz: f1bab1dd428690f47e8e81d97892e47d9cd2764233eb93c44f0f704f030e86e0
 SHA512:
-  metadata.gz: 162535cf6679e3ac35a352ddf4c8389063e9196f848707cf23dab847b2d42dae26803f2918418c13a8e50432fc0a74138eb44d61535692e01c1ff92a70291e06
-  data.tar.gz: 92d781d858a2da50fd81f4c9b1da5c2dab822e0dc9c9f4d69044e193481842b107e151d2dad8580233996e548c45b2e58fdd6bec47f4d4df56f076b35d858eed
+  metadata.gz: 766245e17380af395539025794b2461be4be0aa54ab20e8b3fbfb1128032c1228155e398d25bfb6295bd1050ca30d708a3408107b27d006874fa85fd94befc46
+  data.tar.gz: 6ba57d659080d29788dd8de41ff88f4aa6bacb7b2ba2ef0332714e85c13dd111ebe6745bf4b894ce3e905ced0a1cd2a688d200c33447ad06a728633bf8200943

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2.3
 
 Style/StringLiterals:
   Enabled: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    claws-scan (0.8.0)
+    claws-scan (0.9.0)
       equation (~> 0.6)
       pry
       slop (~> 4.9)

data/README.md

@@ -8,6 +8,82 @@ This is in contrast to common static analysis tools that achieve this by requiri
 
 While it's important to be able to easily write a Rule, it's just as important (if not more!) to write good tests for them. Like with Rubocop, Claws comes with a couple RSpec helpers that makes it easy to write test cases. Test cases are simply example Workflows that exercise a Rule's expressions, ensuring that a modification to a Rule can't accidentally affect its ability to detect known bad content.
 
+## Getting Started
+
+Claws is written in Ruby and distributed as a Ruby Gem, so you can install it using `gem`. Just point it at the [example configuration](example-config.yml) file and you should be good to go.
+
+For one off scans, you can just follow these commands:
+```
+# Install claws
+$ gem install claws-scan
+
+# Optionally, specify a version
+$ gem install claws-scan -v 0.7.5
+
+# Scan a Github Action file
+analyze -c example_config.yml -t .github/workflows/ci.yml
+```
+
+If you'd like to integrate this into your workflow like we have, this should be enough to get you started.
+
+```yaml
+name: Workflow Static Analyzer
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Analyze Github Workflows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set Up Ruby
+        uses: ruby/setup-ruby@d8d83c3960843afb664e821fed6be52f37da5267 # v1.231.0
+        with:
+          ruby-version: '3.0'
+      # Grab your configuration file however makes sense for you
+      # We keep ours in a separate Github repo.
+      - name: Set Up Claws Config
+        run: |
+          echo ... > /tmp/claws-config.yml
+      # Optional, useful if you want Claws to run shellcheck for you
+      - name: Set Up Shellcheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set Up Claws
+        run: |
+          gem install claws-scan -v 0.7.5
+      - name: Analyze Workflows
+        run: |
+          #!/bin/bash
+
+          # Collect all files in the .github/workflows directory
+          workflow_files=$(find .github/workflows -type f)
+
+          # Exit early if there are no workflow files
+          if [[ -z "$workflow_files" ]]; then
+            echo "No workflow files found in .github/workflows"
+            exit 0
+          fi
+
+          flags=()
+
+          # Iterate over each workflow file
+          while IFS= read -r file; do
+            echo "Processing $file"
+            flags+=("-t" "$file")
+          done <<< "$workflow_files"
+
+          # Run the analyze command with all gathered flags
+          analyze -f github -c /tmp/claws-config.yml "${flags[@]}"
+```
+
 ## Built In Rules
 
 These are all the rules that come out of the box with Claws. They can all be found in [the rules subdirectory](https://github.com/Betterment/claws/tree/main/lib/claws/rule), and some of them have configuration options.
@@ -204,6 +280,18 @@ Shellcheck is a great tool for dealing with bugs or otherwise unintended effects
 
 This rule flags workflows that request write access to specific unusual permissions. While this rule cannot flag how these permissions are exercised, it serves as a warning to code reviewers that if these permissions are requested, the way they are used should be scrutinized. A reviewer may find that a permission is left over from testing and no longer needed, or that a specific permission was never needed.
 
+### CheckoutWithStaticCredentials
+
+This rule flags any uses of `actions/checkout` using static credentials. Using static credentials can pose a risk because these credentials are typically not auditable and can be tricky to rotate. In the event of an incident where they are leaked, incident response to determine the scope of impact may be tough.
+
+Where possible, the default `$GITHUB_TOKEN` should be used. Its settings can be configured directly from within the workflow. Check [the official documentation](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token) for more information on how to do this.
+
+If you are using a deploy key via SSH to access a package or otherwise an artifact from another repository, you can instead configure the repository to grant it access explicitly to that other repository. This will give the default `$GITHUB_TOKEN` access to that repository without needing to use a deploy key. To learn more about this, [check out the official documentation](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). This is safer than a static deploy key because the credential is short lived and access can be audited.
+
+If you need a Github Token to perform some authenticated action where the default `$GITHUB_TOKEN` doesn't do what you need, consider setting up a Github App and using [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token). This will generate a short lived access token, and using an app creates a useful audit trail for what this access token can actually do. Then, use this token in just the build steps where it's needed.
+
+In some cases, a static access token or deploy key may still be necessary, especially for APIs that are not yet supported by Github App Tokens. In these cases, make sure to limit the scope of the access token to the bare minimum necessary to function.
+
 ### UnapprovedRunners
 
 This rule flags workflows that use runners that they might not need or should not use. This can come in handy when an organization has available self hosted or otherwise expensive runners but wants to be particular about when they're used.

data/bin/analyze

@@ -5,7 +5,7 @@ require "claws"
 require "slop"
 
 flags = Slop::Options.new
-flags.banner =  "usage: process [options] ..."
+flags.banner =  "usage: analyze [options] ..."
 flags.separator ""
 flags.separator "Options:"
 flags.string "-c", "--config", required: true

data/example-config.yml

@@ -0,0 +1,17 @@
+Enabled:
+  NoContainers:
+    approved_images: ["ubuntu-latest"]
+  SpecialPermissions:
+  EmptyName:
+  RiskyTriggers:
+  UnapprovedRunners:
+    allowed_runners: ["ubuntu-latest", "macos-latest"]
+  CommandInjection:
+  AutomaticMerge:
+  UnpinnedAction:
+    trusted_authors: ["actions"]
+  UnsafeCheckout:
+  InheritedSecrets:
+  BulkPermissions:
+  Shellcheck:
+    shellcheck_bin: "/usr/bin/shellcheck"

data/lib/claws/application.rb

@@ -43,10 +43,10 @@ module Claws
       @detections.each do |detection|
         detection.on_workflow.each do |rule|
           violation = run_detection(
-            filename: filename,
-            detection: detection,
-            rule: rule,
-            workflow: workflow
+            filename:,
+            detection:,
+            rule:,
+            workflow:
           )
 
           violations << violation if violation
@@ -58,7 +58,7 @@ module Claws
             expression: rule[:expression],
             values: {
               data: detection.data,
-              workflow: workflow
+              workflow:
             }
           )
         end
@@ -72,11 +72,11 @@ module Claws
       @detections.each do |detection|
         detection.on_job.each do |rule|
           violation = run_detection(
-            filename: filename,
-            detection: detection,
-            rule: rule,
-            workflow: workflow,
-            job: job
+            filename:,
+            detection:,
+            rule:,
+            workflow:,
+            job:
           )
 
           violations << violation if violation
@@ -88,8 +88,8 @@ module Claws
             expression: rule[:expression],
             values: {
               data: detection.data,
-              workflow: workflow,
-              job: job
+              workflow:,
+              job:
             }
           )
         end
@@ -104,12 +104,12 @@ module Claws
       @detections.each do |detection|
         detection.on_step.each do |rule|
           violation = run_detection(
-            filename: filename,
-            detection: detection,
-            rule: rule,
-            workflow: workflow,
-            job: job,
-            step: step
+            filename:,
+            detection:,
+            rule:,
+            workflow:,
+            job:,
+            step:
           )
 
           violations << violation if violation
@@ -121,9 +121,9 @@ module Claws
             expression: rule[:expression],
             values: {
               data: detection.data,
-              workflow: workflow,
-              job: job,
-              step: step
+              workflow:,
+              job:,
+              step:
             }
           )
         end
@@ -137,19 +137,19 @@ module Claws
     def run_detection(filename:, detection:, rule:, workflow:, job: nil, step: nil) # rubocop:disable Metrics/ParameterLists
       violation = if rule.is_a? Symbol
                     get_dynamic_violation(
-                      detection: detection,
+                      detection:,
                       method: rule,
-                      workflow: workflow,
-                      job: job,
-                      step: step
+                      workflow:,
+                      job:,
+                      step:
                     )
                   else
                     get_static_violations(
-                      detection: detection,
-                      rule: rule,
-                      workflow: workflow,
-                      job: job,
-                      step: step
+                      detection:,
+                      rule:,
+                      workflow:,
+                      job:,
+                      step:
                     )
                   end
 
@@ -164,18 +164,18 @@ module Claws
     def get_dynamic_violation(detection:, method:, workflow:, job:, step:)
       detection.send(
         method,
-        workflow: workflow,
-        job: job,
-        step: step
+        workflow:,
+        job:,
+        step:
       )
     end
 
     def get_static_violations(rule:, detection:, workflow:, job:, step:)
       result = rule[:expression].eval_with(values: {
                                              data: detection.data,
-                                             workflow: workflow,
-                                             job: job,
-                                             step: step
+                                             workflow:,
+                                             job:,
+                                             step:
                                            })
 
       return unless result

data/lib/claws/base_rule.rb

@@ -14,6 +14,7 @@ class BaseRule
               endswith: ->(string, needle) { string.to_s.end_with? needle },
               difference: ->(arr1, arr2) { arr1.difference arr2 },
               intersection: ->(arr1, arr2) { arr1.intersection arr2 },
+              get_key: ->(arr, key) { (arr || {}).fetch(key, nil) },
               count: ->(n) { n.length }
             }
           )
@@ -45,23 +46,23 @@ class BaseRule
   end
 
   def self.on_workflow(value, highlight: nil, debug: false)
-    (@on_workflow ||= []) << extract_value(value, highlight: highlight, debug: debug)
+    (@on_workflow ||= []) << extract_value(value, highlight:, debug:)
   end
 
   def self.on_job(value, highlight: nil, debug: false)
     highlight = highlight.to_s unless highlight.nil?
-    (@on_job ||= []) << extract_value(value, highlight: highlight, debug: debug)
+    (@on_job ||= []) << extract_value(value, highlight:, debug:)
   end
 
   def self.on_step(value, highlight: nil, debug: false)
     highlight = highlight.to_s unless highlight.nil?
-    (@on_step ||= []) << extract_value(value, highlight: highlight, debug: debug)
+    (@on_step ||= []) << extract_value(value, highlight:, debug:)
   end
 
   def self.extract_value(value, highlight: nil, debug: false)
     case value
     when String
-      { expression: parse_rule(value), highlight: highlight, debug: debug }
+      { expression: parse_rule(value), highlight:, debug: }
     when Symbol
       value
     else

data/lib/claws/cli/yaml_with_lines.rb

@@ -18,7 +18,9 @@ module Psych
     class ToRuby
       def accept(target)
         s = super(target)
-        if target.respond_to?(:line) and ![TrueClass, FalseClass, NilClass, Integer].include? s.class
+
+        # types that we cannot monkey patch into holding line information
+        if target.respond_to?(:line) and ![TrueClass, FalseClass, NilClass, Integer, Float].include? s.class
           s.instance_eval do
             extend(Locatable)
           end
@@ -49,7 +51,9 @@ module Psych
           key.line = 0 if key.respond_to? :line and key.line.nil?
           key.line += 1 if key.respond_to? :line
           key.freeze
-          if [TrueClass, FalseClass, NilClass, Integer].include? key.class
+
+          # types that we cannot monkey patch into holding line information
+          if [TrueClass, FalseClass, NilClass, Integer, Float].include? key.class
             val.line = 0 if val.respond_to? :line and val.line.nil?
             val.line += 1 if val.respond_to? :line
           end

data/lib/claws/rule/checkout_with_static_credentials.rb

@@ -0,0 +1,38 @@
+module Claws
+  module Rule
+    class CheckoutWithStaticCredentials < BaseRule
+      description <<~DESC
+        Avoid using static credentials like deploy keys, SSH keys, or personal access
+        tokens to clone other repositories. Static credentials can be tricky to audit
+        and rotate, making them risky to hold onto, especially in the event of an
+        incident where they may be leaked.
+
+        Either grant your repository access directly to other repositories, or use a
+        Github App to generate a short lived access token.
+
+        For more information:
+        https://github.com/betterment/claws/blob/main/README.md#checkoutwithstaticcredentials
+      DESC
+
+      on_step %(
+        $step.meta.action.name == "actions/checkout" &&
+        (
+          get_key($step.with, "ssh-key") =~ "{{.*secrets\..*" ||
+          get_key($step.with, "ssh-key") =~ "{{.*env\..*" ||
+          get_key($step.with, "ssh-key") =~ "{{.*vars\..*" ||
+          get_key($step.with, "ssh-key") =~ ".*-----BEGIN.*"
+        )
+      ), highlight: "with.ssh-key"
+
+      on_step %(
+        $step.meta.action.name == "actions/checkout" &&
+        (
+          get_key($step.with, "token") =~ "{{.*secrets\..*" ||
+          get_key($step.with, "token") =~ "{{.*env\..*" ||
+          get_key($step.with, "token") =~ "{{.*vars\..*" ||
+          get_key($step.with, "token") =~ "gh[a-z]_.*"
+        )
+      ), highlight: "with.token"
+    end
+  end
+end

data/lib/claws/rule/command_injection.rb

@@ -8,7 +8,7 @@ module Claws
         https://github.com/betterment/claws/blob/main/README.md#commandinjection
       DESC
 
-      on_step '$step.run =~ ".*{{[ ]+.*(github.event|inputs).*}}.*"', highlight: "run"
+      on_step '$step.run =~ ".*{{.*(github\.event|inputs)\..*}}.*"', highlight: "run"
     end
   end
 end

data/lib/claws/rule.rb

@@ -11,3 +11,4 @@ require "claws/rule/inherited_secrets"
 require "claws/rule/command_injection"
 require "claws/rule/bulk_permissions"
 require "claws/rule/shellcheck"
+require "claws/rule/checkout_with_static_credentials"

data/lib/claws/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Claws
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/claws/workflow.rb

@@ -173,7 +173,7 @@ class Workflow
     name, version = action.split("@", 2)
     author = name.split("/", 2)[0]
     local = author == "."
-    { type: "action", name: name, author: author, version: version, local: local }
+    { type: "action", name:, author:, version:, local: }
   end
 
   def extract_container_info_from_job(job)
@@ -195,8 +195,8 @@ class Workflow
 
     {
       type: "container",
-      image: image,
-      version: version,
+      image:,
+      version:,
       full: "#{image}:#{version}"
     }
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claws-scan
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Omar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-08 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: equation
@@ -85,6 +85,7 @@ files:
 - Rakefile
 - bin/analyze
 - config.yml
+- example-config.yml
 - lib/claws.rb
 - lib/claws/application.rb
 - lib/claws/base_rule.rb
@@ -97,6 +98,7 @@ files:
 - lib/claws/rule.rb
 - lib/claws/rule/automatic_merge.rb
 - lib/claws/rule/bulk_permissions.rb
+- lib/claws/rule/checkout_with_static_credentials.rb
 - lib/claws/rule/command_injection.rb
 - lib/claws/rule/empty_name.rb
 - lib/claws/rule/inherited_secrets.rb
@@ -123,7 +125,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="