Configuration

AegisShield requires proper configuration of API keys and application settings for full functionality. This guide covers all configuration options for local development, Docker, and production deployments.

Quick Setup

Create Configuration File

Create local_config.py in the project root:

default_nvd_api_key="YOUR_NVD_API_KEY"
default_openai_api_key="YOUR_OPENAI_API_KEY"
default_alienvault_api_key="YOUR_ALIENVAULT_API_KEY"

Obtain API Keys

OpenAI: platform.openai.com/api-keys
NVD: nvd.nist.gov/developers/request-an-api-key
AlienVault OTX: otx.alienvault.com/settings

Verify Configuration

# Test that configuration loads
python -c "import local_config; print('Config loaded successfully')"

Run Application

streamlit run main.py

API Keys

OpenAI API Key

Purpose: Powers AI-driven threat model generation using GPT-4o Required for:

Threat identification and STRIDE categorization
MITRE ATT&CK technique mapping
Security mitigation recommendations
Test case generation
Attack tree creation

How to obtain:

Create account at platform.openai.com
Navigate to API Keys section
Click “Create new secret key”
Copy and save the key (shown only once)

Configuration:

# local_config.py
default_openai_api_key="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Cost considerations:

GPT-4o pricing: ~$0.01-0.03 per threat model
Batch generation (30 models): ~$0.30-0.90
Set usage limits in OpenAI dashboard

GPT-4o access required. GPT-3.5 may produce lower-quality threat models. Verify your OpenAI account has GPT-4o enabled.

NVD API Key

Purpose: Fetches technology-specific vulnerability data from National Vulnerability Database Required for:

CVE vulnerability lookup
Version-specific security issues
Technology stack risk assessment
Compliance vulnerability reporting

How to obtain:

Visit nvd.nist.gov/developers/request-an-api-key
Fill out request form with email
Receive API key via email (typically within 24 hours)
No cost for standard rate limits

Configuration:

# local_config.py
default_nvd_api_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Rate limits:

Without API key: 5 requests per 30 seconds
With API key: 50 requests per 30 seconds
Automatic retry with exponential backoff implemented

NVD API key is optional but highly recommended. Without it, vulnerability searches will be significantly slower and may time out.

AlienVault OTX API Key

Purpose: Provides industry-specific threat intelligence from open threat exchange Required for:

Industry threat context (healthcare, finance, etc.)
Current attack campaigns
Emerging threat patterns
Threat actor intelligence

How to obtain:

Create free account at otx.alienvault.com
Navigate to Settings → API Integration
Copy your OTX Key

Configuration:

# local_config.py
default_alienvault_api_key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rate limits:

Free tier: Generous limits for typical use
Automatic retry logic implemented

AlienVault OTX is optional but adds valuable industry-specific threat context to generated models.

Configuration Methods

Method 1: Local Configuration File (Recommended for Development)

Create local_config.py in project root:

# local_config.py
default_nvd_api_key="your-nvd-api-key"
default_openai_api_key="your-openai-api-key"
default_alienvault_api_key="your-alienvault-api-key"

Advantages:

Simple for local development
Easy to edit and test
Works with main.py and main-batch.py

Security:

# Add to .gitignore to prevent accidental commits
echo "local_config.py" >> .gitignore

Method 2: Streamlit Secrets (Recommended for Production)

Create .streamlit/secrets.toml:

[default]
nvd_api_key = "your-nvd-api-key"
openai_api_key = "your-openai-api-key"
alienvault_api_key = "your-alienvault-api-key"

Usage in code:

import streamlit as st

# Access secrets
nvd_key = st.secrets["default"]["nvd_api_key"]
openai_key = st.secrets["default"]["openai_api_key"]
alienvault_key = st.secrets["default"]["alienvault_api_key"]

Advantages:

Streamlit Cloud integration
Secure secret management
Separate from code

Security:

# Add to .gitignore
echo ".streamlit/secrets.toml" >> .gitignore

Method 3: Environment Variables (Recommended for Docker)

# Set environment variables
export OPENAI_API_KEY="your-openai-api-key"
export NVD_API_KEY="your-nvd-api-key"
export ALIENVAULT_API_KEY="your-alienvault-api-key"

# Run application
streamlit run main.py

Docker usage:

docker run -p 8501:8501 \
  -e OPENAI_API_KEY="your-key" \
  -e NVD_API_KEY="your-key" \
  -e ALIENVAULT_API_KEY="your-key" \
  aegisshield:latest

