tools/error-libraries/huggingface-error-detection/README.md

Hugging Face Error Detection

Purpose: ML-powered vulnerability scanning and error pattern recognition Status: 🟡 Working (performance tuning recommended) Version: 1.0.0+ Maintainer: Security Team (Block 6)

What It Does

Hugging Face error detection uses ML models to:

• Identify security vulnerabilities (SQL injection, XSS, etc.)
• Find API misuse patterns
• Detect performance anti-patterns
• Recognize code smell and potential bugs
• Analyze error propagation paths

Installation

# Already configured in project
# To verify:
python -c "from transformers import pipeline; print('HF installed')"

# To update:
pip install --upgrade transformers torch

# Verify models are cached
ls ~/.cache/huggingface/hub/

Performance Workaround

Problem

Scanning large codebases (>100K lines) takes too long or times out

Solution

Scan by module, not entire project:

# DON'T do this (will timeout)
python tools/error-libraries/huggingface-error-detection/detector.py src/

# DO this instead - scan module by module
cd C:/Users/claus/Projects/WidgetTDC
python tools/error-libraries/huggingface-error-detection/detector.py src/agents/
python tools/error-libraries/huggingface-error-detection/detector.py src/services/
python tools/error-libraries/huggingface-error-detection/detector.py src/routers/

