Troubleshooting

This guide covers common issues encountered when using AegisShield and provides practical solutions.

API Key Issues

OpenAI API Key Errors

Error: OpenAI API key is required

Symptom: Application fails to start or generate threat modelsCause: Missing or incorrectly configured OpenAI API keySolution:

# Verify local_config.py exists and contains key
cat local_config.py

# Should contain:
# default_openai_api_key="sk-proj-..."

# If missing, create it:
echo 'default_openai_api_key="YOUR_KEY_HERE"' >> local_config.py

Verify key format:

Should start with sk-proj- or sk-
No extra spaces or quotes
Approximately 50-60 characters long

Error: Incorrect API key provided

Symptom: Authentication error from OpenAI APICauses:

Key was copied incorrectly (extra spaces, truncated)
Key was revoked or expired
Key doesn’t have GPT-4o access

Solutions:

# Test your OpenAI key
import openai
import local_config as conf

openai.api_key = conf.default_openai_api_key

try:
    response = openai.models.list()
    print("✓ OpenAI API key is valid")
    models = [m.id for m in response.data if 'gpt-4' in m.id]
    print(f"Available GPT-4 models: {models}")
except Exception as e:
    print(f"✗ Error: {e}")

Fix:

Go to platform.openai.com/api-keys
Create a new API key
Update local_config.py with new key
Verify account has GPT-4o access (check usage limits)

Error: Rate limit exceeded

Symptom: “Rate limit reached for requests” or “429 Too Many Requests”Cause: Too many API calls in short time periodSolutions:For interactive use:

Wait 60 seconds before retrying
Reduce complexity of prompts

For batch processing:

# In main-batch.py, reduce parallel workers
workers = 1  # Instead of 3
retries = 10  # Increase retry attempts

Upgrade OpenAI tier:

Tier 1 (Free): 500 RPM
Tier 2: 5,000 RPM
Tier 3+: Higher limits

Check your tier at platform.openai.com/settings/organization/limits

Error: Model 'gpt-4o' not found

Symptom: “The model gpt-4o does not exist”Cause: Account doesn’t have GPT-4o accessSolution:

Verify GPT-4 access in OpenAI account
Add payment method (GPT-4o requires paid account)
Check platform.openai.com/account/billing

Temporary workaround (lower quality):

# In main.py or main-batch.py
selected_model = "gpt-4-turbo"  # or "gpt-4"

NVD API Issues

Slow vulnerability searches

Symptom: Technology selection taking 30+ secondsCause: Using NVD without API key (5 requests/30s limit)Solution:

# Obtain NVD API key (free, 50 requests/30s)
# Visit: https://nvd.nist.gov/developers/request-an-api-key

# Add to local_config.py
echo 'default_nvd_api_key="YOUR_NVD_KEY"' >> local_config.py

Verify:

curl "https://services.nvd.nist.gov/rest/json/cves/2.0?resultsPerPage=1" \
  -H "apiKey: YOUR_NVD_KEY"

Error: No vulnerabilities found

Symptom: NVD returns empty results for valid technologiesCauses:

Technology not in NVD database
Incorrect CPE name format
NVD API temporarily down

Debug:

# Test NVD search manually
import nvdlib
import local_config as conf

# Search for PostgreSQL vulnerabilities
cves = nvdlib.searchCVE(
    cpeName='cpe:2.3:a:postgresql:postgresql:14.0',
    key=conf.default_nvd_api_key,
    limit=5
)

for cve in cves:
    print(f"{cve.id}: {cve.descriptions[0].value[:100]}")

Solutions:

Verify CPE name format is correct
Try broader search (e.g., remove version)
Check NVD status: nvd.nist.gov

AlienVault OTX Issues

Error: Invalid AlienVault API key

Symptom: “401 Unauthorized” or “Invalid API key”Solution:

Log in to otx.alienvault.com
Go to Settings → API Integration
Copy the OTX Key (not username)
Update local_config.py:

default_alienvault_api_key="YOUR_OTX_KEY_HERE"

No OTX data returned

Symptom: Empty or minimal threat intelligence resultsCause: Limited OTX pulses for selected industry/keywordsExpected behavior: OTX data is supplementary; empty results don’t prevent threat model generationVerify connectivity:

curl -X GET "https://otx.alienvault.com/api/v1/pulses/subscribed" \
  -H "X-OTX-API-KEY: YOUR_KEY"

Missing MITRE ATT&CK Data

Error: No MITRE ATT&CK data found

Symptom: Missing MITRE technique mappings in threat modelsCause: MITRE_ATTACK_DATA directory missing or incompleteSolution:

# Check if directory exists
ls -la MITRE_ATTACK_DATA/

# Should contain:
# - enterprise-attack.json
# - mobile-attack.json
# - ics-attack.json

# If missing, download:
mkdir -p MITRE_ATTACK_DATA

curl -o MITRE_ATTACK_DATA/enterprise-attack.json \
  https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json

curl -o MITRE_ATTACK_DATA/mobile-attack.json \
  https://raw.githubusercontent.com/mitre/cti/master/mobile-attack/mobile-attack.json

