Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Open <http://localhost:8000>.
## Update the site

- Edit `index.html` for content and `assets/styles.css` for presentation.
- Keep `index.md` as the clean Markdown equivalent for agents and users who prefer plain text. `llms.txt` is the concise, curated site index; do not turn it into a dump of the entire site.
- Keep examples aligned with the versioned files in `../examples/`.
- Link to the action README for exhaustive input/output tables rather than
duplicating every option on the landing page.
Expand Down
68 changes: 68 additions & 0 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
<meta property="og:type" content="website">
<meta property="og:url" content="https://stackgenhq.github.io/cce-action/">
<title>CCE Action — Cloud API evidence in GitHub Actions</title>
<link rel="alternate" type="text/markdown" href="index.md" title="Markdown version">
<link rel="describedby" type="text/plain" href="llms.txt" title="LLM documentation index">
<link rel="stylesheet" href="assets/styles.css">
</head>
<body>
Expand All @@ -23,6 +25,7 @@
</a>
<nav aria-label="Main navigation">
<a href="#workflows">Workflows</a>
<a href="#example">Example</a>
<a href="#lenses">Lenses</a>
<a href="#trust">Trust</a>
<a href="#quickstart">Quick start</a>
Expand Down Expand Up @@ -162,6 +165,70 @@ <h2>One small workflow.<br>A useful first report.</h2>
</div>
</section>

<section class="section" id="example">
<div class="container">
<div class="section-heading">
<p class="eyebrow">A real repository, a real result</p>
<h2>See what the JSON tells you.</h2>
<p>Scan <code>aws-samples/aws-lambda-extensions</code> at a pinned commit. CCE 0.0.38 examined 313 Python files and emitted 10 AWS evidence rows, including this Secrets Manager call.</p>
</div>
<div class="split-layout">
<div class="section-heading align-start">
<p class="eyebrow">Try it without setting up AWS</p>
<h3>One workflow. One downloadable report.</h3>
<p>The example checks out the public repository, runs the Python scan, and uploads <code>cce-public-repo-results</code>. No AWS credentials, deployed application, or CCE account is needed.</p>
<ol class="steps">
<li><span>1</span>Copy the workflow into any repository.</li>
<li><span>2</span>Run it manually from GitHub Actions.</li>
<li><span>3</span>Download the JSON and inspect the source evidence.</li>
</ol>
<p><a class="text-link" href="https://github.com/stackgenhq/cce-action/blob/main/examples/public-repo.yml">Copy the public-repo workflow <span aria-hidden="true">↗</span></a></p>
<p><a class="text-link" href="https://appcd-dev.github.io/cce/examples/cloud-api-inventory/">Read the full field guide <span aria-hidden="true">↗</span></a></p>
</div>
<div class="code-window">
<div class="code-heading"><span>cce-results.json (verified excerpt)</span><span>JSON</span></div>
<pre><code>{
<span class="code-muted">"files_scanned"</span>: 313,
<span class="code-muted">"summary"</span>: {
<span class="code-muted">"total_entitlements"</span>: 10,
<span class="code-muted">"by_provider"</span>: { <span class="code-muted">"AWS"</span>: 10 }
},
<span class="code-muted">"example"</span>: {
<span class="code-muted">"provider"</span>: <span class="code-muted">"AWS"</span>,
<span class="code-muted">"resource"</span>: <span class="code-muted">"secretsmanager"</span>,
<span class="code-muted">"operation"</span>: <span class="code-muted">"get_secret_value"</span>,
<span class="code-muted">"file"</span>: <span class="code-muted">"python-example-telemetry-opensearch-extension/python-example-telemetry-opensearch-extension/telemetry_dispatcher.py"</span>,
<span class="code-muted">"line"</span>: 19,
<span class="code-muted">"column"</span>: 19,
<span class="code-muted">"method"</span>: <span class="code-muted">"boto3.client('secretsmanager').get_secret_value"</span>
}
}</code></pre>
</div>
</div>
<div class="feature-grid">
<article class="feature-card">
<span class="feature-number">WHAT</span>
<h3>Normalized API evidence</h3>
<p>The row identifies AWS, Secrets Manager, and <code>get_secret_value</code>. The ten summary rows are evidence records, not ten unique permissions.</p>
</article>
<article class="feature-card">
<span class="feature-number">WHERE</span>
<h3>A source location you can inspect</h3>
<p>File, line, column, method, and signature connect the classification to the code. The full guide links directly to the pinned source line.</p>
</article>
<article class="feature-card">
<span class="feature-number">WHY</span>
<h3>A better review starting point</h3>
<p>An IAM reviewer can evaluate <code>secretsmanager:GetSecretValue</code>, then choose the secret ARN and validate the role. CCE does not grant access automatically.</p>
</article>
</div>
<div class="note-box">
<strong>Evidence, not a runtime guarantee.</strong>
<p>The scan does not execute code, read secrets, prove runtime coverage, or test effective IAM. Use it alongside human review and runtime validation.</p>
</div>
</div>
</section>

