Metadata-Version: 2.4
Name: kryptorious-wfguard
Version: 1.0.0
Summary: Lint GitHub Actions workflows for CI-breaking and supply-chain issues — no Go install required.
Author: Kryptorious Quantum Biosciences, Inc.
License: MIT
Project-URL: Homepage, https://kryptorious.gumroad.com/l/jbvet
Project-URL: Repository, https://github.com/CodeGero/wfguard
Keywords: github-actions,ci,yaml,lint,workflow,supply-chain,secops
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# kryptorious-wfguard

**Lint GitHub Actions workflows for CI-breaking and supply-chain issues — no Go install required.**

`wfguard` is a native Python CLI that catches the workflow mistakes that break CI or weaken your
supply-chain posture *before* they merge. It parses `.github/workflows/*.yml` — no `actionlint`
(Golang) dependency, runs anywhere Python runs, offline.

Pairs naturally with the 15 [Kryptorious GitHub Actions](https://codegero.github.io) you can drop in.

## Install

```bash
pip install kryptorious-wfguard
```

## Usage

```bash
# Lint all workflows under the current repo
wfguard check

# In CI — fail the build on any error-severity issue
wfguard check --fail-on error

# Machine-readable output
wfguard check --json
wfguard check --sarif > wfguard.sarif

# Catch warnings too (moving refs, missing shell, duplicate names)
wfguard check --fail-on warning

# Just enumerate discovered workflow files
wfguard list
```

## What it catches

| Rule | Severity | Catches |
|------|----------|---------|
| `WF-002` | error | Missing or empty `on:` trigger |
| `WF-003` | error | Missing or empty `jobs:` |
| `JOB-001` | error | Job is not a mapping |
| `JOB-002` | error | Job missing `runs-on:` |
| `JOB-003` | warning | Job has no `permissions:` (GITHUB_TOKEN defaults to write-all) |
| `JOB-004` | error | `needs:` references an undefined job |
| `JOB-005` | error | Job missing `steps:` |
| `STEP-001` | error | Malformed `uses:` reference |
| `STEP-002` | warning | `uses:` pins a moving tag/branch (`main`, `master`, `develop`, `.x`) |
| `STEP-003` | warning | `uses:` uses a non-standard ref (not semver or SHA) |
| `STEP-004` | warning | `run:` without `shell:` |
| `STEP-005` | warning | Duplicate step name |
| `ENV-001` | warning | References `env.X` that is never defined |
| `YAML-001` | error | YAML parse failure |

## Why not just use actionlint?

`actionlint` is excellent but ships as a Go binary — another toolchain to install and pin in CI,
and it doesn't run on every platform out of the box in a Python shop. `wfguard` is one
`pip install`, drops into a Python project's existing test/CI flow, and emits JSON or SARIF so you
can gate on it directly.

## CI example

```yaml
# .github/workflows/wf-lint.yml
name: Workflow Lint
on: [pull_request]
jobs:
  wfguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install kryptorious-wfguard
      - run: wfguard check --fail-on error
```

## License

MIT — free for any use. Part of the 31-tool [Kryptorious Developer Suite](https://kryptorious.gumroad.com/l/jbvet)
($9 lifetime, DevFlow Premium included).
