Known limitations (all CCE use cases)
This document is the single source of truth for what CCE can and cannot do today. Each use-case guide links here for platform-wide limits; use-case-specific rows are below.
Proof runs: docs/proof/README.md — which workflows have been exercised on real code.
Platform-wide limitations (every use case)
| Limitation | Detail |
|---|---|
| Static analysis only | CCE maps source-level method calls via tree-sitter. It does not execute code, trace runtime reflection, or follow dynamic dispatch across plugins. |
| CGO required | Builds and releases need CGO_ENABLED=1 and a C toolchain (tree-sitter bindings). |
| Languages | Go, Java, Python, JavaScript (.go, .java, .py, .js/.jsx/.mjs/.cjs). Other languages are ignored. |
| Gitignore | Scans honor .gitignore by default (nested rules, Git wildmatch via git-pkgs/gitignore). vendor/ and similar dirs are excluded unless you pass -include-gitignored. Hidden dotfiles (e.g. .env) are skipped even when not gitignored. |
| Multi-lens scans | Standalone cce invocations re-parse the tree each time. Use cce run -pack … or -recipes … for one parse and multiple mapped reports. |
| Parallelism | File parses run with bounded concurrency (CCE_MAX_PARALLELISM, default half of CPU count). Very large repos may still need sufficient RAM for tree-sitter ASTs. |
| One language per scan | Pass -language GO, JAVA, PYTHON, JAVASCRIPT, or AUTO. AUTO picks a single language for the tree; polyglot folders need one scan per language on the same path. |
| No cross-file call graph | Output is a flat list of call sites per file. There is no built-in service graph, package dependency graph, or inter-procedural reachability. |
| Mapper precedence | With -mapper-file, the user lens runs first, then built-in cloud rules if the lens does not match. Overlapping FQNs need explicit rules in your YAML to get custom provider labels; otherwise built-in AWS/GCP labels still apply. |
-filter cloud |
Drops rows without a validated cloud-style provider/resource. Use -filter all for custom providers (CVE, FORBIDDEN, TECH_DEBT, MESSAGING, etc.). |
| Wrappers & code gen | Thin wrappers (e.g. Prowler-style clients) and heavy codegen may need custom Grok rules — see Custom lens YAML and example/prowler.yaml. |
| IaC / config | Terraform, CloudFormation, Kubernetes manifests, and IAM JSON are not parsed by cce. IaC alignment and landing-zone workflows require external diff/merge of JSON outputs. |
| Baseline diff | Use cce diff baseline.json current.json with optional -policy YAML (CI policies). Shorthand: --fail-new. |
| Private GitHub clones | -repo needs GITHUB_TOKEN / -github-token for private repositories. |
| Unmapped calls | Logged at DEBUG only. Tune lenses with -log-level debug when extending YAML. |
| MCP server | Planned — today agents wrap the CLI and parse JSON (agent-mcp-integration). |
| Go import aliases | Callee names use the import alias (http.NewRequestWithContext). Lenses should include both http. and net/http. prefixes where relevant. |
| Lens-only suppress | Scans with a custom lens still emit built-in cloud rows for unmatched SDK calls (e.g. boto3 without TECH_DEBT rules). Filter or extend YAML as needed. |
Per-use-case limitations and proof status
| Use case | Proof status | Known limitations |
|---|---|---|
| cloud-entitlements | Verified (Go, Java, Python, JS + AWS sample repos) | Misses indirect SDK use through internal facades; no IAM effective permissions; polyglot = multiple scans. |
| pre-deploy-iam-review | Verified | Same extraction as cloud entitlements; gate logic (allow/deny lists) is your CI script; does not evaluate Terraform plans. |
| sdk-uplift | Verified (labels) | Built-in mapper may label v1/v2 both as AWS; compare method prefixes. javax/jakarta and Spring rules need Java scan. |
| tech-debt-inventory | Verified (requests) | Starter lens — add your deprecated libraries. Boto3 calls map as AWS unless you add TECH_DEBT rules for them. |
| cve-reachability | Lens-only | Template lens — must rewrite rules per CVE/advisory. Use -filter all. No CVE feed integration. |
| vulnerability-reachability | Lens-only | Same as CVE reachability; duplicate workflow name for f-SBOM teams. |
| data-layer-modernization | Lens-only | Covers ORM/driver call patterns in lens; does not migrate schemas or validate SQL strings in all dialects. |
| integration-replatforming | Verified | Messaging/HTTP rules are starter sets; Kafka/SQS/Rabbit variants need extension. Azure Event Hubs maps via built-in + lens. |
| microservice-decomposition | Verified (Go HTTP) | Outbound/discovery rules are starters; no automatic bounded context. Use -filter all. |
| cloud-readiness | Lens-only | Signals managed-service usage, not 12-factor or serverless fit; custom rules for Lambda/Cloud Run entrypoints. |
| observability-gaps | Lens-only | Detects tracer/metrics client calls, not missing spans at runtime or log correlation. |
| secrets-hygiene | Lens-only | Finds SDK/env patterns in lens; does not scan git history or secret scanners (TruffleHog, etc.). |
| iac-alignment | Verified (app side) | CCE produces app entitlements only; IaC parse and diff are external. Resource names in code may not match TF resource addresses. |
| platform-adoption | Lens-only | Requires your org package prefixes in YAML; no built-in platform catalog. |
| blast-radius-analysis | Lens-only | No graph database — aggregate JSON across services manually or with your graph tool; blast radius is downstream analytics. |
| supply-chain-call-tracing | Lens-only | Traces call sites to library APIs in lens, not full SBOM provenance or transitive dep trees. |
| audit-evidence | Partial | JSON rows are evidence of invocation, not proof of data handling or retention; combine with change tickets. |
| landing-zone-governance | Partial | No multi-repo CLI — run per repo and merge JSON; repo identity is not in schema (add in merge step). |
| regulatory-scope | Lens-only | PCI/HIPAA/SOC rules are templates — compliance teams must maintain FQNs and scope tags. |
| change-control | Partial | Detects new mapped calls vs your stored baseline; CLI does not store baselines or open PR comments. |
| golden-path-enforcement | Lens-only | Requires configured allowed/forbidden prefixes; may conflict with built-in mapper precedence — test with -filter all. |
| llm-code-context | Partial | JSON is evidence for RAG/agents; token limits require summarization; no embedding pipeline included. |
| agent-mcp-integration | Partial | CLI subprocess only today; no native MCP server; agents must handle clone time and large JSON. |
| incident-scoping | Lens-only | Maps likely service touchpoints from SDK usage; not metrics, logs, or deployment correlation. |
| runbook-targeting | Lens-only | Identifies files touching a service API; runbook content and on-call routing are external. |
| change-impact-analysis | Partial | Pre-merge scan vs baseline is your diff; no git-aware incremental scan in CLI. |
| as-built-dependency-map | Lens-only | Compose multiple lenses (cloud + integration + microservice) and merge externally; no single merged report. |
| monorepo-intelligence | Partial | Run per language or path; no module-aware Bazel/Gradle graph; large monorepos need path-scoped -folder. |
| regression-gates | Lens-only | Forbidden list is maintainer-edited YAML; may miss calls through aliases unless rules include them. |
| contract-testing-seeds | Lens-only | Suggests outbound/integration call sites; does not generate Pact/OpenAPI tests automatically. |
Proof status legend
| Status | Meaning |
|---|---|
| Verified | Documented scan on real corpus with artifact or log in docs/proof (includes four-language + AWS examples matrix). |
| Partial | Core scan works; critical steps (diff, merge, agent, IaC) are outside CCE. |
| Lens-only | Workflow depends on customizing <usage>_lenses.yaml; not fully exercised in proof runs yet. |
Anti-patterns (wrong corpus / lens)
| Mistake | Symptom | Fix |
|---|---|---|
| Built-in cloud lens on libraries with no cloud SDK (e.g. resilience4j) | Huge DEBUG unmapped volume, empty or useless entitlements[] |
Use integration, tech-debt, or custom lens; or -filter all with correct YAML. |
-filter cloud with CVE / FORBIDDEN / TECH_DEBT providers |
Empty report despite matches | Use -filter all. |
Single -language GO on polyglot monorepo |
Incomplete coverage | Run JAVA, PYTHON, JS scans separately. |
Expecting SDK uplift provider: AWS_V2 only |
Rows show provider: AWS |
Read method field for aws-sdk-go vs aws-sdk-go-v2 prefixes. |
Maintainers
To refresh Known limitations sections in all usage READMEs after editing this file or proof status:
python3 use-cases/guides/_inject_limitations.py
Edit the CASES map in that script, then re-run.
Related
- Use case catalog
- Use case guides
- Troubleshooting: troubleshooting.md
- Custom lenses: Custom lens YAML