Security Considerations

Security best practices for Epochly deployments.

Security Design Principles

Epochly is designed with security as a core principle:

No Network Access: Epochly does not make network calls during optimization
Local Processing Only: All code execution and data processing happens locally
No Data Exfiltration: Your data never leaves your infrastructure
Process Isolation: Worker processes are isolated from each other
Minimal Attack Surface: No listening ports, no inbound connections

Environment Variable Security

License Key Protection

Never expose license keys in code or version control:

# ❌ BAD - Don't hardcode license keys
epochly.configure(license_key='epk_abc123')
# ✅ GOOD - Use environment variables
import os
epochly.configure(license_key=os.environ.get('EPOCHLY_LICENSE_KEY'))

Secrets Management

Use proper secrets management systems:

# HashiCorp Vault
export EPOCHLY_LICENSE_KEY=$(vault read -field=key secret/epochly)
# AWS Secrets Manager
export EPOCHLY_LICENSE_KEY=$(aws secretsmanager get-secret-value   --secret-id epochly/license --query SecretString --output text)
# Azure Key Vault
export EPOCHLY_LICENSE_KEY=$(az keyvault secret show   --vault-name myvault --name epochly-license --query value -o tsv)

Docker Secrets

version: '3.8'
services:
  app:
    image: myapp
    secrets:
      - epochly_license
    environment:
      - EPOCHLY_LICENSE_KEY_FILE=/run/secrets/epochly_license
secrets:
  epochly_license:
    external: true

Kubernetes Secrets

apiVersion: v1
kind: Secret
metadata:
  name: epochly-secrets
  namespace: production
type: Opaque
stringData:
  EPOCHLY_LICENSE_KEY: "your-license-key"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          envFrom:
            - secretRef:
                name: epochly-secrets

Debug Mode Warnings

Never enable debug mode in production:

# ❌ DANGEROUS in production
export EPOCHLY_LOG_LEVEL=DEBUG
# ✅ Production setting
export EPOCHLY_LOG_LEVEL=WARNING

Debug mode may expose:

Internal state and variables
Performance metrics
Code paths and optimization decisions
Memory addresses

Process Isolation

Worker Process Isolation

Each worker process runs in isolation:

import epochly
# Workers are isolated from each other
epochly.configure(
    enhancement_level=3,
    max_workers=4  # 4 isolated processes
)

Sub-Interpreter Isolation (Python 3.12+)

Python 3.12+ provides true parallelism with sub-interpreters:

Separate GIL per sub-interpreter: No GIL contention
Isolated memory: Sub-interpreters cannot access each other's data
Crash isolation: Crashes in one sub-interpreter don't affect others

Process-Level Security

# Run with minimal privileges
docker run --user 1000:1000 --read-only myapp
# Drop unnecessary capabilities
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE myapp

Memory Safety

Shared Memory is Process-Local

Epochly's shared memory is local to your process:

import epochly
# Shared memory is NOT accessible to other processes
epochly.configure(
    shared_memory_size=134217728  # 128MB, local only
)

GPU Memory Allocation

GPU memory is managed by CUDA and isolated per process:

# Limit GPU memory
export EPOCHLY_GPU_MEMORY_LIMIT=2048  # 2GB per process

JIT Compilation Security

No Arbitrary Code Execution

JIT compilation only optimizes your existing Python code:

Does not execute arbitrary strings
Does not eval() or exec() user input
Only compiles functions you explicitly decorate or optimize

import epochly
# Safe - compiles YOUR function
@epochly.optimize(level=2)
def my_function(data):
    return data ** 2
# This is still YOUR code, just compiled

JIT Cache Security

# Set JIT cache to secure location
export EPOCHLY_JIT_CACHE_DIR=/var/cache/epochly
# Ensure proper permissions
chmod 750 /var/cache/epochly

Telemetry Disable

Epochly respects your privacy. Disable telemetry completely:

# Disable all telemetry
export EPOCHLY_TELEMETRY=0

With telemetry disabled:

No usage metrics collected
No performance data sent
No diagnostic information transmitted
Completely offline operation

License Security

Offline Activation

Epochly supports offline/air-gapped activation:

# For air-gapped environments
export EPOCHLY_OFFLINE_MODE=1
export EPOCHLY_LICENSE_KEY=your-license-key

License Validation

Licenses are validated locally using cryptographic signatures
No network calls required for validation
Time-based validation uses system clock (no NTP calls)

Container Security Best Practices

Minimal Docker Image

# Use minimal base image
FROM python:3.12-slim
# Create non-root user
RUN useradd -m -u 1000 appuser
# Install as non-root
USER appuser
WORKDIR /home/appuser/app
# Copy and install
COPY --chown=appuser:appuser . .
RUN pip install --user epochly
ENV PATH="/home/appuser/.local/bin:$PATH"

