kubescape/docs/troubleshooting.md

Troubleshooting Guide

This guide covers common issues you may encounter when using Kubescape and how to resolve them.

Table of Contents

• Installation Issues
• Scanning Issues
• Image Scanning Issues
• Image Patching Issues
• Operator Issues
• MCP Server Issues
• Output and Reporting Issues
• Performance Issues
• Getting Help

---

Installation Issues

Command not found after installation

Symptom: After running the install script, kubescape command is not found.

Solution:

1. Check if the binary was installed:

   ls -la ~/.kubescape/kubescape
   

2. Add to your PATH:

   # For bash
   echo 'export PATH=$PATH:~/.kubescape' >> ~/.bashrc
   source ~/.bashrc
   
   # For zsh
   echo 'export PATH=$PATH:~/.kubescape' >> ~/.zshrc
   source ~/.zshrc
   

3. Alternatively, move the binary to a directory already in your PATH:

   sudo mv ~/.kubescape/kubescape /usr/local/bin/
   

Permission denied during installation

Symptom: Installation fails with permission errors.

Solution:

# Create the directory with proper permissions
mkdir -p ~/.kubescape
chmod 755 ~/.kubescape

# Re-run the installation
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash

Installation fails on Windows

Symptom: PowerShell script fails to execute.

Solution:

1. Check PowerShell version (must be v5.0+):

   $PSVersionTable.PSVersion
   

2. Set execution policy:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   

3. Retry installation:

   iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex
   

---

Scanning Issues

Cannot connect to cluster

Symptom: kubescape scan fails with connection errors.

Solutions:

1. Verify kubectl works:

   kubectl get nodes
   

2. Check your kubeconfig:

   kubectl config current-context
   kubectl config view
   

3. Use an explicit kubeconfig:

   kubescape scan --kubeconfig /path/to/kubeconfig
   

4. Use a specific context:

   kubescape scan --kube-context my-context
   

Scan times out

Symptom: Scanning large clusters takes too long or times out.

Solutions:

1. Scan specific namespaces:

   kubescape scan --include-namespaces production,staging
   

2. Exclude non-essential namespaces:

   kubescape scan --exclude-namespaces kube-system,kube-public,monitoring
   

3. Scan a specific framework instead of all:

   kubescape scan framework nsa
   

No results returned

Symptom: Scan completes but shows no results.

Solutions:

1. Check if the cluster has workloads:

   kubectl get pods --all-namespaces
   

2. Run with verbose output:

   kubescape scan -v
   

3. Check for namespace filtering issues:

   # Make sure you're not excluding all namespaces
   kubescape scan --include-namespaces default
   

Framework or control not found

Symptom: Error about unknown framework or control.

Solutions:

1. List available frameworks:

   kubescape list frameworks
   

2. List available controls:

   kubescape list controls
   

3. Update Kubescape to get latest controls:

   # Re-run installation to get latest version
   curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
   

4. Download latest artifacts:

   kubescape download artifacts
   

RBAC errors during scan

Symptom: Scan fails with permission denied errors.

Solution:

Ensure your kubeconfig user has sufficient permissions. At minimum, you need read access to:

• Deployments, DaemonSets, StatefulSets, Jobs, CronJobs
• Pods, Services, ConfigMaps, Secrets
• Roles, RoleBindings, ClusterRoles, ClusterRoleBindings
• NetworkPolicies
• ServiceAccounts

---

Image Scanning Issues

Image not found

Symptom: kubescape scan image fails to find the image.

Solutions:

1. Use the full image reference:

   kubescape scan image docker.io/library/nginx:1.21
   

2. For private registries, provide credentials:

   kubescape scan image myregistry.io/myimage:tag \
     --username myuser \
     --password mypassword
   

3. Check if the image exists locally:

   docker images | grep myimage
   

Authentication failed for private registry

Symptom: Scan fails with authentication errors.

Solutions:

1. Verify credentials work with docker:

   docker login myregistry.io
   docker pull myregistry.io/myimage:tag
   

2. Use environment variables for credentials:

   export KUBESCAPE_REGISTRY_USERNAME=myuser
   export KUBESCAPE_REGISTRY_PASSWORD=mypassword
   kubescape scan image myregistry.io/myimage:tag
   

Vulnerability database outdated

Symptom: Known CVEs are not being detected.

Solution:

The vulnerability database is updated automatically. To force an update:

# Clear the cache
rm -rf ~/.kubescape/grype-db

# Run a new scan
kubescape scan image nginx:latest

---

Image Patching Issues

BuildKit not running

Symptom: kubescape patch fails with BuildKit connection errors.

Solutions:

1. Start BuildKit:

   sudo buildkitd &
   

