Metadata-Version: 2.4
Name: actions-scanner
Version: 1.0.0
Summary: GitHub Actions vulnerability scanner for PwnRequest attacks
Project-URL: Homepage, https://github.com/SecKatie/actions-scanner
Project-URL: Documentation, https://github.com/SecKatie/actions-scanner#readme
Project-URL: Repository, https://github.com/SecKatie/actions-scanner
Project-URL: Issues, https://github.com/SecKatie/actions-scanner/issues
Author-email: Katie Mulliken <mulliken@redhat.com>
License: MIT
License-File: LICENSE
Keywords: actions,github,scanner,security,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: click>=8.1.7
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Provides-Extra: all
Requires-Dist: aioresponses>=0.7.0; extra == 'all'
Requires-Dist: ldap3>=2.9.1; extra == 'all'
Requires-Dist: pre-commit>=3.6.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Requires-Dist: ty>=0.0.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: aioresponses>=0.7.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: ty>=0.0.1; extra == 'dev'
Provides-Extra: ldap
Requires-Dist: ldap3>=2.9.1; extra == 'ldap'
Description-Content-Type: text/plain

= GitHub Actions PwnRequest Vulnerability Scanner

A toolkit for detecting GitHub Actions workflows vulnerable to the https://securitylab.github.com/research/github-actions-preventing-pwn-requests/[PwnRequest] attack pattern — where `pull_request_target` workflows check out and execute untrusted PR code, allowing secret exfiltration.

CAUTION: Use findings responsibly and follow responsible disclosure practices.

== Installation

[source,bash]
----
uv tool install git+https://github.com/SecKatie/actions-scanner.git
----

== Usage

[source,bash]
----
# Scan an org, repo URL, local directory, or list file (default format: csv)
actions-scanner scan your-org -o results.csv

# Validate findings with AI-assisted confirmation (accepts csv or json)
actions-scanner validate results.csv

# Export to markdown
actions-scanner report results.csv -o report.md --format markdown
----

== What It Detects

The scanner flags workflows where all three conditions exist in the same job:

1. **Trigger:** `pull_request_target` (runs with write permissions and secrets)
2. **Checkout:** Untrusted PR ref (`head.sha`, `head.ref`, `merge_commit_sha`, `github.head_ref`)
3. **Execution:** Build commands (`npm install`, `make`, `pip install`, `docker build`, etc.) or local actions (`./action`)

== Development

**Prerequisites:** Python 3.11+, https://github.com/astral-sh/uv[uv], `gh` CLI (authenticated), `git`

[source,bash]
----
git clone https://github.com/SecKatie/actions-scanner.git && cd actions-scanner
uv sync
uv run pytest tests/ -v
----

=== Environment Variables

[cols="1,2"]
|===
|Variable |Description

|`GITHUB_TOKEN`
|GitHub personal access token (required for org scanning)
|===

== References

* https://securitylab.github.com/research/github-actions-preventing-pwn-requests/[GitHub Security Lab: Preventing pwn requests]
* https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions[GitHub Docs: Security hardening for GitHub Actions]

== License

Internal use only.
