Guardian Engine - Troubleshooting Guide

Quick solutions to common issues

📑 Quick Links

Installation Issues
Security Errors
Performance Problems
File Analysis Issues
Output & Reporting
Audit Logging
Advanced Debugging

Installation Issues

❌ "No module named 'guardian'"

Symptoms:

ImportError: No module named 'guardian'

Solutions:

# Solution 1: Install in editable mode
cd Guardian-Cybersecurity-Engine
pip install -e .

# Solution 2: Add to PYTHONPATH
export PYTHONPATH="/path/to/Guardian-Cybersecurity-Engine:$PYTHONPATH"

# Solution 3: Install from PyPI (when available)
pip install guardian-cybersecurity-engine

Verify:

python3 -c "import guardian; print(guardian.__version__)"

❌ "Permission denied" during installation

Symptoms:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solutions:

# Solution 1: Use virtual environment (RECOMMENDED)
python3 -m venv guardian_env
source guardian_env/bin/activate
pip install -e .

# Solution 2: User install
pip install --user -e .

# Solution 3: Use sudo (not recommended)
sudo pip install -e .

❌ "rich" or "jinja2" not found

Symptoms:

WARNING: rich not available, using simple output
WARNING: HTML reports require jinja2

Solution:

# Install optional dependencies
pip install rich>=13.0.0 jinja2>=3.1.0

# Or install all dev dependencies
pip install -r requirements-dev.txt

Note: Guardian works without these, but with reduced features.

Security Errors

🛡️ Path Traversal Detected

Symptoms:

======================================================================
🛡️  GUARDIAN SECURITY ERROR
======================================================================

Security Error: Path traversal detected: ../../etc/passwd

Why this happens: Guardian blocks potentially dangerous paths to prevent security vulnerabilities.

Solutions:

# ✅ Use absolute paths
guardian analyze -f /full/path/to/file.txt

# ✅ Use paths relative to current directory
guardian analyze -f ./local/file.txt

# ❌ Don't use parent directory references
guardian analyze -f ../../file.txt  # BLOCKED

🛡️ File Size Limit Exceeded

Symptoms:

Security Error: File exceeds size limit: 15.2MB > 10.0MB

💡 Solution: Use --max-file-size flag to increase limit

Solutions:

# Increase size limit to 100MB
guardian decrypt -d /path --max-bytes 104857600

# Skip large files
guardian decrypt -d /path --skip-large-files

# Configure global limit
python3 << EOF
from guardian.security import SecurityValidator
SecurityValidator.configure_limits(max_file_size=100*1024*1024)
EOF

🛡️ Symbolic Links Not Allowed

Symptoms:

Security Error: Symbolic links not allowed

Solution:

# Allow symlinks explicitly (use with caution!)
guardian decrypt -d /path --allow-symlinks

# Or use real paths
realpath /path/with/symlinks | xargs guardian decrypt -d

Performance Problems

🐌 Analysis Too Slow

Symptoms:

Analysis taking hours for large datasets
Single-threaded processing

Solutions:

# Use parallel processing
guardian decrypt -d /path --workers 8

# Adjust worker count based on CPU cores
CORES=$(nproc)
guardian decrypt -d /path --workers $CORES

# Use checkpoint/resume for very large datasets
guardian decrypt -d /huge_dataset \
    --workers 16 \
    --checkpoint-interval 100

Performance Guide:

Files	Workers	Expected Time
100	1	~2.5s
100	4	~0.7s
10,000	8	~1.2m
100,000	32	~7.5m

🐌 Out of Memory (OOM)

Symptoms:

Killed
MemoryError: Unable to allocate memory

Solutions:

# Limit file size
guardian decrypt -d /path --max-bytes 10485760  # 10MB

# Reduce worker count
guardian decrypt -d /path --workers 2

# Use streaming mode (if available)
guardian decrypt -d /path --stream

# Process in batches
find /path -type f | head -1000 | xargs guardian decrypt --files

⚡ Checkpoint Not Resuming

Symptoms:

Analysis restarts from beginning after interruption
Checkpoint file exists but ignored

Solutions:

# Ensure resume is enabled
guardian decrypt -d /path --workers 8  # Auto-resumes by default

# Force resume
guardian decrypt -d /path --resume

# Check checkpoint location
ls -la ~/.guardian_checkpoints/

