sentinel-ci 0.1.0

data/lib/cli/scan.rb

@@ -0,0 +1,145 @@
+require "optparse"
+require_relative "../scanner"
+
+options = {
+    format: "terminal",
+    severity: :low,
+}
+
+parser = OptionParser.new do |opts|
+    opts.banner = "Usage: sentinel scan [options] [REPO]"
+    opts.separator ""
+    opts.separator "Scan GitHub Actions workflows for security issues."
+    opts.separator ""
+
+    opts.on("--format FORMAT", %w[terminal json], "Output format: terminal (default) or json") do |f|
+        options[:format] = f
+    end
+
+    opts.on("--severity LEVEL", %i[critical high medium low],
+            "Minimum severity: critical, high, medium, low (default: low)") do |s|
+        options[:severity] = s
+    end
+
+    opts.on("--local PATH", "Scan a local directory instead of GitHub API") do |p|
+        options[:local] = p
+    end
+
+    opts.on("--org ORG", "Scan all repos in a GitHub organization") do |o|
+        options[:org] = o
+    end
+
+    opts.on("--token TOKEN", "GitHub API token (default: GITHUB_TOKEN env var)") do |t|
+        options[:token] = t
+    end
+
+    opts.on("-h", "--help", "Show this help message") do
+        puts opts
+        exit 0
+    end
+end
+
+begin
+    parser.parse!
+rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+    $stderr.puts e.message
+    $stderr.puts parser
+    exit 2
+end
+
+repo = ARGV.shift
+
+modes = [options[:local], options[:org], repo].compact
+if modes.empty?
+    $stderr.puts "Error: must specify --local PATH, --org ORG, or a REPO argument"
+    $stderr.puts parser
+    exit 2
+elsif modes.length > 1
+    $stderr.puts "Error: specify only one of --local, --org, or REPO"
+    $stderr.puts parser
+    exit 2
+end
+
+def resolve_token(options)
+    return options[:token] if options[:token]
+    return ENV["GITHUB_TOKEN"] if ENV["GITHUB_TOKEN"]
+
+    gh_path = `which gh 2>/dev/null`.strip
+    if !gh_path.empty? && system("gh", "auth", "status", [:out, :err] => File::NULL)
+        token = `gh auth token 2>/dev/null`.strip
+        return token unless token.empty?
+    end
+
+    nil
+end
+
+token = resolve_token(options)
+
+client = if options[:local]
+    LocalClient.new(options[:local])
+elsif options[:org]
+    unless token
+        $stderr.puts "Error: --org requires a GitHub token to list repos."
+        $stderr.puts ""
+        $stderr.puts "  export GITHUB_TOKEN=$(gh auth token)"
+        $stderr.puts "  sentinel scan --org #{options[:org]}"
+        exit 2
+    end
+    GitHubClient.new(token: token)
+else
+    if token
+        GitHubClient.new(token: token)
+    else
+        CloneClient.new
+    end
+end
+
+formatter = case options[:format]
+when "json"  then Formatter::Json.new
+else              Formatter::Terminal.new
+end
+
+scanner = Scanner.new(client: client, formatter: formatter, min_severity: options[:severity])
+
+all_findings = []
+
+begin
+    if options[:local]
+        result = scanner.scan(options[:local])
+        puts result[:output]
+        all_findings.concat(result[:findings])
+    elsif options[:org]
+        results = scanner.scan_org(options[:org])
+
+        if options[:format] == "json"
+            combined = results.map { |r| JSON.parse(r[:output]) }
+            puts JSON.pretty_generate(combined)
+        else
+            results.each { |r| puts r[:output] }
+
+            totals = Hash.new(0)
+            results.each do |r|
+                r[:findings].each { |f| totals[f.severity] += 1 }
+            end
+
+            summary = Finding::SEVERITIES
+                .select { |s| totals[s] > 0 }
+                .map { |s| "#{totals[s]} #{s}" }
+                .join(", ")
+
+            total = results.sum { |r| r[:findings].length }
+            $stderr.puts "\nOrg scan complete: #{results.length} repos, #{total} findings (#{summary})"
+        end
+
+        results.each { |r| all_findings.concat(r[:findings]) }
+    else
+        result = scanner.scan(repo)
+        puts result[:output]
+        all_findings.concat(result[:findings])
+    end
+
+    has_critical_or_high = all_findings.any? { |f| f.critical? || f.high? }
+    exit(has_critical_or_high ? 1 : 0)
+ensure
+    client.cleanup if client.respond_to?(:cleanup)
+end