Advantages:

Cloud-native deployment
Kubernetes/Docker integration
No file management needed

Method 4: UI Input (Development/Testing Only)

AegisShield allows API key input through the UI sidebar:

Launch application: streamlit run main.py
In sidebar, enter API keys in respective fields
Keys stored in session state (not persisted)

UI input is not recommended for production as keys are not persisted across sessions and must be re-entered each time.

Streamlit Configuration

Application Settings

Create .streamlit/config.toml for Streamlit customization:

[server]
# Port to run on
port = 8501

# Address to bind to
address = "localhost"

# Max upload size in MB (for architecture diagrams)
maxUploadSize = 200

# Enable CORS
enableCORS = false

# Enable XSRF protection
enableXsrfProtection = true

# Enable websocket compression
enableWebsocketCompression = true

[browser]
# Disable usage stats collection
gatherUsageStats = false

# Server address to display
serverAddress = "localhost"

# Server port to display  
serverPort = 8501

[theme]
# Primary color
primaryColor = "#1f77b4"

# Background color
backgroundColor = "#ffffff"

# Secondary background color
secondaryBackgroundColor = "#f0f2f6"

# Text color
textColor = "#262730"

# Font family
font = "sans serif"

[logger]
# Log level (error, warning, info, debug)
level = "info"

# Message format
messageFormat = "%(asctime)s %(levelname)s: %(message)s"

Production Configuration

For production deployments:

[server]
port = 8501
address = "0.0.0.0"  # Listen on all interfaces
maxUploadSize = 200
enableCORS = false
enableXsrfProtection = true
headless = true  # Don't try to open browser

[browser]
gatherUsageStats = false

[logger]
level = "warning"  # Reduce log verbosity

Advanced Configuration

Model Selection

By default, AegisShield uses GPT-4o. To use alternative models, modify main-batch.py or main.py:

# main-batch.py
selected_model = "gpt-4o"  # Default

# Alternative models (if available)
# selected_model = "gpt-4o-mini"  # Faster, lower cost
# selected_model = "gpt-4-turbo"   # Alternative model

Batch Processing Configuration

For research/batch generation, configure in main-batch.py:

# Number of threat models per case study
batches = 30

# Parallel processing threads (balance speed vs API limits)
workers = 3

# API retry attempts
retries = 6

# Process specific case study (None = all)
SPECIFIC_CASE_STUDY = None

Performance tuning:

workers=1: Slowest, most reliable, no rate limiting issues
workers=3: Balanced (recommended)
workers=5+: Faster but may hit OpenAI rate limits

MITRE ATT&CK Data

MITRE ATT&CK data is loaded from local JSON files:

MITRE_ATTACK_DATA/
├── enterprise-attack.json
├── mobile-attack.json
└── ics-attack.json

Updating MITRE data:

# Download latest STIX 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

Recommendation: Update quarterly or when MITRE releases major updates.

Validation

Test Configuration

Verify your configuration is working:

# test_config.py
try:
    import local_config as conf
    print("✓ local_config.py loaded successfully")
    
    if conf.default_openai_api_key:
        print(f"✓ OpenAI API key configured (length: {len(conf.default_openai_api_key)})")
    else:
        print("✗ OpenAI API key missing")
    
    if conf.default_nvd_api_key:
        print(f"✓ NVD API key configured (length: {len(conf.default_nvd_api_key)})")
    else:
        print("✗ NVD API key missing")
    
    if conf.default_alienvault_api_key:
        print(f"✓ AlienVault API key configured (length: {len(conf.default_alienvault_api_key)})")
    else:
        print("✗ AlienVault API key missing")
        
except ImportError:
    print("✗ local_config.py not found")

Common Configuration Issues

ImportError: No module named 'local_config'

Problem: local_config.py not foundSolution:

# Verify file exists in project root
ls -la local_config.py

# Create if missing
cat > local_config.py <<EOF
default_nvd_api_key="YOUR_NVD_KEY"
default_openai_api_key="YOUR_OPENAI_KEY"
default_alienvault_api_key="YOUR_ALIENVAULT_KEY"
EOF

OpenAI Authentication Error

Problem: “Incorrect API key provided” or “Invalid authentication”Solutions:

Verify key starts with sk-proj- or sk-
Check for extra spaces or quotes
Regenerate key in OpenAI dashboard
Verify account has GPT-4o access

# Debug: Print first/last 4 chars
import local_config as conf
key = conf.default_openai_api_key
print(f"Key: {key[:4]}...{key[-4:]}")

