Installation - AegisShield

System Requirements

Before installing AegisShield, ensure your system meets these requirements:

Python Version

Python 3.12 or higher (3.9+ supported, 3.12 recommended)

Memory

Minimum 4GB RAM (8GB+ recommended for large threat models)

Disk Space

500MB for application and dependencies

Internet Access

Required for API calls to OpenAI, NVD, and AlienVault OTX

Supported Platforms

Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+, CentOS 8+
macOS: 11 (Big Sur) or later
Windows: 10/11 with WSL2 recommended
Docker: Any platform with Docker 20.10+

Installation Methods

Local Installation
Docker
Development Setup

1. Clone the Repository

git clone https://github.com/mgrofsky/AegisShield.git
cd AegisShield

2. Create Virtual Environment

Using a virtual environment is strongly recommended to avoid dependency conflicts:

python3 -m venv venv
source venv/bin/activate

You’ll know the virtual environment is active when you see (venv) in your terminal prompt.

3. Install Dependencies

Install all required Python packages:

pip install -r requirements.txt

Dependencies installed:

openai - OpenAI API client for GPT-4o
streamlit - Web application framework
OTXv2 - AlienVault OTX threat intelligence API
nvdlib - National Vulnerability Database API
setuptools - Python package installation utilities
markdown2 - Markdown to HTML conversion
xhtml2pdf - PDF report generation
pytest, pytest-cov, pytest-mock - Testing frameworks

4. Verify Installation

Check that all dependencies are installed correctly:

python -c "import streamlit, openai, OTXv2, nvdlib; print('All dependencies installed successfully!')"

5. Configure API Keys

See the API Key Configuration section below.

Quick Start with Docker

The easiest way to run AegisShield without managing dependencies:

# Build the Docker image
docker build -t aegisshield .

# Run the container
docker run -p 8501:8501 \
  -e OPENAI_API_KEY="your-openai-key" \
  -e NVD_API_KEY="your-nvd-key" \
  -e ALIENVAULT_API_KEY="your-alienvault-key" \
  aegisshield

Access the application at http://localhost:8501

Docker with Configuration File

For persistent configuration, mount your local_config.py:

# Create local_config.py with your keys
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

# Run with mounted configuration
docker run -p 8501:8501 \
  -v $(pwd)/local_config.py:/app/local_config.py:ro \
  aegisshield

Docker Compose

For production deployments with automatic restarts:

docker-compose.yml

version: '3.8'

services:
  aegisshield:
    build: .
    ports:
      - "8501:8501"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NVD_API_KEY=${NVD_API_KEY}
      - ALIENVAULT_API_KEY=${ALIENVAULT_API_KEY}
    volumes:
      - ./local_config.py:/app/local_config.py:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Start with:

docker-compose up -d

Dockerfile Details

The included Dockerfile (/home/daytona/workspace/source/Dockerfile:1-34) provides:

Base Image: Python 3.13-slim for minimal footprint
System Dependencies: Cairo, Pango, GDK-PixBuf for PDF generation
Health Check: Automatic monitoring on port 8501
Optimized Build: Multi-stage build with no-cache pip installs

The container runs as root by default. For production, consider running as a non-root user:

# Add before ENTRYPOINT
RUN useradd -m -u 1000 aegisshield
USER aegisshield

For Contributors and Developers

Set up a development environment with testing and code quality tools:

# Clone the repository
git clone https://github.com/mgrofsky/AegisShield.git
cd AegisShield

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install all dependencies including testing tools
pip install -r requirements.txt

# Install development tools
pip install ruff pylint black

# Verify installation with tests
pytest --cov=.

Code Quality Checks

Run code quality checks before committing:

# Format code with Ruff
ruff format .

# Check for linting issues
ruff check .

# Run Pylint
pylint *.py

Configuration

The project uses pyproject.toml for configuration:

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "C4"]
ignore = ["E501", "B007", "F841"]

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_cases.py

API Key Configuration

AegisShield requires three API keys to function. You can configure them in two ways:

Method 1: Local Configuration File (Recommended)

Create a local_config.py file in the project root:

local_config.py

default_nvd_api_key="your-nvd-api-key-here"
default_openai_api_key="your-openai-api-key-here"
default_alienvault_api_key="your-alienvault-api-key-here"

Security Best Practices:

Never commit local_config.py to version control
Use environment-specific configuration files
Rotate API keys regularly
Use read-only API keys when possible

Method 2: Streamlit Secrets

For deployments using Streamlit Cloud or shared environments: Create .streamlit/secrets.toml:

