Skip to content

What is a lens?

A lens is a YAML file of matching rules that teaches CCE how to read your call sites. Same code, same parser, same report format — a different vocabulary. Pass one with -mapper-file ./your-lens.yaml and every scan speaks that vocabulary.

Think of a camera: the built-in mapper is the default factory lens that frames cloud SDK calls for IAM entitlements. Swapping the lens doesn't change the scene (your code happens to be what it is) — it changes what CCE sees in the scene: which imports matter, what each method call is called, and what to do about it.

  • No Go code, no rebuild: lenses are data. A platform team can maintain one and attach it to CI without ever touching the cce binary.
  • Read-only inventory: a lens finds and classifies call sites; it does not rewrite code. Change steps (if you want them) live in OpenRewrite recipes referenced as hints.
  • Try one now:
cce -folder ./my-service -language AUTO -filter all \
    -mapper-file ./my-lens.yaml -format json -output lens-scan.json
# my-lens.yaml — flag calls to the deprecated `requests` library
definition:
  language:
    python:
      - name: "Legacy requests library"       # human label, shows up in warnings
        prefix: "requests."                   # fast filter: must match the START of the extracted method name
        rule: "requests\\.(?<operation>[a-zA-Z0-9_]+)"   # grok pattern with named captures
        provider: TECH_DEBT                   # the vocabulary bucket this row lands in
        openrewrite_recipe: "org.openrewrite.python.migrate.ReplaceRequestsWithHttpx"
        replacement_fqn: "httpx"
        docs_url: "https://www.python-httpx.org/"
  providers:
    TECH_DEBT:
      servicenameMapping: {}

The pipeline, end to end

flowchart LR
  src["source files<br/>(go / java / py / js)"] --> parser["tree-sitter parser<br/>(unchanged by lenses)"]
  parser --> calls["method-call stream<br/>each call: full package path + symbol"]
  calls --> rules{"match, in order"}
  rules -->|"1. your lens<br/>(-mapper-file)"| rows
  rules -->|"2. built-in mapper<br/>(definition.yaml)"| rows
  rows[/"mapped rows:<br/>provider / resource / operation<br/>+ optional action hints"/] --> report["JSON / SARIF report"]

Every lens runs on top of the same two built-ins: the tree-sitter parse and the report format. Only the middle — what a call site means — is yours to define.

From method name to row

The single most important fact: CCE matches rules against the extracted method name, which is the full package path + symbol — not the import alias in your source file.

Trace one call. Given:

# app.py
import requests

requests.get("https://example.com/health")
Step What happens
1. Extract The parser turns the call site into the method name requests.get
2. Prefix filter prefix: "requests." matches the start of requests.get — this rule is in play
3. Rule match The grok rule matches; the named capture (?<operation>…) captures get
4. Fill blanks Nothing captured resource_group, so CCE derives resource from the prefix (requests. → requests)
5. Emit One structured row goes to the report

The row (same shape as every CCE report):

{
  "provider": "TECH_DEBT",
  "resource": "requests",
  "operation": "get",
  "method": "requests.get",
  "file": "app.py",
  "line": 4
}

Because the row is structured, everything downstream is queryable: count resource × operation, diff two scans with cce diff, or gate CI on a count. The openrewrite_* fields ride along in JSON as suggested_action hints — reminders for the humans, not executable changes.

The built-in cloud lens vs your lens

CCE ships one mapping of its own (pkg/resourcemapper/definition/definition.yaml) — the "cloud entitlements" vocabulary: AWS, Azure, GCP, OCI, IBM, Alibaba. You never opt into it; it is always loaded. Rules to remember:

Fact Why it matters
Your lens is tried first; the built-in fills whatever your lens does not match Lenses add vocabulary on top of cloud entitlements — you get both
First match wins inside a definition Order rules specific → general; overlapping prefix-less rules warn at load time
prefix must match the start of the extracted method name The usual full-package-path FQN, e.g. github.com/aws/aws-sdk-go/service/s3.ListBuckets — copying the visible import alias is the #1 mistake
%{WORD} does not match _ or - Use inline regex (?<name>[a-z0-9_]+) for underscored identifiers
Custom provider values (e.g. PLATFORM, TECH_DEBT) need -filter all -filter cloud keeps only the built-in cloud providers
clientFactories from the lens merge with the built-ins boto3.client('s3')-style factory knowledge composes with yours

When you reach for a lens

Situation Built-in mapper Lens
"What cloud services does this service touch?" (PoLP) ✅ —
"Which services call our internal platform SDK instead of going direct?" ❌ ✅ provider: PLATFORM vs provider: DIRECT_CLOUD
"Where is deprecated library X still called?" ❌ ✅ provider: TECH_DEBT + OpenRewrite hint
"Does this wrapper client (non-standard method names) resolve?" ❌ ✅ grok rule per wrapper shape

If many teams will run the same lens by id (cce run -pack), promote it into a catalog recipe — a small JSON entry pointing at your hosted YAML. That's packaging, not a new concept: see Enterprise lenses and catalogs.

What a lens is not

  • Not an IAM policy — it inventories call sites; it does not verify the caller is allowed to make them. See Entitlements, operations, and IAM.
  • Not a rewriter — openrewrite_recipe is a hint attached to the row, not an action CCE performs.
  • Not language-specific magic — one lens can contain go, java, python, javascript sections, all applied during the same scan.
  • Not a replacement for the built-in rule base — a lens extends it; unmatched calls still fall through to the built-in mapper.

Glossary

Term Plain words
Method name The extracted call identity: full package path + symbol (requests.get)
prefix Cheap string filter: rule is only tried if this matches the method-name start
rule Grok pattern with named captures resource_group and operation; optional — without it, a standard pattern is generated from the prefix
provider The bucket a row is classified under (cloud vendor, or your org's label)
resource / operation What was called (s3) and what was done to it (ListBuckets)
Servicename mapping Normalizes odd SDK names to standard service names
Action hints openrewrite_recipe / replacement_fqn / docs_url — optional suggestions in JSON
Recipe / catalog / pack Packaging for lenses: discover by id and run by pack (see enterprise guide)

Where to go next