# Capabilities and examples

CCE reads supported source files and produces structured evidence about recognizable SDK and library calls. Start with the task closest to yours; every example below can be run locally, and the main adoption paths also have native GitHub Actions workflows.

<div class="cce-task-grid">
  <a href="#cloud-api-inventory"><strong>Inventory cloud usage</strong><span>Provider, resource, operation, and source evidence</span></a>
  <a href="#iam-access-review"><strong>Review IAM access</strong><span>A versioned request for platform and security teams</span></a>
  <a href="#pull-request-review"><strong>Review a change</strong><span>Added and removed API calls in a PR</span></a>
  <a href="#modernization-and-tech-debt"><strong>Find modernization targets</strong><span>Legacy clients, SDK uplift, and outbound coupling</span></a>
  <a href="#custom-lenses"><strong>Recognize internal libraries</strong><span>Custom YAML rules without changing CCE</span></a>
  <a href="#integrations-and-exports"><strong>Connect your tools</strong><span>JSON, SARIF, E-SBOM, IAM, and Backstage</span></a>
</div>

## Cloud API inventory

**Question:** Which cloud services and operations does this repository call?

For a complete first-run bundle:

```bash
cce quickstart .
```

For a focused JSON inventory:

```bash
cce -folder . -language AUTO -filter cloud \
  -format json -output cloud-api.json
```

Each entitlement row connects a provider/resource/operation tuple to a source location:

```json
{
  "provider": "AWS",
  "resource": "s3",
  "operation": "PutObject",
  "file": "internal/upload.go",
  "line": 71
}
```

List the unique AWS service and operation pairs:

```bash
jq -r '.entitlements[]
  | select(.provider == "AWS")
  | [.resource, .operation] | @tsv' cloud-api.json | sort -u
```

Use `cce plan -folder . -language AUTO` first when you want to preview which source files will be scanned.

**New to the JSON?** Follow the [worked public-repository example](examples/cloud-api-inventory.md) for a pinned AWS Samples scan, verified output, and a field-by-field explanation of what the evidence means and why it matters.