.streamlit/secrets.toml

nvd_api_key = "your-nvd-api-key-here"
openai_api_key = "your-openai-api-key-here"
alienvault_api_key = "your-alienvault-api-key-here"

Method 3: UI Input (Development Only)

For testing, you can enter API keys directly in the application sidebar. Not recommended for production.

The application checks for keys in this order:

Streamlit secrets (.streamlit/secrets.toml)
Local configuration (local_config.py)
User input in the UI sidebar

Obtaining API Keys

OpenAI API Key

Create OpenAI Account

Visit OpenAI Platform and sign up or log in.

Set Up Billing

Navigate to Billing and add a payment method. GPT-4o requires a paid account.

Generate API Key

Go to API Keys and click Create new secret key.The key format is: sk-proj-...

Configure Access

Ensure your account has access to GPT-4o (default model) or GPT-5 (if available).

Cost Estimate: ~

0.50-

2.00 per threat model (varies by complexity)

NVD API Key

Request API Key

Visit NVD API Request Form

Provide Email

Enter your email address. API keys are free for public use.

Verify Email

Check your email for the API key (usually arrives within 5-10 minutes).

Save API Key

Add the key to your local_config.py file.

Rate Limits:

With API key: 50 requests per 30 seconds
Without API key: 5 requests per 30 seconds

AlienVault OTX API Key

Create OTX Account

Access API Settings

Navigate to Settings → API

Copy API Key

Your API key is displayed automatically. Copy it to your configuration.

Rate Limits:

Free tier: 10,000 requests per hour
Sufficient for most AegisShield usage

Data Dependencies

AegisShield includes pre-loaded MITRE ATT&CK data in the MITRE_ATTACK_DATA/ directory:

MITRE_ATTACK_DATA/
├── enterprise-attack.json    # Enterprise tactics and techniques
├── mobile-attack.json         # Mobile-specific threats
└── ics-attack.json           # Industrial Control Systems threats

Updating MITRE Data: The repository includes current MITRE ATT&CK data. For the latest version, download from the MITRE ATT&CK GitHub and replace the JSON files.Recommended update frequency: Quarterly

Running the Application

After installation and configuration:

# Activate virtual environment (if using)
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Start the application
streamlit run main.py

The application will:

Load API keys from configuration
Initialize MITRE ATT&CK data
Start the web server on http://localhost:8501
Open your default browser automatically

Custom Port Configuration

# Use a different port
streamlit run main.py --server.port 8502

# Bind to all network interfaces (for remote access)
streamlit run main.py --server.address 0.0.0.0

Debug Mode

For troubleshooting:

streamlit run main.py --logger.level debug

Troubleshooting

Python Version Issues

Error: “Python 3.12 required” or import errorsSolution:

# Check Python version
python --version

# If using older Python, upgrade or use pyenv
pyenv install 3.12.0
pyenv local 3.12.0

# Recreate virtual environment with correct version
python3.12 -m venv venv

Dependency Installation Failures

Error: “Failed building wheel for X” or compilation errorsSolution for xhtml2pdf (common issue):

sudo apt-get update
sudo apt-get install python3-dev libcairo2-dev libpango1.0-dev
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

API Key Validation Errors

Error: “Invalid API key” or authentication failuresChecklist:

API key has no leading/trailing spaces
OpenAI key starts with sk- or sk-proj-
Keys are in quotes in local_config.py
File is named exactly local_config.py (not config.py)
OpenAI account has GPT-4o access enabled

Test API keys:

# Test OpenAI
from openai import OpenAI
client = OpenAI(api_key="your-key")
print(client.models.list())

# Test NVD (in Python shell)
import nvdlib
results = nvdlib.searchCVE(cveId='CVE-2024-1234', key='your-key')

MITRE Data Not Found

Error: “No MITRE ATT&CK data found”Solution:

# Check if directory exists
ls MITRE_ATTACK_DATA/

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

# If missing, re-clone the repository or download from:
# https://github.com/mitre-attack/attack-stix-data

Memory Issues

Error: “Out of memory” or application crashes during threat generationSolutions:

Close other applications to free RAM
Use batch processing for multiple threat models
Reduce concurrent API calls in code
Consider upgrading to 8GB+ RAM

For Docker, increase memory limit:

docker run -m 4g -p 8501:8501 aegisshield

Network and Firewall Issues

Error: Connection timeouts or API request failuresChecklist:

Internet connection is active
Firewall allows outbound HTTPS (443)
No proxy blocking OpenAI, NVD, or OTX domains
Corporate VPN not blocking API endpoints

