1097 Troubleshooting 7a62855a

Troubleshooting Guide - Security Pro Pack

Common issues and solutions for Security Pro Pack plugins

Installation Issues

Issue: "Plugin not found" after installation

Symptoms:

$ /security-scan-quick
Error: Command not found: security-scan-quick

Cause: Plugin not properly installed or Claude Code hasn't reloaded plugins

Solution:

# Step 1: Verify plugin directory exists
ls -la $HOME/.claude/plugins/security-pro-pack

# Step 2: If missing, reinstall
claude plugin install ./security-pro-pack

# Step 3: Reload Claude Code
claude plugin reload

# Step 4: Verify installation
claude plugin list | grep security-pro-pack

Issue: Permission denied errors

Symptoms:

$ /docker-security-scan
Error: Permission denied: /home/user/.claude/plugins/security-pro-pack

Cause: Incorrect file permissions on plugin directory

Solution:

# Fix permissions
chmod -R 755 $HOME/.claude/plugins/security-pro-pack

# Fix ownership
chown -R $USER:$USER $HOME/.claude/plugins/security-pro-pack

# Reload plugins
claude plugin reload

Issue: Validation errors during install

Symptoms:

Error: Invalid plugin structure
Missing required file: .claude-plugin/plugin.json

Cause: Corrupted or incomplete plugin package

Solution:

# Step 1: Verify package integrity
sha256sum security-pro-pack.zip
# Compare with SHA256 in release notes

# Step 2: If mismatch, re-download
rm security-pro-pack.zip
curl -L [download URL] -o security-pro-pack.zip

# Step 3: Extract and reinstall
unzip security-pro-pack.zip
claude plugin install ./security-pro-pack

Command Plugin Issues

Issue: /ss command produces no output

Symptoms:

$ /ss
# Command runs but no report generated

Cause 1: No files to scan in current directory

Solution:

# Verify you're in project directory
pwd

# Check for files
ls -la

# Explicitly specify directory
/ss /path/to/project

Cause 2: All issues filtered out (e.g., .gitignore excludes everything)

Solution:

# Run with verbose flag
/ss --verbose

# Check what's being scanned
/ss --dry-run

Issue: /dss fails with "Docker daemon not running"

Symptoms:

$ /dss nginx:latest
Error: Cannot connect to Docker daemon

Cause: Docker not running or permissions issue

Solution:

macOS:

# Start Docker Desktop
open -a Docker

# Wait for Docker to start (30 seconds)
docker ps

Linux:

# Start Docker service
sudo systemctl start docker

# Verify it's running
sudo systemctl status docker

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

# Test without sudo
docker ps

Issue: /asa returns "Connection refused"

Symptoms:

$ /asa https://api.example.com
Error: Connection refused

Cause: API not accessible or network issue

Solution:

# Step 1: Verify API is accessible
curl https://api.example.com/health
# Should return 200 OK

# Step 2: Check network connectivity
ping api.example.com

# Step 3: Verify firewall not blocking
# If behind corporate firewall, use --proxy flag
/asa https://api.example.com --proxy http://proxy.corp.com:8080

# Step 4: For local development
/asa http://localhost:3000  # Use http://, not https://

Agent Plugin Issues

Issue: Security Auditor Expert not activating

Symptoms:

"Can you perform a security audit?"

Claude responds without using Security Auditor Expert agent

Cause: Activation triggers not recognized

Solution:

# Use explicit trigger words
> "Please use the Security Auditor Expert to perform an OWASP Top 10 audit"

# Or mention specific capabilities
> "Review this code for SQL injection and XSS vulnerabilities using the security expert"

# Or ask directly
> "Can you activate the Security Auditor Expert agent?"

Issue: Compliance Checker provides generic advice

Symptoms: Agent gives general security advice instead of specific HIPAA/PCI DSS/GDPR guidance

Cause: Unclear which framework to assess against

Solution:

# Be specific about framework
> "Use Compliance Checker to review this application for HIPAA compliance"

# Mention specific controls
> "Check this authentication system against PCI DSS Requirement 8"

# Provide context
> "We're a healthcare app. Review our database encryption for HIPAA Technical Safeguards."

Issue: Crypto Expert recommends outdated algorithms

Symptoms: Agent suggests algorithms that are no longer recommended

Cause: This should NOT happen - if it does, report as bug

Solution:

# Verify plugin version
claude plugin info security-pro-pack
# Should be v1.0.0 or later

# Update to latest version
claude plugin update security-pro-pack

# Report the issue
# Include: What was recommended, what should have been recommended

Docker Security Scan Issues

