Skip to main content

Common Issues

Solutions to frequently encountered problems when using CXRay.

Installation Issues​

Issue: command not found: cxray​

Cause: CXRay binary is not in your system PATH.

Solution:

# Find where cxray was installed
which cxray

# If not found, add to PATH (Linux/macOS)
export PATH=$PATH:/path/to/cxray

# Add to shell profile for persistence
echo 'export PATH=$PATH:/path/to/cxray' >> ~/.bashrc
source ~/.bashrc

Issue: Permission Denied​

Cause: CXRay binary doesn't have execute permissions.

Solution:

chmod +x /path/to/cxray

Issue: Docker Installation Fails​

Cause: Docker daemon not running or insufficient permissions.

Solution:

# Check Docker status
sudo systemctl status docker

# Start Docker if not running
sudo systemctl start docker

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Scanning Issues​

Issue: Scan Fails with "No package manager detected"​

Cause: CXRay cannot identify the package manager in your project.

Solution:

Ensure your project has the appropriate manifest files:

  • Node.js: package.json
  • Python: requirements.txt, Pipfile, or pyproject.toml
  • Java: pom.xml or build.gradle
  • Ruby: Gemfile
  • Go: go.mod

Or specify the package manager explicitly:

cxray scan --package-manager npm .

Issue: "Database not found" Error​

Cause: Vulnerability database hasn't been downloaded.

Solution:

# Download/update database
cxray db update

# Verify database
cxray db info

Issue: Scan Takes Too Long​

Cause: Large project or slow network connection.

Solutions:

  1. Exclude unnecessary directories:
# .cxray.yml
scan:
  exclude:
    - node_modules/
    - vendor/
    - test/
    - docs/
  1. Use incremental scanning:
cxray scan --incremental .
  1. Scan specific paths only:
cxray scan --path src/ .

Issue: Too Many False Positives​

Cause: Overly sensitive default configuration.

Solutions:

  1. Adjust severity threshold:
cxray scan --severity high,critical .
  1. Ignore specific findings:
# .cxray.yml
ignore:
  cve:
    - CVE-2021-12345  # Reason: Not applicable to our use case
  cce:
    - CCE-001  # Reason: Exception approved by security team
  1. Use allowlists:
# .cxray.yml
allowlist:
  packages:
    - name: "old-package"
      version: "1.2.3"
      reason: "Required for legacy support, isolated environment"

Configuration Issues​

Issue: Configuration File Not Found​

Cause: CXRay looking in wrong location.

Solution:

# Specify config file location
cxray scan --config /path/to/.cxray.yml .

# Or set environment variable
export CXRAY_CONFIG=/path/to/.cxray.yml

Issue: Invalid YAML Configuration​

Cause: Syntax error in configuration file.

Solution:

# Validate configuration
cxray config validate

# Use YAML linter
yamllint .cxray.yml

API Issues​

Issue: 401 Unauthorized Error​

Cause: Invalid or missing API key.

Solution:

# Verify API key is set
echo $CXRAY_API_KEY

# Set API key
export CXRAY_API_KEY="your-api-key"

# Or specify in command
cxray scan --api-key "your-api-key" .

Issue: 429 Rate Limit Exceeded​

Cause: Too many API requests.

Solution:

  1. Check rate limit status:
cxray api limits
  1. Use local scanning instead of API:
cxray scan --mode local .
  1. Implement exponential backoff in scripts:
import time

for attempt in range(5):
    try:
        result = cxray_scan()
        break
    except RateLimitError:
        time.sleep(2 ** attempt)

Output and Reporting Issues​

Issue: Report Not Generated​

Cause: Output directory doesn't exist or insufficient permissions.

Solution:

# Create output directory
mkdir -p reports/

# Ensure write permissions
chmod 755 reports/

# Generate report
cxray report --output reports/cxray-report.html

Issue: Truncated or Incomplete Results​

Cause: Output buffer limitation.

Solution:

# Save to file instead of stdout
cxray scan . --output json > results.json

# Increase buffer size (if using programmatically)
cxray scan . --buffer-size 10MB

Integration Issues​

Issue: Jenkins Plugin Not Working​

Cause: Plugin configuration or permissions issue.

Solutions:

  1. Verify plugin installation:

    • Navigate to Jenkins → Manage Plugins → Installed
    • Ensure CXRay plugin is listed and enabled

  2. Check credentials:

    • Verify API key is correctly configured in Jenkins credentials
    • Ensure credential ID matches pipeline configuration

  3. Check console output:

cxrayScan(
    verbose: true,
    logLevel: 'debug'
)

Issue: GitHub Actions Failing​

Cause: Missing secrets or incorrect workflow configuration.

Solution:

  1. Add required secrets:

    • Go to repository Settings → Secrets
    • Add CXRAY_API_KEY

  2. Verify workflow syntax:

- name: CXRay Scan
  env:
    CXRAY_API_KEY: ${{ secrets.CXRAY_API_KEY }}
  run: cxray scan --fail-on critical .

Performance Issues​

Issue: High Memory Usage​

Cause: Large project or dependency tree.

Solutions:

  1. Increase memory limit:
cxray scan --memory-limit 4GB .
  1. Scan in batches:
# Scan by subdirectory
for dir in src/*; do
    cxray scan "$dir"
done
  1. Use lightweight scan mode:
cxray scan --mode fast .

Issue: Slow Database Updates​

Cause: Network connectivity or large database.

Solutions:

  1. Use CDN mirror:
# .cxray.yml
database:
  mirror: https://cdn.cxray.io/db
  1. Update during off-peak hours:
# Schedule update via cron
0 2 * * * cxray db update

Network Issues​

Issue: Cannot Connect to CXRay API​

Cause: Firewall, proxy, or network restriction.

Solutions:

  1. Configure proxy:
export HTTPS_PROXY=http://proxy.example.com:8080
cxray scan .

  1. Add firewall exceptions:

    • Allow outbound HTTPS to *.cxray.io
    • Ports: 443 (HTTPS)

  2. Use offline mode:

# Download database offline
cxray db download --offline

# Run scans offline
cxray scan --offline .

Getting Help​

If you're still experiencing issues:

  1. Check Logs:

    cxray logs --level debug

  2. Verify Version:

    cxray --version

  3. Check System Requirements:

    cxray doctor

  4. Contact Support:

Next Steps​