sentinel-ci 0.1.0

data/lib/rules/docker_build_arg_secrets.rb

@@ -0,0 +1,30 @@
+module Rules
+  class DockerBuildArgSecrets < Base
+    def name = "docker-build-arg-secrets"
+    def description = "Secrets passed as Docker build-args (visible in image layers)"
+    def severity = :high
+
+    def check(workflow)
+      findings = []
+
+      workflow.lines_of(/build-args:/).each do |line_num|
+        (line_num..(line_num + 20)).each do |i|
+          break if i > workflow.raw_lines.length
+          line = workflow.line_content(i)
+          break if line&.match?(/^\s*\w+:/) && !line.match?(/^\s+["']?[A-Z_]+=/)
+
+          if line&.match?(/secrets\./)
+            findings << finding(workflow,
+              line: i,
+              code: line.strip,
+              message: "Secret in Docker build-arg — extractable via docker history",
+              fix: "Use --secret flag or RUN --mount=type=secret instead of build-arg"
+            )
+          end
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/git_config_global.rb

@@ -0,0 +1,25 @@
+module Rules
+  class GitConfigGlobal < Base
+    def name = "git-config-global"
+    def description = "git config --global persists credentials beyond the repo clone"
+    def severity = :medium
+
+    def check(workflow)
+      findings = []
+
+      workflow.lines_of(/git config --global/).each do |line_num|
+        line = workflow.line_content(line_num)
+        next unless line&.match?(/insteadOf|url\.|credential/)
+
+        findings << finding(workflow,
+          line: line_num,
+          code: line.strip,
+          message: "git config --global writes credentials to ~/.gitconfig — accessible to all subsequent git operations",
+          fix: "Use --local instead of --global to scope to the repo clone"
+        )
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/missing_env_protection.rb

@@ -0,0 +1,37 @@
+module Rules
+  class MissingEnvProtection < Base
+    def name = "missing-env-protection"
+    def description = "Publish/deploy job without GitHub Environment protection"
+    def severity = :medium
+
+    PUBLISH_INDICATORS = /npm publish|pnpm publish|twine upload|gem push|docker push|railway up|cdk deploy/
+    OIDC_PUBLISH = /id-token:\s*write/
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |job_id, job|
+        next if job.key?("environment")
+
+        steps = workflow.steps(job)
+        has_publish = steps.any? { |s| s["run"]&.match?(PUBLISH_INDICATORS) }
+
+        job_perms = workflow.permissions(scope: :job, job: job)
+        has_oidc = job_perms&.to_s&.match?(OIDC_PUBLISH) ||
+                   workflow.permissions(scope: :workflow)&.to_s&.match?(OIDC_PUBLISH)
+
+        if has_publish || has_oidc
+          line = workflow.line_of(/^\s+#{Regexp.escape(job_id)}:/)
+          findings << finding(workflow,
+            line: line || 0,
+            code: "#{job_id}:",
+            message: "Publish/deploy job without environment protection — no human gate before publication",
+            fix: "Add environment: <name> with required reviewers"
+          )
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/missing_frozen_lockfile.rb

@@ -0,0 +1,28 @@
+module Rules
+  class MissingFrozenLockfile < Base
+    def name = "missing-frozen-lockfile"
+    def description = "Package install without lockfile enforcement"
+    def severity = :medium
+
+    INSTALL_WITHOUT_LOCK = /(?:npm|pnpm|yarn)\s+install(?!\s+(-g|--global|--frozen-lockfile|--ci|--immutable))/
+
+    def check(workflow)
+      findings = []
+
+      workflow.raw_lines.each_with_index do |line, i|
+        next unless line.match?(INSTALL_WITHOUT_LOCK)
+        next if line.match?(/--frozen-lockfile|--ci|--immutable|npm ci/)
+        next if line.strip.start_with?("#")
+
+        findings << finding(workflow,
+          line: i + 1,
+          code: line.strip,
+          message: "Package install without --frozen-lockfile — dependency resolution may differ from tested versions",
+          fix: "Use pnpm install --frozen-lockfile or npm ci"
+        )
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/missing_permissions.rb

@@ -0,0 +1,18 @@
+module Rules
+  class MissingPermissions < Base
+    def name = "missing-permissions"
+    def description = "No top-level permissions block"
+    def severity = :medium
+
+    def check(workflow)
+      return [] if workflow.permissions(scope: :workflow)
+
+      line = workflow.line_of(/^jobs:/) || 1
+      [finding(workflow,
+        line: line,
+        message: "No top-level permissions block — jobs inherit broad default token permissions",
+        fix: "Add permissions: contents: read at the workflow level"
+      )]
+    end
+  end
+end

data/lib/rules/missing_persist_creds.rb

@@ -0,0 +1,51 @@
+module Rules
+  class MissingPersistCreds < Base
+    def name = "missing-persist-credentials"
+    def description = "actions/checkout without persist-credentials: false"
+    def severity = :high
+
+    def check(workflow)
+      findings = []
+      seen_checkout_lines = Hash.new(0)
+
+      workflow.jobs.each do |_job_id, job|
+        job_pushes = job_does_push?(job, workflow)
+
+        workflow.steps(job).each do |step|
+          next unless step["uses"]&.match?(/actions\/checkout[@\s]|actions\/checkout$/)
+
+          with = step["with"] || {}
+          persist = with["persist-credentials"]
+
+          next if persist == false || persist == "false"
+          next if job_pushes && persist == true
+
+          uses = step["uses"]
+          all_lines = workflow.lines_of(/uses:\s*#{Regexp.escape(uses)}/)
+          idx = seen_checkout_lines[uses]
+          line = all_lines[idx] || all_lines.last
+          seen_checkout_lines[uses] += 1
+
+          findings << finding(workflow,
+            line: line || 0,
+            code: "uses: #{uses}",
+            message: "Checkout without persist-credentials: false — token persists in .git/config",
+            fix: "Add persist-credentials: false to the with: block"
+          )
+        end
+      end
+
+      findings
+    end
+
+    private
+
+    def job_does_push?(job, workflow)
+      workflow.steps(job).any? { |s|
+        run = s["run"]&.to_s
+        run&.match?(/git push|gh pr create|peter-evans\/create-pull-request/) ||
+          s["uses"]&.match?(/create-pull-request|yaml-update-action/)
+      }
+    end
+  end
+end

data/lib/rules/missing_timeouts.rb

@@ -0,0 +1,25 @@
+module Rules
+  class MissingTimeouts < Base
+    def name = "missing-timeouts"
+    def description = "Job without timeout-minutes"
+    def severity = :medium
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |job_id, job|
+        next if job.key?("timeout-minutes")
+
+        line = workflow.line_of(/^\s+#{Regexp.escape(job_id)}:/)
+        findings << finding(workflow,
+          line: line || 0,
+          code: "#{job_id}:",
+          message: "Job '#{job_id}' has no timeout-minutes — default is 360 minutes (6 hours)",
+          fix: "Add timeout-minutes: appropriate for the job type (5-30 min)"
+        )
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/overly_broad_triggers.rb

@@ -0,0 +1,31 @@
+module Rules
+  class OverlyBroadTriggers < Base
+    def name = "overly-broad-triggers"
+    def description = "Push or pull_request trigger without branch filter"
+    def severity = :low
+
+    def check(workflow)
+      findings = []
+      triggers = workflow.triggers
+
+      return findings unless triggers.is_a?(Hash)
+
+      %w[push pull_request].each do |trigger|
+        next unless triggers.key?(trigger)
+        config = triggers[trigger]
+
+        if config.nil? || config == true || (config.is_a?(Hash) && !config.key?("branches") && !config.key?("branches-ignore") && !config.key?("tags") && !config.key?("tags-ignore") && !config.key?("paths") && !config.key?("paths-ignore"))
+          line = workflow.line_of(/^\s+#{trigger}:/)
+          findings << finding(workflow,
+            line: line || 0,
+            code: "#{trigger}:",
+            message: "'#{trigger}' trigger with no branch filter — runs on all branches",
+            fix: "Add branches: [main] to scope the trigger"
+          )
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/shell_injection_expr.rb

@@ -0,0 +1,57 @@
+module Rules
+  class ShellInjectionExpr < Base
+    def name = "shell-injection-expr"
+    def description = "Attacker-controllable ${{ }} expression in run: block"
+    def severity = :critical
+
+    DANGEROUS_CONTEXTS = %w[
+      github.event.pull_request.title
+      github.event.pull_request.body
+      github.event.pull_request.head.ref
+      github.event.pull_request.head.label
+      github.event.issue.title
+      github.event.issue.body
+      github.event.comment.body
+      github.event.review.body
+      github.event.discussion.title
+      github.event.discussion.body
+      github.event.workflow_run.head_branch
+      github.head_ref
+      github.actor
+      github.triggering_actor
+    ].freeze
+
+    PATTERN = /\$\{\{\s*(#{DANGEROUS_CONTEXTS.map { |c| Regexp.escape(c) }.join('|')})/
+
+    def check(workflow)
+      findings = []
+      workflow.lines_of(PATTERN).each do |line_num|
+        line = workflow.line_content(line_num)
+        next unless in_run_block?(workflow, line_num)
+
+        match = line.match(PATTERN)
+        next unless match
+
+        findings << finding(workflow,
+          line: line_num,
+          code: line.strip,
+          message: "Attacker-controllable expression ${{ #{match[1]} }} in run: block — shell injection risk",
+          fix: "Move to env: block and reference as $ENV_VAR in the shell"
+        )
+      end
+      findings
+    end
+
+    private
+
+    def in_run_block?(workflow, target_line)
+      (target_line - 1).downto([target_line - 20, 0].max) do |i|
+        content = workflow.raw_lines[i]
+        return true if content&.match?(/^\s+run:\s*[\|>]?\s*$/) || content&.match?(/^\s+run:\s+\S/)
+        return true if content&.match?(/^\s+-\s+run:\s*[\|>]?\s*$/) || content&.match?(/^\s+-\s+run:\s+\S/)
+        return false if content&.match?(/^\s+(uses|with|if|id|name|env):/) || content&.match?(/^\s+-\s+name:/)
+      end
+      false
+    end
+  end
+end

data/lib/rules/shell_injection_jq.rb

@@ -0,0 +1,59 @@
+module Rules
+  class ShellInjectionJq < Base
+    def name = "shell-injection-jq"
+    def description = "Shell variable interpolated in double-quoted jq/curl JSON argument"
+    def severity = :critical
+
+    ATTACKER_ENV_VARS = %w[
+      PR_TITLE PR_BODY PR_AUTHOR HEAD_REF ISSUE_TITLE ISSUE_BODY COMMENT_BODY
+      PR_HEAD_REF BRANCH_NAME
+    ].freeze
+
+    JQ_PATTERN = /jq\s+([a-zA-Z-]+\s+)*--arg\s+\w+\s+"[^"]*\$\{/
+    CURL_JSON_PATTERN = /curl\s.*-d\s+"[^"]*\$\{/
+    def check(workflow)
+      findings = []
+
+      workflow.raw_lines.each_with_index do |line, i|
+        line_num = i + 1
+
+        if line.match?(JQ_PATTERN)
+          var_match = line.match(/\$\{(\w+)\}/)
+          next unless var_match
+          var_name = var_match[1]
+          next unless potentially_attacker_controlled?(var_name)
+
+          findings << finding(workflow,
+            line: line_num,
+            code: line.strip,
+            message: "${#{var_name}} interpolated in double-quoted jq argument — $(command) executes via bash substitution",
+            fix: "Use jq --arg: jq -nc --arg #{var_name.downcase} \"$#{var_name}\" '{text: $#{var_name.downcase}}'"
+          )
+        end
+
+        if line.match?(CURL_JSON_PATTERN)
+          var_match = line.match(/\$\{(\w+)\}/)
+          next unless var_match
+          var_name = var_match[1]
+          next unless potentially_attacker_controlled?(var_name)
+
+          findings << finding(workflow,
+            line: line_num,
+            code: line.strip,
+            message: "${#{var_name}} interpolated in double-quoted curl JSON — command substitution risk",
+            fix: "Build JSON payload with jq -nc --arg instead of string interpolation"
+          )
+        end
+      end
+
+      findings
+    end
+
+    private
+
+    def potentially_attacker_controlled?(var_name)
+      ATTACKER_ENV_VARS.any? { |v| var_name.upcase == v } ||
+        var_name.match?(/^(PR_|ISSUE_|COMMENT_)?(TITLE|BODY|HEAD_REF|BRANCH_NAME|COMMENT_BODY|AUTHOR)$/i)
+    end
+  end
+end

data/lib/rules/static_aws_credentials.rb

@@ -0,0 +1,33 @@
+module Rules
+  class StaticAwsCredentials < Base
+    def name = "static-aws-credentials"
+    def description = "AWS credentials using static keys instead of OIDC"
+    def severity = :high
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |_job_id, job|
+        workflow.steps(job).each do |step|
+          next unless step["uses"]&.include?("configure-aws-credentials")
+
+          with = step["with"] || {}
+          has_static = with.key?("aws-access-key-id")
+          has_oidc = with.key?("role-to-assume")
+
+          if has_static && !has_oidc
+            line = workflow.line_of(/aws-access-key-id/)
+            findings << finding(workflow,
+              line: line || 0,
+              code: "aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}",
+              message: "Static AWS access keys — long-lived credentials that don't auto-expire",
+              fix: "Use OIDC federation: role-to-assume with id-token: write permission"
+            )
+          end
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/unpinned_actions.rb

@@ -0,0 +1,35 @@
+module Rules
+    class UnpinnedActions < Base
+        def name = "unpinned-actions"
+        def description = "Action referenced by tag instead of SHA pin"
+        def severity = :critical
+
+        SHA_PATTERN = /@[0-9a-f]{40}\b/
+        FIRST_PARTY = %w[actions/ github/].freeze
+
+        def check(workflow)
+            findings = []
+            workflow.uses_actions.each do |action|
+                uses = action[:uses]
+                next if uses.nil?
+                next if uses.start_with?("./")
+                next if uses.start_with?("docker://")
+                next if uses.match?(SHA_PATTERN)
+
+                first_party = FIRST_PARTY.any? { |prefix| uses.start_with?(prefix) }
+                sev = first_party ? :medium : :critical
+
+                findings << Finding.new(
+                    rule: name,
+                    severity: sev,
+                    file: workflow.filename,
+                    line: action[:line] || 0,
+                    code: "uses: #{uses}",
+                    message: "Action '#{uses}' is not SHA-pinned — tag references are mutable",
+                    fix: "Pin to a commit SHA: uses: #{uses.split('@').first}@<commit-sha> # #{uses.split('@').last}"
+                )
+            end
+            findings
+        end
+    end
+end

data/lib/rules/unpinned_docker_image.rb

@@ -0,0 +1,25 @@
+module Rules
+  class UnpinnedDockerImage < Base
+    def name = "unpinned-docker-image"
+    def description = "Docker image referenced by :latest tag"
+    def severity = :low
+
+    def check(workflow)
+      findings = []
+
+      workflow.lines_of(/:latest\b/).each do |line_num|
+        line = workflow.line_content(line_num)
+        next unless line&.match?(/docker:\/\/.*:latest|image:.*:latest|uses:.*:latest|docker:.*:latest|container:.*:latest/)
+
+        findings << finding(workflow,
+          line: line_num,
+          code: line.strip,
+          message: "Docker image uses :latest tag — mutable, not reproducible",
+          fix: "Pin to a specific digest: image@sha256:..."
+        )
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/unscoped_app_token.rb

@@ -0,0 +1,31 @@
+module Rules
+  class UnscopedAppToken < Base
+    def name = "unscoped-app-token"
+    def description = "GitHub App token without scoped permissions"
+    def severity = :high
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |_job_id, job|
+        workflow.steps(job).each do |step|
+          next unless step["uses"]&.include?("create-github-app-token")
+
+          with = step["with"] || {}
+          has_permissions = with.keys.any? { |k| k.start_with?("permission-") }
+
+          unless has_permissions
+            line = workflow.line_of(/create-github-app-token/)
+            findings << finding(workflow,
+              line: line || 0,
+              message: "App token inherits blanket installation permissions",
+              fix: "Add permission-<name>: write inputs to scope the token"
+            )
+          end
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/scanner.rb

@@ -0,0 +1,95 @@
+require_relative "finding"
+require_relative "workflow"
+require_relative "rule_engine"
+require_relative "github_client"
+require_relative "local_client"
+require_relative "clone_client"
+require_relative "formatter/terminal"
+require_relative "formatter/json"
+
+class Scanner
+    def initialize(client:, formatter:, min_severity: :low)
+        @client = client
+        @formatter = formatter
+        @min_severity = min_severity
+        @engine = RuleEngine.new
+    end
+
+    def scan(repo)
+        raw_workflows = @client.fetch_workflows(repo)
+
+        workflows = raw_workflows.map { |w|
+            Workflow.new(filename: w[:filename], content: w[:content])
+        }
+
+        dependabot = @client.fetch_dependabot_config(repo)
+        has_zizmor = workflows.any? { |w| w.filename.match?(/zizmor/i) }
+        has_dependabot_actions = dependabot_has_actions?(dependabot)
+
+        findings = []
+
+        workflows.each do |wf|
+            next if wf.parse_error?
+            findings.concat(@engine.scan(wf))
+        end
+
+        unless has_dependabot_actions
+            findings << Finding.new(
+                rule: "missing-dependabot",
+                severity: :low,
+                file: "dependabot.yml",
+                line: 0,
+                code: nil,
+                message: "No Dependabot configuration for github-actions ecosystem",
+                fix: "Add package-ecosystem: github-actions to .github/dependabot.yml"
+            )
+        end
+
+        unless has_zizmor
+            findings << Finding.new(
+                rule: "missing-zizmor",
+                severity: :low,
+                file: "(missing)",
+                line: 0,
+                code: nil,
+                message: "No zizmor static analysis workflow found",
+                fix: "Add a security_zizmor.yml workflow for GitHub Actions static analysis"
+            )
+        end
+
+        findings.select! { |f| severity_passes?(f.severity) }
+
+        output = @formatter.format(
+            repo: repo,
+            workflow_count: workflows.length,
+            findings: findings
+        )
+
+        { output: output, findings: findings, workflow_count: workflows.length }
+    end
+
+    def scan_org(org)
+        repos = @client.fetch_repos(org)
+        results = []
+
+        repos.each do |repo|
+            $stderr.puts "Scanning #{repo}..." if @formatter.is_a?(Formatter::Terminal)
+            results << scan(repo)
+        end
+
+        results
+    end
+
+    private
+
+    def dependabot_has_actions?(config)
+        return false unless config.is_a?(Hash)
+        updates = config["updates"]
+        return false unless updates.is_a?(Array)
+        updates.any? { |u| u["package-ecosystem"] == "github-actions" }
+    end
+
+    def severity_passes?(sev)
+        (Finding::SEVERITY_ORDER[sev] || 99) <= (Finding::SEVERITY_ORDER[@min_severity] || 99)
+    end
+end

data/lib/sha_resolver.rb

@@ -0,0 +1,60 @@
+require "net/http"
+require "json"
+require "uri"
+
+class ShaResolver
+    API_BASE = "https://api.github.com"
+
+    def initialize(token: nil)
+        @token = token || ENV["GITHUB_TOKEN"]
+        @cache = {}
+    end
+
+    def resolve(owner_action, tag)
+        repo = extract_repo(owner_action)
+        key = "#{repo}@#{tag}"
+        @cache[key] ||= fetch_sha(repo, tag)
+    end
+
+    private
+
+    def extract_repo(owner_action)
+        parts = owner_action.split("/")
+        "#{parts[0]}/#{parts[1]}"
+    end
+
+    def fetch_sha(repo, tag)
+        encoded_repo = repo.split("/").map { |p| URI.encode_www_form_component(p) }.join("/")
+        encoded_tag = URI.encode_www_form_component(tag)
+        uri = URI("#{API_BASE}/repos/#{encoded_repo}/commits/#{encoded_tag}")
+        req = Net::HTTP::Get.new(uri)
+        req["Accept"] = "application/vnd.github+json"
+        req["Authorization"] = "Bearer #{@token}" if @token
+        req["X-GitHub-Api-Version"] = "2022-11-28"
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 30
+
+        resp = http.request(req)
+
+        case resp.code.to_i
+        when 200
+            data = JSON.parse(resp.body)
+            data["sha"]
+        when 404
+            $stderr.puts "ShaResolver: tag '#{tag}' not found for #{repo}"
+            nil
+        when 403
+            $stderr.puts "ShaResolver: rate limited or forbidden for #{repo}"
+            nil
+        else
+            $stderr.puts "ShaResolver: API error #{resp.code} for #{repo}@#{tag}"
+            nil
+        end
+    rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, Errno::ECONNREFUSED => e
+        $stderr.puts "SHA resolve failed for #{repo}@#{tag}: #{e.message}"
+        nil
+    end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module Sentinel
+    VERSION = "0.1.0"
+end