Issue: "Image not found" error

Symptoms:

$ /dss myapp:latest
Error: Image not found: myapp:latest

Cause: Image doesn't exist locally or typo in image name

Solution:

# Step 1: List all images
docker images

# Step 2: Verify exact image name (case-sensitive)
docker images | grep myapp

# Step 3: If not found, pull it
docker pull myapp:latest

# Step 4: For local builds
docker build -t myapp:latest .

Issue: Scan reports "0 vulnerabilities" suspiciously

Symptoms: All scans show zero vulnerabilities (unlikely for real images)

Cause: Scanner not accessing vulnerability database

Solution:

# Update vulnerability database
docker pull aquasec/trivy:latest

# Re-run scan
/dss myapp:latest --force-update

# Verify scanner is working
/dss nginx:latest  # Known to have some CVEs

API Security Audit Issues

Issue: Rate limiting errors during audit

Symptoms:

$ /asa https://api.example.com
Error: 429 Too Many Requests

Cause: API has aggressive rate limiting

Solution:

# Use slower scan mode
/asa https://api.example.com --slow

# Scan specific endpoints only
/asa https://api.example.com --endpoints /users,/orders

# Add authentication (may have higher limits)
/asa https://api.example.com --auth "Bearer YOUR_TOKEN"

Issue: "SSL certificate verification failed"

Symptoms:

Error: SSL certificate verification failed

Cause: Self-signed certificate or invalid SSL

Solution:

# For development/staging with self-signed certs
/asa https://staging-api.example.com --insecure

# ️ WARNING: Never use --insecure for production audits!

# Better solution: Add certificate to system trust store
# macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain cert.pem

# Linux:
sudo cp cert.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

Compliance Documentation Issues

Issue: Generated docs missing organization details

Symptoms: Documentation says "[Company Name]" instead of your company

Cause: Organization name not specified

Solution:

# Specify organization during generation
/compliance-docs-generate --framework hipaa --org "HealthCare Inc"

# Or set environment variable
export COMPLIANCE_ORG_NAME="HealthCare Inc"
/cdg --framework hipaa

Issue: Documentation doesn't match our architecture

Symptoms: Generated policies reference "cloud provider" but we're on-premises

Cause: Templates are generic, need customization

Solution:

# Step 1: Generate base documentation
/cdg --framework hipaa

# Step 2: Customize generated files
# Files are in markdown, edit as needed:
vim compliance-docs/hipaa/Security-Management-Process-Policy.md

# Step 3: Save customized version
cp compliance-docs/hipaa/*.md /your-repo/compliance/

# Step 4: Track in version control
git add compliance/
git commit -m "Add customized HIPAA documentation"

Cryptography Audit Issues

Issue: False positives on test code

Symptoms:

 CRITICAL: MD5 hashing detected
File: tests/fixtures/test-data.js:12

Cause: Scanner can't distinguish test code from production

Solution:

Option 1: Add ignore comments

// tests/fixtures/test-data.js
// CRYPTO_AUDIT_IGNORE: Test fixture, not used in production
const TEST_HASH = md5("test-data")

Option 2: Exclude test directories

/ca src/crypto/ --exclude tests/,fixtures/

Option 3: Configure in .cryptoauditignore file

# .cryptoauditignore
tests/**/*
fixtures/**/*
*.test.js
*.spec.js

Issue: "No cryptographic code found"

Symptoms: Audit completes but reports 0 findings (you know you have crypto)

Cause: Scanner looking in wrong directory or file types not recognized

Solution:

# Specify exact files
/ca src/crypto/encryption.js src/auth/password.js

# Include specific file extensions
/ca --include "*.js,*.ts,*.py"

# Verbose mode to see what's scanned
/ca --verbose

Threat Modeling Issues

Issue: Agent produces generic threats

Symptoms: Threat model lists obvious issues without system-specific analysis

Cause: Insufficient context provided about your system

Solution:

# Provide detailed context
> "I need a STRIDE threat model for our payment processing system.
>
> Architecture:
> - User browser → HTTPS → Nginx load balancer
> - Nginx → HTTP → Node.js API server (port 3000)
> - API → PostgreSQL database (port 5432)
> - API → Stripe API (external, HTTPS)
>
> Trust boundaries:
> 1. Internet to DMZ (Nginx)
> 2. DMZ to internal network (API server)
> 3. Internal to database
>
> Sensitive data:
> - Credit card tokens (encrypted)
> - User PII (name, email, address)
> - Payment history
>
> Please threat model this with STRIDE and prioritize by risk."

Performance Issues

Issue: Security scans taking too long

