Skip to content

cli-reference.md

Latest commit

 

History

History
215 lines (161 loc) · 11.7 KB

cli-reference.md

File metadata and controls

215 lines (161 loc) · 11.7 KB
Raw

ActionScope CLI Reference

This page documents the current ActionScope command-line interface.

Global Options

Option Default Description Example
--version n/a Print the installed ActionScope version. actionscope --version
--help n/a Show command help. actionscope --help

actionscope scan [PATH] [OPTIONS]

Scan a repository or a single workflow file for GitHub Actions AWS security exposure.

actionscope scan .
actionscope scan tests/fixtures/demo_repo --output-format json

Arguments

Argument Default Description Example
PATH . Repository root or workflow file to scan. actionscope scan /path/to/repo

Options

Flag Short Default Description Example
--output-format -f terminal Output format: terminal, json, markdown, or sarif. actionscope scan . -f sarif
--output-file -o none Write output to a file. Terminal mode writes Markdown when this is used. actionscope scan . -f json -o scan.json
--fail-on none none Enable CI gating at critical, high, medium, or low. With no confidence or new-only option, this preserves aggregate-risk behavior. actionscope scan . --fail-on high
--new-only none False Apply --fail-on only to findings not already eligible under the loaded baseline. This includes new findings and existing findings that cross the configured severity or confidence threshold. Implies --load-state. actionscope scan . --fail-on high --new-only
--min-confidence none none Gate only findings at or above high, medium, or low confidence. Requires --fail-on. actionscope scan . --fail-on high --min-confidence high
--require-baseline none False Exit with code 2 when --new-only cannot load an exact version-2 baseline. actionscope scan . --fail-on high --new-only --require-baseline
--aws-verify none False Fetch live AWS IAM role policies with read-only IAM API calls. Requires actionscope[aws] and AWS credentials. actionscope scan . --aws-verify
--no-color none False Disable terminal color output. actionscope scan . --no-color
--quiet -q False Suppress terminal output, useful with --output-file. actionscope scan . -q -o report.md
--save-state none False Save compact scan state to .actionscope/last_scan.json. actionscope scan . --save-state
--load-state none False Load previous state and compute a risk delta. actionscope scan . --load-state
--state-file none .actionscope/last_scan.json Custom path for state save/load. actionscope scan . --save-state --state-file /tmp/state.json
--resolve-pins none False Resolve unpinned GitHub Action tags to current commit SHAs via GitHub API. actionscope scan . --resolve-pins
--github-token none $GITHUB_TOKEN GitHub token used for pin resolution and authenticated inspection of external reusable workflows. actionscope scan . --github-token "$GITHUB_TOKEN"
--offline none False Disable all scan-time network calls. Cannot be combined with --aws-verify or --resolve-pins. actionscope scan . --offline
--config none PATH/.actionscope.yml when present Load a custom repository risk policy file. actionscope scan . --config security/actionscope.yml
--max-policy-files none 800 Limit JSON policy candidates outside common policy directories. Set to 0 for unlimited. actionscope scan . --max-policy-files 2000

Common Scan Examples

# Human-readable output
actionscope scan .

# CI JSON output
actionscope scan . --output-format json --output-file actionscope.json

# GitHub Code Scanning SARIF
actionscope scan . --output-format sarif --output-file actionscope.sarif

# Fail CI on high or critical findings
actionscope scan . --fail-on high

# Recommended: fail only on new, high-confidence findings
actionscope scan . --load-state --fail-on high --new-only \
  --min-confidence high

# Compare with the previous scan
actionscope scan . --load-state --save-state

# Inspect external reusable workflows referenced by jobs.<id>.uses.
# This example assumes GITHUB_TOKEN is already configured in the environment.
actionscope scan . --github-token "$GITHUB_TOKEN"

# Guarantee that ambient credentials cannot trigger API calls
actionscope scan . --offline

actionscope config init [OPTIONS]

Create a validated starter .actionscope.yml with examples for IAM action overrides, hard blocks, custom escalation paths, suppressions, and deploy-job calibration.

actionscope config init
actionscope config init --output security/actionscope.yml
Flag Default Description Example
--output .actionscope.yml Configuration file to create. actionscope config init --output security/actionscope.yml
--force False Replace an existing configuration file. actionscope config init --force

See Repository Risk Policy for schema and precedence details.

actionscope update-db [OPTIONS]

Fetch GitHub Actions malware advisories and write a merged local cache. This is the only command that refreshes advisory data; normal scans never update it in the background.

actionscope update-db
actionscope update-db --ttl-hours 12

The updater always preserves the bundled curated entries. GitHub's global malware advisory endpoint is the primary feed. The OpenSSF malicious-packages repository is probed conditionally and skipped cleanly while it has no stable GitHub Actions feed.

