Skip to content

Quick Start

ActionScope runs in three modes. Pick whichever fits.

1. As a CLI (static analysis, no AWS creds)

pip install actionscope
cd /path/to/your/repo
actionscope scan .

Output looks like:

ActionScope — Blast Radius Report
Path: /my-repo  |  Workflows: 4
Observed Risk: 🔴 CRITICAL
Coverage: COMPLETE
Gate: REPORT ONLY

⛔ KNOWN COMPROMISED ACTIONS (1 found)
⛔ CRITICAL: actions-cool/issues-helper@v3 (issue-triage.yml)

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

  ┌─────────────────────────────┬────────────────────┬──────────┐
  │ iam:PassRole                │ Permissions mgmt   │ 🔴 CRIT  │
  │ ec2:TerminateInstances      │ Write              │ 🟠 HIGH  │
  └─────────────────────────────┴────────────────────┴──────────┘

  🔴 Privilege Escalation Path: iam:PassRole on * — can escalate to any role

Common flags

actionscope scan . --aws-verify        # fetch live IAM policies (read-only)
actionscope scan . --resolve-pins      # suggest full-SHA pins
actionscope update-db                  # refresh compromised-action advisories
actionscope scan . --offline           # disable scan-time API calls
actionscope scan . --fail-on high      # legacy aggregate-risk gate
actionscope scan . --fail-on high --new-only --min-confidence high
actionscope scan . --output-format sarif --output-file results.sarif
actionscope scan . --output-format json --output-file results.json
actionscope scan . --save-state        # save state for delta tracking
actionscope scan . --load-state        # compare against previous state

See the CLI Reference for every flag.

2. As a GitHub Action (PR comments + Code Scanning)

Add this to .github/workflows/security.yml:

name: ActionScope
on: [push, pull_request]

permissions:
  contents: read
  security-events: write   # for SARIF upload
  pull-requests: write     # for PR comments

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: r12habh/ActionScope@v0
        with:
          fail-on: high          # block new, high-confidence HIGH/CRITICAL findings
          new-only: true         # only newly gate-eligible findings
          min-confidence: high   # avoid blocking on heuristic matches
          save-state: true       # seed baseline from the default branch
          comment-pr: true       # post findings as a PR comment
          upload-sarif: true     # show in GitHub Security tab

This gives you:

  • A PR comment on every pull request summarising the risk delta
  • SARIF results in the Security tab as first-class Code Scanning alerts
  • CI failure only for new, high-confidence HIGH/CRITICAL findings

The Action is report-only if fail-on is omitted. On the first new-only run, the gate is NOT EVALUATED; a trusted default-branch run creates the baseline. See Confidence-Aware CI Gating for the rollout model.

3. With live AWS verification

For repos where the IAM policies aren't in the same repo, ActionScope can hit the IAM API directly (read-only):

pip install "actionscope[aws]"
export AWS_PROFILE=my-profile
actionscope scan . --aws-verify

Required IAM permissions are minimal and documented at AWS Verification Permissions.

What's next