Symptoms:

$ /ss
# Runs for 10+ minutes on large codebase

Cause: Scanning too many files (including node_modules, vendor, etc.)

Solution:

# Exclude large directories
/ss --exclude node_modules/,vendor/,dist/,build/

# Scan specific directories only
/ss src/ --output src-security-scan.md

# Use .securityscanignore file
# .securityscanignore
node_modules/
vendor/
dist/
build/
*.min.js

Issue: Docker scans very slow

Symptoms: Each Docker image scan takes 5+ minutes

Cause: Downloading vulnerability database on each scan

Solution:

# Pre-download vulnerability DB (run once)
docker pull aquasec/trivy:latest

# Use local cache
/dss myapp:latest --cache

# Scan offline (use cached DB)
/dss myapp:latest --offline

Output/Reporting Issues

Issue: Reports not being saved

Symptoms:

$ /ss --output report.md
# Scan completes but report.md not created

Cause: Permission issue or invalid path

Solution:

# Check current directory permissions
ls -la

# Use absolute path
/ss --output /home/user/reports/security-scan.md

# Verify directory exists
mkdir -p reports/
/ss --output reports/security-scan.md

Issue: Report formatting broken

Symptoms: Markdown report doesn't render correctly in viewer

Cause: Special characters or encoding issue

Solution:

# Specify UTF-8 encoding
/ss --output report.md --encoding utf-8

# Convert to PDF (if markdown rendering issues persist)
pandoc report.md -o report.pdf

# Or view in different tool
cat report.md | less

Integration Issues

Issue: CI/CD pipeline fails with plugin

Symptoms:

# GitHub Actions
- name: Security Scan
  run: /ss
  # Error: claude command not found

Cause: Claude Code not installed in CI environment

Solution:

Option 1: Use standalone scripts

# Extract scanner logic to standalone script
# security-scan.sh (generated by plugin)
./scripts/security-scan.sh src/

Option 2: Install Claude Code in CI

- name: Install Claude Code
  run: |
    curl -L https://claude.com/download/cli -o claude
    chmod +x claude
    sudo mv claude /usr/local/bin/

- name: Install Security Pro Pack
  run: |
    claude plugin install security-pro-pack.zip

- name: Run Security Scan
  run: claude exec /ss

Environment-Specific Issues

Issue: Different results locally vs CI

Symptoms: Local scan finds 5 issues, CI finds 15 issues

Cause: Different file sets scanned (CI has no .gitignore exclusions)

Solution:

# Use consistent exclusions
# Create .securityscanignore (committed to git)
echo "node_modules/" >> .securityscanignore
echo "dist/" >> .securityscanignore

# CI respects .securityscanignore
/ss --respect-gitignore=false

Getting Help

Before Asking for Help

1. Check plugin version:

   claude plugin info security-pro-pack
   # Should be v1.0.0 or later
   

2. Run in verbose mode:

   /ss --verbose 2>&1 | tee debug.log
   

3. Check logs:

   tail -f ~/.claude/logs/plugins.log
   

How to Report Issues

Good Bug Report:

**Plugin:** security-scan-quick
**Version:** 1.0.0
**OS:** macOS 14.0 / Ubuntu 22.04 / Windows 11

**Issue:**
Running /ss produces "Permission denied" error

**Steps to Reproduce:**
1. cd ~/my-project
2. /ss
3. Error appears

**Expected Behavior:**
Security scan should run and produce report

**Actual Behavior:**
Error: Permission denied: /tmp/security-scan-12345

**Logs:**
[Attach verbose output]

**Additional Context:**
- Docker is running
- Has worked previously (last week)
- Changed: Upgraded to macOS 14.0

Support Channels

• Email: [email protected]
• GitHub Issues: https://github.com/jeremylongshore/claude-code-plugins/issues
• Discord: https://discord.gg/claude-code-plugins
• Documentation: https://docs.claude-code-plugins.com

Common Error Messages

"Command not found"

→ See "Installation Issues" section above

"Permission denied"

→ See "Permission denied errors" section above

"Connection refused"

→ See "/asa returns 'Connection refused'" section above

"Rate limit exceeded"

→ See "Rate limiting errors during audit" section above

"SSL certificate verification failed"

→ See "SSL certificate verification failed" section above

"Docker daemon not running"

→ See "/dss fails with Docker daemon" section above

"Image not found"

→ See "Docker Security Scan Issues" section above

Still stuck? Email [email protected] with:

1. Plugin version
2. Operating system
3. Error message (full text)
4. Steps to reproduce
5. Verbose output

We typically respond within 24 hours.