NVD Rate Limiting

Problem: “Rate limit exceeded” or very slow vulnerability searchesSolutions:

Obtain NVD API key (increases limit from 5 to 50 requests/30s)
Reduce batch processing workers count
Built-in exponential backoff will handle this automatically

# Batch config for slow NVD access
workers = 1  # Sequential processing
retries = 10  # More retries

Streamlit Secrets Not Loading

Problem: Secrets not accessible in deployed appSolutions:

Verify file location: .streamlit/secrets.toml (note the dot prefix)
Check TOML syntax:

# Correct
[default]
key = "value"

# Incorrect
key = value  # Missing quotes
key: "value"  # Wrong separator

Streamlit Cloud: Add secrets in dashboard under Settings → Secrets

Security Best Practices

Critical Security Guidelines:

Never commit secrets to version control

# .gitignore
local_config.py
.streamlit/secrets.toml
.env

Use environment-specific configurations
- Development: local_config.py
- Production: Environment variables or secret managers
Rotate API keys regularly
- OpenAI: Quarterly or after suspected exposure
- NVD: Annually or after policy changes
- AlienVault: Bi-annually
Use least-privilege access
- Separate keys for dev/staging/prod
- Monitor API usage for anomalies
Encrypt secrets at rest
- Use AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault
- Never store plain-text keys in CI/CD logs
Audit access logs
- Review OpenAI usage dashboard
- Monitor NVD and AlienVault API usage
- Set up billing alerts

Environment-Specific Configurations

Development

# local_config.py
default_nvd_api_key="dev-nvd-key"
default_openai_api_key="dev-openai-key"
default_alienvault_api_key="dev-alienvault-key"

Staging

# .env.staging
OPENAI_API_KEY=staging-key
NVD_API_KEY=staging-key
ALIENVAULT_API_KEY=staging-key

Production

# Use secret management service
aws secretsmanager get-secret-value --secret-id aegisshield/prod/openai
kubectl create secret generic aegisshield-secrets \
  --from-literal=openai-key=xxx \
  --from-literal=nvd-key=xxx \
  --from-literal=alienvault-key=xxx

Using AegisShield

Research & Validation

Deployment

Configuration

Configuration

Quick Setup

API Keys

OpenAI API Key

NVD API Key

AlienVault OTX API Key

Configuration Methods

Method 1: Local Configuration File (Recommended for Development)

Method 2: Streamlit Secrets (Recommended for Production)

Method 3: Environment Variables (Recommended for Docker)

Method 4: UI Input (Development/Testing Only)

Streamlit Configuration

Application Settings

Production Configuration

Advanced Configuration

Model Selection

Batch Processing Configuration

MITRE ATT&CK Data

Validation

Test Configuration

Common Configuration Issues

Security Best Practices

Environment-Specific Configurations

Development

Staging

Production

Next Steps

Docker Deployment

Troubleshooting

Build docs developers (and LLMs) love

Using AegisShield

Research & Validation

Deployment

​Configuration

​Quick Setup

​API Keys

​OpenAI API Key

​NVD API Key

​AlienVault OTX API Key

​Configuration Methods

​Method 1: Local Configuration File (Recommended for Development)

​Method 2: Streamlit Secrets (Recommended for Production)

​Method 3: Environment Variables (Recommended for Docker)

​Method 4: UI Input (Development/Testing Only)

​Streamlit Configuration

​Application Settings

​Production Configuration

​Advanced Configuration

​Model Selection

​Batch Processing Configuration

​MITRE ATT&CK Data

​Validation

​Test Configuration

​Common Configuration Issues

​Security Best Practices

​Environment-Specific Configurations

​Development

​Staging

​Production

​Next Steps

Docker Deployment

Troubleshooting

Build docs developers (and LLMs) love

Configuration

Quick Setup

API Keys

OpenAI API Key

NVD API Key

AlienVault OTX API Key

Configuration Methods

Method 1: Local Configuration File (Recommended for Development)

Method 2: Streamlit Secrets (Recommended for Production)

Method 3: Environment Variables (Recommended for Docker)

Method 4: UI Input (Development/Testing Only)

Streamlit Configuration

Application Settings

Production Configuration

Advanced Configuration

Model Selection

Batch Processing Configuration

MITRE ATT&CK Data

Validation

Test Configuration

Common Configuration Issues

Security Best Practices

Environment-Specific Configurations

Development

Staging

Production

Next Steps