CCE Troubleshooting Guide

This guide documents common issues encountered when using the cce CLI and how to diagnose and resolve them.

Table of Contents

1. Understanding the Analysis Pipeline
2. Common Issues
3. Debugging Workflow
4. Tool Chain Setup

---

Understanding the Analysis Pipeline

The cce folder scan follows this pipeline:

Source Code → Tree-sitter Parser → AST Traversal → Method Call Extraction → Resource Mapping → Output

Key Components

1. Tree-sitter Parser: Parses source code into an Abstract Syntax Tree (AST)
2. Language Strategy (python_strategy.go, go_strategy.go, etc.): Extracts method calls from AST
3. Resource Mapper (mapping_definition.go): Maps method calls to cloud provider resources using definition files
4. Definition Files (def.yaml, custom YAML files): Define rules for matching method calls to resources

---

Common Issues

Issue 1: Zero Resources Detected

Symptom: Running cce returns an empty array [] or "cloudProviderCount":0

Example Output:

$ cce -folder /path/to/code -mapper-file def.yaml -language AUTO -filter all -format json -output output.json
[]

Possible Causes:

A. Method Calls Not Being Detected by Tree-sitter

How to Diagnose:

# Run with debug logging to see what method calls are being detected
cce -folder /path/to/code \
  -mapper-file def.yaml \
  -language AUTO -filter all -format json -output output.json \
  --log-level debug 2>&1 | grep "method call"

What to Look For: - If you see "msg":"method call" entries with your expected function names, the parser IS detecting them - If you don't see any method call logs, the tree-sitter parser is not finding the calls

Common Root Causes: 1. Language not supported: Check if the file extension is recognized (.py, .go, .js, etc.) 2. Syntax errors: Tree-sitter may skip malformed code 3. Wrong node types: The language strategy may be looking for the wrong AST node types

B. Method Calls Detected But Not Mapped

How to Diagnose:

# Look for mapping errors
cce -folder /path/to/code \
  -mapper-file def.yaml \
  -language AUTO -filter all -format json -output output.json \
  --log-level debug 2>&1 | grep "could not map"

What to Look For:

{
  "msg":"could not map the method call",
  "methodCall":{"Name":"connect","Arguments":[...]},
  "error":"no valid mapped resource found for method call: connect, tried: STS Connect"
}

This means: - ✅ The method call WAS detected - ❌ The resource mapper could NOT match it to a definition rule

Common Root Causes:

1. Rule name mismatch: The rule field in your definition doesn't match the method name

   # ❌ Wrong - rule doesn't match method name
   - name: "STS Connect"
     prefix: "connect"
     rule: "sts_connect"  # Method is "connect", not "sts_connect"
   
   # ✅ Correct
   - name: "STS Connect"
     prefix: "connect"
     rule: "connect"
   

2. Incorrect extract_resource_from logic: The resource extraction is failing

3. Missing service name mapping: The extracted resource name doesn't exist in servicenameMapping

C. Arguments Not Being Extracted Correctly

How to Diagnose:

# Check the Arguments field in method call logs
cce -folder /path/to/code \
  -mapper-file def.yaml \
  -language AUTO -filter all -format json -output output.json \
  --log-level debug 2>&1 | grep -A5 "method call" | grep "Arguments"

What to Look For:

"Arguments":[
  {"Name":"account","TypeFunction":"","FullPackage":""},
  {"Name":"sns","TypeFunction":"","FullPackage":""},
  {"Name":"region=region","TypeFunction":"","FullPackage":""}
]

Expected Behavior: - For connect(account, 'boto3.ec2.client', region=region), the second argument should be normalized to "ec2" - For connect(account, 'sns', region=region), the second argument should be "sns"

Common Issues: 1. Quotes not stripped: Argument shows as "'sns'" instead of "sns" 2. Boto3 pattern not normalized: Argument shows as "boto3.ec2.client" instead of "ec2" 3. Wrong argument index: Using first_argument when you need second_argument

---

Issue 2: Tree-sitter C Dependencies Missing

