actionscope 0.1.0__tar.gz

actionscope-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.idea/
+.venv/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/

actionscope-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to ActionScope are documented here.
+
+## [0.1.0] - 2026-05-16
+
+### Added
+- GitHub Actions workflow parser: detects AWS credential configurations
+- IAM policy risk classifier using policy-sentry action database
+- Terraform HCL parser for IAM resource definitions
+- JSON IAM policy file parser
+- GITHUB_TOKEN permission analyzer
+- Privilege escalation path detector (8 common paths)
+- Terminal reporter with Rich color output
+- JSON output format for CI integration
+- Markdown output format for GitHub PR comments
+- GitHub Action integration (actionscope@v0)
+- `--aws-verify` flag for live AWS IAM API verification
+
+### Security
+- All analysis is read-only and deterministic
+- No data is sent to external services
+- AWS verification uses minimum required IAM permissions

actionscope-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to ActionScope
+
+## Adding a New IAM Risk Rule
+
+The easiest contribution is adding IAM action risk classifications.
+See `actionscope/analyzers/iam_risk.py` — the `ALWAYS_CRITICAL` set.
+
+To add a new always-critical action:
+
+1. Add it to the `ALWAYS_CRITICAL` set in iam_risk.py
+2. Add a test in tests/test_iam_risk.py
+3. Open a PR
+
+## Adding a New Workflow Parser Pattern
+
+ActionScope currently detects `aws-actions/configure-aws-credentials`.
+To add support for another credential provider (e.g. Google Cloud):
+
+1. Add a parser function in `actionscope/parsers/workflow.py`
+2. Add a new CredentialSource type in models.py if needed
+3. Add test fixtures in tests/fixtures/workflows/
+4. Open a PR
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Self-Scan
+
+ActionScope scans itself in CI. This repo intentionally uses minimal
+permissions (contents: read only) to demonstrate good practice.

actionscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rishabh Singh
+
+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.

