From 2e0a147da32e6a843a1b292d99ff5c4c4216a7b5 Mon Sep 17 00:00:00 2001 From: sabith Date: Fri, 13 Nov 2026 12:11:22 -0800 Subject: [PATCH] feat: add lens and PLG adoption workflows --- .github/workflows/access-request.yml | 94 +++++++ .github/workflows/lens-verify.yml | 98 +++++++ .github/workflows/pr-review.yml | 384 ++++++++++++++++++++++++++ .github/workflows/quickstart.yml | 100 +++++++ .github/workflows/scan.yml | 34 ++- .github/workflows/self-test.yml | 155 +++++++++++ README.md | 113 +++++++- access-request/action.yml | 99 +++++++ action.yml | 25 +- examples/access-request.yml | 18 ++ examples/lens-verify.yml | 17 ++ examples/pr-review.yml | 19 ++ examples/quickstart.yml | 15 + examples/scan.yml | 3 + lens-verify/action.yml | 104 +++++++ quickstart/action.yml | 105 +++++++ scripts/install-cce.sh | 2 +- scripts/run-access-request.sh | 155 +++++++++++ scripts/run-lens-verify.sh | 187 +++++++++++++ scripts/run-quickstart.sh | 155 +++++++++++ scripts/run-scan.sh | 98 ++++++- testdata/fixture/app.py | 5 + testdata/fixture/lens.yaml | 7 + testdata/lens-fixture/app.py | 6 + testdata/lens-fixture/candidate.yaml | 16 ++ testdata/lens-fixture/current.yaml | 10 + testdata/lens-fixture/regression.yaml | 12 + 27 files changed, 2026 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/access-request.yml create mode 100644 .github/workflows/lens-verify.yml create mode 100644 .github/workflows/pr-review.yml create mode 100644 .github/workflows/quickstart.yml create mode 100644 access-request/action.yml create mode 100644 examples/access-request.yml create mode 100644 examples/lens-verify.yml create mode 100644 examples/pr-review.yml create mode 100644 examples/quickstart.yml create mode 100644 lens-verify/action.yml create mode 100644 quickstart/action.yml create mode 100755 scripts/run-access-request.sh create mode 100755 scripts/run-lens-verify.sh create mode 100755 scripts/run-quickstart.sh create mode 100644 testdata/fixture/lens.yaml create mode 100644 testdata/lens-fixture/app.py create mode 100644 testdata/lens-fixture/candidate.yaml create mode 100644 testdata/lens-fixture/current.yaml create mode 100644 testdata/lens-fixture/regression.yaml diff --git a/.github/workflows/access-request.yml b/.github/workflows/access-request.yml new file mode 100644 index 0000000..2e80cae --- /dev/null +++ b/.github/workflows/access-request.yml @@ -0,0 +1,94 @@ +name: CCE access request (reusable) + +# Artifact-first integration: the calling repository can review or forward the +# access request without granting this workflow cross-repository credentials. +on: + workflow_call: + inputs: + path: + description: Directory to scan inside the checked-out repo. + type: string + default: "." + lens: + description: Local custom lens YAML or HTTPS URL. + type: string + default: "" + lens-sha256: + description: Expected lens file SHA-256 (required for HTTPS lenses). + type: string + default: "" + service: + description: Service name (defaults to the scanned folder name). + type: string + default: "" + commit: + description: Source commit (defaults to git HEAD when available). + type: string + default: "" + output-dir: + description: Directory for the access-request artifact. + type: string + default: cce-results/access-request + upload-artifact: + description: Upload the access-request artifact. + type: boolean + default: true + artifact-name: + description: Name of the uploaded artifact. + type: string + default: cce-access-request + image: + description: CCE container image used to install the CLI. + type: string + default: ghcr.io/stackgenhq/cce:0.0.38 + outputs: + version: + description: Installed cce version. + value: ${{ jobs.access-request.outputs.version }} + image: + description: Container image used for install, or preinstalled. + value: ${{ jobs.access-request.outputs.image }} + access-request-path: + description: Path to cce-access-request.json. + value: ${{ jobs.access-request.outputs.access-request-path }} + operation-count: + description: Number of unique code-evidenced operations. + value: ${{ jobs.access-request.outputs.operation-count }} + commit: + description: Source commit recorded in the access request. + value: ${{ jobs.access-request.outputs.commit }} + lens-file-sha256: + description: SHA-256 of the custom lens file bytes. + value: ${{ jobs.access-request.outputs.lens-file-sha256 }} + +permissions: + contents: read + packages: read + +jobs: + access-request: + runs-on: ubuntu-latest + outputs: + version: ${{ steps.cce.outputs.version }} + image: ${{ steps.cce.outputs.image }} + access-request-path: ${{ steps.cce.outputs.access-request-path }} + operation-count: ${{ steps.cce.outputs.operation-count }} + commit: ${{ steps.cce.outputs.commit }} + lens-file-sha256: ${{ steps.cce.outputs.lens-file-sha256 }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Generate CCE access request + id: cce + uses: stackgenhq/cce-action/access-request@v1 + with: + path: ${{ inputs.path }} + lens: ${{ inputs.lens }} + lens-sha256: ${{ inputs.lens-sha256 }} + service: ${{ inputs.service }} + commit: ${{ inputs.commit }} + output-dir: ${{ inputs.output-dir }} + upload-artifact: ${{ inputs.upload-artifact }} + artifact-name: ${{ inputs.artifact-name }} + image: ${{ inputs.image }} diff --git a/.github/workflows/lens-verify.yml b/.github/workflows/lens-verify.yml new file mode 100644 index 0000000..7dbf8ab --- /dev/null +++ b/.github/workflows/lens-verify.yml @@ -0,0 +1,98 @@ +name: CCE lens verify (reusable) + +on: + workflow_call: + inputs: + fixture: + description: Fixture corpus directory inside the checked-out repository + type: string + required: true + candidate: + description: Candidate lens YAML (local path or pinned HTTPS URL) + type: string + required: true + current: + description: Baseline lens YAML; empty uses the built-in catalog + type: string + default: "" + candidate-sha256: + description: Candidate lens SHA-256 pin + type: string + default: "" + current-sha256: + description: Current lens SHA-256 pin + type: string + default: "" + language: + description: Language scope for fixture verification + type: string + default: AUTO + fail-regression: + description: Fail when verification finds regressed rows + type: boolean + default: true + output-dir: + description: Directory for the lens verdict JSON + type: string + default: cce-results/lens-verify + image: + description: CCE container image (Gate 0 requires 0.0.38 or newer) + type: string + default: ghcr.io/stackgenhq/cce:0.0.38 + upload-artifact: + description: Upload verdict JSON even when verification fails + type: boolean + default: true + artifact-name: + description: Name of the uploaded verdict artifact + type: string + default: cce-lens-verify + outputs: + verdict-path: + description: Path to the verdict JSON evidence + value: ${{ jobs.verify.outputs.verdict-path }} + verdict: + description: Lens verification verdict + value: ${{ jobs.verify.outputs.verdict }} + newly-mapped-count: + description: Number of newly mapped fixture rows + value: ${{ jobs.verify.outputs.newly-mapped-count }} + regressed-count: + description: Number of regressed fixture rows + value: ${{ jobs.verify.outputs.regressed-count }} + candidate-sha256: + description: SHA-256 pin used for the candidate lens + value: ${{ jobs.verify.outputs.candidate-sha256 }} + +permissions: + contents: read + packages: read + +jobs: + verify: + runs-on: ubuntu-latest + outputs: + verdict-path: ${{ steps.lens.outputs.verdict-path }} + verdict: ${{ steps.lens.outputs.verdict }} + newly-mapped-count: ${{ steps.lens.outputs.newly-mapped-count }} + regressed-count: ${{ steps.lens.outputs.regressed-count }} + candidate-sha256: ${{ steps.lens.outputs.candidate-sha256 }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Verify lens Gate 0 + id: lens + uses: stackgenhq/cce-action/lens-verify@v1 + with: + fixture: ${{ inputs.fixture }} + candidate: ${{ inputs.candidate }} + current: ${{ inputs.current }} + candidate-sha256: ${{ inputs.candidate-sha256 }} + current-sha256: ${{ inputs.current-sha256 }} + language: ${{ inputs.language }} + fail-regression: ${{ inputs.fail-regression }} + output-dir: ${{ inputs.output-dir }} + image: ${{ inputs.image }} + upload-artifact: ${{ inputs.upload-artifact }} + artifact-name: ${{ inputs.artifact-name }} diff --git a/.github/workflows/pr-review.yml b/.github/workflows/pr-review.yml new file mode 100644 index 0000000..b7774e8 --- /dev/null +++ b/.github/workflows/pr-review.yml @@ -0,0 +1,384 @@ +name: CCE PR review (reusable) + +on: + workflow_call: + inputs: + path: + description: Directory to scan inside the checked-out repository + type: string + default: "." + language: + description: "Language: GO, PYTHON, JAVA, JAVASCRIPT, or AUTO" + type: string + default: AUTO + filter: + description: "Result filter: cloud or all" + type: string + default: cloud + lens: + description: Local lens path or remote lens URL + type: string + default: "" + lens-sha256: + description: Expected SHA-256 of the lens file bytes + type: string + default: "" + base-ref: + description: Baseline ref (falls back to the pull request base, then main) + type: string + default: "" + policy: + description: Optional CCE policy YAML used to gate the diff + type: string + default: "" + fail-new: + description: Fail when the diff adds entitlements + type: boolean + default: false + comment: + description: Create or update the sticky pull request comment + type: boolean + default: true + upload-sarif: + description: Generate SARIF and upload it to Code Scanning + type: boolean + default: true + artifact-name: + description: Name of the uploaded results artifact + type: string + default: cce-pr-review + image: + description: Container image used to install CCE + type: string + default: ghcr.io/stackgenhq/cce:0.0.38 + outputs: + report-path: + description: Path to the current JSON scan report + value: ${{ jobs.review.outputs.report-path }} + diff-path: + description: Path to the policy-free JSON diff + value: ${{ jobs.review.outputs.diff-path }} + markdown-path: + description: Path to the markdown diff, including policy results + value: ${{ jobs.review.outputs.markdown-path }} + added-count: + description: Number of added entitlements + value: ${{ jobs.review.outputs.added-count }} + removed-count: + description: Number of removed entitlements + value: ${{ jobs.review.outputs.removed-count }} + entitlement-count: + description: Number of entitlements in the current report + value: ${{ jobs.review.outputs.entitlement-count }} + +permissions: + contents: read + packages: read + pull-requests: write + security-events: write + +jobs: + review: + runs-on: ubuntu-latest + outputs: + report-path: ${{ steps.current.outputs.report-path }} + diff-path: cce-results/diff.json + markdown-path: cce-results/api-diff.md + added-count: ${{ steps.results.outputs.added-count }} + removed-count: ${{ steps.results.outputs.removed-count }} + entitlement-count: ${{ steps.current.outputs.entitlement-count }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Resolve baseline ref and lens + id: resolve + shell: bash + env: + INPUT_BASE_REF: ${{ inputs.base-ref }} + PR_BASE_REF: ${{ github.base_ref }} + INPUT_LENS: ${{ inputs.lens }} + INPUT_LENS_SHA256: ${{ inputs.lens-sha256 }} + run: | + set -euo pipefail + + base_ref="${INPUT_BASE_REF:-${PR_BASE_REF:-main}}" + lens="$INPUT_LENS" + lens_sha256="$INPUT_LENS_SHA256" + + case "$lens" in + "") + ;; + https://*) + if [[ -z "$lens_sha256" ]]; then + echo "::error::lens-sha256 is required for a remote HTTPS lens" + exit 1 + fi + ;; + http://*) + echo "::error::Remote lenses must use HTTPS" + exit 1 + ;; + *) + if [[ "$lens" != /* ]]; then + lens="${GITHUB_WORKSPACE}/${lens}" + fi + if [[ ! -f "$lens" ]]; then + echo "::error::Local lens does not exist: $lens" + exit 1 + fi + # The baseline lives in another worktree, so both scans must use + # the current workspace's absolute lens path and exact bytes. + lens="$(realpath "$lens")" + actual_sha="$(sha256sum "$lens" | awk '{print $1}')" + if [[ -n "$lens_sha256" && "$lens_sha256" != "$actual_sha" ]]; then + echo "::error::Lens SHA-256 mismatch: expected $lens_sha256, got $actual_sha" + exit 1 + fi + lens_sha256="$actual_sha" + ;; + esac + + { + printf 'base-ref=%s\n' "$base_ref" + printf 'lens=%s\n' "$lens" + printf 'lens-sha256=%s\n' "$lens_sha256" + } >> "$GITHUB_OUTPUT" + + - name: Scan current source + id: current + uses: stackgenhq/cce-action@v1 + with: + path: ${{ inputs.path }} + language: ${{ inputs.language }} + filter: ${{ inputs.filter }} + lens: ${{ steps.resolve.outputs.lens }} + lens-sha256: ${{ steps.resolve.outputs.lens-sha256 }} + format: json + output-dir: cce-results/current + export-policies: false + image: ${{ inputs.image }} + + - name: Scan baseline source + id: baseline + shell: bash + env: + BASE_REF: ${{ steps.resolve.outputs.base-ref }} + BASE_WORKTREE: /tmp/cce-base + SCAN_PATH: ${{ inputs.path }} + SCAN_LANGUAGE: ${{ inputs.language }} + SCAN_FILTER: ${{ inputs.filter }} + CCE_LENS: ${{ steps.resolve.outputs.lens }} + CCE_LENS_SHA256: ${{ steps.resolve.outputs.lens-sha256 }} + BASELINE_REPORT: cce-results/baseline/scan.json + run: | + set -euo pipefail + + git worktree add --detach "$BASE_WORKTREE" "origin/${BASE_REF}" + + baseline_folder="${BASE_WORKTREE}/${SCAN_PATH}" + if [[ ! -d "$baseline_folder" ]]; then + echo "::error::Baseline scan path does not exist: $baseline_folder" + exit 1 + fi + mkdir -p "$(dirname "$BASELINE_REPORT")" + + args=( + --folder "$baseline_folder" + --language "$SCAN_LANGUAGE" + --filter "$SCAN_FILTER" + --format json + --output "$BASELINE_REPORT" + ) + if [[ -n "$CCE_LENS" ]]; then + args+=(--mapper-file "$CCE_LENS") + fi + if [[ -n "$CCE_LENS_SHA256" ]]; then + args+=(--mapper-sha256 "$CCE_LENS_SHA256") + fi + cce "${args[@]}" + + - name: Generate JSON and policy markdown diffs + id: diff + shell: bash + env: + BASELINE_REPORT: cce-results/baseline/scan.json + CURRENT_REPORT: cce-results/current/scan.json + JSON_DIFF: cce-results/diff.json + MARKDOWN_DIFF: cce-results/api-diff.md + INPUT_POLICY: ${{ inputs.policy }} + INPUT_FAIL_NEW: ${{ inputs.fail-new }} + POLICY_STATUS_FILE: cce-results/policy-status + run: | + set -euo pipefail + + if ! cce diff --help 2>&1 | grep -q markdown; then + echo "::error::CCE Markdown diff requires CCE >= 0.0.38; set image to ghcr.io/stackgenhq/cce:0.0.38 or newer." + exit 1 + fi + + # Keep the machine-readable diff policy-free. Policy is evaluated only + # for the human-facing markdown and the deferred final gate. + cce diff "$BASELINE_REPORT" "$CURRENT_REPORT" \ + --format json --output "$JSON_DIFF" + + args=( + "$BASELINE_REPORT" + "$CURRENT_REPORT" + --format markdown + --output "$MARKDOWN_DIFF" + ) + if [[ -n "$INPUT_POLICY" ]]; then + args+=(--policy "$INPUT_POLICY") + fi + if [[ "$INPUT_FAIL_NEW" == "true" ]]; then + args+=(--fail-new) + fi + + policy_status=0 + cce diff "${args[@]}" || policy_status=$? + printf '%s\n' "$policy_status" > "$POLICY_STATUS_FILE" + + - name: Record diff counts + id: results + shell: bash + env: + JSON_DIFF: cce-results/diff.json + run: | + set -euo pipefail + + added_count="$(jq -r '(.added // []) | length' "$JSON_DIFF")" + removed_count="$(jq -r '(.removed // []) | length' "$JSON_DIFF")" + { + printf 'added-count=%s\n' "$added_count" + printf 'removed-count=%s\n' "$removed_count" + } >> "$GITHUB_OUTPUT" + + - name: Explain fork publishing restrictions + if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork + shell: bash + run: | + set -euo pipefail + echo "::notice::Sticky PR comments are skipped for fork pull requests." + echo "::notice::SARIF generation and upload are skipped for fork pull requests." + + - name: Create or update sticky PR comment + if: inputs.comment && github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork + uses: actions/github-script@v7 + env: + MARKDOWN_PATH: cce-results/api-diff.md + with: + script: | + const fs = require('fs'); + const body = fs.readFileSync(process.env.MARKDOWN_PATH, 'utf8'); + const issue_number = context.issue.number; + const comments = await github.paginate(github.rest.issues.listComments, { + owner: context.repo.owner, + repo: context.repo.repo, + issue_number, + per_page: 100, + }); + const existing = comments.find(comment => + comment.body && comment.body.includes('') + ); + const params = { + owner: context.repo.owner, + repo: context.repo.repo, + body, + }; + if (existing) { + await github.rest.issues.updateComment({ + ...params, + comment_id: existing.id, + }); + } else { + await github.rest.issues.createComment({ + ...params, + issue_number, + }); + } + + - name: Generate SARIF from current source + if: inputs.upload-sarif && (github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork) + shell: bash + env: + SCAN_PATH: ${{ inputs.path }} + SCAN_LANGUAGE: ${{ inputs.language }} + SCAN_FILTER: ${{ inputs.filter }} + CCE_LENS: ${{ steps.resolve.outputs.lens }} + CCE_LENS_SHA256: ${{ steps.resolve.outputs.lens-sha256 }} + SARIF_PATH: cce-results/current/scan.sarif + run: | + set -euo pipefail + + args=( + --folder "$SCAN_PATH" + --language "$SCAN_LANGUAGE" + --filter "$SCAN_FILTER" + --format sarif + --output "$SARIF_PATH" + ) + if [[ -n "$CCE_LENS" ]]; then + args+=(--mapper-file "$CCE_LENS") + fi + if [[ -n "$CCE_LENS_SHA256" ]]; then + args+=(--mapper-sha256 "$CCE_LENS_SHA256") + fi + cce "${args[@]}" + + - name: Upload SARIF to Code Scanning + if: inputs.upload-sarif && (github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork) + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: cce-results/current/scan.sarif + + - name: Upload review artifacts + if: always() + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.artifact-name }} + path: cce-results/ + if-no-files-found: warn + + - name: Write job summary + if: always() + shell: bash + env: + CURRENT_ENTITLEMENT_COUNT: ${{ steps.current.outputs.entitlement-count }} + ADDED_COUNT: ${{ steps.results.outputs.added-count }} + REMOVED_COUNT: ${{ steps.results.outputs.removed-count }} + run: | + set -euo pipefail + + { + echo '## CCE PR review' + echo + echo '| Metric | Count |' + echo '| --- | ---: |' + printf '| Current entitlements | %s |\n' "${CURRENT_ENTITLEMENT_COUNT:-0}" + printf '| Added entitlements | %s |\n' "${ADDED_COUNT:-0}" + printf '| Removed entitlements | %s |\n' "${REMOVED_COUNT:-0}" + } >> "$GITHUB_STEP_SUMMARY" + + - name: Enforce captured policy diff status + if: always() + shell: bash + env: + POLICY_STATUS_FILE: cce-results/policy-status + run: | + set -euo pipefail + + policy_status=0 + if [[ -f "$POLICY_STATUS_FILE" ]]; then + policy_status="$(cat "$POLICY_STATUS_FILE")" + fi + if [[ ! "$policy_status" =~ ^[0-9]+$ ]]; then + echo "::error::Invalid captured CCE policy status: $policy_status" + exit 1 + fi + if (( policy_status != 0 )); then + echo "::error::CCE policy diff failed with exit status $policy_status" + exit "$policy_status" + fi diff --git a/.github/workflows/quickstart.yml b/.github/workflows/quickstart.yml new file mode 100644 index 0000000..b0adbbe --- /dev/null +++ b/.github/workflows/quickstart.yml @@ -0,0 +1,100 @@ +name: CCE quickstart (reusable) + +on: + workflow_call: + inputs: + path: + description: Directory to scan inside the checked-out repo. + type: string + default: "." + lens: + description: Local custom lens YAML or HTTPS URL. + type: string + default: "" + lens-sha256: + description: Expected lens file SHA-256 (required for HTTPS lenses). + type: string + default: "" + policy: + description: Optional local IAM policy JSON for potential-drift review. + type: string + default: "" + write-workflow: + description: Generate .github/workflows/cce.yml if absent. + type: boolean + default: true + output-dir: + description: Directory for the complete quickstart artifact set. + type: string + default: cce-results/quickstart + upload-artifact: + description: Upload the complete quickstart artifact set. + type: boolean + default: true + artifact-name: + description: Name of the uploaded artifact. + type: string + default: cce-quickstart + image: + description: CCE container image used to install the CLI. + type: string + default: ghcr.io/stackgenhq/cce:0.0.38 + outputs: + version: + description: Installed cce version. + value: ${{ jobs.quickstart.outputs.version }} + image: + description: Container image used for install, or preinstalled. + value: ${{ jobs.quickstart.outputs.image }} + bom-path: + description: Path to the Cloud API BOM JSON. + value: ${{ jobs.quickstart.outputs.bom-path }} + html-path: + description: Path to the self-contained HTML report. + value: ${{ jobs.quickstart.outputs.html-path }} + sarif-path: + description: Path to the SARIF report. + value: ${{ jobs.quickstart.outputs.sarif-path }} + lens-lock-path: + description: Path to the lens provenance lockfile. + value: ${{ jobs.quickstart.outputs.lens-lock-path }} + workflow-path: + description: Path to the workflow copy in the artifact set. + value: ${{ jobs.quickstart.outputs.workflow-path }} + entitlement-count: + description: Total entitlements found in the Cloud API BOM. + value: ${{ jobs.quickstart.outputs.entitlement-count }} + +permissions: + contents: read + packages: read + +jobs: + quickstart: + runs-on: ubuntu-latest + outputs: + version: ${{ steps.cce.outputs.version }} + image: ${{ steps.cce.outputs.image }} + bom-path: ${{ steps.cce.outputs.bom-path }} + html-path: ${{ steps.cce.outputs.html-path }} + sarif-path: ${{ steps.cce.outputs.sarif-path }} + lens-lock-path: ${{ steps.cce.outputs.lens-lock-path }} + workflow-path: ${{ steps.cce.outputs.workflow-path }} + entitlement-count: ${{ steps.cce.outputs.entitlement-count }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run CCE quickstart + id: cce + uses: stackgenhq/cce-action/quickstart@v1 + with: + path: ${{ inputs.path }} + lens: ${{ inputs.lens }} + lens-sha256: ${{ inputs.lens-sha256 }} + policy: ${{ inputs.policy }} + write-workflow: ${{ inputs.write-workflow }} + output-dir: ${{ inputs.output-dir }} + upload-artifact: ${{ inputs.upload-artifact }} + artifact-name: ${{ inputs.artifact-name }} + image: ${{ inputs.image }} diff --git a/.github/workflows/scan.yml b/.github/workflows/scan.yml index 17f1c18..71d59da 100644 --- a/.github/workflows/scan.yml +++ b/.github/workflows/scan.yml @@ -21,6 +21,18 @@ on: description: Opt in to StackGen field diagnostics (off by default) type: boolean default: false + lens: + description: Workspace-relative lens YAML or HTTPS URL + type: string + default: "" + lens-sha256: + description: Expected lens file SHA-256 (required for HTTPS) + type: string + default: "" + lens-required: + description: Fail when the lens adds no unique operations + type: boolean + default: false export-policies: description: Export aws-iam, gcp-iam, azure-rbac, and esbom type: boolean @@ -37,14 +49,18 @@ on: description: Wall-clock seconds allowed for the cce scan itself (0 = no limit) type: string default: "0" + output-dir: + description: Directory where scan artifacts are written + type: string + default: cce-results artifact-name: description: Name of the uploaded artifact type: string default: cce-results image: - description: CCE container image (job runs in this image; cce is preinstalled) + description: CCE container image (defaults to the action-tested CLI release) type: string - default: ghcr.io/stackgenhq/cce:latest + default: ghcr.io/stackgenhq/cce:0.0.38 outputs: version: description: Installed cce version @@ -55,6 +71,12 @@ on: entitlement-count: description: Total entitlements found value: ${{ jobs.scan.outputs.entitlement-count }} + lens-file-sha256: + description: Verified local lens digest or configured remote pin + value: ${{ jobs.scan.outputs.lens-file-sha256 }} + lens-new-operation-count: + description: Unique operations added by the lens when requested + value: ${{ jobs.scan.outputs.lens-new-operation-count }} permissions: contents: read @@ -67,6 +89,8 @@ jobs: version: ${{ steps.cce.outputs.version }} report-path: ${{ steps.cce.outputs.report-path }} entitlement-count: ${{ steps.cce.outputs.entitlement-count }} + lens-file-sha256: ${{ steps.cce.outputs.lens-file-sha256 }} + lens-new-operation-count: ${{ steps.cce.outputs.lens-new-operation-count }} steps: - name: Checkout uses: actions/checkout@v4 @@ -82,6 +106,10 @@ jobs: language: ${{ inputs.language }} filter: ${{ inputs.filter }} diagnostics: ${{ inputs.diagnostics }} + lens: ${{ inputs.lens }} + lens-sha256: ${{ inputs.lens-sha256 }} + lens-required: ${{ inputs.lens-required }} + output-dir: ${{ inputs.output-dir }} export-policies: ${{ inputs.export-policies }} fail-on-empty: ${{ inputs.fail-on-empty }} log-level: ${{ inputs.log-level }} @@ -93,5 +121,5 @@ jobs: uses: actions/upload-artifact@v4 with: name: ${{ inputs.artifact-name }} - path: cce-results/* + path: ${{ inputs.output-dir }}/* if-no-files-found: warn diff --git a/.github/workflows/self-test.yml b/.github/workflows/self-test.yml index 96260d5..55d509b 100644 --- a/.github/workflows/self-test.yml +++ b/.github/workflows/self-test.yml @@ -108,3 +108,158 @@ jobs: export-policies: true fail-on-empty: true artifact-name: reusable-self-test-cce-results + + plg-adoption: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Scan with a pinned local lens and measure its value + id: lens-scan + uses: ./ + with: + path: testdata/fixture + language: PYTHON + filter: all + lens: testdata/fixture/lens.yaml + lens-required: true + export-policies: false + fail-on-empty: true + log-level: error + + - name: Assert lens adoption outputs + env: + REPORT: ${{ steps.lens-scan.outputs.report-path }} + LENS_SHA256: ${{ steps.lens-scan.outputs.lens-file-sha256 }} + NEW_OPERATIONS: ${{ steps.lens-scan.outputs.lens-new-operation-count }} + run: | + set -euo pipefail + test -f "$REPORT" + test "$NEW_OPERATIONS" = "1" + test "${#LENS_SHA256}" = "64" + test "$(sha256sum testdata/fixture/lens.yaml | awk '{print $1}')" = "$LENS_SHA256" + jq -e '.entitlements[] | select(.provider == "TECH_DEBT" and .resource == "requests" and .operation == "get")' "$REPORT" + + - name: Reject a tampered local lens + id: bad-pin + uses: ./ + continue-on-error: true + with: + path: testdata/fixture + language: PYTHON + filter: all + lens: testdata/fixture/lens.yaml + lens-sha256: "0000000000000000000000000000000000000000000000000000000000000000" + export-policies: false + + - name: Assert bad lens pin failed closed + run: test "${{ steps.bad-pin.outcome }}" = "failure" + + - name: Reject an unpinned remote lens + id: remote-pin + uses: ./ + continue-on-error: true + with: + path: testdata/fixture + language: PYTHON + lens: https://example.com/never-fetch-without-a-pin.yaml + export-policies: false + + - name: Assert remote lens requires a pin + run: test "${{ steps.remote-pin.outcome }}" = "failure" + + - name: Generate access request + id: access + uses: ./access-request + with: + path: testdata/fixture + service: action-fixture + lens: testdata/fixture/lens.yaml + artifact-name: self-test-access-request + + - name: Assert access request contract + env: + REPORT: ${{ steps.access.outputs.access-request-path }} + COMMIT: ${{ steps.access.outputs.commit }} + run: | + set -euo pipefail + test "${{ steps.access.outputs.operation-count }}" = "3" + test "$COMMIT" = "${{ github.sha }}" + jq -e '.schema == "cce-access-request/v1" and .service == "action-fixture"' "$REPORT" + jq -e '.operations[] | select(.provider == "TECH_DEBT" and .operation == "get")' "$REPORT" + jq -e '[.operations[] | select((.operation // "") == "")] | length == 0' "$REPORT" + + - name: Generate quickstart artifacts + id: quickstart + uses: ./quickstart + with: + path: testdata/fixture + lens: testdata/fixture/lens.yaml + artifact-name: self-test-quickstart + + - name: Assert quickstart artifact set + env: + BOM: ${{ steps.quickstart.outputs.bom-path }} + HTML: ${{ steps.quickstart.outputs.html-path }} + SARIF: ${{ steps.quickstart.outputs.sarif-path }} + LENS_LOCK: ${{ steps.quickstart.outputs.lens-lock-path }} + WORKFLOW: ${{ steps.quickstart.outputs.workflow-path }} + run: | + set -euo pipefail + for artifact in "$BOM" "$HTML" "$SARIF" "$LENS_LOCK" "$WORKFLOW"; do + test -s "$artifact" + done + test "${{ steps.quickstart.outputs.entitlement-count }}" = "6" + + - name: Verify a good lens candidate + id: verify + uses: ./lens-verify + with: + fixture: testdata/lens-fixture + current: testdata/lens-fixture/current.yaml + candidate: testdata/lens-fixture/candidate.yaml + language: PYTHON + artifact-name: self-test-lens-ok + + - name: Assert good candidate outputs + run: | + set -euo pipefail + test "${{ steps.verify.outputs.verdict }}" = "ok" + test "${{ steps.verify.outputs.newly-mapped-count }}" = "2" + test "${{ steps.verify.outputs.regressed-count }}" = "0" + test -s "${{ steps.verify.outputs.verdict-path }}" + + - name: Detect an intentional lens regression + id: regression + uses: ./lens-verify + continue-on-error: true + with: + fixture: testdata/lens-fixture + current: testdata/lens-fixture/current.yaml + candidate: testdata/lens-fixture/regression.yaml + language: PYTHON + artifact-name: self-test-lens-regression + + - name: Assert regression evidence survives the failed gate + run: | + set -euo pipefail + test "${{ steps.regression.outcome }}" = "failure" + test "${{ steps.regression.outputs.verdict }}" = "regression" + test "${{ steps.regression.outputs.regressed-count }}" = "1" + test -s "${{ steps.regression.outputs.verdict-path }}" + + pr-review: + permissions: + contents: read + packages: read + pull-requests: write + security-events: write + uses: ./.github/workflows/pr-review.yml + with: + path: testdata/fixture + language: PYTHON + filter: cloud + base-ref: main + comment: false + upload-sarif: false diff --git a/README.md b/README.md index 8cdb2df..765b335 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,10 @@ GitHub Action and reusable workflow that runs [StackGen CCE](https://appcd-dev.g Both the composite action and the reusable workflow install `cce` by pulling [`ghcr.io/stackgenhq/cce`](https://github.com/stackgenhq/homebrew-stackgen/pkgs/container/cce) and copying `/usr/local/bin/cce` onto `PATH`. That replaces the previous -Homebrew formula download and works on linux amd64 and arm64 runners. +Homebrew formula download and works on linux amd64 and arm64 runners. Each +action release defaults to the CCE image version its self-tests exercised +(currently `0.0.38`), rather than the moving `latest` tag; `image` remains an +explicit override. By default it attempts to export AWS IAM, GCP IAM, Azure RBAC, and cloud-neutral E-SBOM artifacts. GCP IAM and Azure RBAC exports use the CLI's @@ -50,6 +53,105 @@ onto `PATH`: See [`examples/scan.yml`](examples/scan.yml). +## Use a custom lens + +A lens teaches CCE your organization's SDK wrappers or inventory categories. +Use a workspace-relative path; the action hashes the local file and passes the +pin to CCE automatically. Custom providers such as `TECH_DEBT` need +`filter: all`. + +```yaml +- uses: actions/checkout@v4 +- uses: stackgenhq/cce-action@v1 + id: cce + with: + language: AUTO + lens: .cce/tech-debt.yaml + filter: all + # Optional: scan a built-in baseline and fail unless this lens adds a + # unique provider/resource/operation mapping. + lens-required: true +``` + +The step outputs `lens-file-sha256` and, when requested, +`lens-new-operation-count`. For a mutable HTTPS lens, supply the expected hash +so changed content fails before any rules load: + +```yaml +- uses: stackgenhq/cce-action@v1 + with: + lens: https://example.com/approved-lens.yaml + lens-sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef + filter: all +``` + +## Cloud API review on every PR + +The reusable PR workflow handles base/head worktrees, Markdown and JSON diffs, +a paginated sticky comment, SARIF, artifacts, and optional policy gates: + +```yaml +jobs: + cloud-api-review: + uses: stackgenhq/cce-action/.github/workflows/pr-review.yml@v1 + with: + language: AUTO + lens: .cce/cloud.yaml # optional + filter: all # use all for custom lens providers + fail-new: false +``` + +Set `comment: false` for a read-only workflow. Comment and SARIF publication +are skipped for fork PRs, where the token normally cannot write. The workflow +outputs added/removed counts and report paths. + +## Access requests, quickstart, and lens Gate 0 + +Generate a versioned IAM-review artifact without hand-writing CLI or upload +steps: + +```yaml +- uses: stackgenhq/cce-action/access-request@v1 + with: + service: payments-api + lens: .cce/cloud.yaml +``` + +Outputs include `access-request-path`, `operation-count`, `commit`, and +`lens-file-sha256`. The reusable `access-request.yml` wraps checkout and upload. +Cross-repository notification remains a separate, explicit IAM-repository +integration; this action does not require a cross-repo token. + +For a shareable first-run bundle (Cloud API BOM, HTML, SARIF, lens lockfile, +and a suggested CI workflow): + +```yaml +- uses: stackgenhq/cce-action/quickstart@v1 + with: + path: . +``` + +Lens repositories can run deterministic Gate 0 on every lens PR: + +```yaml +jobs: + lens-gate: + uses: stackgenhq/cce-action/.github/workflows/lens-verify.yml@v1 + with: + fixture: testdata/lens-fixture + current: current.yaml + candidate: candidate.yaml +``` + +The gate uploads verdict evidence even on failure and reports newly mapped and +regressed rows in the job summary. Regressions fail by default. Local current +and candidate lenses are hashed automatically; HTTPS lenses require their +respective SHA-256 inputs. These workflows and subactions require CCE `0.0.38` +or newer and fail with an upgrade message when an older preinstalled binary +lacks the command. + +See [`examples/`](examples/) for complete workflow snippets. + ## Diagnostics (off by default) CCE field diagnostics are **disabled** unless you set `diagnostics: true`. @@ -72,11 +174,14 @@ can slow CI log ingestion. | `format` | `json` | Primary report format | | `output-dir` | `cce-results` | Where reports are written | | `diagnostics` | `false` | Opt in to StackGen field diagnostics | +| `lens` | empty | Workspace-relative lens YAML or HTTPS URL | +| `lens-sha256` | empty | Expected lens bytes hash; required for HTTPS, automatic for local files | +| `lens-required` | `false` | Fail if the lens adds no unique operations (JSON; scans a baseline) | | `export-policies` | `true` | Export aws-iam / gcp-iam / azure-rbac / esbom | | `fail-on-empty` | `false` | Fail when entitlements == 0 | | `log-level` | `info` | `debug`, `info`, `warn`, `error` | | `scan-timeout` | `0` | Wall-clock seconds allowed for the cce scan itself (0 = no limit) | -| `image` | `ghcr.io/stackgenhq/cce:latest` | Container image used to provide `cce` | +| `image` | `ghcr.io/stackgenhq/cce:0.0.38` | Action-tested CCE image; override to select another CLI | ## Outputs @@ -90,6 +195,8 @@ can slow CI log ingestion. | `azure-rbac-path` | Azure role JSON only if all relevant actions are catalog-mapped; otherwise empty | | `esbom-path` | Cloud-neutral E-SBOM JSON, or empty | | `entitlement-count` | Total entitlements in the report | +| `lens-file-sha256` | Verified local digest or configured remote lens pin | +| `lens-new-operation-count` | Unique operations added by the lens when `lens-required` is true | ## Large repositories @@ -108,7 +215,7 @@ or checking the repo size in a prior step. ## Versioning -Use a major tag (`@v1`) or a pinned release (`@v0.2.0`). Pin `image` to a version tag (for example `ghcr.io/stackgenhq/cce:0.0.12`) when you need a fixed CLI. +Use a major tag (`@v1`) or a pinned release (`@v0.2.0`). The action's default image is fixed to its tested CLI release; override `image` (for example `ghcr.io/stackgenhq/cce:0.0.38`) when you deliberately need another CLI. Releases are cut from the **Release** workflow (Actions tab -> Run workflow on `main`). The workflow refuses to release unless Self-test is green for the diff --git a/access-request/action.yml b/access-request/action.yml new file mode 100644 index 0000000..0c937b6 --- /dev/null +++ b/access-request/action.yml @@ -0,0 +1,99 @@ +name: CCE access request +description: Generate a code-evidenced access-request artifact for IAM/platform review. +author: StackGen + +branding: + icon: lock + color: blue + +inputs: + path: + description: Directory to scan (relative to the workspace). Caller should check out the repo first. + required: false + default: "." + lens: + description: Local custom lens YAML or HTTPS URL. Remote lenses require lens-sha256. + required: false + default: "" + lens-sha256: + description: Expected SHA-256 of the lens file bytes. Calculated automatically for local lenses when omitted. + required: false + default: "" + service: + description: Service name (defaults to the scanned folder name). + required: false + default: "" + commit: + description: Source commit (defaults to the checkout's git HEAD when available). + required: false + default: "" + output-dir: + description: Directory for the access-request artifact. + required: false + default: cce-results/access-request + upload-artifact: + description: Upload the access-request artifact with actions/upload-artifact. + required: false + default: "true" + artifact-name: + description: Name of the uploaded artifact. + required: false + default: cce-access-request + image: + description: Container image used to install the cce binary (copied onto PATH). + required: false + default: ghcr.io/stackgenhq/cce:0.0.38 + +outputs: + version: + description: Installed cce version. + value: ${{ steps.install.outputs.version }} + image: + description: Container image used for install, or preinstalled. + value: ${{ steps.install.outputs.image }} + access-request-path: + description: Path to cce-access-request.json. + value: ${{ steps.run.outputs.access-request-path }} + operation-count: + description: Number of unique code-evidenced operations. + value: ${{ steps.run.outputs.operation-count }} + commit: + description: Source commit recorded in the access request. + value: ${{ steps.run.outputs.commit }} + lens-file-sha256: + description: SHA-256 of the custom lens file bytes, or empty for built-in rules only. + value: ${{ steps.run.outputs.lens-file-sha256 }} + +runs: + using: composite + steps: + - name: Install cce + id: install + shell: bash + env: + INPUT_IMAGE: ${{ inputs.image }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/install-cce.sh" + + - name: Generate access request + id: run + shell: bash + env: + INPUT_PATH: ${{ inputs.path }} + INPUT_LENS: ${{ inputs.lens }} + INPUT_LENS_SHA256: ${{ inputs.lens-sha256 }} + INPUT_SERVICE: ${{ inputs.service }} + INPUT_COMMIT: ${{ inputs.commit }} + INPUT_OUTPUT_DIR: ${{ inputs.output-dir }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/run-access-request.sh" + + - name: Upload access request + if: ${{ always() && inputs.upload-artifact == 'true' }} + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.artifact-name }} + path: ${{ inputs.output-dir }} + if-no-files-found: warn diff --git a/action.yml b/action.yml index 9b3c8b3..6dd8d78 100644 --- a/action.yml +++ b/action.yml @@ -31,6 +31,18 @@ inputs: description: "Opt in to StackGen field diagnostics for unmapped method signatures (off by default)" required: false default: "false" + lens: + description: "Custom lens YAML path (workspace-relative) or HTTPS URL; mapped to cce --mapper-file" + required: false + default: "" + lens-sha256: + description: "Expected SHA-256 of lens file bytes. Required for HTTPS lenses; local lenses are hashed automatically when omitted" + required: false + default: "" + lens-required: + description: "Run a built-in baseline and fail when the lens adds no unique provider/resource/operation mappings (JSON only)" + required: false + default: "false" export-policies: description: "Export aws-iam, gcp-iam, azure-rbac, and esbom from the scan report" required: false @@ -48,9 +60,9 @@ inputs: required: false default: "0" image: - description: "Container image used to install the cce binary (copied onto PATH)" + description: "Container image used to install the cce binary (copied onto PATH). Defaults to the CLI version tested by this action release" required: false - default: ghcr.io/stackgenhq/cce:latest + default: ghcr.io/stackgenhq/cce:0.0.38 outputs: version: @@ -77,6 +89,12 @@ outputs: entitlement-count: description: Total entitlements found in the scan report value: ${{ steps.scan.outputs.entitlement-count }} + lens-file-sha256: + description: Verified local lens digest or configured remote lens pin (empty without a lens) + value: ${{ steps.scan.outputs.lens-file-sha256 }} + lens-new-operation-count: + description: Unique operations added by the lens when lens-required is true + value: ${{ steps.scan.outputs.lens-new-operation-count }} runs: using: composite @@ -100,6 +118,9 @@ runs: INPUT_FORMAT: ${{ inputs.format }} INPUT_OUTPUT_DIR: ${{ inputs.output-dir }} INPUT_DIAGNOSTICS: ${{ inputs.diagnostics }} + INPUT_LENS: ${{ inputs.lens }} + INPUT_LENS_SHA256: ${{ inputs.lens-sha256 }} + INPUT_LENS_REQUIRED: ${{ inputs.lens-required }} INPUT_EXPORT_POLICIES: ${{ inputs.export-policies }} INPUT_FAIL_ON_EMPTY: ${{ inputs.fail-on-empty }} INPUT_LOG_LEVEL: ${{ inputs.log-level }} diff --git a/examples/access-request.yml b/examples/access-request.yml new file mode 100644 index 0000000..c73a438 --- /dev/null +++ b/examples/access-request.yml @@ -0,0 +1,18 @@ +# .github/workflows/cce-access-request.yml +name: CCE access request +on: + pull_request: + workflow_dispatch: + +permissions: + contents: read + packages: read + +jobs: + request: + uses: stackgenhq/cce-action/.github/workflows/access-request.yml@v1 + with: + path: . + service: my-service + # lens: .cce/cloud.yaml + # lens-sha256: only needed for an HTTPS lens; local files are auto-hashed diff --git a/examples/lens-verify.yml b/examples/lens-verify.yml new file mode 100644 index 0000000..f9affde --- /dev/null +++ b/examples/lens-verify.yml @@ -0,0 +1,17 @@ +# .github/workflows/cce-lens-gate.yml in a lens repository +name: CCE lens Gate 0 +on: [pull_request] + +permissions: + contents: read + packages: read + +jobs: + verify: + uses: stackgenhq/cce-action/.github/workflows/lens-verify.yml@v1 + with: + fixture: testdata/lens-fixture + current: current.yaml + candidate: candidate.yaml + language: AUTO + fail-regression: true diff --git a/examples/pr-review.yml b/examples/pr-review.yml new file mode 100644 index 0000000..abf0fd8 --- /dev/null +++ b/examples/pr-review.yml @@ -0,0 +1,19 @@ +# .github/workflows/cce-pr-review.yml +name: CCE Cloud API review +on: [pull_request] + +permissions: + contents: read + packages: read + pull-requests: write + security-events: write + +jobs: + review: + uses: stackgenhq/cce-action/.github/workflows/pr-review.yml@v1 + with: + language: AUTO + # Optional lens. Use filter=all for custom providers such as TECH_DEBT. + # lens: .cce/cloud.yaml + filter: cloud + fail-new: false diff --git a/examples/quickstart.yml b/examples/quickstart.yml new file mode 100644 index 0000000..e9eba24 --- /dev/null +++ b/examples/quickstart.yml @@ -0,0 +1,15 @@ +# .github/workflows/cce-quickstart.yml +name: CCE quickstart +on: workflow_dispatch + +permissions: + contents: read + packages: read + +jobs: + quickstart: + uses: stackgenhq/cce-action/.github/workflows/quickstart.yml@v1 + with: + path: . + # lens: .cce/cloud.yaml + write-workflow: true diff --git a/examples/scan.yml b/examples/scan.yml index ef1a70e..4163c52 100644 --- a/examples/scan.yml +++ b/examples/scan.yml @@ -17,6 +17,9 @@ jobs: with: language: AUTO filter: cloud + # Optional: lens: .cce/cloud.yaml + # Use filter: all for custom providers such as TECH_DEBT. + # Local lens hashes are automatic; HTTPS lenses require lens-sha256. # Leave diagnostics false unless you intentionally opt in to sending # unmapped method signatures to StackGen field ingest. diagnostics: false diff --git a/lens-verify/action.yml b/lens-verify/action.yml new file mode 100644 index 0000000..b781e06 --- /dev/null +++ b/lens-verify/action.yml @@ -0,0 +1,104 @@ +name: CCE lens verify +description: Run CCE lens Gate 0 against a deterministic fixture corpus and emit newly mapped and regressed evidence. +author: StackGen + +branding: + icon: check-circle + color: blue + +inputs: + fixture: + description: Fixture corpus directory, relative to the workspace unless absolute + required: true + candidate: + description: Candidate lens YAML (local path or pinned HTTPS URL) + required: true + current: + description: Baseline lens YAML (local path or pinned HTTPS URL); empty uses the built-in catalog + required: false + default: "" + candidate-sha256: + description: Candidate lens SHA-256 pin; calculated automatically for a local lens when omitted + required: false + default: "" + current-sha256: + description: Current lens SHA-256 pin; calculated automatically for a local lens when omitted + required: false + default: "" + language: + description: "Language scope: AUTO, GO, PYTHON, JAVA, or JAVASCRIPT" + required: false + default: AUTO + fail-regression: + description: Fail the step when verification finds regressed rows + required: false + default: "true" + output-dir: + description: Directory for the lens verdict JSON + required: false + default: cce-results/lens-verify + image: + description: Container image used to install cce (Gate 0 requires CCE 0.0.38 or newer) + required: false + default: ghcr.io/stackgenhq/cce:0.0.38 + upload-artifact: + description: Upload the verdict JSON even when verification fails + required: false + default: "true" + artifact-name: + description: Name of the uploaded verdict artifact + required: false + default: cce-lens-verify + +outputs: + verdict-path: + description: Path to the verdict JSON evidence + value: ${{ steps.verify.outputs.verdict-path }} + verdict: + description: Lens verification verdict (ok or regression) + value: ${{ steps.verify.outputs.verdict }} + newly-mapped-count: + description: Number of newly mapped fixture rows + value: ${{ steps.verify.outputs.newly-mapped-count }} + regressed-count: + description: Number of regressed fixture rows + value: ${{ steps.verify.outputs.regressed-count }} + candidate-sha256: + description: SHA-256 pin supplied to CCE for the candidate lens + value: ${{ steps.verify.outputs.candidate-sha256 }} + +runs: + using: composite + steps: + - name: Install cce + id: install + shell: bash + env: + INPUT_IMAGE: ${{ inputs.image }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/install-cce.sh" + + - name: Verify lens + id: verify + shell: bash + env: + INPUT_FIXTURE: ${{ inputs.fixture }} + INPUT_CANDIDATE: ${{ inputs.candidate }} + INPUT_CURRENT: ${{ inputs.current }} + INPUT_CANDIDATE_SHA256: ${{ inputs.candidate-sha256 }} + INPUT_CURRENT_SHA256: ${{ inputs.current-sha256 }} + INPUT_LANGUAGE: ${{ inputs.language }} + INPUT_FAIL_REGRESSION: ${{ inputs.fail-regression }} + INPUT_OUTPUT_DIR: ${{ inputs.output-dir }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/run-lens-verify.sh" + + - name: Upload lens verdict + if: ${{ always() && inputs.upload-artifact == 'true' }} + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.artifact-name }} + path: ${{ inputs.output-dir }}/verdict.json + if-no-files-found: warn diff --git a/quickstart/action.yml b/quickstart/action.yml new file mode 100644 index 0000000..a3c5f2e --- /dev/null +++ b/quickstart/action.yml @@ -0,0 +1,105 @@ +name: CCE quickstart +description: Generate a Cloud API BOM, HTML report, SARIF, lens lockfile, and optional CI workflow. +author: StackGen + +branding: + icon: zap + color: blue + +inputs: + path: + description: Directory to scan (relative to the workspace). Caller should check out the repo first. + required: false + default: "." + lens: + description: Local custom lens YAML or HTTPS URL. Remote lenses require lens-sha256. + required: false + default: "" + lens-sha256: + description: Expected SHA-256 of the lens file bytes. Calculated automatically for local lenses when omitted. + required: false + default: "" + policy: + description: Optional local IAM policy JSON for potential-drift review (otherwise CCE auto-detects one). + required: false + default: "" + write-workflow: + description: Generate .github/workflows/cce.yml if absent. Existing workflows are never overwritten. + required: false + default: "true" + output-dir: + description: Directory for the complete quickstart artifact set. + required: false + default: cce-results/quickstart + upload-artifact: + description: Upload the complete quickstart artifact set with actions/upload-artifact. + required: false + default: "true" + artifact-name: + description: Name of the uploaded artifact. + required: false + default: cce-quickstart + image: + description: Container image used to install the cce binary (copied onto PATH). + required: false + default: ghcr.io/stackgenhq/cce:0.0.38 + +outputs: + version: + description: Installed cce version. + value: ${{ steps.install.outputs.version }} + image: + description: Container image used for install, or preinstalled. + value: ${{ steps.install.outputs.image }} + bom-path: + description: Path to the Cloud API BOM JSON. + value: ${{ steps.run.outputs.bom-path }} + html-path: + description: Path to the self-contained HTML report. + value: ${{ steps.run.outputs.html-path }} + sarif-path: + description: Path to the SARIF report. + value: ${{ steps.run.outputs.sarif-path }} + lens-lock-path: + description: Path to the lens provenance lockfile. + value: ${{ steps.run.outputs.lens-lock-path }} + workflow-path: + description: Path to the workflow copy in the artifact set, or empty when no source workflow exists. + value: ${{ steps.run.outputs.workflow-path }} + entitlement-count: + description: Total entitlements found in the Cloud API BOM. + value: ${{ steps.run.outputs.entitlement-count }} + +runs: + using: composite + steps: + - name: Install cce + id: install + shell: bash + env: + INPUT_IMAGE: ${{ inputs.image }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/install-cce.sh" + + - name: Run quickstart + id: run + shell: bash + env: + INPUT_PATH: ${{ inputs.path }} + INPUT_LENS: ${{ inputs.lens }} + INPUT_LENS_SHA256: ${{ inputs.lens-sha256 }} + INPUT_POLICY: ${{ inputs.policy }} + INPUT_WRITE_WORKFLOW: ${{ inputs.write-workflow }} + INPUT_OUTPUT_DIR: ${{ inputs.output-dir }} + run: | + set -euo pipefail + "${{ github.action_path }}/../scripts/run-quickstart.sh" + + - name: Upload quickstart results + if: ${{ always() && inputs.upload-artifact == 'true' }} + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.artifact-name }} + path: ${{ inputs.output-dir }} + if-no-files-found: warn diff --git a/scripts/install-cce.sh b/scripts/install-cce.sh index 06c2aa8..2901313 100755 --- a/scripts/install-cce.sh +++ b/scripts/install-cce.sh @@ -4,7 +4,7 @@ # job itself runs inside the CCE container. set -euo pipefail -image="${INPUT_IMAGE:-ghcr.io/stackgenhq/cce:latest}" +image="${INPUT_IMAGE:-ghcr.io/stackgenhq/cce:0.0.38}" if command -v cce >/dev/null 2>&1; then version="$(cce --version 2>/dev/null | head -1 || true)" diff --git a/scripts/run-access-request.sh b/scripts/run-access-request.sh new file mode 100755 index 0000000..b1a3a26 --- /dev/null +++ b/scripts/run-access-request.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# Generate a code-evidenced access request for review by an IAM/platform team. +set -euo pipefail + +path="${INPUT_PATH:-.}" +lens="${INPUT_LENS:-}" +lens_sha256="${INPUT_LENS_SHA256:-}" +service="${INPUT_SERVICE:-}" +commit="${INPUT_COMMIT:-}" +output_dir="${INPUT_OUTPUT_DIR:-cce-results/access-request}" +report_path="${output_dir}/cce-access-request.json" + +if ! command -v cce >/dev/null 2>&1; then + echo "::error::cce is not on PATH; install-cce.sh must run first" + exit 1 +fi + +command_help="" +if ! command_help="$(cce access-request --help 2>&1)" || ! grep -q -- '--mapper-sha256' <<<"$command_help"; then + echo "::error::cce access-request with lens pinning is unavailable. This action requires CCE >= 0.0.38; set image to ghcr.io/stackgenhq/cce:0.0.38 or newer." + if [[ -n "$command_help" ]]; then + printf '%s\n' "$command_help" + fi + exit 1 +fi + +if [[ "$path" != /* ]]; then + path="${GITHUB_WORKSPACE:-$PWD}/$path" +fi +if [[ ! -d "$path" ]]; then + echo "::error::access-request path does not exist: $path" + exit 1 +fi + +mapper_file="" +lens_file_sha256="" +args=(access-request "$path" --output "$report_path") +if [[ -n "$service" ]]; then + args+=(--service "$service") +fi +if [[ -n "$commit" ]]; then + args+=(--commit "$commit") +fi + +if [[ -n "$lens" ]]; then + if [[ "$lens" =~ ^[Hh][Tt][Tt][Pp][Ss]:// ]]; then + # Remote content is mutable: an explicit digest is required to fail closed. + if [[ "$lens_sha256" =~ ^[[:space:]]*$ ]]; then + echo "::error::lens-sha256 is required when lens is an HTTPS URL" + exit 1 + fi + mapper_file="$lens" + lens_file_sha256="$lens_sha256" + elif [[ "$lens" =~ ^[A-Za-z][A-Za-z0-9+.-]*:// ]]; then + echo "::error::lens URL must use HTTPS; non-HTTPS URLs are not supported: $lens" + exit 1 + else + mapper_file="$lens" + if [[ "$mapper_file" != /* ]]; then + mapper_file="${GITHUB_WORKSPACE:-$PWD}/$mapper_file" + fi + if [[ ! -f "$mapper_file" ]]; then + echo "::error::local lens file does not exist: $mapper_file" + exit 1 + fi + if [[ -z "$lens_sha256" ]]; then + if command -v sha256sum >/dev/null 2>&1; then + lens_sha256="$(sha256sum "$mapper_file")" + lens_sha256="${lens_sha256%% *}" + elif command -v shasum >/dev/null 2>&1; then + lens_sha256="$(shasum -a 256 "$mapper_file")" + lens_sha256="${lens_sha256%% *}" + else + echo "::error::sha256sum or shasum is required to calculate the local lens SHA-256; otherwise set lens-sha256 explicitly" + exit 1 + fi + fi + lens_file_sha256="$lens_sha256" + fi + # Always pin custom lenses, including local files whose digest was computed above. + args+=(--mapper-file "$mapper_file" --mapper-sha256 "$lens_file_sha256") +fi + +mkdir -p "$output_dir" +echo "Generating access request for $path" +cce "${args[@]}" + +if [[ ! -f "$report_path" ]]; then + echo "::error::cce access-request produced no report at $report_path" + exit 1 +fi + +operation_count=0 +document_commit="" +document_lens_sha256="" +if command -v jq >/dev/null 2>&1; then + operation_count="$(jq -r '.operations | length' "$report_path")" + document_commit="$(jq -r '.commit // ""' "$report_path")" + document_lens_sha256="$(jq -r '.provenance.lens_file_sha256 // ""' "$report_path")" +elif command -v python3 >/dev/null 2>&1; then + metadata="$(python3 - "$report_path" <<'PY' +import json +import sys + +with open(sys.argv[1], encoding="utf-8") as stream: + document = json.load(stream) +print(len(document.get("operations", []))) +print(document.get("commit", "")) +print(document.get("provenance", {}).get("lens_file_sha256", "")) +PY +)" + operation_count="$(sed -n '1p' <<<"$metadata")" + document_commit="$(sed -n '2p' <<<"$metadata")" + document_lens_sha256="$(sed -n '3p' <<<"$metadata")" +else + # GitHub-hosted runners include jq. Keep a narrow fallback for the formatted + # access-request schema on minimal runners rather than requiring an install. + operation_count="$(grep -c '"operation"[[:space:]]*:' "$report_path" || true)" + document_commit="$(sed -n 's/^[[:space:]]*"commit"[[:space:]]*:[[:space:]]*"\([^"]*\)".*$/\1/p' "$report_path" | head -1)" + document_lens_sha256="$(sed -n 's/^[[:space:]]*"lens_file_sha256"[[:space:]]*:[[:space:]]*"\([^"]*\)".*$/\1/p' "$report_path" | head -1)" +fi + +if [[ ! "$operation_count" =~ ^[0-9]+$ ]]; then + echo "::error::could not read operation count from $report_path" + exit 1 +fi +# Prefer the document's verified provenance, with the effective pin as a +# fallback for compatible producers that omit the optional provenance field. +if [[ -n "$document_lens_sha256" ]]; then + lens_file_sha256="$document_lens_sha256" +fi + +if [[ -n "${GITHUB_OUTPUT:-}" ]]; then + { + echo "access-request-path=$report_path" + echo "operation-count=$operation_count" + echo "commit=$document_commit" + echo "lens-file-sha256=$lens_file_sha256" + } >> "$GITHUB_OUTPUT" +fi + +if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then + { + echo "## CCE access request" + echo + echo "- Operations: **$operation_count**" + echo "- Commit: \`${document_commit:-not detected}\`" + echo "- Lens file SHA-256: \`${lens_file_sha256:-built-in rules only}\`" + echo "- Artifact: \`$report_path\`" + echo + echo "Static code evidence only; review operations against policy before granting access." + } >> "$GITHUB_STEP_SUMMARY" +fi + +echo "CCE access request complete: operations=$operation_count report=$report_path" diff --git a/scripts/run-lens-verify.sh b/scripts/run-lens-verify.sh new file mode 100755 index 0000000..a7a1bcd --- /dev/null +++ b/scripts/run-lens-verify.sh @@ -0,0 +1,187 @@ +#!/usr/bin/env bash +# Run lens Gate 0 and preserve machine-readable evidence even when CCE exits +# non-zero for a regression. +set -euo pipefail + +fixture="${INPUT_FIXTURE:-}" +candidate="${INPUT_CANDIDATE:-}" +current="${INPUT_CURRENT:-}" +candidate_sha256="${INPUT_CANDIDATE_SHA256:-}" +current_sha256="${INPUT_CURRENT_SHA256:-}" +language="${INPUT_LANGUAGE:-AUTO}" +fail_regression="${INPUT_FAIL_REGRESSION:-true}" +output_dir="${INPUT_OUTPUT_DIR:-cce-results/lens-verify}" +workspace="${GITHUB_WORKSPACE:-$PWD}" + +if ! command -v cce >/dev/null 2>&1; then + echo "::error::cce is not on PATH; install-cce.sh must run first" + exit 1 +fi +if ! command -v jq >/dev/null 2>&1; then + echo "::error::jq is required to parse the lens verdict and write job outputs" + exit 1 +fi +if ! cce lens verify --help >/dev/null 2>&1; then + echo "::error::cce lens verify is unavailable. Lens Gate 0 requires CCE >= 0.0.38; use ghcr.io/stackgenhq/cce:0.0.38 or newer." + exit 1 +fi +if [[ -z "$fixture" ]]; then + echo "::error::fixture is required" + exit 1 +fi +if [[ -z "$candidate" ]]; then + echo "::error::candidate is required" + exit 1 +fi + +resolve_local_path() { + local value="$1" + if [[ "$value" = /* ]]; then + printf '%s\n' "$value" + else + printf '%s/%s\n' "${workspace%/}" "$value" + fi +} + +sha256_file() { + local path="$1" + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$path" | awk '{print $1}' + elif command -v shasum >/dev/null 2>&1; then + shasum -a 256 "$path" | awk '{print $1}' + else + echo "::error::sha256sum or shasum is required to pin local lens $path" + return 1 + fi +} + +# Resolve local lenses against the checkout, not the composite action directory. +# Remote lenses are intentionally HTTPS-only and must always be content-pinned. +prepare_lens() { + local label="$1" + local value="$2" + local pin="$3" + local resolved + + if [[ "$value" =~ ^[hH][tT][tT][pP][sS]:// ]]; then + if [[ -z "$pin" ]]; then + echo "::error::${label}-sha256 is required for HTTPS remote lens: $value" + return 1 + fi + resolved="$value" + elif [[ "$value" =~ ^[A-Za-z][A-Za-z0-9+.-]*: ]]; then + echo "::error::unsupported remote scheme for $label lens: $value (use a local path or pinned HTTPS URL)" + return 1 + else + resolved="$(resolve_local_path "$value")" + if [[ ! -f "$resolved" ]]; then + echo "::error::$label lens does not exist: $resolved" + return 1 + fi + if [[ -z "$pin" ]]; then + pin="$(sha256_file "$resolved")" + fi + fi + + RESOLVED_LENS="$resolved" + RESOLVED_SHA256="$pin" +} + +fixture="$(resolve_local_path "$fixture")" +if [[ ! -d "$fixture" ]]; then + echo "::error::fixture directory does not exist: $fixture" + exit 1 +fi + +prepare_lens candidate "$candidate" "$candidate_sha256" +candidate="$RESOLVED_LENS" +candidate_sha256="$RESOLVED_SHA256" +if [[ -n "$current" ]]; then + prepare_lens current "$current" "$current_sha256" + current="$RESOLVED_LENS" + current_sha256="$RESOLVED_SHA256" +fi + +mkdir -p "$output_dir" +verdict_path="${output_dir%/}/verdict.json" +rm -f "$verdict_path" + +args=( + lens verify + --fixture "$fixture" + --candidate "$candidate" + --candidate-sha256 "$candidate_sha256" + --language "$language" + --fail-regression="$fail_regression" + --output "$verdict_path" +) +if [[ -n "$current" ]]; then + args+=(--current "$current" --current-sha256 "$current_sha256") +fi + +verify_status=0 +if cce "${args[@]}"; then + verify_status=0 +else + verify_status=$? +fi + +# A regression is a normal Gate 0 result, not a reason to discard its evidence. +# Parse and publish first; restore CCE's status only after outputs are durable. +if [[ ! -f "$verdict_path" ]]; then + echo "::error::cce lens verify produced no verdict JSON at $verdict_path (exit $verify_status)" + [[ "$verify_status" -ne 0 ]] && exit "$verify_status" + exit 1 +fi +if ! jq -e . "$verdict_path" >/dev/null 2>&1; then + echo "::error::cce lens verify produced invalid verdict JSON at $verdict_path" + [[ "$verify_status" -ne 0 ]] && exit "$verify_status" + exit 1 +fi + +verdict="$(jq -r '.verdict // "unknown"' "$verdict_path")" +newly_mapped_count="$(jq -r '(.newly_mapped // []) | length' "$verdict_path")" +regressed_count="$(jq -r '(.regressed // []) | length' "$verdict_path")" + +if [[ -n "${GITHUB_OUTPUT:-}" ]]; then + { + echo "verdict-path=$verdict_path" + echo "verdict=$verdict" + echo "newly-mapped-count=$newly_mapped_count" + echo "regressed-count=$regressed_count" + echo "candidate-sha256=$candidate_sha256" + } >> "$GITHUB_OUTPUT" +fi + +if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then + { + echo "## CCE lens Gate 0" + echo + echo "- Verdict: **$verdict**" + echo "- Newly mapped: **$newly_mapped_count**" + echo "- Regressed: **$regressed_count**" + echo "- Evidence: \`$verdict_path\`" + if [[ "$newly_mapped_count" -gt 0 ]]; then + echo + echo "### Newly mapped (first 20)" + echo + echo "| Provider | Resource | Operation | File | Line |" + echo "| --- | --- | --- | --- | ---: |" + jq -r '(.newly_mapped // [])[:20][] | "| \(.provider // "") | \(.resource // "") | \(.operation // "") | \(.file // "") | \(.line // 0) |"' "$verdict_path" + fi + if [[ "$regressed_count" -gt 0 ]]; then + echo + echo "### Regressed (first 20)" + echo + echo "| Provider | Resource | Operation | File | Line |" + echo "| --- | --- | --- | --- | ---: |" + jq -r '(.regressed // [])[:20][] | "| \(.provider // "") | \(.resource // "") | \(.operation // "") | \(.file // "") | \(.line // 0) |"' "$verdict_path" + fi + } >> "$GITHUB_STEP_SUMMARY" +fi + +echo "Lens verify: verdict=$verdict newly-mapped=$newly_mapped_count regressed=$regressed_count evidence=$verdict_path" +if [[ "$verify_status" -ne 0 ]]; then + echo "::error::cce lens verify exited $verify_status; verdict outputs and evidence were preserved" + exit "$verify_status" +fi diff --git a/scripts/run-quickstart.sh b/scripts/run-quickstart.sh new file mode 100755 index 0000000..52123f9 --- /dev/null +++ b/scripts/run-quickstart.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# Produce CCE's first-run artifact set and package the optional CI workflow. +set -euo pipefail + +path="${INPUT_PATH:-.}" +lens="${INPUT_LENS:-}" +lens_sha256="${INPUT_LENS_SHA256:-}" +policy="${INPUT_POLICY:-}" +write_workflow="${INPUT_WRITE_WORKFLOW:-true}" +output_dir="${INPUT_OUTPUT_DIR:-cce-results/quickstart}" + +bom_path="${output_dir}/cce-api-bom.json" +html_path="${output_dir}/cce-report.html" +sarif_path="${output_dir}/cce-results.sarif" +lens_lock_path="${output_dir}/cce-lens-lock.yaml" +workflow_path="" + +if ! command -v cce >/dev/null 2>&1; then + echo "::error::cce is not on PATH; install-cce.sh must run first" + exit 1 +fi + +command_help="" +if ! command_help="$(cce quickstart --help 2>&1)" || ! grep -q -- '--mapper-sha256' <<<"$command_help" || ! grep -q -- '--write-workflow' <<<"$command_help"; then + echo "::error::cce quickstart with lens pinning and workflow generation is unavailable. This action requires CCE >= 0.0.38; set image to ghcr.io/stackgenhq/cce:0.0.38 or newer." + if [[ -n "$command_help" ]]; then + printf '%s\n' "$command_help" + fi + exit 1 +fi + +if [[ "$path" != /* ]]; then + path="${GITHUB_WORKSPACE:-$PWD}/$path" +fi +if [[ ! -d "$path" ]]; then + echo "::error::quickstart path does not exist: $path" + exit 1 +fi +if [[ "$write_workflow" != "true" && "$write_workflow" != "false" ]]; then + echo "::error::write-workflow must be true or false (got $write_workflow)" + exit 1 +fi + +mapper_file="" +args=(quickstart "$path" --output-dir "$output_dir" "--write-workflow=$write_workflow") +if [[ -n "$policy" ]]; then + args+=(--policy "$policy") +fi + +if [[ -n "$lens" ]]; then + if [[ "$lens" =~ ^[Hh][Tt][Tt][Pp][Ss]:// ]]; then + # Remote content is mutable: an explicit digest is required to fail closed. + if [[ "$lens_sha256" =~ ^[[:space:]]*$ ]]; then + echo "::error::lens-sha256 is required when lens is an HTTPS URL" + exit 1 + fi + mapper_file="$lens" + elif [[ "$lens" =~ ^[A-Za-z][A-Za-z0-9+.-]*:// ]]; then + echo "::error::lens URL must use HTTPS; non-HTTPS URLs are not supported: $lens" + exit 1 + else + mapper_file="$lens" + if [[ "$mapper_file" != /* ]]; then + mapper_file="${GITHUB_WORKSPACE:-$PWD}/$mapper_file" + fi + if [[ ! -f "$mapper_file" ]]; then + echo "::error::local lens file does not exist: $mapper_file" + exit 1 + fi + if [[ -z "$lens_sha256" ]]; then + if command -v sha256sum >/dev/null 2>&1; then + lens_sha256="$(sha256sum "$mapper_file")" + lens_sha256="${lens_sha256%% *}" + elif command -v shasum >/dev/null 2>&1; then + lens_sha256="$(shasum -a 256 "$mapper_file")" + lens_sha256="${lens_sha256%% *}" + else + echo "::error::sha256sum or shasum is required to calculate the local lens SHA-256; otherwise set lens-sha256 explicitly" + exit 1 + fi + fi + fi + # Always pin custom lenses, including local files whose digest was computed above. + args+=(--mapper-file "$mapper_file" --mapper-sha256 "$lens_sha256") +fi + +mkdir -p "$output_dir" +echo "Running CCE quickstart for $path" +cce "${args[@]}" + +for artifact in "$bom_path" "$html_path" "$sarif_path" "$lens_lock_path"; do + if [[ ! -f "$artifact" ]]; then + echo "::error::cce quickstart produced no artifact at $artifact" + exit 1 + fi +done + +# CCE itself never overwrites the source workflow. Copy either a newly generated +# workflow or the already-existing source into the artifact bundle when present. +workflow_source="${path}/.github/workflows/cce.yml" +if [[ -f "$workflow_source" ]]; then + workflow_path="${output_dir}/cce-workflow.yml" + cp "$workflow_source" "$workflow_path" +fi + +entitlement_count=0 +if command -v jq >/dev/null 2>&1; then + entitlement_count="$(jq -r '.summary.total_entitlements // 0' "$bom_path")" +elif command -v python3 >/dev/null 2>&1; then + entitlement_count="$(python3 - "$bom_path" <<'PY' +import json +import sys + +with open(sys.argv[1], encoding="utf-8") as stream: + document = json.load(stream) +print(document.get("summary", {}).get("total_entitlements", 0)) +PY +)" +else + entitlement_count="$(grep -Eo '"total_entitlements"[[:space:]]*:[[:space:]]*[0-9]+' "$bom_path" | head -1 | grep -Eo '[0-9]+$' || echo 0)" +fi +if [[ ! "$entitlement_count" =~ ^[0-9]+$ ]]; then + echo "::error::could not read entitlement count from $bom_path" + exit 1 +fi + +if [[ -n "${GITHUB_OUTPUT:-}" ]]; then + { + echo "bom-path=$bom_path" + echo "html-path=$html_path" + echo "sarif-path=$sarif_path" + echo "lens-lock-path=$lens_lock_path" + echo "workflow-path=$workflow_path" + echo "entitlement-count=$entitlement_count" + } >> "$GITHUB_OUTPUT" +fi + +if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then + { + echo "## CCE quickstart" + echo + echo "- Entitlements: **$entitlement_count**" + echo "- API BOM: \`$bom_path\`" + echo "- HTML report: \`$html_path\`" + echo "- SARIF: \`$sarif_path\`" + echo "- Lens lockfile: \`$lens_lock_path\`" + if [[ -n "$workflow_path" ]]; then + echo "- CI workflow: \`$workflow_path\` (source workflow left untouched)" + else + echo "- CI workflow: not generated (write-workflow=$write_workflow)" + fi + } >> "$GITHUB_STEP_SUMMARY" +fi + +echo "CCE quickstart complete: entitlements=$entitlement_count output=$output_dir" diff --git a/scripts/run-scan.sh b/scripts/run-scan.sh index 8b780df..fd705f7 100755 --- a/scripts/run-scan.sh +++ b/scripts/run-scan.sh @@ -12,12 +12,18 @@ export_policies="${INPUT_EXPORT_POLICIES:-true}" fail_on_empty="${INPUT_FAIL_ON_EMPTY:-false}" log_level="${INPUT_LOG_LEVEL:-info}" scan_timeout="${INPUT_SCAN_TIMEOUT:-0}" +lens="${INPUT_LENS:-}" +lens_sha256="${INPUT_LENS_SHA256:-}" +lens_required="${INPUT_LENS_REQUIRED:-false}" if ! command -v cce >/dev/null 2>&1; then echo "::error::cce is not on PATH; install-cce.sh must run first" exit 1 fi +if [[ "$path" != /* ]]; then + path="${GITHUB_WORKSPACE:-$PWD}/$path" +fi if [[ ! -d "$path" ]]; then echo "::error::scan path does not exist: $path" exit 1 @@ -34,7 +40,57 @@ if [[ "$log_level" == "debug" ]]; then echo "::warning::log-level=debug streams one DEBUG line per unmapped SDK call; large or SDK-heavy repos can produce tens of MB of logs and may slow CI log ingestion. Prefer diagnostics=true with log-level=info." fi -echo "Scanning $path (language=$language filter=$filter diagnostics=${CCE_DIAGNOSTICS:-false})" +if [[ "$lens_required" == "true" && -z "$lens" ]]; then + echo "::error::lens-required=true requires a lens" + exit 1 +fi +if [[ "$lens_required" == "true" && "$format" != "json" ]]; then + echo "::error::lens-required=true requires format=json so unique operation growth can be measured" + exit 1 +fi + +# A repository-local lens is already pinned by the checkout. Hash its exact +# bytes as provenance and pass that pin to CCE; a remote lens needs a caller- +# supplied expected hash because there is no repository commit protecting it. +lens_args=() +lens_file_sha256="" +if [[ -n "$lens" ]]; then + if [[ "$lens" =~ ^[Hh][Tt][Tt][Pp][Ss]:// ]]; then + if [[ -z "$lens_sha256" ]]; then + echo "::error::lens-sha256 is required for an HTTPS lens so remote content cannot change unnoticed" + exit 1 + fi + lens_file_sha256="$lens_sha256" + elif [[ "$lens" =~ ^[a-zA-Z][a-zA-Z0-9+.-]*:// ]]; then + echo "::error::lens must be a workspace file or HTTPS URL: $lens" + exit 1 + else + if [[ "$lens" != /* ]]; then + lens="${GITHUB_WORKSPACE:-$PWD}/$lens" + fi + if [[ ! -f "$lens" ]]; then + echo "::error::lens file does not exist: $lens" + exit 1 + fi + actual_sha="$(sha256sum "$lens" | awk '{print $1}')" + if [[ -n "$lens_sha256" && "$lens_sha256" != "$actual_sha" ]]; then + echo "::error::lens-sha256 mismatch for $lens: expected $lens_sha256, got $actual_sha" + exit 1 + fi + lens_sha256="$actual_sha" + lens_file_sha256="$actual_sha" + fi + if ! cce --help 2>&1 | grep -q -- '--mapper-sha256'; then + echo "::error::Pinned lenses require CCE >= 0.0.38; set image to ghcr.io/stackgenhq/cce:0.0.38 or newer." + exit 1 + fi + lens_args=(--mapper-file "$lens" --mapper-sha256 "$lens_sha256") + if [[ "$filter" == "cloud" ]]; then + echo "::notice::A lens with custom providers such as TECH_DEBT requires filter=all; filter=cloud keeps cloud providers only." + fi +fi + +echo "Scanning $path (language=$language filter=$filter diagnostics=${CCE_DIAGNOSTICS:-false} lens=${lens:-built-in})" run_scan() { local args=( @@ -44,6 +100,7 @@ run_scan() { --format "$format" --log-level "$log_level" --output "$report_path" + "${lens_args[@]}" ) if [[ "$scan_timeout" != "0" && "$scan_timeout" != "" ]] && command -v timeout >/dev/null 2>&1; then # Fail fast on huge repos instead of letting the job burn its whole runner @@ -77,6 +134,27 @@ if [[ "$format" == "json" ]]; then fi fi +lens_new_operation_count="" +if [[ "$lens_required" == "true" ]]; then + if ! command -v jq >/dev/null 2>&1; then + echo "::error::lens-required=true requires jq on the runner" + exit 1 + fi + baseline_path="${output_dir}/baseline-without-lens.json" + lens_diff_path="${output_dir}/lens-added.json" + echo "Measuring lens value against the built-in catalog (diagnostics disabled for baseline)" + CCE_DIAGNOSTICS=false cce \ + --folder "$path" --language "$language" --filter "$filter" --format json \ + --log-level "$log_level" --output "$baseline_path" + cce diff "$baseline_path" "$report_path" --mode tuple --format json -o "$lens_diff_path" + lens_new_operation_count="$(jq -r '.added | length' "$lens_diff_path")" + if [[ "$lens_new_operation_count" == "0" ]]; then + echo "::error::lens added no unique provider/resource/operation mappings (lens-required=true). See $lens_diff_path" + exit 1 + fi + echo "Lens added $lens_new_operation_count unique operation(s)" +fi + if [[ "$fail_on_empty" == "true" && "$entitlement_count" == "0" ]]; then echo "::error::scan found zero entitlements and fail-on-empty is true" exit 1 @@ -135,7 +213,25 @@ if [[ -n "${GITHUB_OUTPUT:-}" ]]; then echo "azure-rbac-path=$azure_rbac_path" echo "esbom-path=$esbom_path" echo "entitlement-count=$entitlement_count" + echo "lens-file-sha256=$lens_file_sha256" + echo "lens-new-operation-count=$lens_new_operation_count" } >> "$GITHUB_OUTPUT" fi +if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then + { + echo "### CCE scan" + echo + echo "- Entitlements: **$entitlement_count**" + echo "- Report: \`$report_path\`" + if [[ -n "$lens" ]]; then + echo "- Lens: \`$lens\`" + echo "- Lens SHA-256: \`$lens_file_sha256\`" + fi + if [[ -n "$lens_new_operation_count" ]]; then + echo "- Unique operations added by lens: **$lens_new_operation_count**" + fi + } >> "$GITHUB_STEP_SUMMARY" +fi + echo "CCE scan complete: entitlements=$entitlement_count report=$report_path" diff --git a/testdata/fixture/app.py b/testdata/fixture/app.py index d76d6cc..03e53a2 100644 --- a/testdata/fixture/app.py +++ b/testdata/fixture/app.py @@ -1,6 +1,7 @@ """Minimal AWS SDK fixture so self-test can assert entitlements > 0.""" import boto3 +import requests def list_bucket_names(): @@ -12,3 +13,7 @@ def get_object_bytes(bucket: str, key: str) -> bytes: client = boto3.client("s3") response = client.get_object(Bucket=bucket, Key=key) return response["Body"].read() + + +def fetch_legacy_status(url: str) -> int: + return requests.get(url, timeout=5).status_code diff --git a/testdata/fixture/lens.yaml b/testdata/fixture/lens.yaml new file mode 100644 index 0000000..80fad06 --- /dev/null +++ b/testdata/fixture/lens.yaml @@ -0,0 +1,7 @@ +definition: + language: + python: + - name: Legacy requests inventory + prefix: "requests." + rule: "requests\\.%{WORD:operation}" + provider: TECH_DEBT diff --git a/testdata/lens-fixture/app.py b/testdata/lens-fixture/app.py new file mode 100644 index 0000000..a180814 --- /dev/null +++ b/testdata/lens-fixture/app.py @@ -0,0 +1,6 @@ +import httpx +import requests + +requests.get("https://example.com/health") +requests.post("https://example.com/submit", json={"ok": True}) +httpx.get("https://example.com/modern") diff --git a/testdata/lens-fixture/candidate.yaml b/testdata/lens-fixture/candidate.yaml new file mode 100644 index 0000000..535a7f3 --- /dev/null +++ b/testdata/lens-fixture/candidate.yaml @@ -0,0 +1,16 @@ +definition: + language: + python: + - name: "Modern httpx client" + prefix: "httpx." + rule: "httpx\\.(?[a-zA-Z0-9_]+)" + provider: TARGET + - name: "Legacy requests library" + prefix: "requests." + rule: "requests\\.(?[a-zA-Z0-9_]+)" + provider: TECH_DEBT + providers: + TARGET: + servicenameMapping: {} + TECH_DEBT: + servicenameMapping: {} diff --git a/testdata/lens-fixture/current.yaml b/testdata/lens-fixture/current.yaml new file mode 100644 index 0000000..85d78ec --- /dev/null +++ b/testdata/lens-fixture/current.yaml @@ -0,0 +1,10 @@ +definition: + language: + python: + - name: "Modern httpx client" + prefix: "httpx." + rule: "httpx\\.(?[a-zA-Z0-9_]+)" + provider: TARGET + providers: + TARGET: + servicenameMapping: {} diff --git a/testdata/lens-fixture/regression.yaml b/testdata/lens-fixture/regression.yaml new file mode 100644 index 0000000..785ba71 --- /dev/null +++ b/testdata/lens-fixture/regression.yaml @@ -0,0 +1,12 @@ +# Bad change: adds the requests rule but drops the httpx rule — the verify +# harness must flag the lost httpx row as a regression. +definition: + language: + python: + - name: "Legacy requests library" + prefix: "requests." + rule: "requests\\.(?[a-zA-Z0-9_]+)" + provider: TECH_DEBT + providers: + TECH_DEBT: + servicenameMapping: {}