claws-scan 0.9.0 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f4c3263217e12165f1f7c89c402a4e9cf1085ccfca4d4ab8316d9693569a8bb
-  data.tar.gz: f1bab1dd428690f47e8e81d97892e47d9cd2764233eb93c44f0f704f030e86e0
+  metadata.gz: 99e68a15fab38b583b1b9c34717ef25f2a1612f0da8b0bf50d5b0d4530829ce5
+  data.tar.gz: ca653965f7c90d93e2122d70ceb1a54e0c1a326d13d8cbbfbfaa8cadc8e01273
 SHA512:
-  metadata.gz: 766245e17380af395539025794b2461be4be0aa54ab20e8b3fbfb1128032c1228155e398d25bfb6295bd1050ca30d708a3408107b27d006874fa85fd94befc46
-  data.tar.gz: 6ba57d659080d29788dd8de41ff88f4aa6bacb7b2ba2ef0332714e85c13dd111ebe6745bf4b894ce3e905ced0a1cd2a688d200c33447ad06a728633bf8200943
+  metadata.gz: c1fbbe050665049b3a913681debe61e374d825197e3be5883e7bcbf3e0ea7818937700e576feba9fdd5fd0edb16798a9b2ce1c6a157781036324ff8b6ab4aa59
+  data.tar.gz: f715f4ea43b80cdc3d25a41554d30b0fcf88a3055e500f325c93f31a3d35020083cf45bcbff14cf10f9373952a8fb918da674fec2bb9aebf1b6c341a522a7eec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    claws-scan (0.9.0)
+    claws-scan (0.9.5)
       equation (~> 0.6)
       pry
       slop (~> 4.9)
@@ -10,21 +10,26 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.2)
     coderay (1.1.3)
     diff-lcs (1.5.0)
     equation (0.6.2)
     fakefs (2.3.0)
-    faraday (2.7.4)
-      faraday-net_http (>= 2.0, < 3.1)
-      ruby2_keywords (>= 0.0.4)
-    faraday-net_http (3.0.2)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
     faraday-retry (2.0.0)
       faraday (~> 2.0)