data/lib/clone_client.rb

@@ -0,0 +1,64 @@
+require "tmpdir"
+require "fileutils"
+require_relative "local_client"
+
+class CloneClient
+    REPO_FORMAT = %r{\A[A-Za-z0-9\-_.]+/[A-Za-z0-9\-_.]+\z}
+
+    def initialize
+        @tmpdir = nil
+    end
+
+    def fetch_workflows(repo)
+        unless repo.match?(REPO_FORMAT)
+            $stderr.puts "Invalid repo format: #{repo} (expected owner/repo)"
+            return []
+        end
+
+        @tmpdir = Dir.mktmpdir("sentinel-")
+
+        # Shallow sparse clone — only .github/ directory
+        success = system(
+            "git", "clone", "--depth", "1", "--filter=blob:none", "--sparse",
+            "https://github.com/#{repo}.git", @tmpdir,
+            [:out, :err] => File::NULL
+        )
+
+        unless success
+            $stderr.puts ""
+            $stderr.puts "ERROR: Could not access #{repo}"
+            $stderr.puts ""
+            $stderr.puts "This repo may be private. To scan private repos:"
+            $stderr.puts ""
+            $stderr.puts "  export GITHUB_TOKEN=$(gh auth token)"
+            $stderr.puts "  sentinel scan #{repo}"
+            $stderr.puts ""
+            $stderr.puts "Or pass a token directly:"
+            $stderr.puts ""
+            $stderr.puts "  sentinel scan --token ghp_xxx #{repo}"
+            $stderr.puts ""
+            exit 2
+        end
+
+        system(
+            "git", "-C", @tmpdir, "sparse-checkout", "set", ".github",
+            [:out, :err] => File::NULL
+        )
+
+        LocalClient.new(@tmpdir).fetch_workflows(repo)
+    end
+
+    def fetch_dependabot_config(repo)
+        return nil unless @tmpdir
+        LocalClient.new(@tmpdir).fetch_dependabot_config(repo)
+    end
+
+    def file_exists?(repo, path)
+        return false unless @tmpdir
+        File.exist?(File.join(@tmpdir, path))
+    end
+
+    def cleanup
+        FileUtils.rm_rf(@tmpdir) if @tmpdir
+    end
+end

data/lib/finding.rb

@@ -0,0 +1,27 @@
+Finding = Struct.new(:rule, :severity, :file, :line, :code, :message, :fix, keyword_init: true)
+
+class Finding
+    SEVERITIES = %i[critical high medium low].freeze
+    SEVERITY_ORDER = SEVERITIES.each_with_index.to_h.freeze
+
+    def <=>(other)
+        (SEVERITY_ORDER[severity] || 99) <=> (SEVERITY_ORDER[other.severity] || 99)
+    end
+
+    def critical? = severity == :critical
+    def high?     = severity == :high
+    def medium?   = severity == :medium
+    def low?      = severity == :low
+
+    def to_h
+        {
+            rule: rule,
+            severity: severity.to_s,
+            file: file,
+            line: line,
+            code: code,
+            message: message,
+            fix: fix
+        }
+    end
+end

data/lib/formatter/json.rb

@@ -0,0 +1,18 @@
+require "json"
+
+module Formatter
+    class Json
+        def format(repo:, workflow_count:, findings:)
+            summary = Finding::SEVERITIES.each_with_object({}) { |s, h|
+                h[s.to_s] = findings.count { |f| f.severity == s }
+            }
+
+            JSON.pretty_generate({
+                repo: repo,
+                workflows: workflow_count,
+                findings: findings.sort.map(&:to_h),
+                summary: summary
+            })
+        end
+    end
+end

data/lib/formatter/terminal.rb