Symptom: Build fails with errors like:

fatal error: 'tree_sitter/api.h' file not found
fatal error: '../../src/parser.c' file not found

Solution: Build CCE from this repository with CGO enabled (tree-sitter requires a C toolchain), or install via Homebrew:

brew tap stackgenhq/homebrew-stackgen
brew install stackgenhq/homebrew-stackgen/cce

Build from source:

cd /path/to/cce   # this repository (github.com/appcd-dev/cce)
CGO_ENABLED=1 go build -mod=mod -o /tmp/cce ./cmd/cce

Verification:

which cce
cce -version

---

Issue 3: Using an Outdated CCE Binary

Symptom: Analysis doesn't reflect recent code changes or definition updates

How to Diagnose:

ls -la $(which cce)

Solution: Rebuild or upgrade CCE

brew upgrade cce
# or from source:
CGO_ENABLED=1 go build -mod=mod -o $(go env GOPATH)/bin/cce ./cmd/cce

---

Debugging Workflow

Step 1: Verify CCE Installation

which cce
cce -version
cce -folder . -language AUTO -filter cloud -format json -output /tmp/smoke.json

Step 2: Create a Minimal Test Case

# test_connect.py
from security_monkey.common.sts_connect import connect

def test_function():
    # Test simple service name
    sns = connect(account, 'sns', region=region)

    # Test boto3 format
    ec2 = connect(account, 'boto3.ec2.client', region=region)

Step 3: Run Analysis with Debug Logging

cce -folder /path/to/test_connect.py -language AUTO \
  -mapper-file /path/to/def.yaml -filter all \
  -format json -output /tmp/test_output.json \
  -log-level debug 2>&1 | tee /tmp/debug.log

Step 4: Analyze Debug Output

# Check if method calls are being detected
grep "method call" /tmp/debug.log

# Check for mapping errors
grep "could not map" /tmp/debug.log

# Check what rules were tried
grep "tried:" /tmp/debug.log

# Check argument extraction
grep "Arguments" /tmp/debug.log

Step 5: Verify Definition File

# Check your def.yaml structure
definition:
  language:
    python:
      - name: "STS Connect"
        prefix: "connect"
        rule: "connect"  # Must match the actual method name
        extract_resource_from: "second_argument"  # Extract from 2nd arg
        provider: AWS

  providers:
    AWS:
      servicenameMapping:
        "sns": "sns"
        "ec2": "ec2"
        "iam": "iam"
        # Add all services you expect to see

Step 6: Test Argument Normalization

The normalizePythonBoto3Argument function in python_strategy.go handles these transformations:

Input	Output
'boto3.ec2.client'	ec2
"boto3.s3.resource"	s3
'sns'	sns
"iam"	iam

Verification:

# Check if normalization is working
cce -folder test.py -mapper-file def.yaml --log-level debug 2>&1 \
  | grep -E "Arguments.*Name" \
  | jq '.Arguments[1].Name'

Expected: "ec2" (not "boto3.ec2.client")

---

Tool Chain Setup

Repository Structure

github.com/appcd-dev/cce/     # This repository
├── cmd/cce/                  # CLI entrypoint
├── pkg/
│   ├── analyzer/treesitter/  # Method call extraction
│   └── resourcemapper/       # YAML / Grok mapping
└── docs/
    ├── site/                 # User docs (MkDocs → GitHub Pages)
    └── troubleshooting_guide.md

Build Process

1. Edit and test in this repo:

   cd /path/to/cce
   CGO_ENABLED=1 go test -mod=mod ./pkg/analyzer/treesitter/... ./pkg/resourcemapper/...
   

2. Rebuild the CLI:

   CGO_ENABLED=1 go build -mod=mod -o /tmp/cce ./cmd/cce
   

3. Verify:

   /tmp/cce -version
   /tmp/cce -folder /path/to/code -mapper-file def.yaml -language AUTO -filter all -format json -output out.json
   

Definition File Locations