Flag Default Description Example
--github-token $GITHUB_TOKEN Token for higher GitHub API rate limits. actionscope update-db --github-token "$GITHUB_TOKEN"
--cache-file ~/.actionscope/compromised_actions_cache.json Override the local cache path. actionscope update-db --cache-file /tmp/actions.json
--ttl-hours 24 Number of hours the cache remains fresh. actionscope update-db --ttl-hours 12

actionscope report [JSON_FILE] [OPTIONS]

Render a previously saved ActionScope JSON result without re-scanning.

actionscope report scan.json --format markdown
actionscope report --from-json scan.json --format sarif

Arguments

Argument Default Description Example
JSON_FILE none Saved JSON result from actionscope scan --output-format json. actionscope report scan.json

Options

Flag Short Default Description Example
--from-json none none Alternate way to provide the saved JSON file. actionscope report --from-json scan.json
--format -f markdown Render as markdown, terminal, json, or sarif. actionscope report scan.json -f terminal

actionscope gate JSON_FILE [OPTIONS]

Evaluate CI policy against a saved ActionScope JSON report without rescanning. This is the command used by the Marketplace Action after producing its single JSON scan.

actionscope gate scan.json --fail-on high
actionscope gate scan.json --fail-on high --new-only --min-confidence high
Flag Default Description Example
--fail-on required Severity threshold: critical, high, medium, or low. actionscope gate scan.json --fail-on high
--min-confidence high Minimum confidence for a finding to block. actionscope gate scan.json --fail-on high --min-confidence medium
--new-only False Gate findings that are absent from the exact baseline or newly cross the configured severity/confidence policy. actionscope gate scan.json --fail-on high --new-only
--require-baseline False Exit 2 instead of 0 when a new-only gate has no exact baseline. Requires --new-only. actionscope gate scan.json --fail-on high --new-only --require-baseline
--write-back False Store the gate decision in the JSON report for later rendering. actionscope gate scan.json --fail-on high --write-back

actionscope corpus scan MANIFEST [OPTIONS]

Scan many repositories, each pinned to a commit SHA, and write per-repository and per-credential-binding tables for empirical studies. Repository identities are anonymized by default. See Corpus Scans for the manifest format, output schema, and anonymization model.

actionscope corpus scan manifest.csv --output-dir results/
actionscope corpus scan manifest.csv --output-dir results/ --resume

Arguments

Argument Description
MANIFEST CSV or JSON file with repo_url and commit (full 40-character SHA) per row, plus an optional path subdirectory.

Options

Flag Short Default Description Example
--output-dir -o required Directory for the result tables. Must be new or empty unless resuming. actionscope corpus scan m.csv -o results/
--jobs -j 4 Repositories to fetch and scan in parallel (1–64). actionscope corpus scan m.csv -o results/ -j 8
--fetch-timeout none 300 Seconds allowed to fetch one repository. A slower fetch is recorded as fetch_timeout. actionscope corpus scan m.csv -o results/ --fetch-timeout 600
--scan-timeout none 300 Seconds allowed to scan one repository. A slower scan is recorded as scan_timeout. actionscope corpus scan m.csv -o results/ --scan-timeout 120
--resume none False Continue an interrupted run in the same output directory. Scanned entries are kept; every other entry is retried. The manifest and ActionScope version must match the original run. actionscope corpus scan m.csv -o results/ --resume
--no-anonymize none False Put repository URLs, commits, paths, and workflow, job, and step names in the shareable tables. Intended for owners scanning their own repositories. Role ARNs are never written. actionscope corpus scan m.csv -o results/ --no-anonymize
--quiet -q False Suppress per-repository progress lines and the final summary. actionscope corpus scan m.csv -o results/ -q

Planned Commands

The roadmap issues below are open, but these commands are not implemented in the current release:

Command Status Tracking issue
actionscope trend Planned GitHub issue: historical risk tracking and trend reporting
actionscope pin Not implemented; current support is scan --resolve-pins GitHub issue: auto-pin resolver follow-ups

Exit Codes

Code Meaning
0 Scan or gate completed without a blocking finding. This also covers a new-only gate with no baseline unless --require-baseline is set.
1 At least one finding matched the configured gate policy.
2 CLI usage error, report-file read error, or required baseline unavailable.

Environment Variables

Variable Used by Description
GITHUB_TOKEN --resolve-pins, reusable workflow inspection Authenticates GitHub API calls for tag resolution and access to external reusable workflow YAML.
ACTIONSCOPE_COMPROMISED_DB_CACHE scan, update-db Override the compromised-action cache path. Primarily useful for CI and tests.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS profile variables --aws-verify Standard AWS SDK credential sources used by boto3.