<section class="section" id="workflows">
<div class="container">
<div class="section-heading">
Expand Down Expand Up @@ -306,6 +373,7 @@ <h2>Make cloud usage easier to see, share, and review.</h2>
<a href="https://github.com/stackgenhq/cce-action">Repository</a>
<a href="https://github.com/stackgenhq/cce-action#inputs">Inputs &amp; outputs</a>
<a href="https://github.com/stackgenhq/cce-action/issues">Issues</a>
<a href="llms.txt">For LLM agents</a>
<a href="https://github.com/stackgenhq/cce-action/blob/main/LICENSE">License</a>
</div>
</div>
Expand Down
236 changes: 236 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
# CCE Action developer guide

> Turn source code into Cloud API evidence with GitHub Actions: inventories, PR diffs, IAM access requests, SARIF, and custom lenses.

CCE Action runs [StackGen CCE](https://appcd-dev.github.io/cce/) against the repository where a GitHub workflow is running. It supports Go, Python, Java, and JavaScript. No CCE account is required, field diagnostics are off by default, and reports remain available as workflow artifacts.

## Quick start

Create `.github/workflows/cce.yml`:

```yaml
name: CCE
on: [push, pull_request]
permissions:
contents: read
packages: read
jobs:
scan:
uses: stackgenhq/cce-action/.github/workflows/scan.yml@v1
with:
language: AUTO
filter: cloud
```

Open the workflow run and download the `cce-results` artifact. Use `@v0.3.0` instead of `@v1` when you want an exact action release.

## Use inside an existing job

```yaml
- uses: actions/checkout@v4
- uses: stackgenhq/cce-action@v1
id: cce
with:
language: AUTO
filter: cloud
- uses: actions/upload-artifact@v4
with:
name: cce-results
path: cce-results/*
```

The reusable workflows perform checkout and artifact upload themselves. Composite actions require `actions/checkout` first.

## Worked example: scan a public repository

This workflow checks out [AWS Samples' Lambda Extensions repository](https://github.com/aws-samples/aws-lambda-extensions) at a fixed commit, scans its Python source, and uploads the JSON result. Add it to any repository and run it manually; no AWS credentials or CCE account are needed.

```yaml
name: CCE public repository example
on: workflow_dispatch
permissions:
contents: read
packages: read
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
repository: aws-samples/aws-lambda-extensions
ref: cfed93e212d6415115d6a0a8a10885cded5a2b3b
- uses: stackgenhq/cce-action@v1
with:
language: PYTHON
filter: cloud
output-dir: cce-results
- uses: actions/upload-artifact@v4
with:
name: cce-public-repo-results
path: cce-results/*
```

[Copy this workflow](https://github.com/stackgenhq/cce-action/blob/main/examples/public-repo.yml). The reusable scan workflow is simpler when scanning the repository that owns the workflow; explicit checkout is needed for this public-repository demonstration.

### What the result looks like

CCE 0.0.38 examined 313 files and emitted 10 AWS evidence rows at the pinned commit. This excerpt keeps the summary and one complete Secrets Manager call:

```json
{
"files_scanned": 313,
"summary": {
"total_entitlements": 10,
"by_provider": { "AWS": 10 }
},
"example": {
"provider": "AWS",
"resource": "secretsmanager",
"operation": "get_secret_value",
"file": "python-example-telemetry-opensearch-extension/python-example-telemetry-opensearch-extension/telemetry_dispatcher.py",
"line": 19,
"column": 19,
"method": "boto3.client('secretsmanager').get_secret_value",
"signature": "sm_client.get_secret_value(SecretId=os.getenv('AUTH_SECRET'))",
"import_path": "boto3.client('secretsmanager')"
}
}
```

### What it means and why it matters

- `files_scanned` describes analysis scope, not the number of cloud calls.
- `total_entitlements` counts emitted evidence rows, not unique API operations or IAM permissions. Client construction can produce separate rows.
- `provider`, `resource`, and `operation` classify the call as AWS Secrets Manager `get_secret_value`.
- `file`, `line`, and `column` link the finding to [the exact source line](https://github.com/aws-samples/aws-lambda-extensions/blob/cfed93e212d6415115d6a0a8a10885cded5a2b3b/python-example-telemetry-opensearch-extension/python-example-telemetry-opensearch-extension/telemetry_dispatcher.py#L19). `method`, `signature`, and `import_path` explain the SDK match.
- A reviewer can use this evidence when evaluating `secretsmanager:GetSecretValue`, then choose the secret ARN and validate the execution role. CCE does not make that grant automatically.

The scan does not execute code, read secret values, prove runtime coverage, or test effective IAM. Treat it as review evidence, not a ready-to-deploy policy. See the [full CLI reproduction and field guide](https://appcd-dev.github.io/cce/examples/cloud-api-inventory/) for the local command, complete explanation, and access-request next step.

## Workflows

### Scan

Produces a JSON Cloud API report and, by default, attempts AWS IAM, GCP IAM, Azure RBAC, and cloud-neutral E-SBOM exports. Strict GCP and Azure exports do not publish unverified inferred permissions; check the relevant output path before consuming a role.

Example: <https://github.com/stackgenhq/cce-action/blob/main/examples/scan.yml>

### Pull-request review

Scans the base and head revisions, posts one sticky Cloud API diff, and publishes JSON, Markdown, and optional SARIF evidence.

```yaml
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
filter: cloud
fail-new: false
```

Set `comment: false` or `upload-sarif: false` to disable either publication. Fork PRs skip comment and SARIF writes when the normal token cannot publish safely; artifacts and summaries remain available.

Example: <https://github.com/stackgenhq/cce-action/blob/main/examples/pr-review.yml>

### IAM access request

Creates a versioned `cce-access-request/v1` JSON artifact containing deduplicated provider/resource/operation evidence, call-site counts, service, commit, and mapping provenance.

```yaml
jobs:
request:
uses: stackgenhq/cce-action/.github/workflows/access-request.yml@v1
with:
path: .
service: payments-api
```

The default flow needs no cross-repository token. Download the artifact and attach it to your IAM review process.

Example: <https://github.com/stackgenhq/cce-action/blob/main/examples/access-request.yml>

### Quickstart bundle

Creates a Cloud API BOM, self-contained HTML report, SARIF, lens lockfile, and suggested CI workflow:

```yaml
jobs:
quickstart:
uses: stackgenhq/cce-action/.github/workflows/quickstart.yml@v1
with:
path: .
```

Example: <https://github.com/stackgenhq/cce-action/blob/main/examples/quickstart.yml>

### Lens Gate 0

Compares current and candidate lenses against committed fixtures. It reports newly mapped and regressed rows and uploads verdict JSON even when a regression fails the job.

```yaml
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
```

Example: <https://github.com/stackgenhq/cce-action/blob/main/examples/lens-verify.yml>

## Custom lenses

A lens is YAML that teaches CCE to recognize internal SDKs, legacy clients, or organization-specific patterns. Local checkout lenses are hashed automatically. HTTPS lenses require `lens-sha256`; non-HTTPS remote URLs are rejected.

```yaml
- uses: actions/checkout@v4
- uses: stackgenhq/cce-action@v1
with:
language: AUTO
lens: .cce/internal-platform.yaml
filter: all
lens-required: true
```

Use `filter: all` for custom providers such as `TECH_DEBT`. `lens-required: true` compares against a built-in baseline and fails when the lens adds no unique operations. Outputs include `lens-file-sha256` and `lens-new-operation-count`.

## Requirements and common inputs

- Linux runner with Docker; `ubuntu-latest` is the simplest choice.
- CCE 0.0.38 or newer for PR review, access requests, quickstart, lens verification, and lens hash pinning.
- `path`: directory to scan; defaults to `.`.
- `language`: `AUTO`, `GO`, `PYTHON`, `JAVA`, or `JAVASCRIPT`.
- `filter`: `cloud` or `all`.
- `output-dir`: report directory; defaults to `cce-results` for scans.
- `scan-timeout`: optional wall-clock limit for large scans.
- `image`: optional CCE image override; action releases default to the CCE version their self-tests exercised.

For large repositories, scan a subdirectory or set `scan-timeout` so CI remains bounded.

## Important boundaries

- Static analysis can miss dynamic, reflected, or unrecognized wrapped calls.
- An empty report does not prove that no Cloud APIs or permissions are used.
- IAM access requests are review input, not ready-to-deploy policies.
- Reviewers remain responsible for resource scope, runtime needs, and final approval.
- Field diagnostics are disabled unless `diagnostics: true` is explicitly set.

## References

- [Action repository](https://github.com/stackgenhq/cce-action)
- [Complete inputs and outputs](https://github.com/stackgenhq/cce-action#inputs)
- [CCE documentation](https://appcd-dev.github.io/cce/)
- [Plain-language lens guide](https://appcd-dev.github.io/cce/guides/lenses/)
- [Known CCE limitations](https://appcd-dev.github.io/cce/reference/known-limitations/)
- [LLM site index](llms.txt)
43 changes: 43 additions & 0 deletions docs/llms.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# CCE Action

> CCE Action turns Go, Python, Java, and JavaScript source into Cloud API evidence inside GitHub Actions, including inventories, PR diffs, IAM access requests, SARIF, and custom lens verification.

Use this file to choose the smallest useful document. The developer guide is clean Markdown. Workflow examples and action references link directly to raw YAML so agents can inspect exact inputs without parsing HTML.

CCE Action requires no CCE account. Diagnostics are off by default. Static results are review evidence, not proof of runtime coverage or ready-to-deploy IAM policy. Use `filter: all` for custom lens providers. Remote lenses require HTTPS and a SHA-256 pin.

## Start here

- [CCE Action developer guide](https://stackgenhq.github.io/cce-action/index.md): Quick start, capabilities, requirements, examples, security defaults, and limitations in Markdown.
- [Action README](https://raw.githubusercontent.com/stackgenhq/cce-action/main/README.md): Complete scan inputs, outputs, exports, versioning, and operating notes.

## Workflow examples

- [Public repository scan with real output](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/public-repo.yml): Pinned AWS Samples checkout, Python scan, and artifact upload; the developer guide explains the resulting JSON.
- [Repository scan](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/scan.yml): Reusable scan workflow and composite action alternatives.
- [Cloud API pull-request review](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/pr-review.yml): Sticky Markdown diff, SARIF, artifacts, and optional gates.
- [IAM access request](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/access-request.yml): Artifact-first `cce-access-request/v1` generation without a cross-repository token.
- [Quickstart artifact bundle](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/quickstart.yml): Cloud API BOM, HTML, SARIF, lens lockfile, and suggested workflow.
- [Lens Gate 0](https://raw.githubusercontent.com/stackgenhq/cce-action/main/examples/lens-verify.yml): Fixture comparison with newly mapped and regressed evidence.

## Exact action contracts

- [Scan composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/action.yml): Authoritative composite input and output definitions.
- [Reusable scan workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/scan.yml): Reusable scan inputs and outputs.
- [Access-request composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/access-request/action.yml): IAM artifact inputs and outputs.
- [Quickstart composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/quickstart/action.yml): First-run artifact inputs and outputs.
- [Lens verification composite action](https://raw.githubusercontent.com/stackgenhq/cce-action/main/lens-verify/action.yml): Gate 0 inputs and verdict outputs.

## Related documentation

- [CCE llms.txt](https://appcd-dev.github.io/cce/llms.txt): Curated index for the CCE CLI, lenses, recipes, diffs, exports, and limitations.
- [CCE capabilities and examples](https://appcd-dev.github.io/cce/capabilities/index.md): Clean Markdown examples for the underlying CLI.
- [Worked Cloud API inventory](https://appcd-dev.github.io/cce/examples/cloud-api-inventory/index.md): Verified public-repository output, field explanations, IAM interpretation, and boundaries.

## Optional

- [PR-review reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/pr-review.yml): Full base/head review contract and publication controls.
- [Access-request reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/access-request.yml): Checkout and artifact-upload wrapper.
- [Quickstart reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/quickstart.yml): Quickstart wrapper contract.
- [Lens verification reusable workflow](https://raw.githubusercontent.com/stackgenhq/cce-action/main/.github/workflows/lens-verify.yml): Lens Gate 0 wrapper contract.
- [Source repository](https://github.com/stackgenhq/cce-action): Issues, releases, license, and implementation source.
4 changes: 4 additions & 0 deletions docs/robots.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
User-agent: *
Allow: /

Sitemap: https://stackgenhq.github.io/cce-action/sitemap.xml
6 changes: 6 additions & 0 deletions docs/sitemap.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://stackgenhq.github.io/cce-action/</loc>
</url>
</urlset>
Loading
Loading