• Security Monkey: /Users/sabithks/src/github.com/Netflix/security_monkey/def.yaml
• Prowler: /Users/sabithks/src/github.com/sks/permissions/docs/example/prowler.yaml
• Custom definitions: Can be stored anywhere, referenced via -mapper-file flag

---

Advanced Debugging

Inspecting Tree-sitter AST

To understand what the tree-sitter parser is seeing:

# Install tree-sitter CLI
npm install -g tree-sitter-cli

# Parse a Python file
tree-sitter parse test.py

Look for call nodes in the output - these are what the analyzer detects as method calls.

Checking Resource Mapper Logic

The resource mapper (mapping_definition.go) extracts resources based on extract_resource_from:

// For extract_resource_from: "second_argument"
if langDef.ExtractResourceFrom == "second_argument" && len(args) > 1 {
    secondArg := args[1].Name
    secondArg = strings.Trim(secondArg, "'\"")  // Remove quotes
    result.Resource = secondArg
}

Key Points: 1. Argument index is 0-based: second_argument = args[1] 2. Quotes are stripped automatically 3. Boto3 normalization happens in python_strategy.go, NOT in the mapper

Testing Normalization Function

cd /Users/sabithks/src/github.com/sks/permissions
go test ./pkg/analyzer/treesitter -v -run "normalizePythonBoto3Argument"

Expected output:

=== RUN   TestPythonTraversalStrategy
=== RUN   TestPythonTraversalStrategy/normalizePythonBoto3Argument
    ✓ boto3.ec2.client with single quotes → ec2
    ✓ boto3.s3.client with double quotes → s3
    ✓ simple service name 'sns' → sns
PASS

---

Quick Reference

Common Commands

# Rebuild cce from source
cd /path/to/cce && CGO_ENABLED=1 go build -mod=mod -o /tmp/cce ./cmd/cce

# Run analysis with debug
cce -folder /path -mapper-file def.yaml -language AUTO -filter all -format json -output out.json --log-level debug

# Check method call detection
cce ... --log-level debug 2>&1 | grep "method call"

# Check mapping errors
cce ... --log-level debug 2>&1 | grep "could not map"

# Run CCE tests
cd /Users/sabithks/src/github.com/sks/permissions
go test ./pkg/analyzer/treesitter -v
go test ./pkg/resourcemapper -v

Definition File Template

definition:
  language:
    python:
      - name: "Descriptive Name"
        prefix: "method_prefix"
        rule: "exact_method_name"  # Must match actual method name
        extract_resource_from: "second_argument"  # or "first_argument"
        provider: AWS

  providers:
    AWS:
      servicenameMapping:
        "service_name": "aws_service_name"

---

Case Study: Security Monkey Analysis

Problem

Running cce on Security Monkey returned zero resources despite many connect() calls in the codebase.

Investigation Steps

1. Verified method call detection:

   cce -folder security_monkey --log-level debug 2>&1 | grep "connect"
   

   Result: connect() calls WERE being detected ✅

2. Checked mapping errors:

   cce --log-level debug 2>&1 | grep "could not map"
   

   Result: "error":"no valid mapped resource found for method call: connect, tried: STS Connect" ❌

3. Examined arguments:

   "Arguments":[
     {"Name":"account"},
     {"Name":"sns"},  // ✅ Correctly normalized from 'sns'
     {"Name":"region=region"}
   ]
   

4. Verified definition file:

5. ✅ rule: "connect" matches method name
6. ✅ extract_resource_from: "second_argument" is set
7. ✅ servicenameMapping includes "sns": "sns"

Current Status

The investigation revealed that all components are working correctly: - Tree-sitter is detecting connect() calls - Arguments are being extracted and normalized - The definition file is properly configured

Next Step: Investigate why the resource mapper validation is failing despite correct configuration.

---

Getting Help

If you encounter issues not covered in this guide:

1. Check the logs: Always run with --log-level debug
2. Create a minimal test case: Isolate the problematic pattern
3. Verify the tool chain: Ensure cce is up-to-date (cce -version)
4. Review definition files: Double-check YAML syntax and field names
5. Run unit tests: go test ./pkg/... -v to verify core functionality