@@ -0,0 +1,47 @@
+module Formatter
+    class Terminal
+        COLORS = {
+            critical: "\e[31m",   # red
+            high:     "\e[33m",   # yellow
+            medium:   "\e[36m",   # cyan
+            low:      "\e[90m",   # dim
+            reset:    "\e[0m",
+            bold:     "\e[1m",
+            green:    "\e[32m",
+        }.freeze
+
+        def format(repo:, workflow_count:, findings:)
+            lines = []
+            lines << ""
+            lines << "#{c(:bold)}=== #{repo} (#{workflow_count} workflows) ===#{c(:reset)}"
+            lines << ""
+
+            if findings.empty?
+                lines << "  #{c(:green)}No findings.#{c(:reset)}"
+            else
+                findings.sort.each do |f|
+                    sev = f.severity.to_s.upcase.ljust(10)
+                    lines << "  #{c(f.severity)}#{sev}#{c(:reset)} #{c(:bold)}#{f.rule}#{c(:reset)}  #{f.file}:#{f.line}"
+                    lines << "            #{f.message}"
+                    lines << "            #{c(:green)}Fix: #{f.fix}#{c(:reset)}" if f.fix
+                    lines << ""
+                end
+
+                summary = Finding::SEVERITIES.map { |s|
+                    count = findings.count { |f| f.severity == s }
+                    next nil if count == 0
+                    "#{c(s)}#{count} #{s}#{c(:reset)}"
+                }.compact.join(", ")
+
+                lines << "  --- Summary: #{summary} ---"
+            end
+
+            lines << ""
+            lines.join("\n")
+        end
+
+        private
+
+        def c(name) = COLORS[name] || ""
+    end
+end

data/lib/github_client.rb

@@ -0,0 +1,98 @@
+require "net/http"
+require "json"
+require "uri"
+require "base64"
+require "yaml"
+
+class GitHubClient
+    API_BASE = "https://api.github.com"
+
+    def initialize(token: nil)
+        @token = token || ENV["GITHUB_TOKEN"]
+    end
+
+    def fetch_workflows(repo)
+        workflows = []
+        files = api_get("/repos/#{repo}/contents/.github/workflows")
+        return workflows unless files.is_a?(Array)
+
+        files.each do |f|
+            next unless f["name"].end_with?(".yml", ".yaml")
+            content = fetch_file_content(repo, f["path"])
+            next unless content
+            workflows << { filename: f["name"], content: content }
+        end
+
+        workflows
+    end
+
+    def fetch_file_content(repo, path)
+        data = api_get("/repos/#{repo}/contents/#{path}")
+        return nil unless data.is_a?(Hash) && data["content"]
+        Base64.decode64(data["content"])
+    end
+
+    def fetch_repos(org)
+        repos = []
+        page = 1
+        loop do
+            batch = api_get("/orgs/#{org}/repos?per_page=100&page=#{page}&type=all")
+            break unless batch.is_a?(Array) && !batch.empty?
+            batch.each do |r|
+                next if r["archived"]
+                repos << r["full_name"]
+            end
+            page += 1
+            break if batch.length < 100
+        end
+        repos.sort
+    end
+
+    def file_exists?(repo, path)
+        api_get("/repos/#{repo}/contents/#{path}")
+        true
+    rescue StandardError
+        false
+    end
+
+    def fetch_dependabot_config(repo)
+        content = fetch_file_content(repo, ".github/dependabot.yml")
+        content ||= fetch_file_content(repo, ".github/dependabot.yaml")
+        return nil unless content
+        begin
+            YAML.safe_load(content)
+        rescue StandardError => e
+            nil
+        end
+    end
+
+    private
+
+    def api_get(path)
+        uri = URI("#{API_BASE}#{path}")
+        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
+            JSON.parse(resp.body)
+        when 404
+            nil
+        when 403
+            $stderr.puts "Rate limited or forbidden: #{path}"
+            nil
+        else
+            $stderr.puts "API error #{resp.code}: #{path}"
+            nil
+        end
+    end
+end

data/lib/local_client.rb