2. Or run BuildKit in Docker:

   docker run --detach --rm --privileged \
     -p 127.0.0.1:8888:8888/tcp \
     --name buildkitd \
     --entrypoint buildkitd \
     moby/buildkit:latest \
     --addr tcp://0.0.0.0:8888
   
   kubescape patch -i nginx:1.22 -a tcp://0.0.0.0:8888
   

3. Check BuildKit socket:

   ls -la /run/buildkit/buildkitd.sock
   

Patching fails with no fixes available

Symptom: Patch command reports no patches available.

Explanation: Image patching only fixes OS-level vulnerabilities that have available patches. Application-level vulnerabilities or vulnerabilities without fixes cannot be patched.

Solution:

1. Check the vulnerability report:

   kubescape scan image myimage:tag -v
   

2. Look for vulnerabilities marked as "wont-fix" or without fix versions.

3. Consider updating the base image to a newer version.

Permission denied during patching

Symptom: Patch fails with permission errors.

Solution:

Run with sudo when using the default Unix socket:

sudo kubescape patch --image nginx:1.22

Or use the Docker-based BuildKit approach which doesn't require sudo.

---

Operator Issues

Operator not responding to CLI commands

Symptom: kubescape operator scan hangs or fails.

Solutions:

1. Verify the operator is installed:

   kubectl -n kubescape get pods
   

2. Check operator logs:

   kubectl -n kubescape logs -l app=kubescape-operator
   

3. Verify the operator service:

   kubectl -n kubescape get svc
   

No vulnerability manifests in cluster

Symptom: No VulnerabilityManifest CRs found.

Solutions:

1. Check if vulnerability scanning is enabled:

   kubectl -n kubescape get configmap kubescape-config -o yaml
   

2. Verify kubevuln is running:

   kubectl -n kubescape get pods -l app=kubevuln
   

3. Check kubevuln logs:

   kubectl -n kubescape logs -l app=kubevuln
   

---

MCP Server Issues

MCP server fails to start

Symptom: kubescape mcpserver exits with errors.

Solutions:

1. Verify kubectl connectivity:

   kubectl get nodes
   

2. Check if the operator CRDs are installed:

   kubectl get crd vulnerabilitymanifests.spdx.softwarecomposition.kubescape.io
   kubectl get crd workloadconfigurationscans.spdx.softwarecomposition.kubescape.io
   

3. Install the Kubescape operator if not present:

   helm repo add kubescape https://kubescape.github.io/helm-charts/
   helm upgrade --install kubescape kubescape/kubescape-operator \
     --namespace kubescape --create-namespace
   

AI assistant cannot connect to MCP server

Symptom: AI tool reports connection failures.

Solutions:

1. Verify the MCP server is running:

   kubescape mcpserver
   

2. Check your AI tool's MCP configuration:

   {
     "mcpServers": {
       "kubescape": {
         "command": "kubescape",
         "args": ["mcpserver"]
       }
     }
   }
   

3. Ensure kubescape is in your PATH.

---

Output and Reporting Issues

JSON output is malformed

Symptom: JSON output cannot be parsed.

Solution:

Ensure you're redirecting to a file, not mixing with console output:

kubescape scan --format json --output results.json

SARIF format fails

Symptom: SARIF output not working.

Note: SARIF format is only supported for file/repository scans, not live cluster scans.

Solution:

# This works
kubescape scan /path/to/manifests --format sarif --output results.sarif

# This does NOT work
kubescape scan --format sarif --output results.sarif  # cluster scan

HTML/PDF report generation fails

Symptom: Report generation fails or produces empty files.

Solutions:

1. Ensure you have write permissions to the output directory.

2. Check available disk space.

3. Try JSON first to verify scan works:

   kubescape scan --format json --output test.json
   

---

Performance Issues

High memory usage during scan

Solutions:

1. Scan fewer namespaces:

   kubescape scan --include-namespaces production
   

2. Scan one framework at a time:

   kubescape scan framework nsa
   

3. Use the operator for large clusters instead of CLI scanning.

Slow vulnerability database downloads

Solutions:

1. Use offline mode with pre-downloaded artifacts:

   # On a machine with good connectivity
   kubescape download artifacts --output /path/to/artifacts
   
   # On the target machine
   kubescape scan --use-artifacts-from /path/to/artifacts
   

2. Configure a proxy if needed:

   export HTTPS_PROXY=http://proxy:8080
   kubescape scan
   

---

Getting Help

If you're still experiencing issues:

1. Check the logs with debug logging:

   kubescape scan -l debug
   

2. Search existing issues: https://github.com/kubescape/kubescape/issues

3. Join the community Slack:

   • Users Channel
   • Developers Channel

4. Open a new issue with:

   • Kubescape version (kubescape version)
   • Kubernetes version (kubectl version)
   • Full error message
   • Steps to reproduce
   • Debug logs (kubescape scan -l debug 2>&1 | tee debug.log)