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.