@@ -0,0 +1,33 @@
+class LocalClient
+    def initialize(path)
+        @path = File.expand_path(path)
+        @workflows_dir = File.join(@path, ".github", "workflows")
+    end
+
+    def fetch_workflows(_repo = nil)
+        workflows = []
+        return workflows unless File.directory?(@workflows_dir)
+
+        Dir[File.join(@workflows_dir, "*.{yml,yaml}")].sort.each do |f|
+            content = File.read(f)
+            workflows << { filename: File.basename(f), content: content }
+        end
+
+        workflows
+    end
+
+    def file_exists?(_repo, path)
+        File.exist?(File.join(@path, path))
+    end
+
+    def fetch_dependabot_config(_repo)
+        path = File.join(@path, ".github", "dependabot.yml")
+        path = File.join(@path, ".github", "dependabot.yaml") unless File.exist?(path)
+        return nil unless File.exist?(path)
+        begin
+            YAML.safe_load(File.read(path))
+        rescue StandardError => e
+            nil
+        end
+    end
+end

data/lib/rule_engine.rb

@@ -0,0 +1,39 @@
+class RuleEngine
+    attr_reader :rules
+
+    def initialize
+        @rules = []
+        load_rules
+    end
+
+    def scan(workflow)
+        findings = []
+        @rules.each do |rule|
+            begin
+                findings.concat(rule.check(workflow))
+            rescue => e
+                $stderr.puts "Rule #{rule.name} failed on #{workflow.filename}: #{e.message}"
+            end
+        end
+        findings.sort
+    end
+
+    private
+
+    def load_rules
+        rules_dir = File.join(__dir__, "rules")
+        require File.join(rules_dir, "base.rb")
+        Dir[File.join(rules_dir, "*.rb")].sort.each do |file|
+            next if File.basename(file) == "base.rb"
+            require file
+        end
+
+        Rules.constants.each do |const|
+            klass = Rules.const_get(const)
+            next unless klass.is_a?(Class) && klass < Rules::Base
+            @rules << klass.new
+        end
+
+        @rules.sort_by! { |r| Finding::SEVERITY_ORDER[r.severity] || 99 }
+    end
+end

data/lib/rules/allow_forks_artifact.rb

@@ -0,0 +1,22 @@
+module Rules
+  class AllowForksArtifact < Base
+    def name = "allow-forks-artifact"
+    def description = "Artifact download with allow_forks: true in privileged context"
+    def severity = :medium
+
+    def check(workflow)
+      findings = []
+
+      workflow.lines_of(/allow_forks:\s*true/).each do |line_num|
+        findings << finding(workflow,
+          line: line_num,
+          code: workflow.line_content(line_num).strip,
+          message: "Downloading fork-produced artifacts in a privileged workflow_run context",
+          fix: "Ensure fork-produced artifact content is not executed or processed unsafely"
+        )
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/base.rb

@@ -0,0 +1,33 @@
+module Rules
+    class Base
+        def name
+            raise NotImplementedError
+        end
+
+        def description
+            raise NotImplementedError
+        end
+
+        def severity
+            raise NotImplementedError
+        end
+
+        def check(workflow)
+            raise NotImplementedError
+        end
+
+        private
+
+        def finding(workflow, line:, code: nil, message: nil, fix: nil)
+            Finding.new(
+                rule: name,
+                severity: severity,
+                file: workflow.filename,
+                line: line,
+                code: code || workflow.line_content(line)&.strip,
+                message: message || description,
+                fix: fix
+            )
+        end
+    end
+end

data/lib/rules/build_publish_same_job.rb