# Or use parallel processing
parallel -j 3 "timeout 30 python detector.py {}" ::: src/*/

Quick Start

1. Scan Single Module

# Scan one service
cd C:/Users/claus/Projects/WidgetTDC
python tools/error-libraries/huggingface-error-detection/detector.py src/services/email_service.py

# Expected output:
# [CRITICAL] SQL injection vulnerability in query: "SELECT * FROM users WHERE id=" + user_input
# [HIGH] Missing error handler for network timeout
# [MEDIUM] Unvalidated user input in API response

2. Scan Entire Directory (with timeout)

# With enforced 30-second timeout
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/agents/

# Multiple directories in sequence
for dir in src/agents src/services src/routers; do
    echo "Scanning $dir..."
    timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py "$dir"
done

3. Generate Report

# Scan and save results
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/ > hf-scan-report.txt 2>&1

# Review report
cat hf-scan-report.txt

# Count vulnerabilities by severity
grep "\[CRITICAL\]" hf-scan-report.txt | wc -l
grep "\[HIGH\]" hf-scan-report.txt | wc -l
grep "\[MEDIUM\]" hf-scan-report.txt | wc -l

Severity Levels

🔴 CRITICAL

• SQL injection vulnerabilities
• Authentication bypass
• Credential exposure
• Remote code execution risks
• Data exfiltration paths

Action: Fix immediately before any deployment

🟠 HIGH

• Missing input validation
• Improper error handling
• Weak cryptography usage
• Privilege escalation paths
• Performance DoS patterns

Action: Fix within current sprint

🟡 MEDIUM

• Code smell and anti-patterns
• Potential logic errors
• Non-optimal algorithms
• Deprecated API usage
• Type safety issues

Action: Schedule for next sprint

🟢 LOW

• Style improvements
• Documentation suggestions
• Refactoring recommendations
• Performance micro-optimizations
• Best practice violations

Action: Consider for future improvement

Usage Patterns

Pattern 1: Security-Focused Scan

# Scan for security issues only
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --security-only \
    src/

# Output will only show CRITICAL and HIGH severity

Pattern 2: Performance Analysis

# Scan for performance anti-patterns
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --performance-check \
    src/services/

# Identifies O(n²) algorithms, memory leaks, etc.

Pattern 3: API Misuse Detection

# Scan for common API misuse patterns
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --api-validation \
    src/integrations/

# Finds incorrect library usage, wrong parameters, etc.

Pattern 4: Compare Before/After

# Baseline scan
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/ > baseline.txt

# Make changes...
# ... edit code ...

# Rescan
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/ > after.txt

# Compare
diff baseline.txt after.txt

Configuration

File: config/error-detection/huggingface-params.json

{
  "timeout_seconds": 30,
  "severity_threshold": "MEDIUM",
  "models": [
    "microsoft/codebert-base",
    "huggingface/CodeBERTa-small-v1"
  ],
  "parallel_workers": 3,
  "cache_results": true,
  "exclude_patterns": [
    "node_modules/",
    "dist/",
    "*.test.py"
  ]
}

Custom Configuration

# Use custom params file
python tools/error-libraries/huggingface-error-detection/detector.py \
    --config custom-hf-params.json \
    src/

Common Issues and Solutions

Issue: "CUDA out of memory"

Cause: GPU memory exhausted by ML model Solution:

# Run on CPU instead
CUDA_VISIBLE_DEVICES="" python detector.py src/

# Or limit batch size
python detector.py --batch-size 16 src/

Issue: "Timeout after 30 seconds"

Cause: Large directory or slow model Solution:

# Scan smaller subsets
timeout 30 python detector.py src/agents/ > agents.txt
timeout 30 python detector.py src/services/ > services.txt

# Or increase timeout
timeout 60 python detector.py src/

Issue: "Model download failed"

Cause: First run needs to download model (slow) Solution:

# Pre-download model
python -c "from transformers import AutoModel; AutoModel.from_pretrained('microsoft/codebert-base')"

# Then run detector (cached)
python detector.py src/

Issue: "High false-positive rate"

Cause: ML model marking legitimate code as vulnerable Solution:

# Review reported vulnerabilities manually
# Update config to set higher threshold
python detector.py --severity-threshold HIGH src/

# Or exclude specific patterns
python detector.py --exclude-pattern "test_*" src/

Example Scenarios

Scenario 1: Widget Discovery Security Review

Block: 5 (QASpecialist) Task: Verify widget discovery from Git/Hugging Face is secure

# Scan widget discovery service
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --security-only \
    src/services/widget_discovery.py

# Expected findings:
# - Input validation for URLs
# - Git URL injection protection
# - Model download safety
# - Sandboxing of untrusted code

Scenario 2: MCP Communication Validation

Block: 2 (CloudArch) Task: Find vulnerabilities in MCP widget trigger mechanism

# Scan MCP integration code
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --security-only \
    src/integrations/mcp_framework.py

# Expected findings:
# - Message injection protection
# - Parameter validation
# - Cross-widget access control
# - State synchronization safety

Scenario 3: Widget Registry Data Safety

Block: 4 (DatabaseMaster) Task: Verify widget registry prevents data corruption

# Scan database operations
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py \
    --api-validation \
    src/models/widget_registry.py

# Expected findings:
# - SQL injection prevention
# - Transaction integrity
# - Concurrent access safety
# - Backup mechanism validation

Integration with Cascade

Hugging Face detector runs:

• On code changes for security-critical paths
• Results logged to: .claude/logs/security-scan.log
• CRITICAL findings block deployment
• HIGH findings trigger review
• Results included in daily standup

Performance Optimization Tips

Tip 1: Use Caching

# Results are cached by default
# Second run on same code is instant

# Clear cache if needed
rm -rf .cache/huggingface-detector/

Tip 2: Parallel Scanning

# Install GNU Parallel
pip install parallel

# Scan 3 directories in parallel
parallel -j 3 "timeout 30 python detector.py {}" ::: src/agents src/services src/routers

Tip 3: Incremental Scanning

# Only scan files changed since last commit
git diff --name-only | xargs -I {} timeout 30 python detector.py {}

# Or use git hooks for automatic scanning
# (setup in pre-commit hooks)

Success Metrics

Good HF detection results:

• ✅ All CRITICAL issues identified
• ✅ Security vulnerabilities clearly reported
• ✅ Actionable fix recommendations
• ✅ Reasonable false-positive rate (<20%)
• ✅ Scans complete within 30 seconds

Poor results (need investigation):

• ❌ Scan timeout every run
• ❌ Memory errors or crashes
• ❌ High false-positive rate (>50%)
• ❌ Missing obvious vulnerabilities
• ❌ Cannot download models

Troubleshooting Checklist

• Have 30+ second timeout available?
• Scanning module, not entire project?
• Models cached? (first run is slow)
• Have GPU memory available? (or use CPU)
• Internet connection for first model download?
• Sufficient disk space for model cache?

Next Steps

1. Start small: Scan one Python file first
2. Review findings: Read security warnings carefully
3. Fix issues: Address CRITICAL findings first
4. Rescan: Confirm fixes worked
5. Automate: Add to CI/CD pipeline

Questions?

Escalation path:

1. Check this README
2. Try lower severity threshold to exclude false positives
3. File issue in daily standup with:
   • Command you ran
   • Error message (if any)
   • Your block number
   • Timeout issues or false positives encountered

---

Ready to use?

cd C:/Users/claus/Projects/WidgetTDC

# Start with one file
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/services/email_service.py

# Then expand to module
timeout 30 python tools/error-libraries/huggingface-error-detection/detector.py src/services/

# Review findings and fix

Security scanning enabled. 🔒