actionscope-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: actionscope
+Version: 0.1.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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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
+```
+
+## How It Works
+
+ActionScope performs **static analysis only** — it never sends your code to
+any external service.
+
+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 (coming in v1.0)
+```
+
+In v1.0, `--aws-verify` will use read-only AWS API calls to fetch the real
+attached policies for any role ARN found in your workflows.
+
+## Public Research
+
+ActionScope includes a reproducible public-data research scaffold for analyzing
+workflow-level AWS security patterns across public GitHub repositories. See
+[`research/`](research/) for the scanner, methodology, and anonymized findings
+template.
+
+## Built By
+
+Rishabh Singh — AWS Security Engineer.
+[GitHub](https://github.com/r12habh)

actionscope-0.1.0/README.md

@@ -0,0 +1,89 @@
+# ActionScope
+
+> Map the AWS blast radius of your GitHub Actions workflows.
+
+[![PyPI](https://img.shields.io/pypi/v/actionscope)](https://pypi.org/project/actionscope/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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
+```
+
+## How It Works
+
+ActionScope performs **static analysis only** — it never sends your code to
+any external service.
+
+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 (coming in v1.0)
+```
+
+In v1.0, `--aws-verify` will use read-only AWS API calls to fetch the real
+attached policies for any role ARN found in your workflows.
+
+## Public Research
+
+ActionScope includes a reproducible public-data research scaffold for analyzing
+workflow-level AWS security patterns across public GitHub repositories. See
+[`research/`](research/) for the scanner, methodology, and anonymized findings
+template.
+
+## Built By
+
+Rishabh Singh — AWS Security Engineer.
+[GitHub](https://github.com/r12habh)

actionscope-0.1.0/action.yml

@@ -0,0 +1,109 @@
+name: 'ActionScope'
+description: 'Map the AWS blast radius of GitHub Actions workflows and AI agent configs'
+author: 'Rishabh Singh'
+
+branding:
+  icon: 'shield'
+  color: 'orange'
+
+inputs:
+  path:
+    description: 'Path to the repository root to scan'
+    required: false
+    default: '.'
+  fail-on:
+    description: 'Fail the action if overall risk is at or above this level (critical, high, medium, low)'
+    required: false
+    default: 'high'
+  output-format:
+    description: 'Output format: terminal, json, or markdown'
+    required: false
+    default: 'terminal'
+  comment-pr:
+    description: 'Post findings as a PR comment (requires pull-requests: write permission)'
+    required: false
+    default: 'false'
+  github-token:
+    description: 'GitHub token for posting PR comments'
+    required: false
+    default: '${{ github.token }}'
+  version:
+    description: 'ActionScope version to install (default: latest)'
+    required: false
+    default: ''
+
+outputs:
+  overall-risk:
+    description: 'The overall risk level found (critical, high, medium, low, info)'
+    value: ${{ steps.scan.outputs.overall-risk }}
+  findings-json:
+    description: 'JSON string of all findings'
+    value: ${{ steps.scan.outputs.findings-json }}
+  credential-sources-count:
+    description: 'Number of AWS credential sources found'
+    value: ${{ steps.scan.outputs.credential-sources-count }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.11'
+
+    - name: Install ActionScope
+      shell: bash
+      run: |
+        if [ -n "${{ inputs.version }}" ]; then
+          pip install "actionscope==${{ inputs.version }}"
+        else
+          pip install actionscope
+        fi
+
+    - name: Run ActionScope
+      id: scan
+      shell: bash
+      run: |
+        actionscope scan ${{ inputs.path }} \
+          --output-format json \
+          --output-file /tmp/actionscope-results.json || true
+
+        if [ -f /tmp/actionscope-results.json ]; then
+          RISK=$(python3 -c "
+        import json
+        d = json.load(open('/tmp/actionscope-results.json'))
+        print(d.get('overall_risk', 'info'))
+          ")
+          COUNT=$(python3 -c "
+        import json
+        d = json.load(open('/tmp/actionscope-results.json'))
+        print(d.get('summary', {}).get('credential_sources', 0))
+          ")
+          echo "overall-risk=$RISK" >> "$GITHUB_OUTPUT"
+          {
+            echo 'findings-json<<JSON_EOF'
+            cat /tmp/actionscope-results.json
+            echo JSON_EOF
+          } >> "$GITHUB_OUTPUT"
+          echo "credential-sources-count=$COUNT" >> "$GITHUB_OUTPUT"
+        fi
+
+
+    - name: Post PR comment
+      if: inputs.comment-pr == 'true' && github.event_name == 'pull_request'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+      run: |
+        MARKDOWN=$(actionscope scan ${{ inputs.path }} --output-format markdown 2>/dev/null || echo "ActionScope scan failed")
+        gh pr comment ${{ github.event.pull_request.number }} \
+          --body "$MARKDOWN" \
+          --edit-last 2>/dev/null || \
+        gh pr comment ${{ github.event.pull_request.number }} \
+          --body "$MARKDOWN"
+
+    - name: Fail on risk level
+      if: inputs.fail-on != ''
+      shell: bash
+      run: |
+        actionscope scan ${{ inputs.path }} --fail-on ${{ inputs.fail-on }}

actionscope-0.1.0/actionscope/__init__.py

@@ -0,0 +1,6 @@
+"""Top-level package for ActionScope."""
+
+from __future__ import annotations
+
+version = "0.1.0"
+__version__ = version

actionscope-0.1.0/actionscope/analyzers/__init__.py

@@ -0,0 +1,3 @@
+"""Analyzers that classify IAM and GitHub token blast radius."""
+
+from __future__ import annotations

actionscope-0.1.0/actionscope/analyzers/github_token.py

@@ -0,0 +1,201 @@
+"""GITHUB_TOKEN permission analyzer for workflow-level and job-level scopes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from actionscope.models import GitHubTokenPermission, RiskLevel
+
+KNOWN_PERMISSION_SCOPES = (
+    "actions",
+    "checks",
+    "contents",
+    "deployments",
+    "discussions",
+    "id-token",
+    "issues",
+    "packages",
+    "pages",
+    "pull-requests",
+    "repository-projects",
+    "security-events",
+    "statuses",
+)
+
+HIGH_WRITE_SCOPES = {"pull-requests", "packages", "id-token"}
+MEDIUM_WRITE_SCOPES = {"contents", "actions", "deployments"}
+
+
+def analyze_workflow_permissions(
+    workflow_data: dict,
+    workflow_file: str,
+) -> list[GitHubTokenPermission]:
+    """Return GITHUB_TOKEN permission findings from parsed workflow YAML."""
+    if not isinstance(workflow_data, dict):
+        return []
+
+    findings: list[GitHubTokenPermission] = []
+
+    if "permissions" in workflow_data and workflow_data["permissions"] is not None:
+        findings.extend(
+            _permissions_to_findings(
+                permissions=workflow_data["permissions"],
+                workflow_file=workflow_file,
+                job_name="",
+                oidc_expected=_workflow_uses_role_to_assume(workflow_data),
+            )
+        )
+
+    jobs = workflow_data.get("jobs")
+    if jobs is None:
+        jobs = {}
+    if isinstance(jobs, dict):
+        for job_name, job_data in jobs.items():
+            if not isinstance(job_data, dict):
+                continue
+            if "permissions" not in job_data or job_data["permissions"] is None:
+                continue
+            findings.extend(
+                _permissions_to_findings(
+                    permissions=job_data["permissions"],
+                    workflow_file=workflow_file,
+                    job_name=str(job_name),
+                    oidc_expected=_job_uses_role_to_assume(job_data),
+                )
+            )
+
+    return findings
+
+
+def get_dangerous_token_permissions(
+    perms: list[GitHubTokenPermission],
+) -> list[GitHubTokenPermission]:
+    """Return only permissions with risk MEDIUM or higher."""
+    return [
+        permission
+        for permission in perms
+        if permission.risk_level >= RiskLevel.MEDIUM
+    ]
+
+
+def summarize_token_risk(perms: list[GitHubTokenPermission]) -> dict:
+    """Summarize notable GITHUB_TOKEN permission risks."""
+    write_permissions = {
+        permission.scope
+        for permission in perms
+        if permission.access.lower() == "write"
+    }
+
+    return {
+        "has_write_all": all(
+            scope in write_permissions for scope in KNOWN_PERMISSION_SCOPES
+        ),
+        "has_code_write": "contents" in write_permissions,
+        "has_workflow_write": "actions" in write_permissions,
+        "has_pr_write": "pull-requests" in write_permissions,
+        "has_package_write": "packages" in write_permissions,
+        "overall_risk": max(
+            (permission.risk_level for permission in perms),
+            default=RiskLevel.INFO,
+        ),
+    }
+
+
+def _permissions_to_findings(
+    permissions: Any,
+    workflow_file: str,
+    job_name: str,
+    oidc_expected: bool,
+) -> list[GitHubTokenPermission]:
+    if permissions is None or permissions == {}:
+        return []
+
+    if isinstance(permissions, str):
+        access = permissions.strip().lower()
+        if access == "write-all":
+            return [
+                GitHubTokenPermission(
+                    workflow_file=workflow_file,
+                    job_name=job_name,
+                    scope=scope,
+                    access="write",
+                    risk_level=RiskLevel.HIGH,
+                )
+                for scope in KNOWN_PERMISSION_SCOPES
+            ]
+        if access == "read-all":
+            return [
+                GitHubTokenPermission(
+                    workflow_file=workflow_file,
+                    job_name=job_name,
+                    scope=scope,
+                    access="read",
+                    risk_level=RiskLevel.LOW,
+                )
+                for scope in KNOWN_PERMISSION_SCOPES
+            ]
+        return []
+
+    if not isinstance(permissions, dict):
+        return []
+
+    findings: list[GitHubTokenPermission] = []
+    for scope, access in permissions.items():
+        normalized_scope = str(scope).strip().lower()
+        normalized_access = str(access).strip().lower()
+        findings.append(
+            GitHubTokenPermission(
+                workflow_file=workflow_file,
+                job_name=job_name,
+                scope=normalized_scope,
+                access=normalized_access,
+                risk_level=_classify_permission(
+                    normalized_scope,
+                    normalized_access,
+                    oidc_expected,
+                ),
+            )
+        )
+    return findings
+
+
+def _classify_permission(scope: str, access: str, oidc_expected: bool) -> RiskLevel:
+    if access != "write":
+        return RiskLevel.LOW
+
+    if scope == "id-token" and oidc_expected:
+        return RiskLevel.INFO
+
+    if scope in HIGH_WRITE_SCOPES:
+        return RiskLevel.HIGH
+
+    if scope in MEDIUM_WRITE_SCOPES:
+        return RiskLevel.MEDIUM
+
+    return RiskLevel.LOW
+
+
+def _workflow_uses_role_to_assume(workflow_data: dict) -> bool:
+    jobs = workflow_data.get("jobs")
+    if jobs is None:
+        jobs = {}
+    if not isinstance(jobs, dict):
+        return False
+    return any(
+        isinstance(job_data, dict) and _job_uses_role_to_assume(job_data)
+        for job_data in jobs.values()
+    )
+
+
+def _job_uses_role_to_assume(job_data: dict) -> bool:
+    steps = job_data.get("steps", [])
+    if not isinstance(steps, list):
+        return False
+
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        step_with = step.get("with", {})
+        if isinstance(step_with, dict) and step_with.get("role-to-assume"):
+            return True
+    return False