@@ -0,0 +1,39 @@
+module Rules
+  class BuildPublishSameJob < Base
+    def name = "build-publish-same-job"
+    def description = "Build and publish in same job with publish secrets available during build"
+    def severity = :high
+
+    INSTALL_PATTERNS = /npm install|pnpm install|yarn install|pip install|bundle install/
+    PUBLISH_PATTERNS = /npm publish|pnpm publish|npx pkg-pr-new|twine upload|gem push/
+    PUBLISH_SECRETS = /NPM_TOKEN|PYPI_TOKEN|GEM_HOST_API_KEY|NUGET_API_KEY/
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |job_id, job|
+        steps = workflow.steps(job)
+        has_install = steps.any? { |s| s["run"]&.match?(INSTALL_PATTERNS) }
+        has_publish = steps.any? { |s| s["run"]&.match?(PUBLISH_PATTERNS) }
+
+        next unless has_install && has_publish
+
+        job_env = job["env"]&.to_s || ""
+        step_envs = steps.map { |s| (s["env"] || {}).to_s }.join(" ")
+        all_env = job_env + step_envs
+
+        if all_env.match?(PUBLISH_SECRETS) || all_env.match?(/secrets\./)
+          line = workflow.line_of(/#{job_id}:/)
+          findings << finding(workflow,
+            line: line || 0,
+            code: "job: #{job_id}",
+            message: "Build and publish in same job — a compromised dependency could exfiltrate publish credentials",
+            fix: "Split into separate build (read-only) and publish (with secrets) jobs connected via artifacts"
+          )
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/credential_window.rb

@@ -0,0 +1,43 @@
+module Rules
+  class CredentialWindow < Base
+    def name = "credential-window"
+    def description = "Git credentials configured far before push step"
+    def severity = :high
+
+    MAX_STEPS_BETWEEN = 5
+
+    def check(workflow)
+      findings = []
+
+      workflow.jobs.each do |_job_id, job|
+        steps = workflow.steps(job)
+        cred_step = nil
+        push_step = nil
+
+        steps.each_with_index do |step, i|
+          run = step["run"]&.to_s
+          if run&.match?(/git config.*insteadOf|git remote set-url/)
+            cred_step = i if cred_step.nil?
+          end
+          if run&.match?(/git push/)
+            push_step = i
+          end
+        end
+
+        next unless cred_step && push_step
+        gap = push_step - cred_step
+
+        if gap > MAX_STEPS_BETWEEN
+          line = workflow.line_of(/git config.*insteadOf|git remote set-url/)
+          findings << finding(workflow,
+            line: line || 0,
+            message: "Git credentials configured #{gap} steps before push — #{gap - 1} steps have access to the token",
+            fix: "Move credential configuration to immediately before the push step"
+          )
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/rules/curl_pipe_shell.rb

@@ -0,0 +1,29 @@
+module Rules
+    class CurlPipeShell < Base
+        def name = "curl-pipe-shell"
+        def description = "Remote script piped directly to shell without integrity check"
+        def severity = :high
+
+        PIPE_PATTERN = /curl\s.*\|\s*(sudo\s+)?(sh|bash|zsh|source|\.)/
+        WGET_PIPE = /wget\s.*-O\s*-\s*\|\s*(sudo\s+)?(sh|bash|zsh)/
+
+        def check(workflow)
+            findings = []
+
+            workflow.raw_lines.each_with_index do |line, i|
+                next if line.strip.start_with?("#")
+
+                if line.match?(PIPE_PATTERN) || line.match?(WGET_PIPE)
+                    findings << finding(workflow,
+                        line: i + 1,
+                        code: line.strip,
+                        message: "Remote script piped to shell — no integrity verification, mutable endpoint",
+                        fix: "Download first, verify checksum, then execute; or use a pinned GitHub Action instead"
+                    )
+                end
+            end
+
+            findings
+        end
+    end
+end

data/lib/rules/dangerous_triggers.rb

@@ -0,0 +1,43 @@
+module Rules
+  class DangerousTriggers < Base
+    def name = "dangerous-triggers"
+    def description = "pull_request_target with fork code checkout"
+    def severity = :critical
+
+    def check(workflow)
+      findings = []
+      triggers = workflow.triggers
+
+      has_prt = case triggers
+                when Hash then triggers.key?("pull_request_target")
+                when Array then triggers.include?("pull_request_target")
+                when String then triggers == "pull_request_target"
+                else false
+                end
+
+      return findings unless has_prt
+
+      workflow.jobs.each do |_job_id, job|
+        workflow.steps(job).each do |step|
+          next unless step["uses"]&.include?("checkout")
+
+          with = step["with"] || {}
+          ref = with["ref"]&.to_s || ""
+
+          if ref.match?(/\bgithub\.event\.pull_request\.head\b|\.head_ref\b|pull_request\.head\.sha/i) ||
+             ref.match?(/\$\{\{\s*github\.head_ref\s*\}\}/)
+            line = workflow.line_of(/ref:.*head/i) || workflow.line_of(/checkout/)
+            findings << finding(workflow,
+              line: line || 0,
+              code: "ref: #{ref}",
+              message: "pull_request_target + checkout of PR head — fork code runs with base repo secrets",
+              fix: "Use pull_request trigger instead, or don't checkout PR head code"
+            )
+          end
+        end
+      end
+
+      findings
+    end
+  end
+end