Non-Root User

# Never run as root
USER appuser
# Verify in running container
docker exec myapp id
# Output: uid=1000(appuser) gid=1000(appuser)

Read-Only Filesystem

# Run with read-only root filesystem
docker run --read-only --tmpfs /tmp myapp

Drop Capabilities

# Drop all capabilities
docker run --cap-drop=ALL myapp
# Or in docker-compose
services:
  app:
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

Complete Secure Dockerfile

FROM python:3.12-slim
# Create non-root user
RUN useradd -m -u 1000 appuser &&     mkdir -p /tmp/epochly &&     chown appuser:appuser /tmp/epochly
WORKDIR /app
COPY --chown=appuser:appuser . .
RUN pip install --no-cache-dir epochly
USER appuser
# Configure securely
ENV EPOCHLY_LOG_LEVEL=WARNING
ENV EPOCHLY_TELEMETRY=0
ENV EPOCHLY_JIT_CACHE_DIR=/tmp/epochly
# Security hardening
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=30s CMD python -c "import epochly; assert epochly.get_status()['initialized']"
CMD ["python", "app.py"]

Network Security

No Inbound Connections

Epochly does not listen on any ports by default:

No network servers
No listening sockets
No inbound traffic

Optional Prometheus Port

If you enable Prometheus metrics:

export EPOCHLY_PROMETHEUS_PORT=9090

Security recommendations:

Bind to localhost only: EPOCHLY_PROMETHEUS_BIND=127.0.0.1
Use firewall rules to restrict access
Enable authentication if exposing externally

Firewall Configuration

# Allow only Prometheus scraping from monitoring host
iptables -A INPUT -p tcp --dport 9090 -s 10.0.1.50 -j ACCEPT
iptables -A INPUT -p tcp --dport 9090 -j DROP

Audit Logging

Enable audit logging for security monitoring:

import epochly
epochly.configure(
    log_level='INFO',
    log_file='/var/log/epochly/audit.log',
    log_format='json'  # Structured logging for SIEM
)

Log Events to Monitor

Configuration changes
Level adjustments
Emergency disable events
Optimization failures
License validation results

Log Rotation

# /etc/logrotate.d/epochly
/var/log/epochly/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0640 appuser appuser
}

Vulnerability Management

Keeping Epochly Updated

# Check current version
epochly --version
# Update to latest
pip install --upgrade epochly
# Verify installation
epochly doctor

Dependency Scanning

# Scan for vulnerabilities
pip install safety
safety check
# Or use pip-audit
pip install pip-audit
pip-audit

Compliance Considerations

Data Residency

All data processing happens locally:

No data sent to external services
No cloud processing
Your data stays in your infrastructure

PII Protection

Epochly does not inspect or log data:

No access to your application data
No telemetry of processed values
Only performance metrics (if enabled)

Data Protection

With EPOCHLY_TELEMETRY=0:

No personal data collected
No data processing agreements needed
Designed to support data protection requirements

Security Checklist

Pre-Deployment

[ ] License key stored in secrets management (not code)
[ ] EPOCHLY_LOG_LEVEL set to WARNING or ERROR
[ ] EPOCHLY_TELEMETRY=0 for privacy
[ ] Debug mode disabled in production
[ ] Non-root user configured in containers
[ ] Read-only filesystem where possible
[ ] All capabilities dropped (Docker)
[ ] Firewall rules configured for Prometheus (if used)
[ ] JIT cache directory has proper permissions
[ ] Audit logging enabled and configured

Post-Deployment

[ ] Verify non-root user: docker exec app id
[ ] Check no unexpected listening ports: netstat -tulpn
[ ] Verify license validation working
[ ] Review audit logs for anomalies
[ ] Monitor for failed optimization attempts
[ ] Ensure emergency disable procedures documented
[ ] Test security incident response
[ ] Regular vulnerability scanning scheduled

Ongoing Maintenance

[ ] Keep Epochly updated to latest version
[ ] Review security advisories regularly
[ ] Rotate license keys according to policy
[ ] Audit log review and retention
[ ] Security training for operations team
[ ] Incident response plan updated
[ ] Regular security assessments

Incident Response

Emergency Disable

# Immediate disable if security issue suspected
export EPOCHLY_EMERGENCY_DISABLE=1
# Restart application
systemctl restart myapp

Forensics

# Collect logs
docker cp myapp:/var/log/epochly /tmp/incident-logs
# Check current status
docker exec myapp python -c "import epochly; print(epochly.get_status())"
# Review metrics
curl localhost:9090/metrics > metrics-snapshot.txt