FinWiz Security & Type Safety Standards

Critical security practices and type safety requirements for FinWiz development.

Type Safety (mypy strict mode)

Required Type Annotations

All public functions and methods MUST have complete type annotations:

# ✅ CORRECT
def analyze_stock(ticker: str, period: int = 365) -> StockAnalysis:
    return StockAnalysis(ticker=ticker, period=period)

def log_analysis(ticker: str) -> None:
    logger.info(f"Analyzing {ticker}")

# ❌ WRONG - Missing return type
def analyze_stock(ticker: str):
    return StockAnalysis(ticker=ticker)

Type Annotation Rules

• Return type required (use -> None if no return)
• All parameters must have type hints
• Use modern Python 3.12+ syntax: str | None instead of Optional[str]
• Use list[Type] instead of List[Type]
• Use # type: ignore only with explanatory comment

API Key Security (CRITICAL)

Environment Variables Only

NEVER hardcode API keys:

# ✅ CORRECT
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY environment variable not set")

# ❌ WRONG - Hardcoded
api_key = "sk-proj-abc123..."

Required Environment Variables

Core APIs (Required):

• OPENAI_API_KEY - OpenAI API
• SERPER_API_KEY - Serper search
• FIRECRAWL_API_KEY - Web scraping
• ALPHA_VANTAGE_API_KEY - Financial data

Enhanced Features (Optional):

• TWELVE_DATA_API_KEY - Market data (technical analysis)
• PPLX_API_KEY - Perplexity search (enhanced research)
• SEC_API_API_KEY - SEC filings (optional)
• CHART_IMG_API_KEY - Chart generation
• COINMARKETCAP_API_KEY - Cryptocurrency data

Logging Security

NEVER log full API keys:

# ✅ CORRECT - Masked (first 8 chars only)
logger.info(f"Using API key: {api_key[:8]}...")

# ❌ WRONG - Full key exposed
logger.info(f"API key: {api_key}")

Input Validation (Pydantic v2 strict)

All External Inputs Must Be Validated

from pydantic import BaseModel, Field, field_validator

class TickerInput(BaseModel):
    """Validate ticker input with strict security."""
    
    model_config = {
        "str_strip_whitespace": True,
        "str_upper": True,
        "extra": "forbid"  # Reject unknown fields
    }
    
    symbol: str = Field(..., pattern=r'^[A-Z]{1,5}$')
    
    @field_validator('symbol')
    @classmethod
    def validate_ticker(cls, v: str) -> str:
        if not v.isalpha():
            raise ValueError('Ticker must contain only letters')
        return v.upper()

Validation Requirements

• extra='forbid' - Reject unknown fields
• Field() constraints - pattern, min_length, ge, le
• @field_validator - Complex validation logic
• Sanitize inputs - Strip whitespace, normalize case
• Clear error messages - Actionable feedback

Data Privacy

Never Log Personal Financial Data

# ✅ CORRECT - Anonymized
logger.info(f"Analyzing portfolio with {len(holdings)} holdings")

# ❌ WRONG - Exposes personal data
logger.info(f"Analyzing portfolio: {holdings}")

Error Messages

Generic to users, detailed internally:

# ✅ CORRECT
try:
    result = api_call(ticker)
except Exception as e:
    logger.error(f"API call failed for {ticker}: {e}", exc_info=True)
    raise ValueError("Unable to fetch data. Please try again later.")

# ❌ WRONG - Exposes internals
except Exception as e:
    raise ValueError(f"API call to {api_url} failed: {e}")

Rate Limiting & Timeouts

Rate Limiting (Required)

from finwiz.utils.rate_limiter import RateLimiter

limiter = RateLimiter(max_calls=20, period=60)

@limiter.limit
async def fetch_stock_data(ticker: str) -> dict:
    return await api_client.get(f"/stock/{ticker}")

Timeouts (Required)

Always set explicit timeouts:

# ✅ CORRECT
async with httpx.AsyncClient(timeout=30.0) as client:
    response = await client.get(url)

# ❌ WRONG - Can hang indefinitely
async with httpx.AsyncClient() as client:
    response = await client.get(url)

Secure Coding Patterns

SQL Injection Prevention

# ✅ CORRECT - Parameterized queries
cursor.execute(
    "SELECT * FROM stocks WHERE ticker = %s",
    (ticker,)
)

# ❌ WRONG - SQL injection risk
cursor.execute(f"SELECT * FROM stocks WHERE ticker = '{ticker}'")

Path Traversal Prevention

from pathlib import Path

# ✅ CORRECT - Validate paths
def read_report(filename: str) -> str:
    # Validate filename
    if not filename.replace('-', '').replace('_', '').isalnum():
        raise ValueError("Invalid filename")
    
    # Resolve path safely
    base_path = Path("reports")
    file_path = (base_path / filename).resolve()
    
    # Ensure path is within base directory
    if not str(file_path).startswith(str(base_path.resolve())):
        raise ValueError("Path traversal attempt")
    
    return file_path.read_text()

# ❌ WRONG - Path traversal risk
def read_report(filename: str) -> str:
    with open(f"reports/{filename}") as f:
        return f.read()

Command Injection Prevention

import subprocess
import shlex

# ✅ CORRECT - Safe command execution
def run_analysis(ticker: str) -> str:
    # Validate input
    if not ticker.isalpha():
        raise ValueError("Invalid ticker")
    
    # Use list form (safer)
    result = subprocess.run(
        ["python", "analyze.py", ticker],
        capture_output=True,
        text=True,
        timeout=30
    )
    return result.stdout

# ❌ WRONG - Command injection risk
def run_analysis(ticker: str) -> str:
    result = subprocess.run(f"python analyze.py {ticker}", shell=True)
    return result.stdout

Dependency Security

Dependency Scanning

# Check for known vulnerabilities
uv audit

# Update dependencies regularly
uv sync --upgrade

Secure Dependencies

• Keep dependencies updated
• Use dependency scanning tools
• Review third-party packages before adding
• Use lock files (uv.lock)
• Remove unused dependencies regularly

Infrastructure Security

HTTPS Configuration

# ✅ CORRECT - Force HTTPS
import httpx

client = httpx.AsyncClient(
    verify=True,  # Verify SSL certificates
    timeout=30.0
)

# ❌ WRONG - Insecure connection
client = httpx.AsyncClient(verify=False)

Secure Headers

# Add security headers
headers = {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "X-XSS-Protection": "1; mode=block",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
}

Security Checklist

Before committing code:

• API keys in environment variables only
• No sensitive data in logs (mask keys, anonymize financial data)
• All inputs validated with Pydantic strict models
• All public functions have type annotations
• Rate limiting configured for API calls
• Timeouts set for all external requests (30s default)
• Error messages generic to users, detailed internally
• No hardcoded credentials
• mypy passes with no errors
• Dependencies scanned for vulnerabilities

Quick Reference

Development Practices

Secure Development Lifecycle

• Use static code analysis tools (ruff, mypy)
• Implement security testing in CI/CD
• Code reviews for security issues
• Security training for developers
• Incident response procedures

Monitoring and Logging

• Log security events (failed auth, suspicious activity)
• Monitor for unusual patterns
• Set up alerts for security incidents
• Regular security audits
• Penetration testing

Apply these security standards consistently across all FinWiz development to protect sensitive financial data and maintain system integrity.