Metadata-Version: 2.4
Name: actionscope
Version: 0.2.0
Summary: Map the AWS blast radius of GitHub Actions workflows
Project-URL: Homepage, https://github.com/r12habh/ActionScope
Project-URL: Documentation, https://github.com/r12habh/ActionScope#readme
Project-URL: Repository, https://github.com/r12habh/ActionScope
Project-URL: Issues, https://github.com/r12habh/ActionScope/issues
Author-email: Rishabh Singh <rishabhsinghe@gmail.com>
License: MIT
License-File: LICENSE
Keywords: aws,blast-radius,cicd,devops,devsecops,github-actions,iam,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: policy-sentry>=0.12.0
Requires-Dist: python-hcl2>=4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: aws
Requires-Dist: boto3>=1.26; extra == 'aws'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: moto[iam]>=5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: research
Requires-Dist: requests>=2.31; extra == 'research'
Requires-Dist: tqdm>=4.66; extra == 'research'
Description-Content-Type: text/markdown

# ActionScope

> Map the AWS blast radius of your GitHub Actions workflows.

[![PyPI](https://img.shields.io/pypi/v/actionscope)](https://pypi.org/project/actionscope/)
[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-ActionScope-blue?logo=github)](https://github.com/marketplace/actions/actionscope)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/r12habh/ActionScope/actions/workflows/ci.yml/badge.svg)](https://github.com/r12habh/ActionScope/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/r12habh/ActionScope/branch/main/graph/badge.svg)](https://codecov.io/gh/r12habh/ActionScope)

ActionScope reads your `.github/workflows/` files, Terraform IAM resources,
and inline JSON IAM policies, then tells you — in plain English — what your
CI/CD pipelines can actually do to your AWS environment.

**It answers the question no other tool answers:**
"If this workflow is compromised, what can an attacker do in AWS?"

## Install

```bash
pip install actionscope
```

## Quick Start

```bash
actionscope scan .
```

## Example Output

```
ActionScope — Blast Radius Report
Path: /my-repo  |  Workflows: 2  |  Overall Risk: 🔴 CRITICAL

deploy.yml → deploy → Configure AWS credentials
  AWS Role: arn:aws:iam::123456789012:role/github-deploy-role
  Auth: OIDC ✓

  ┌─────────────────────────────┬────────────────────┬──────────┐
  │ Action                      │ Access Level       │ Risk     │
  ├─────────────────────────────┼────────────────────┼──────────┤
  │ iam:PassRole                │ Permissions mgmt   │ 🔴 CRIT  │
  │ ec2:TerminateInstances      │ Write              │ 🟠 HIGH  │
  │ s3:GetObject                │ Read               │ 🟢 LOW   │
  └─────────────────────────────┴────────────────────┴──────────┘

  ⚠️  iam:PassRole on * — privilege escalation path exists
```

## Use as a GitHub Action

```yaml
- uses: r12habh/ActionScope@v0
  with:
    fail-on: high
    comment-pr: true
```

## What ActionScope Adds Beyond Existing Tools

| Capability | actionlint | zizmor | Scorecard | ActionScope |
|-----------|-----------|--------|-----------|-------------|
| Workflow syntax validation | ✅ | Partial | ❌ | Partial |
| Security pattern detection | ❌ | ✅ | ✅ | ✅ |
| GITHUB_TOKEN review | ❌ | ✅ | ✅ | ✅ |
| Unpinned actions detection | ❌ | ✅ | ✅ | ✅ |
| AWS credential source detection | ❌ | ❌ | ❌ | ✅ |
| Workflow → IAM role correlation | ❌ | ❌ | ❌ | ✅ |
| Blast-radius plain-English report | ❌ | ❌ | ❌ | ✅ |
| SARIF / GitHub Security tab | ❌ | ✅ | ✅ | ✅ |

## How It Works

ActionScope performs **static analysis by default** — it never sends your code
to any external service unless you explicitly enable live AWS verification.

1. Finds all `.github/workflows/*.yml` files
2. Extracts AWS role ARNs and GITHUB_TOKEN permission declarations
3. Finds matching IAM policies in Terraform or JSON files in your repo
4. Classifies each IAM action by risk using the
   [policy-sentry](https://github.com/salesforce/policy_sentry) database
5. Outputs a plain-English blast radius report

### What If My Policies Aren't in the Repo?

```
ℹ️  Policy not found in repo for role: arn:aws:iam::123456:role/ci-deploy
💡  Run with --aws-verify to fetch live policies from AWS
```

`--aws-verify` uses read-only IAM API calls to fetch the real attached
policies for any role ARN found in your workflows. See
[`docs/aws-verify-permissions.md`](docs/aws-verify-permissions.md) for the
exact AWS permissions required.

Release and Marketplace publishing steps are documented in
[`docs/release-runbook.md`](docs/release-runbook.md).

## Research

ActionScope is backed by a public measurement study of 493 GitHub repositories
and 3,981 workflow files that use AWS via GitHub Actions.

Key findings from May 2026:
- **95.5%** use at least one unpinned action (the supply-chain attack surface)
- **58.2%** use static AWS access keys instead of OIDC
- **44.0%** expose role ARNs directly in workflow files
- **8.1%** use `pull_request_target` with write-capable permissions

→ [Full research findings](research/FINDINGS.md) | [Scanner and data](research/)

## Built By

Rishabh Singh.
[GitHub](https://github.com/r12habh)