Test connectivity:

# Test OpenAI
curl https://api.openai.com/v1/models -H "Authorization: Bearer sk-..."

# Test NVD
curl https://services.nvd.nist.gov/rest/json/cves/2.0

# Test AlienVault
curl https://otx.alienvault.com/api/v1/indicators/domain/example.com

Docker Issues

Error: Docker build fails or container won’t startCommon solutions:

# Clear Docker cache and rebuild
docker system prune -a
docker build --no-cache -t aegisshield .

# Check container logs
docker logs <container-id>

# Interactive troubleshooting
docker run -it aegisshield /bin/bash

# Port conflicts
docker run -p 8502:8501 aegisshield

Streamlit Won't Start

Error: “Address already in use” or Streamlit crashesSolutions:

# Kill existing Streamlit processes
pkill -f streamlit

# Or on Windows
taskkill /F /IM streamlit.exe

# Use different port
streamlit run main.py --server.port 8502

# Check for port conflicts
lsof -i :8501  # Linux/macOS
netstat -ano | findstr :8501  # Windows

Performance Optimization

API Rate Limit Management

AegisShield includes built-in retry logic with exponential backoff (see nvd_search.py:23-63, alientvault_search.py:25-50):

# Automatic retry configuration
max_retries = 3
initial_delay = 1.0  # seconds
# Exponential backoff: 1s → 2s → 4s

Memory Management

For large threat models:

# In main.py, adjust session state caching
# Reduce concurrent processing if needed
import streamlit as st
st.set_page_config(layout="wide")  # Already configured

Caching Strategy

Security First: AegisShield deliberately avoids caching sensitive threat model data to prevent information disclosure (NIST SP 800-53 SC-4).

Verification

After installation, verify everything works:

# 1. Check Python version
python --version  # Should be 3.12+

# 2. Import all dependencies
python -c "import streamlit, openai, OTXv2, nvdlib, markdown2, xhtml2pdf; print('✓ All imports successful')"

# 3. Check configuration file
python -c "import local_config; print('✓ Config file found')"

# 4. Verify MITRE data
ls MITRE_ATTACK_DATA/*.json | wc -l  # Should output: 3

# 5. Start application
streamlit run main.py

Expected output:

  You can now view your Streamlit app in your browser.

  Local URL: http://localhost:8501
  Network URL: http://192.168.1.x:8501

Next Steps

Quickstart Guide

Create your first threat model

Features

Explore all capabilities

Compliance

NIST SP 800-53 implementation details

API Reference

Integration and automation guides

Support

Installation Issues?

Check the FAQ
Review GitHub Issues
Consult the troubleshooting guide

Get Started

Core Features

Threat Intelligence

Workflows

Compliance

​System Requirements

Python Version

Memory

Disk Space

Internet Access

​Supported Platforms

​Installation Methods

​1. Clone the Repository

​2. Create Virtual Environment

​3. Install Dependencies

​4. Verify Installation

​5. Configure API Keys

​Quick Start with Docker

​Docker with Configuration File

​Docker Compose

​Dockerfile Details

​For Contributors and Developers

​Code Quality Checks

​Configuration

​Running Tests

​API Key Configuration

​Method 1: Local Configuration File (Recommended)

​Method 2: Streamlit Secrets

​Method 3: UI Input (Development Only)

​Obtaining API Keys

​OpenAI API Key

​NVD API Key

​AlienVault OTX API Key

​Data Dependencies

​Running the Application

​Custom Port Configuration

​Debug Mode

​Troubleshooting

​Performance Optimization

​API Rate Limit Management

​Memory Management

​Caching Strategy

​Verification

​Next Steps

Quickstart Guide

Features

Compliance

API Reference

​Support

Build docs developers (and LLMs) love

System Requirements

Supported Platforms

Installation Methods

1. Clone the Repository

2. Create Virtual Environment

3. Install Dependencies

4. Verify Installation

5. Configure API Keys

Quick Start with Docker

Docker with Configuration File

Docker Compose

Dockerfile Details

For Contributors and Developers

Code Quality Checks

Configuration

Running Tests

API Key Configuration

Method 1: Local Configuration File (Recommended)

Method 2: Streamlit Secrets

Method 3: UI Input (Development Only)

Obtaining API Keys

OpenAI API Key

NVD API Key

AlienVault OTX API Key

Data Dependencies

Running the Application

Custom Port Configuration

Debug Mode

Troubleshooting

Performance Optimization

API Rate Limit Management

Memory Management

Caching Strategy

Verification

Next Steps

Support