# Manual cleanup if corrupted
rm ~/.guardian_checkpoints/*

File Analysis Issues

❓ "No files found"

Symptoms:

❌ No files found

Solutions:

# Check directory exists
ls -la /path/to/encrypted

# Use recursive scan
guardian decrypt -d /path -r

# Check file permissions
find /path -type f ! -perm -444

# Verify not empty
find /path -type f | wc -l

❓ "Invalid file format"

Symptoms:

WARNING: Could not analyze file: invalid format

Solutions:

# Check file isn't corrupted
file /path/to/suspicious.enc

# Try with different max bytes
guardian decrypt -d /path --max-bytes 524288  # 512KB

# Skip problematic files
guardian decrypt -d /path --skip-errors

❓ Low Confidence File Identification

Symptoms:

File type identification confidence: 45% (LOW)

Why this happens:

File is heavily encrypted
Unknown/rare file type
Corrupted file

Interpretation:

Confidence	Meaning
>90%	Highly confident
70-90%	Likely correct
50-70%	Uncertain
<50%	Unreliable

Solution: Focus on high-confidence identifications (>70%) for recovery prioritization.

Output & Reporting

📄 HTML Report Not Generated

Symptoms:

⚠️  HTML reports require jinja2. Install with: pip install jinja2>=3.1.0

Solution:

# Install jinja2
pip install jinja2>=3.1.0

# Verify installation
python3 -c "import jinja2; print(jinja2.__version__)"

# Generate report
guardian decrypt -d /path --html report.html

📄 Ugly CLI Output (No Colors)

Symptoms:

Plain text output
No progress bars
No colors

Solution:

# Install rich
pip install rich>=13.0.0

# Verify
python3 -c "from rich import print; print('[bold green]Success![/bold green]')"

📄 JSON Output Malformed

Symptoms:

{
  "error": "Object of type datetime is not JSON serializable"
}

Solution:

Guardian handles this automatically. If you see this, you're likely using a custom script:

import json
from datetime import datetime

# ❌ Don't do this
json.dumps({"time": datetime.now()})

# ✅ Do this
json.dumps({"time": datetime.now()}, default=str)

Audit Logging

📝 Audit Log Not Created

Symptoms:

$ ls ~/.guardian/logs/
ls: cannot access '~/.guardian/logs/': No such file or directory

Why this happens: Audit logs are only created when operations are performed.

Solution:

# Run an operation
guardian decrypt -d /some/path

# Check again
ls -la ~/.guardian/logs/
# Should now see: guardian_audit.jsonl

📝 Audit Log Permission Denied

Symptoms:

ERROR: Failed to write audit log: Permission denied

Solutions:

# Fix permissions
sudo chown -R $USER:$USER ~/.guardian/

# Or specify different log location
export GUARDIAN_LOG_DIR=/tmp/guardian_logs
guardian decrypt -d /path

📝 Audit Log Too Large

Symptoms:

$ du -h ~/.guardian/logs/guardian_audit.jsonl
1.5G	/root/.guardian/logs/guardian_audit.jsonl

Solution:

# Archive old logs
cd ~/.guardian/logs/
gzip guardian_audit.jsonl
mv guardian_audit.jsonl.gz archive/audit_$(date +%Y%m%d).jsonl.gz

# Or rotate logs
logrotate /etc/logrotate.d/guardian  # Configure as needed

Advanced Debugging

🔍 Enable Verbose Logging

# CLI verbose mode
guardian decrypt -d /path --verbose

# Debug level
guardian decrypt -d /path --log-level DEBUG

# Python logging
python3 << EOF
import logging
logging.basicConfig(level=logging.DEBUG)

from guardian import GuardianEngine
engine = GuardianEngine()
# ... operations ...
EOF

🔍 Inspect Internal State

from guardian.ransomware.semantic_decryptor import SemanticDecryptionEngine
from guardian.security import SecurityValidator

# Check security limits
print(f"Max file size: {SecurityValidator.MAX_FILE_SIZE / 1024 / 1024}MB")
print(f"Max files: {SecurityValidator.MAX_FILES_PER_BATCH}")

# Check engine state
engine = SemanticDecryptionEngine()
print(f"Signature database size: {len(engine.signature_db.signatures)}")

🔍 Test Individual Components

# Test security validation
from guardian.security import validate_file_path
try:
    path = validate_file_path("../../etc/passwd")
except Exception as e:
    print(f"Expected error: {e}")

# Test audit logging
from guardian.core.audit import get_audit_logger
logger = get_audit_logger()
logger.log_security_event("test", "Testing audit", severity="info")
print(f"Log file: {logger.log_file}")

Common Error Codes

Exit Code	Meaning	Action
0	Success	None needed
1	General error	Check error message
2	Security violation	Review path/permissions
130	User cancelled (Ctrl+C)	None needed

Getting More Help

📊 Generate Diagnostic Report

#!/bin/bash
# diagnostic_report.sh

echo "=== Guardian Diagnostic Report ===" > guardian_diag.txt
echo "" >> guardian_diag.txt

echo "Version:" >> guardian_diag.txt
python3 -c "import guardian; print(guardian.__version__)" 2>&1 >> guardian_diag.txt

echo -e "\nPython Version:" >> guardian_diag.txt
python3 --version >> guardian_diag.txt

echo -e "\nInstalled Packages:" >> guardian_diag.txt
pip list | grep -E "(guardian|rich|jinja2|pytest)" >> guardian_diag.txt

echo -e "\nSecurity Limits:" >> guardian_diag.txt
python3 -c "from guardian.security import SecurityValidator; \
    print(f'Max file size: {SecurityValidator.MAX_FILE_SIZE}'); \
    print(f'Max path length: {SecurityValidator.MAX_PATH_LENGTH}')" >> guardian_diag.txt

echo -e "\nAudit Log Location:" >> guardian_diag.txt
python3 -c "from guardian.core.audit import get_audit_logger; \
    print(get_audit_logger().log_file)" >> guardian_diag.txt

echo -e "\nRecent Errors:" >> guardian_diag.txt
grep -i error ~/.guardian/logs/guardian_audit.jsonl 2>/dev/null | tail -5 >> guardian_diag.txt

echo ""
echo "Diagnostic report saved to: guardian_diag.txt"

Run and attach to bug reports!

💬 Where to Get Help

Check Documentation
Search Issues
- GitHub: https://github.com/BruinGrowly/Guardian-Cybersecurity-Engine/issues
Ask Community
- GitHub Discussions
- Stack Overflow (tag: guardian-engine)
Report Bugs
- GitHub Issues (include diagnostic report!)

Known Issues

Issue #1: Slow First Analysis

Status: Known behavior Cause: Engine initialization loads signature database Workaround: Subsequent analyses are fast (database cached)

Issue #2: Windows Path Support

Status: Limited Cause: Windows paths with backslashes Workaround: Use forward slashes: C:/Users/... instead of C:\Users\...

Still stuck? Open an issue with your diagnostic report! 🐛

Guardian Engine v3.0 - Production Ready 🛡️

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guardian Engine - Troubleshooting Guide

📑 Quick Links

Installation Issues

❌ "No module named 'guardian'"

❌ "Permission denied" during installation

❌ "rich" or "jinja2" not found

Security Errors

🛡️ Path Traversal Detected

🛡️ File Size Limit Exceeded

🛡️ Symbolic Links Not Allowed

Performance Problems

🐌 Analysis Too Slow

🐌 Out of Memory (OOM)

⚡ Checkpoint Not Resuming

File Analysis Issues

❓ "No files found"

❓ "Invalid file format"

❓ Low Confidence File Identification

Output & Reporting

📄 HTML Report Not Generated

📄 Ugly CLI Output (No Colors)

📄 JSON Output Malformed

Audit Logging

📝 Audit Log Not Created

📝 Audit Log Permission Denied

📝 Audit Log Too Large

Advanced Debugging

🔍 Enable Verbose Logging

🔍 Inspect Internal State

🔍 Test Individual Components

Common Error Codes

Getting More Help

📊 Generate Diagnostic Report

💬 Where to Get Help

Known Issues

Issue #1: Slow First Analysis

Issue #2: Windows Path Support

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Guardian Engine - Troubleshooting Guide

📑 Quick Links

Installation Issues

❌ "No module named 'guardian'"

❌ "Permission denied" during installation

❌ "rich" or "jinja2" not found

Security Errors

🛡️ Path Traversal Detected

🛡️ File Size Limit Exceeded

🛡️ Symbolic Links Not Allowed

Performance Problems

🐌 Analysis Too Slow

🐌 Out of Memory (OOM)

⚡ Checkpoint Not Resuming

File Analysis Issues

❓ "No files found"

❓ "Invalid file format"

❓ Low Confidence File Identification

Output & Reporting

📄 HTML Report Not Generated

📄 Ugly CLI Output (No Colors)

📄 JSON Output Malformed

Audit Logging

📝 Audit Log Not Created

📝 Audit Log Permission Denied

📝 Audit Log Too Large

Advanced Debugging

🔍 Enable Verbose Logging

🔍 Inspect Internal State

🔍 Test Individual Components

Common Error Codes

Getting More Help

📊 Generate Diagnostic Report

💬 Where to Get Help

Known Issues

Issue #1: Slow First Analysis

Issue #2: Windows Path Support