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
ccebinary. - 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_recipeis a hint attached to the row, not an action CCE performs. - Not language-specific magic — one lens can contain
go,java,python,javascriptsections, 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
- Custom lens YAML — full syntax:
dataTables,prefixes_from,clientFactories,extract_resource_from, debugging, security limits - Enterprise lenses and catalogs — host lenses for CI, register recipes and packs, self-host the catalog
- Prowler wrapper-client example — lens for non-standard method names in a real codebase
- Analysis recipes — the catalog/pack side