curl -o MITRE_ATTACK_DATA/ics-attack.json \
  https://raw.githubusercontent.com/mitre/cti/master/ics-attack/ics-attack.json

Error: Failed to parse STIX data

Symptom: JSON parsing errors when loading MITRE dataCause: Corrupted or incomplete JSON filesSolution:

# Validate JSON files
python -m json.tool MITRE_ATTACK_DATA/enterprise-attack.json > /dev/null

# If error, re-download:
rm MITRE_ATTACK_DATA/*.json
# Then re-run download commands from above

Application Startup Issues

Port 8501 already in use

Symptom: “Address already in use” or “Port 8501 is already allocated”Solutions:Option 1: Use different port

streamlit run main.py --server.port 8502

Option 2: Kill existing process

# Find process using port 8501
lsof -ti:8501

# Kill the process
kill $(lsof -ti:8501)

# Or force kill
kill -9 $(lsof -ti:8501)

Option 3: Stop Docker container

docker ps | grep 8501
docker stop <container-id>

ModuleNotFoundError

Symptom: “No module named ‘streamlit’” or other import errorsCause: Missing dependenciesSolution:

# Verify Python version (requires 3.9+, recommended 3.12)
python --version

# Install dependencies
pip install -r requirements.txt

# If still failing, create fresh virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

pip install -r requirements.txt

Streamlit not rendering correctly

Symptom: Blank page, JavaScript errors, or broken UISolutions:Clear Streamlit cache:

rm -rf ~/.streamlit/cache
streamlit cache clear

Update Streamlit:

pip install --upgrade streamlit

Try different browser:

Chrome/Edge (recommended)
Firefox
Safari

Disable browser extensions:

Ad blockers may interfere
Privacy extensions may block WebSocket

Memory and Performance Issues

Out of memory during batch processing

Symptom: Python crashes with “MemoryError” or “Killed”Cause: Processing too many threat models concurrentlySolutions:Reduce parallel workers:

# In main-batch.py
workers = 1  # Sequential processing

Process case studies individually:

# In main-batch.py
SPECIFIC_CASE_STUDY = 1  # Process one at a time

Increase system memory:

# Check available memory
free -h  # Linux
# or
vm_stat  # macOS

For Docker:

docker run --memory="4g" -p 8501:8501 aegisshield:latest

Slow threat model generation

Symptom: Taking 5+ minutes per threat modelCauses:

OpenAI API latency
NVD API rate limiting
Large application descriptions
Network connectivity issues

Solutions:Optimize API usage:

# Get NVD API key (10x faster)
# Reduce description length (<4000 chars recommended)
# Use workers=3 in batch mode for parallel processing

Check network latency:

ping api.openai.com
curl -w "@-" -o /dev/null -s https://api.openai.com <<'EOF'
time_namelookup:  %{time_namelookup}\n
time_connect:  %{time_connect}\n
time_total:  %{time_total}\n
EOF

PDF Generation Issues

Error: PDF generation failed

Symptom: “Failed to generate PDF” or xhtml2pdf errorsCauses:

Missing Cairo/Pango libraries (Linux)
Large threat models timing out
Invalid HTML/CSS in report template

Solutions:Install system dependencies (Linux):

sudo apt-get update
sudo apt-get install -y \
  libcairo2-dev \
  libpango1.0-dev \
  libpangocairo-1.0-0 \
  libgdk-pixbuf2.0-dev

# Reinstall Python packages
pip install --force-reinstall xhtml2pdf

macOS:

brew install cairo pango gdk-pixbuf

Windows: Use Docker (system dependencies difficult to install)

PDF missing images or formatting

Symptom: PDF generated but missing logo or broken layoutCause: Missing static assets or CSS issuesSolution:

# Verify aegisshield.png exists
ls -la aegisshield.png

# Check file permissions
chmod 644 aegisshield.png

Docker Issues

Container fails to start

Symptom: Container exits immediately after startingDebug:

# Check container logs
docker logs aegisshield

# Run interactively to see errors
docker run -it --rm -p 8501:8501 aegisshield:latest

Common causes:

Missing API keys (set via -e flags)
Port conflict (use different port)
Insufficient memory (increase with --memory)

Health check failing

Symptom: Docker marks container as “unhealthy”Check health status:

docker inspect --format='{{json .State.Health}}' aegisshield | jq

Solutions:

Increase start_period (Streamlit needs ~30-40s to start)
Verify curl is installed in container
Check Streamlit is actually listening:

docker exec aegisshield curl http://localhost:8501/_stcore/health

Cannot access from host browser

Symptom: localhost:8501 not loadingSolutions:Verify port mapping:

docker ps
# Should show: 0.0.0.0:8501->8501/tcp

Check firewall:

# Linux
sudo ufw allow 8501

# macOS
# System Preferences → Security & Privacy → Firewall

Verify container network:

docker exec aegisshield curl http://localhost:8501/_stcore/health

If this works but browser doesn’t, issue is host networking.

Batch Processing Issues

Invalid threat model validation errors

Symptom: “Invalid threat model. Regenerating…” repeated multiple timesCause: Generated models not meeting STRIDE criteria (3 threats per category)Solutions:Check prompt clarity:

# Verify batch input has sufficient detail
cat batch_inputs/Case-Study-X-schema.json | jq .app_input

Increase retries:

# In main-batch.py
retries = 10  # Up from 6

Check OpenAI model:

# Ensure using GPT-4o (not GPT-3.5)
selected_model = "gpt-4o"

Batch processing times out

Symptom: Some batches never complete or timeout errorsSolution:

# In main-batch.py, increase timeout
with ThreadPoolExecutor(max_workers=workers) as executor:
    futures = [...]  
    try:
        for future in as_completed(futures, timeout=7200):  # 2 hours
            ...
    except TimeoutError:
        print("Timeout occurred")

Error log shows repeated failures

Symptom: error_log.txt filled with errorsCheck error log:

cat error_log.txt | tail -20

Common errors:

API rate limits → Reduce workers
Invalid JSON in batch inputs → Validate with jq
MITRE data missing → Download STIX files

Streamlit-Specific Issues

Session state errors

Symptom: KeyError for session state variablesCause: Streamlit session restarted or cache clearedSolution: Reload the page (Streamlit automatically reinitializes)Prevention: Application already initializes all required state variables at startup

File upload not working

Symptom: Architecture diagram upload fails or doesn’t processCauses:

File too large (>200MB default)
Unsupported file format
Streamlit upload widget issue

Solutions:Increase upload size:

# .streamlit/config.toml
[server]
maxUploadSize = 500

Supported formats: PNG, JPG, JPEG, PDFClear cache and retry:

streamlit cache clear

Debug Mode

Enable detailed logging for troubleshooting:

# Run with debug logging
streamlit run main.py --logger.level debug

# Check Streamlit logs
tail -f ~/.streamlit/logs/streamlit.log

# Application error logs
tail -f logs/error.log

Enable Python Debug Logging

# Add to main.py for detailed debugging
import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('debug.log'),
        logging.StreamHandler()
    ]
)

Getting Help

If issues persist:

Check Existing Issues

Search GitHub Issues for similar problems

Collect Debug Information

# System info
python --version
pip list | grep -E "streamlit|openai|nvdlib"

# Application logs
tail -100 logs/error.log > debug_output.txt
tail -100 ~/.streamlit/logs/streamlit.log >> debug_output.txt

Create GitHub Issue

Open new issue with:

Clear description of problem
Steps to reproduce
Debug logs (remove sensitive data)
Environment details (OS, Python version, deployment method)

Quick Reference

Common Commands

# Start application
streamlit run main.py

# Start on different port
streamlit run main.py --server.port 8502

# Clear cache
streamlit cache clear

# Check Python environment
pip list | grep streamlit

# Test configuration
python -c "import local_config; print('Config OK')"

# View logs
tail -f logs/error.log

Configuration File Locations

Project Root/
├── local_config.py           # API keys
├── .streamlit/
│   ├── config.toml          # Streamlit settings
│   └── secrets.toml         # Streamlit Cloud secrets
├── logs/
│   └── error.log            # Application errors
└── MITRE_ATTACK_DATA/       # Threat intelligence
    ├── enterprise-attack.json
    ├── mobile-attack.json
    └── ics-attack.json

Using AegisShield

Research & Validation

Deployment

Troubleshooting

Troubleshooting

API Key Issues

OpenAI API Key Errors

NVD API Issues

AlienVault OTX Issues

Missing MITRE ATT&CK Data

Application Startup Issues

Memory and Performance Issues

PDF Generation Issues

Docker Issues

Batch Processing Issues

Streamlit-Specific Issues

Debug Mode

Enable Python Debug Logging

Getting Help

Quick Reference

Common Commands

Configuration File Locations

Next Steps

Configuration

Docker Deployment

Build docs developers (and LLMs) love

Using AegisShield

Research & Validation

Deployment

​Troubleshooting

​API Key Issues

​OpenAI API Key Errors

​NVD API Issues

​AlienVault OTX Issues

​Missing MITRE ATT&CK Data

​Application Startup Issues

​Memory and Performance Issues

​PDF Generation Issues

​Docker Issues

​Batch Processing Issues

​Streamlit-Specific Issues

​Debug Mode

​Enable Python Debug Logging

​Getting Help

​Quick Reference

​Common Commands

​Configuration File Locations

​Next Steps

Configuration

Docker Deployment

Build docs developers (and LLMs) love

Troubleshooting

API Key Issues

OpenAI API Key Errors

NVD API Issues

AlienVault OTX Issues

Missing MITRE ATT&CK Data

Application Startup Issues

Memory and Performance Issues

PDF Generation Issues

Docker Issues

Batch Processing Issues

Streamlit-Specific Issues

Debug Mode

Enable Python Debug Logging

Getting Help

Quick Reference

Common Commands

Configuration File Locations

Next Steps