[Cloud entitlement guide](use-cases/guides/cloud-entitlements/index.md) · [First-run artifacts](get-started.md#first-run-cce-quickstart)

## IAM access review

**Question:** What operations should an IAM reviewer evaluate for this service?

```bash
cce access-request . \
  --service payments-api \
  --output cce-access-request.json
```

The `cce-access-request/v1` document deduplicates operations, counts call sites, records the source commit when available, and includes mapping provenance:

```json
{
  "schema": "cce-access-request/v1",
  "service": "payments-api",
  "operations": [
    {
      "provider": "AWS",
      "resource": "s3",
      "operation": "PutObject",
      "file": "internal/upload.go",
      "line": 71,
      "sites": 2
    }
  ]
}
```

The app repository can upload this artifact without receiving credentials for the IAM repository:

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

!!! important "Review before granting"
    This is static code evidence, not an effective-permission test or ready-to-deploy policy. CCE does not infer the complete runtime resource scope. Reviewers must bind resources and validate the final policy.

[Cross-repository IAM workflow](guides/cross-repo-iam-review.md) · [Operations and IAM model](guides/entitlements-operations-and-iam.md)

## Pull-request review

**Question:** Did this change add or remove Cloud API usage?

The native workflow scans the base and head revisions, updates one sticky PR comment, and preserves JSON, Markdown, and 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
```

For two existing JSON reports, the CLI equivalent is:

```bash
cce diff baseline.json current.json \
  --mode callsite --format markdown \
  --output api-diff.md
```

Use `--mode tuple` when you care only about unique provider/resource/operation changes rather than individual call-site additions and removals. Add `--fail-new` to make new tuples a CI gate after the diff is produced.

[GitHub Actions guide](guides/github-actions.md#pr-review-cloud-api-diff)

## Modernization and tech debt

**Question:** Where are legacy clients, SDK uplift opportunities, or outbound dependencies?

Recipes give common investigations a stable name. Packs combine related recipes into one merged report:

```bash
cce catalog

cce run -folder . -language AUTO \
  -pack modernization-pack \
  -output modernization.json
```

The modernization pack covers cloud entitlements, SDK uplift, and deprecated API/tech-debt inventory. Other packs focus on security governance and platform governance.

Run only selected recipes:

```bash
cce run -folder . -language AUTO \
  -recipes sdk-uplift,tech-debt-inventory \
  -output modernization-targets.json
```

The output is an inventory with evidence, not an automatic rewrite. Pair it with OpenRewrite or your own codemods when you are ready to change code.

[Browse all use cases](use-cases/catalog.md) · [Recipes and packs](reference/analysis-recipes.md) · [CCE versus OpenRewrite](reference/cce-vs-openrewrite.md)

## Custom lenses

**Question:** Can CCE recognize an internal SDK, wrapper, or deprecated library?

A lens is a YAML file that tells CCE which call sites matter and how to classify them. Your lens runs first; built-in cloud mappings still handle unmatched calls.

```bash
cce -folder . -language AUTO -filter all \
  -mapper-file ./my-lens.yaml \
  -format json -output findings.json
```

Use `filter: all` for custom providers such as `TECH_DEBT` or `PLATFORM`.

### Pin the content you reviewed

```bash
sha256sum my-lens.yaml  # macOS: shasum -a 256 my-lens.yaml

cce -folder . -language AUTO -filter all \
  -mapper-file ./my-lens.yaml \
  -mapper-sha256 9f2c... \
  -format json -output findings.json
```

Remote lenses must use HTTPS and should always be pinned with `-mapper-sha256`. A mismatch fails before lens rules load.

### Test a lens change

Commit a small fixture corpus and compare the current and candidate lenses:

```bash
cce lens verify \
  --fixture testdata/lens-fixtures/my-lens \
  --current current.yaml \
  --candidate candidate.yaml \
  --output lens-verdict.json
```

The result separates newly mapped rows from regressions. Regressions fail by default, making this a useful Gate 0 for lens pull requests.

[Lens concept guide](guides/lenses.md) · [Lens YAML reference](reference/custom-lens-yaml.md) · [Gate 0 in GitHub Actions](guides/enterprise-lenses-and-catalogs.md#7-gate-every-lens-change-on-the-fixture-corpus)

## Integrations and exports

### GitHub Actions

Use reusable workflows for scanning, PR review, access requests, quickstart artifacts, and lens verification. Diagnostics are off unless explicitly enabled.

```yaml
jobs:
  scan:
    uses: stackgenhq/cce-action/.github/workflows/scan.yml@v1
    with:
      language: AUTO
```

[GitHub Actions examples](guides/github-actions.md)

### SARIF and policy exports

```bash
cce -folder . -language AUTO -filter cloud \
  -format sarif -output cce-results.sarif

cce policy export cloud-api.json \
  --format aws-iam --provider AWS \
  --output aws-policy.json

cce policy export cloud-api.json \
  --format esbom \
  --output cloud-esbom.json
```

Strict GCP and Azure exports reject unverified inferred permission mappings rather than publishing guesses. A scan report can still be useful when a provider role cannot be exported.

[Cloud-agnostic model](reference/cloud-agnostic-model.md)

### Backstage Software Catalog

Generate Component, API, and cloud Resource YAML from a local checkout:

```bash
cce --folder . --language AUTO --filter cloud \
  --format backstage --output catalog.yaml \
  --backstage-name payments-api
```

Review ownership and discovered metadata before committing the result to your catalog repository.

[Backstage guide](guides/backstage-software-catalog.md)

### SCM metadata

Fetch repository metadata from GitLab into deterministic YAML:

```bash
cce scm describe \
  --provider gitlab \
  --base-url https://gitlab.com \
  --repo group/sub/project \
  --token "$GITLAB_TOKEN" \
  --output repo.yaml
```

This SCM command reads repository metadata; it does not scan source code.

[SCM metadata reference](reference/scm-metadata-spec.md)

## Choose the right comparison or filter

| Setting | Use it when |
|---------|-------------|
| `filter: cloud` | You want built-in cloud-provider mappings |
| `filter: all` | You also want custom lens providers and other inventory categories |
| `diff --mode callsite` | You care about exact file, line, and method changes |
| `diff --mode tuple` | You care about unique provider/resource/operation changes |
| `-language AUTO` | You want CCE to detect supported source languages |
| `cce plan` | You want to inspect scope before a long scan |

## Know the boundaries

- CCE is read-only and does not rewrite source code.
- Static analysis can miss dynamic, reflected, or unrecognized wrapped calls.
- An empty report does not prove that no Cloud APIs or permissions are used.
- Access requests and IAM exports require human review and provider-specific validation.

[Read the known limitations](reference/known-limitations.md) · [Troubleshoot a scan](reference/troubleshooting.md)