-    json (2.6.2)
+    json (2.21.2)
+    logger (1.7.0)
     method_source (1.0.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     octokit (6.0.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
@@ -35,11 +40,11 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (5.0.1)
+    public_suffix (7.0.5)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.0)
-    rexml (3.3.9)
+    rexml (3.4.2)
     rspec (3.11.0)
       rspec-core (~> 3.11.0)
       rspec-expectations (~> 3.11.0)
@@ -66,7 +71,6 @@ GEM
     rubocop-ast (1.23.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.5)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
@@ -74,12 +78,14 @@ GEM
     treetop (1.6.12)
       polyglot (~> 0.3)
     unicode-display_width (2.3.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -292,6 +292,12 @@ If you need a Github Token to perform some authenticated action where the defaul
 
 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.
 
+### StaticAwsCredentials
+
+This rule flags long-lived AWS credentials in Github workflows — not just `aws-actions/configure-aws-credentials`, but also `env:` blocks and common shell patterns (`export`, `aws configure set`). Static credentials stored in GitHub secrets, variables, or environment variables can be tricky to audit and rotate. In the event of an incident where they are leaked, incident response may be tough.
+
+Where possible, configure AWS to trust GitHub's OIDC provider and use `role-to-assume` to get short-lived credentials for each workflow run. Check [GitHub's documentation on configuring OIDC in AWS](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-for-github-actions/configuring-openid-connect-in-amazon-web-services) for setup instructions.
+
 ### 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.
@@ -395,6 +401,121 @@ This rule only looks for user supplied branches being checked out for `pull_requ
 |-------------|------------------------|---------------------------------------------------------------|
 | `risky_events` | ["pull_request_target", "workflow_dispatch"]               | An array of Github events you consider risky. |
 
+### ImplicitPersistCredentials
+
+By default, all versions of the official [`actions/checkout`](https://github.com/actions/checkout) have a default value of `true` for the `persist-credentials` setting. This means the temporary credentials generated to clone a repository's source code will be written to disk. This is necessary if you intend on using the `git` command line tool to further interact with this repository (e.g. check out a specific branch or push new commits to it). However, if you don't intend on doing this, this opens up an unnecessary risk. Untrusted or otherwise malicious code can find these temporary credentials and use them to access source code and other resources that would otherwise not have been exposed by your workflow. For example, if during a supply chain attack someone steals your job's environment variables, they may be able to use these credentials from their own system to access private repositories.
+
+For example, take the following workflow:
+
+```yaml
+name: Ruby CI (PR)
+
+on: [pull_request]
+
+jobs:
+  bundle-install:
+    name: Bundle install
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+
+      - name: Install dependencies
+        run: bundle install
+```
+
+Because `persist-credentials` is not specified, its value is `true` by default. That means the temporary Github credentials used to clone the repository will be either written to `.git/config` or to a temporary directory. Both of these locations will be accessible to subsequent steps, so if for example we were installing a malicious dependency with the `bundle install` command, it could find those credentials on disk and send them to someone via the network, letting them clone this repository and potentially access even other repositories. In this workflow, we aren't interacting with git beyond that checkout, so we don't need to persist the credential. We can fix this by setting `persist-credentials` to `false`:
+
+```yaml
+# ...
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+```
+
+However, if you do need to interact with the repository via git, you should explicitly set `persist-credentials` to `true`. This way, you signal to your reviewers that your workflow interacts with the local checkout in a way that needs this credential.
+
+Note, there is [a Github Issue tracking this](https://github.com/actions/checkout/issues/485) that has been open for a few years by now.
+
+### GlobalPermissionsBlock
+
+[The permissions block](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions) dictates which permissions a workflow or a job have or don't have. When permissions are defined at the workflow level, each job gets the same set of permissions, potentially giving more access than a job or a step truly needs. Instead, permissions should be defined at the job level, making sure each job and step has access only to the permissions it needs. This can minimize the impact of untrusted code using an overly permissive `$GITHUB_TOKEN`, such as during a supply chain attack.
+
+For example, take the following workflow:
+
+```yaml
+name: Build and Deploy
+
+on: [push]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    name: Build
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Upload build artifact to GitHub
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.ARTIFACT_NAME }}-${{ steps.meta.outputs.version }}
+          path: ${{ env.ARTIFACT_NAME }}.tgz
+
+  deploy:
+    name: Deploy
+    needs: build
+
+    steps:
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ env.ROLE_TO_ASSUME }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Upload release artifact to S3
+        run: |
+          aws s3 cp "${ARTIFACT_NAME}.tgz" "s3://${S3_BUCKET}/${{ needs.build.outputs.s3_key }}"
+```
+
+This sample workflow deploys to AWS using OIDC, so it needs the `id-token: write` permission to generate temporary AWS credentials. However, because this permission is defined at the workflow level, the `build` job can also use OIDC to grab temporary AWS credentials. This means if this job has some kind of vulnerability, an attacker could use it to gain access to an AWS environment that would otherwise have been entirely inaccessible.
+
+To remedy this, we should move the `permissions:` block into the specific job that actually needs this permission:
+
+```yaml
+# ...
+  deploy:
+    name: Deploy
+    needs: build
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ env.ROLE_TO_ASSUME }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Upload release artifact to S3
+        run: |
+          aws s3 cp "${ARTIFACT_NAME}.tgz" "s3://${S3_BUCKET}/${{ needs.build.outputs.s3_key }}"
+```
+
+This limits AWS OIDC access to just `deploy`.
+
 ## Walkthrough
 
 Let's start with a minimal configuration file that enables some basic Rules.

data/example-config.yml

@@ -7,6 +7,7 @@ Enabled:
   UnapprovedRunners:
     allowed_runners: ["ubuntu-latest", "macos-latest"]
   CommandInjection:
+  StaticAwsCredentials:
   AutomaticMerge:
   UnpinnedAction:
     trusted_authors: ["actions"]

data/lib/claws/base_rule.rb

@@ -1,10 +1,10 @@
 class BaseRule
   attr_accessor :on_workflow, :on_job, :on_step, :configuration
 
-  def self.parse_rule(rule) # rubocop:disable Metrics/AbcSize
+  def self.parse_rule(rule) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     ExpressionParser.parse_expression(rule).tap do |expression|
       expression.instance_eval do
-        def ctx # rubocop:disable Metrics/AbcSize
+        def ctx # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           @ctx ||= Context.new(
             default: {},
             methods: {
@@ -15,7 +15,28 @@ class BaseRule
               difference: ->(arr1, arr2) { arr1.difference arr2 },
               intersection: ->(arr1, arr2) { arr1.intersection arr2 },
               get_key: ->(arr, key) { (arr || {}).fetch(key, nil) },
-              count: ->(n) { n.length }
+              count: ->(n) { n.length },
+              dig: lambda { |object, path, default = nil|
+                # sometimes we might want to traverse the object as if it were a hash
+                # sometimes we might want to traverse it as a Ruby object
+                # annoying up front, but the edge cases are few and keeps expressions simple
+                path.to_s.split(".").reduce(object) do |current, part|
+                  return default if current.nil?
+
+                  if current.is_a?(Hash)
+                    # Prefer exact string key, then symbol key
+                    if current.key?(part)
+                      current[part]
+                    elsif current.key?(part.to_sym)
+                      current[part.to_sym]
+                    else
+                      default
+                    end
+                  else
+                    current.respond_to?(part) ? current.public_send(part) : default
+                  end
+                end
+              }
             }
           )
         end

data/lib/claws/rule/global_permissions_block.rb

@@ -0,0 +1,34 @@
+module Claws
+  module Rule
+    class GlobalPermissionsBlock < BaseRule
+      description <<~DESC
+        Permissions should be set at the job level, not globally at the workflow level.
+        Because jobs will often need varying permissions, it's better to specify a set
+        of permissions for each individual job, minimizing potential misuse from
+        untrusted code in a job with permissions it never needed in the first place.
+
+        This rule will flag workflows that have multiple jobs and a root level
+        permissions block. If there is a root level permissions block but just one job,
+        it will not be flagged.
+
+        For more information:
+        https://github.com/betterment/claws/blob/main/README.md#globalpermissionsblock
+      DESC
+
+      on_workflow :test_root_level_permissions
+
+      def test_root_level_permissions(workflow:, job:, step:) # rubocop:disable Lint/UnusedMethodArgument
+        root_permission_block_line = workflow.keys.filter { |x| x == "permissions" }.first&.line
+        return if root_permission_block_line.nil?
+
+        job_count = workflow["jobs"]&.count || 0
+        return if job_count < 2
+
+        Violation.new(
+          line: root_permission_block_line,
+          description:
+        )
+      end
+    end
+  end
+end

data/lib/claws/rule/implicit_persist_credentials.rb

@@ -0,0 +1,27 @@
+module Claws
+  module Rule
+    class ImplicitPersistCredentials < BaseRule
+      description <<~DESC
+        By default, actions/checkout will store generated credentials to disk so that
+        subsequent git operations will not require reauthentication. These credentials
+        will be available to subsequent steps and jobs. This may be undesirable and
+        potentially unsafe in scenarios where these credentials may be accessible to
+        untrusted code. In these cases, if these credentials are stolen they can be used
+        externally by an attacker to clone repositories that would otherwise have been
+        inaccessible.
+
+        If you know you will not need to access this repository for the rest of your
+        workflow, consider setting `persist-credentials` to false. Conversely,
+        explicitly set it to true if you know you will need these credentials.
+
+        For more information:
+        https://github.com/betterment/claws/blob/main/README.md#implicitpersistcredentials
+      DESC
+
+      on_step %(
+        $step.meta.action.name == "actions/checkout" &&
+        !contains([true, false], dig($step, "with.persist-credentials"))
+      ), highlight: "uses"
+    end
+  end
+end

data/lib/claws/rule/static_aws_credentials.rb

@@ -0,0 +1,54 @@
+module Claws
+  module Rule
+    class StaticAwsCredentials < BaseRule
+      description <<~DESC
+        Avoid using long-lived AWS secret access keys in Github workflows. 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.
+
+        Use GitHub's OIDC provider and authenticate with `role-to-assume` instead.
+
+        For more information:
+        https://github.com/betterment/claws/blob/main/README.md#staticawscredentials
+      DESC
+
+      on_workflow %(
+        get_key($workflow.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*secrets\..*" ||
+        get_key($workflow.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*env\..*" ||
+        get_key($workflow.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*vars\..*" ||
+        get_key($workflow.env, "AWS_SECRET_ACCESS_KEY") =~ "^[A-Za-z0-9/+=]+$"
+      ), highlight: "env.AWS_SECRET_ACCESS_KEY"
+
+      on_job %(
+        get_key($job.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*secrets\..*" ||
+        get_key($job.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*env\..*" ||
+        get_key($job.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*vars\..*" ||
+        get_key($job.env, "AWS_SECRET_ACCESS_KEY") =~ "^[A-Za-z0-9/+=]+$"
+      ), highlight: "env.AWS_SECRET_ACCESS_KEY"
+
+      on_step %(
+        $step.meta.action.name == "aws-actions/configure-aws-credentials" &&
+        (
+          get_key($step.with, "aws-secret-access-key") =~ "{{.*secrets\..*" ||
+          get_key($step.with, "aws-secret-access-key") =~ "{{.*env\..*" ||
+          get_key($step.with, "aws-secret-access-key") =~ "{{.*vars\..*" ||
+          get_key($step.with, "aws-secret-access-key") =~ "^[A-Za-z0-9/+=]+$"
+        )
+      ), highlight: "with.aws-secret-access-key"
+
+      on_step %(
+        get_key($step.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*secrets\..*" ||
+        get_key($step.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*env\..*" ||
+        get_key($step.env, "AWS_SECRET_ACCESS_KEY") =~ "{{.*vars\..*" ||
+        get_key($step.env, "AWS_SECRET_ACCESS_KEY") =~ "^[A-Za-z0-9/+=]+$"
+      ), highlight: "env.AWS_SECRET_ACCESS_KEY"
+
+      on_step %(
+        $step.run =~ "AWS_SECRET_ACCESS_KEY=['\\x22]?\\$\\{\\{\\s*(secrets\\.|vars\\.)" ||
+        $step.run =~ "aws configure set aws_secret_access_key\\s+\\$\\{\\{\\s*(secrets\\.|vars\\.)" ||
+        $step.run =~ "AWS_SECRET_ACCESS_KEY=['\\x22]?[A-Za-z0-9/+=]+" ||
+        $step.run =~ "aws configure set aws_secret_access_key\\s+[A-Za-z0-9/+=]+"
+      ), highlight: "run"
+    end
+  end
+end

data/lib/claws/rule.rb

@@ -12,3 +12,6 @@ require "claws/rule/command_injection"
 require "claws/rule/bulk_permissions"
 require "claws/rule/shellcheck"
 require "claws/rule/checkout_with_static_credentials"
+require "claws/rule/static_aws_credentials"
+require "claws/rule/implicit_persist_credentials"
+require "claws/rule/global_permissions_block"

data/lib/claws/version.rb

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

data/lib/claws/workflow.rb

@@ -4,7 +4,7 @@ require "claws/cli/yaml_with_lines"
 class Workflow
   extend Forwardable
 
-  attr_accessor :data, :on, :jobs, :name, :meta, :permissions
+  attr_accessor :data, :on, :jobs, :name, :meta, :permissions, :env
 
   def_delegators :@workflow, :get_line, :include?, :keys
 
@@ -19,6 +19,7 @@ class Workflow
     extract_normalized_jobs(@workflow)
     extract_normalized_name(@workflow)
     extract_permissions(@workflow)
+    extract_env(@workflow)
 
     @raw_yaml = raw_yaml
   end
@@ -35,6 +36,7 @@ class Workflow
     return @on if key.to_s == "on"
     return @jobs if key.to_s == "jobs"
     return @name if key.to_s == "name"
+    return @env if key.to_s == "env"
   end
 
   def get_snippet(line, context: 3)
@@ -92,6 +94,10 @@ class Workflow
     @meta["permissions"] = normalize_permissions(input["permissions"])
   end
 
+  def extract_env(input)
+    @env = input["env"]
+  end
+
   def normalize_permissions(input) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     permissions = {
       read: [],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claws-scan
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.5
 platform: ruby
 authors:
 - Omar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-26 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: equation
@@ -74,7 +74,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".policy.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -101,11 +100,14 @@ files:
 - lib/claws/rule/checkout_with_static_credentials.rb
 - lib/claws/rule/command_injection.rb
 - lib/claws/rule/empty_name.rb
+- lib/claws/rule/global_permissions_block.rb
+- lib/claws/rule/implicit_persist_credentials.rb
 - lib/claws/rule/inherited_secrets.rb
 - lib/claws/rule/no_containers.rb
 - lib/claws/rule/risky_triggers.rb
 - lib/claws/rule/shellcheck.rb
 - lib/claws/rule/special_permissions.rb
+- lib/claws/rule/static_aws_credentials.rb
 - lib/claws/rule/unapproved_runners.rb
 - lib/claws/rule/unpinned_action.rb
 - lib/claws/rule/unsafe_checkout.rb

data/.policy.yml

@@ -1,3 +0,0 @@
-remote: Betterment/policy-bot-config
-path: security-policy.yml
-ref: main