sentinel-ci 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 32b245849733b662cb30bc87855190f0f85529a1467ff63414c9200aa6293251
+  data.tar.gz: 3ff45c00a69a18e351a94fdeec5540350ca5dc48b7e38f45d89a72a84698b7ae
+SHA512:
+  metadata.gz: 843c0f319cf5666311abc62e87b939d717fb1c0b2ef028b23d528c5ba5b3aa99d7ea9740c713cc79bd6463d4dd99e379d52b0016b975faeb2a43eb18f2e660a4
+  data.tar.gz: 264f40e687806d1eb6a3af350ab265160b8d9d67f26769dab3349549298ff532d44df8884377adaeebf16e483cf58749253fdcd6ef17979931ed26fd35893f54

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Ritter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,235 @@
+# Sentinel
+
+**Deterministic security scanner for GitHub Actions workflows**
+
+<!-- badges -->
+![Build](https://img.shields.io/badge/build-passing-brightgreen)
+![Ruby](https://img.shields.io/badge/ruby-3.2%2B-red)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+Scan GitHub Actions workflows for 21 security vulnerabilities. No AI, no gems -- pure Ruby stdlib.
+
+Documentation: https://sentinel.copilotkit.dev
+
+## Install
+
+```bash
+# Zero-config for public repos — no GITHUB_TOKEN needed
+gem install sentinel-ci
+sentinel scan owner/repo
+
+# One-shot (like npx)
+gem exec sentinel-ci scan owner/repo
+
+# For private repos or org scanning, set a token
+export GITHUB_TOKEN=$(gh auth token)
+sentinel scan --org my-org
+```
+
+Requires Ruby 3.2+ and `git`. Public repos are scanned via shallow clone -- no API token required.
+For private repos or `--org` scanning, set `GITHUB_TOKEN`.
+
+## Usage
+
+```bash
+# Scan a single repo
+bin/gh-workflow-scanner owner/repo
+
+# Scan a local checkout
+bin/gh-workflow-scanner --local /path/to/repo
+
+# Scan an entire GitHub org
+bin/gh-workflow-scanner --org my-org
+
+# JSON output, filter to high+ severity
+bin/gh-workflow-scanner --format json --severity high owner/repo
+```
+
+## GitHub Action
+
+Use as a GitHub Action to automatically scan workflows on every PR:
+
+```yaml
+- uses: jpr5/gh-workflow-scanner-action@v1
+  with:
+    severity: high
+```
+
+Full workflow example:
+
+```yaml
+name: Workflow Security Scan
+on:
+  pull_request:
+    paths: ['.github/workflows/**']
+permissions:
+  contents: read
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jpr5/gh-workflow-scanner-action@v1
+        id: scan
+        with:
+          severity: high
+          fail-on-findings: true
+```
+
+**Inputs:**
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `severity` | `high` | Minimum severity: `critical`, `high`, `medium`, `low` |
+| `fail-on-findings` | `true` | Fail the check if findings above threshold exist |
+
+**Outputs:**
+
+| Name | Description |
+|------|-------------|
+| `findings-count` | Total findings at or above severity |
+| `critical-count` | Critical findings count |
+| `high-count` | High findings count |
+
+Findings appear as inline annotations on the PR diff -- critical/high as errors,
+medium as warnings, low as notices.
+
+## What It Checks
+
+| # | Rule | Severity | What |
+|---|------|----------|------|
+| 1 | `unpinned-actions` | critical/medium | Tag-pinned actions (critical for third-party, medium for `actions/*`) |
+| 2 | `shell-injection-expr` | critical | Attacker-controllable `${{ }}` in `run:` blocks |
+| 3 | `shell-injection-jq` | critical | `${VAR}` in double-quoted jq/curl strings |
+| 4 | `dangerous-triggers` | critical | `pull_request_target` + fork code checkout |
+| 5 | `missing-persist-credentials` | high | `actions/checkout` without `persist-credentials: false` |
+| 6 | `credential-window` | high | Git credentials configured far from push step |
+| 7 | `static-aws-credentials` | high | Static AWS keys instead of OIDC federation |
+| 8 | `unscoped-app-token` | high | `create-github-app-token` without `permission-*` scoping |
+| 9 | `docker-build-arg-secrets` | high | Secrets in Docker build-args (visible in image layers) |
+| 10 | `build-publish-same-job` | high | Build + publish in same job with publish secrets |
+| 11 | `curl-pipe-shell` | high | `curl \| sh` without integrity verification |
+| 12 | `missing-permissions` | medium | No top-level permissions block |
+| 13 | `git-config-global` | medium | `git config --global` with credentials |
+| 14 | `missing-timeouts` | medium | Jobs without `timeout-minutes` |
+| 15 | `missing-env-protection` | medium | Publish/deploy jobs without environment protection |
+| 16 | `allow-forks-artifact` | medium | Fork-produced artifact download in privileged context |
+| 17 | `missing-frozen-lockfile` | medium | Package install without `--frozen-lockfile` / `npm ci` |
+| 18 | `unpinned-docker-image` | low | Docker images using `:latest` tag |
+| 19 | `overly-broad-triggers` | low | Push/PR triggers without branch/path filters |
+| 20 | `missing-dependabot` | low | No Dependabot config for github-actions ecosystem |
+| 21 | `missing-zizmor` | low | No zizmor static analysis workflow |
+
+## Auto-Fix
+
+Sentinel can automatically generate fixes for three rule categories:
+
+```bash
+bin/gh-workflow-scanner --fix owner/repo    # future CLI flag
+```
+
+Or use the Ruby API directly:
+
+```ruby
+require_relative "lib/auto_fix"
+require_relative "lib/sha_resolver"
+
+resolver = ShaResolver.new
+patched = AutoFix.apply(finding, raw_yaml, sha_resolver: resolver)
+```
+
+**Fixable rules:**
+
+| Rule | Fix Strategy |
+|------|-------------|
+| `unpinned-actions` | Resolves tag to SHA via GitHub API |
+| `shell-injection-expr` | Moves expression to step-level `env:` block |
+| `missing-persist-credentials` | Adds `persist-credentials: false` to checkout |
+
+## PR Bot
+
+Proactively scan popular public repos and open fix PRs for critical findings.
+
+```bash
+ruby bot/scanner_bot.rb --pattern shell-injection --dry-run
+```
+
+**Features:**
+
+- GitHub Code Search to find vulnerable repos
+- Auto-generates fix PRs for mechanically-fixable rules
+- Rate limited (50 PRs/day), stars threshold (>100)
+- Opt-out support, clear bot identity
+- Runs as daily cron via GitHub Actions
+
+## Options
+
+```
+--format FORMAT    terminal (default) or json
+--severity LEVEL   minimum severity: critical, high, medium, low (default: low)
+--local PATH       scan local directory
+--org ORG          scan all repos in a GitHub org (requires GITHUB_TOKEN)
+--token TOKEN      GitHub API token — only needed for private repos and --org scanning
+```
+
+## Exit Codes
+
+- `0` -- no critical or high findings
+- `1` -- critical or high findings present
+- `2` -- usage error
+
+## Architecture
+
+```
+bin/gh-workflow-scanner         # CLI entry point (optparse)
+action/
+  annotate.rb                   # GitHub Action annotation emitter
+lib/
+  scanner.rb                    # orchestrator
+  rule_engine.rb                # loads + runs all rules
+  workflow.rb                   # YAML parser + helpers
+  finding.rb                    # finding data struct
+  github_client.rb              # GitHub API client
+  local_client.rb               # filesystem client
+  auto_fix.rb                   # auto-fix engine
+  sha_resolver.rb               # GitHub tag -> SHA resolver
+  formatter/
+    terminal.rb                 # colored terminal output
+    json.rb                     # JSON output
+  rules/
+    base.rb                     # abstract rule interface
+    *.rb                        # one file per rule (19 rules)
+bot/
+  scanner_bot.rb                # PR bot orchestrator
+  search.rb                     # GitHub Code Search client
+  state.rb                      # JSON-file state tracking
+  pr_writer.rb                  # cross-fork PR creation
+  config.rb                     # bot configuration
+```
+
+## Adding Rules
+
+Create `lib/rules/my_rule.rb`:
+
+```ruby
+module Rules
+    class MyRule < Base
+        def name = "my-rule"
+        def description = "What this detects"
+        def severity = :high  # :critical, :high, :medium, :low
+
+        def check(workflow)
+            findings = []
+            # workflow.uses_actions, workflow.run_blocks, workflow.raw_lines, etc.
+            # Use finding() helper or construct Finding.new() directly
+            findings
+        end
+    end
+end
+```
+
+Rules are auto-discovered from `lib/rules/`.
+
+## License
+
+MIT

data/bin/gh-workflow-scanner

@@ -0,0 +1 @@
+sentinel

data/bin/sentinel

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/version"
+
+SUBCOMMANDS = %w[scan fix bot version help].freeze
+
+HELP_TEXT = <<~HELP
+    Usage: sentinel <command> [options] [args]
+
+    Commands:
+        scan [REPO]           Scan a repo, org, or local path for vulnerabilities
+        fix [REPO]            Auto-fix findings (coming soon)
+        bot                   Run the PR bot
+        version               Print version
+        help                  Show this help message
+
+    Examples:
+        sentinel scan owner/repo
+        sentinel scan --local .
+        sentinel scan --org myorg --severity high
+        sentinel scan --format json owner/repo
+        sentinel owner/repo                        # implicit scan
+
+    Run 'sentinel <command> --help' for command-specific options.
+HELP
+
+subcmd = ARGV.first
+
+if subcmd.nil?
+    $stderr.puts HELP_TEXT
+    exit 0
+elsif subcmd == "-h" || subcmd == "--help"
+    puts HELP_TEXT
+    exit 0
+elsif subcmd == "--version" || subcmd == "-v"
+    puts "sentinel #{Sentinel::VERSION}"
+    exit 0
+elsif SUBCOMMANDS.include?(subcmd)
+    ARGV.shift
+else
+    # Not a known subcommand — default to scan (backwards compatible).
+    # This handles both `sentinel owner/repo` and `sentinel --local .`
+    subcmd = "scan"
+end
+
+case subcmd
+when "scan"
+    require_relative "../lib/cli/scan"
+when "fix"
+    require_relative "../lib/cli/fix"
+when "bot"
+    require_relative "../lib/cli/bot"
+when "version"
+    puts "sentinel #{Sentinel::VERSION}"
+when "help"
+    puts HELP_TEXT
+end