trustos/README.md

TrustOS

The AI Operating System for Cyber Resilience

TrustOS is an AI-powered cyber resilience platform for SMB and mid-market companies that need enterprise-grade security clarity without building an enterprise security team. The platform helps leadership teams understand their top cyber risks, prioritize fixes, track remediation, and prove improvement to customers, boards, insurers, and regulators.

---

Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Project Structure
• Quick Start
• Development Setup
• Configuration
• Database Migrations
• Testing
• Deployment
• Documentation
• Security
• Troubleshooting
• Contributing
• License

---

Overview

TrustOS transforms cybersecurity from a technical burden into a business asset by:

• Translating technical risks into business language - AI-powered explanations that executives understand
• Providing continuous visibility - Living dashboard instead of static reports
• Tracking remediation progress - Clear ownership, deadlines, and proof of fixes
• Proving improvement over time - Measurable risk score trends for boards and insurers
• Protecting executive exposure - Digital footprint monitoring for leadership teams

Dashboard Preview

The TrustOS Vault Dashboard provides executive-ready security visibility:

┌─────────────────────────────────────────────────────────────────────────┐
│ TrustOS Vault Dashboard                                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Cyber Resilience Overview                    Audit baseline: Jul 6    │
│                                                                          │
│  ┌──────────────────────┐  ┌─────────┬─────────┬─────────┬─────────┐  │
│  │   Cyber Health       │  │Critical │  High   │ Medium  │  Total  │  │
│  │      Score           │  │    2    │    5    │   12    │   19    │  │
│  │       89.2           │  └─────────┴─────────┴─────────┴─────────┘  │
│  │                      │                                              │
│  │  ↑ +2.5 pts         │  Risk Score — 90 Day Trend                   │
│  │   this month        │  ┌────────────────────────────────────────┐ │
│  │                      │  │ 100 ─ ╱╲                              │ │
│  └──────────────────────┘  │  90 ─╱  ╲  ╱╲  ╱╲                     │ │
│                            │  80 ────  ╱──╲╱  ╲╱╲  ╱─ Current: 89.2 │
│                            │  70 ─────────────────────────          │ │
│                            │     Jun      Jul      Aug              │ │
│                            └────────────────────────────────────────┘ │
│                                                                        │
│  Top Risks Requiring Your Attention                 View all findings →│
│                                                                        │
│  ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐│
│  │🔴 CRITICAL        │ │🟠 HIGH             │ │🟠 HIGH             ││
│  │                    │ │                    │ │                    ││
│  │Internet-accessible│ │5 executive email   │ │S3 bucket publicly  ││
│  │admin panel with    │ │accounts found in   │ │accessible with     ││
│  │no authentication   │ │breach database     │ │customer files      ││
│  │                    │ │                    │ │                    ││
│  │An attacker could   │ │Attackers could     │ │This constitutes a  ││
│  │gain full control   │ │access email, cloud │ │data breach. Exposure││
│  │of your platform,   │ │systems, and data   │ │of customer PII may ││
│  │access all customer │ │— enabling targeted │ │trigger regulatory  ││
│  │data, and disrupt   │ │phishing and wire   │ │penalties.          ││
│  │operations.         │ │fraud.              │ │                    ││
│  │                    │ │                    │ │                    ││
│  │Fix Priority:       │ │Fix Priority:       │ │Fix Priority:       ││
│  │URGENT              │ │URGENT              │ │URGENT              ││
│  └────────────────────┘ └────────────────────┘ └────────────────────┘│
│                                                                        │
└─────────────────────────────────────────────────────────────────────────┘

Current Status:

• Cyber Health Score: 89.2 (healthy baseline)
• Open Critical Issues: 2
• Open High Issues: 5
• 30-day Improvement: +2.5 points 📈
• Demo Data: 6 findings with AI-translated business impact

System Architecture Overview

graph TB
    subgraph Client["Client Layer"]
        Browser[Web Browser]
    end
    
    subgraph Frontend["Frontend Layer"]
        NextJS[Next.js 16 + TypeScript]
        Tailwind[Tailwind CSS + shadcn/ui]
    end
    
    subgraph API["API Layer"]
        FastAPI[FastAPI + Pydantic]
        Auth[Authentication & Authorization]
        Services[Business Logic Services]
        AI[AI Integration Layer]
    end
    
    subgraph Database["Database Layer"]
        PostgreSQL[(PostgreSQL 16)]
        Migrations[Alembic Migrations]
    end
    
    subgraph External["External Services"]
        OpenAI[OpenAI API]
        Anthropic[Anthropic API]
        HIBP[HIBP API]
        NVD[NVD API]
    end
    
    Browser -->|HTTPS| NextJS
    NextJS -->|REST API| FastAPI
    FastAPI --> Auth
    FastAPI --> Services
    Services --> AI
    Services --> PostgreSQL
    AI --> OpenAI
    AI --> Anthropic
    Services --> HIBP
    Services --> NVD
    PostgreSQL --> Migrations
    
    style Frontend fill:#e1f5ff
    style API fill:#fff4e1
    style Database fill:#e8f5e9
    style External fill:#f3e5f5

Business Model

graph LR
    subgraph Phase1["Phase 1: Vault Audit"]
        Audit[One-time Assessment<br/>$25K-$95K]
        Dashboard[Interactive Dashboard]
        Report[Audit Report]
    end
    
    subgraph Phase2["Phase 2: Monthly Monitoring"]
        Monitor[Continuous Monitoring<br/>$5K-$15K/month]
        Daily[Daily Assessments]
        Alerts[Automated Alerts]
    end
    
    subgraph Phase3["Phase 3: Full Platform"]
        Platform[Full Platform<br/>$180K-$900K/year]
        AI[AI Security Coach]
        Advanced[Advanced Integrations]
    end
    
    Audit --> Dashboard
    Audit --> Report
    Audit --> Monitor
    Monitor --> Daily
    Monitor --> Alerts
    Monitor --> Platform
    Platform --> AI
    Platform --> Advanced
    
    style Phase1 fill:#e3f2fd
    style Phase2 fill:#fff3e0
    style Phase3 fill:#f3e5f5

• Phase 1: Vault Audit ($25K–$95K) - One-time comprehensive assessment with interactive dashboard
• Phase 2: Monthly Monitoring ($5K–$15K/month) - Continuous monitoring and daily risk updates
• Phase 3: Full Platform ($180K–$900K/year) - Complete cyber resilience operating system

---

For Executives

Business Value

TrustOS provides executives with:

• Clear Risk Visibility: Understand your cyber posture in minutes, not days
• Board-Ready Reporting: Professional reports for boards, insurers, and regulators
• Measurable Improvement: Track risk score trends to prove security investments
• Executive Protection: Monitor digital footprint of leadership team
• Compliance Support: Demonstrate due diligence to customers and auditors

Key Metrics Tracked

Metric	Description	Target
Cyber Health Score	Overall security posture (0-100)	80+
Critical Findings	High-priority vulnerabilities	0
Remediation Rate	Issues resolved per month	90%+
Risk Trend	90-day score change	Positive

ROI Calculator

Before TrustOS:

• Annual security consulting: $50,000
• Breach risk: 15% chance × $200,000 avg cost = $30,000 expected loss
• Total: $80,000/year

After TrustOS:

• TrustOS subscription: $288,000/year
• Breach risk reduction: 5% chance × $200,000 = $10,000 expected loss
• Insurance premium savings: $15,000/year
• Net cost: $263,000/year

Value: Professional-grade security with measurable ROI

---

For Developers

Tech Stack Details

Layer	Technology	Purpose
Frontend	Next.js 16	React framework with App Router
Frontend	TypeScript	Type-safe JavaScript
Frontend	Tailwind CSS	Utility-first CSS framework
Frontend	shadcn/ui	Pre-built UI components
Backend	FastAPI	Modern Python web framework
Backend	SQLAlchemy 2.0	Async ORM for database
Backend	PostgreSQL	Relational database
Backend	Alembic	Database migration tool
AI	OpenAI/Anthropic	LLM for risk translation
Infra	Docker	Containerization
Infra	Docker Compose	Multi-container orchestration

Development Workflow

graph TD
    Start[Start Development] --> Clone[Clone Repository]
    Clone --> SetupEnv[Setup Environment]
    SetupEnv --> BackendSetup[Backend Setup]
    SetupEnv --> FrontendSetup[Frontend Setup]
    BackendSetup --> InstallDeps[Install Dependencies]
    FrontendSetup --> NPMInstall[npm install]
    InstallDeps --> ConfigEnv[Configure .env]
    NPMInstall --> ConfigFrontend[Configure .env.local]
    ConfigEnv --> SeedDB[Seed Database]
    ConfigFrontend --> StartDev[Start Dev Servers]
    SeedDB --> StartDev
    StartDev --> DevLoop[Development Loop]
    DevLoop --> Test[Write Tests]
    Test --> Commit[Commit Changes]
    Commit --> Push[Push to Git]
    
    style Start fill:#e8f5e9
    style DevLoop fill:#fff3e0
    style Test fill:#e3f2fd

Key Design Patterns

• Repository Pattern: Database access through service layer
• Dependency Injection: FastAPI dependencies for database, auth
• Async/Await: Non-blocking I/O throughout
• JWT Authentication: Stateless token-based auth
• Multi-Tenant: Tenant isolation at all layers
• RBAC: Role-based access control

API Response Times

Endpoint	Expected Response Time	SLA
Login	< 500ms	99.9%
Dashboard	< 1s	99.5%
Findings List	< 500ms	99.5%
Finding Detail	< 300ms	99.9%
Report Generation	< 30s	95%

---

Features

Current Implementation (Phase 1)

Executive Dashboard

• Cyber Health Score - 0–100 gauge showing overall security posture
• Top 3 Risks - AI-translated business impact for critical vulnerabilities
• Risk Trend Visualization - 90-day history showing improvement or decline
• Baseline Comparison - Compare current state against audit baseline

Findings Management

• Comprehensive Finding Database - CVEs, cloud misconfigurations, credential exposures
• AI Risk Translation - Plain-English explanations for every technical finding
• Remediation Tracking - Kanban-style board: Open → In Progress → Resolved → Verified
• Asset Ownership - Assign findings to team members with due dates

Digital Footprint Center

• Executive Exposure Monitoring - Publicly available information about leadership
• Domain/Asset Exposure - Exposed subdomains, misconfigured DNS, certificate issues
• Breach Intelligence - Leaked credentials from public breach databases

Authentication & Access Control

• Multi-Tenant Architecture - Complete data isolation between organizations
• Role-Based Access Control - Executive, IT Admin, TrustOS Admin roles
• JWT Authentication - Secure token-based sessions

Reporting

• Vault Audit Reports - Branded PDF exports with executive summaries
• Baseline Snapshots - Point-in-time assessments for comparison
• Board-Ready Formatting - Professional layouts for stakeholders

Advanced Features (Phase 2 - NEW)

AI-Powered Intelligence

• ✅ AI Finding Translation - Automated conversion of technical vulnerabilities to business language (OpenAI/Anthropic)
• ✅ Attack Path Visualization - Graph-based attack vector diagrams with nodes and edges
• ✅ AI Security Coach - Interactive Q&A system for questions about specific findings
• ✅ PDF Report Generation - Professional PDF exports with findings, scores, and metrics
• ✅ Mock AI System - Demo mode functional without API keys, ready for production API integration

Advanced Remediation

• Attack Path Analysis - Understand how attackers would reach sensitive data
• Remediation Priority - AI-suggested fix sequences based on exploit complexity
• Impact Quantification - Estimated business cost of each security issue

Planned Features (Phase 3)

• Continuous Monitoring Engine - Daily automated assessments
• Executive Protection Services - Enhanced monitoring for leadership
• Advanced Integrations - Cloud APIs, SIEM connectors, threat intelligence feeds
• Workflow Automation - Auto-remediation for certain findings
• Executive Briefing Generator - Automated executive summaries

---

Architecture

TrustOS follows a modern, scalable architecture designed for security and performance:

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend Layer                          │
│  Next.js 16 + TypeScript + Tailwind CSS + shadcn/ui             │
│  - Executive Dashboard                                           │
│  - Findings Management                                            │
│  - Digital Footprint Center                                      │
│  - Report Generation                                             │
└────────────────────┬────────────────────────────────────────────┘
                     │ HTTPS / REST API
┌────────────────────▼────────────────────────────────────────────┐
│                         API Layer                                │
│  FastAPI + Pydantic + SQLAlchemy 2.0                             │
│  - Authentication & Authorization                               │
│  - Business Logic Services                                      │
│  - AI Integration Layer                                          │
│  - Risk Calculator                                               │
│  - Report Generator                                              │
└────────────────────┬────────────────────────────────────────────┘
                     │ Async PostgreSQL
┌────────────────────▼────────────────────────────────────────────┐
│                      Database Layer                             │
│  PostgreSQL 16 + Alembic Migrations                              │
│  - Tenants, Users, Assets, Findings                             │
│  - Risk Scores, Attack Paths, Audit Reports                      │
│  - Executives, Authorized Assets                                │
└─────────────────────────────────────────────────────────────────┘

External Integrations:
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ OpenAI API   │  │ Anthropic API│  │ HIBP API     │  │ NVD API      │
│ (AI Translation)│ (AI Coach)   │  │ (Breach Data)│  │ (CVE Data)   │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘

Key Design Principles

• Authorization First - Only scan explicitly authorized assets
• Multi-Tenant Isolation - Complete data separation at database and API levels
• Privacy by Design - Executive monitoring requires explicit organizational authorization
• AI-Augmented, Not AI-Dependent - Graceful degradation when AI is unavailable
• Audit Trail - All changes tracked with timestamps and user attribution

---

Tech Stack

Frontend

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Components: shadcn/ui (Radix UI primitives)
• Charts: Recharts
• State Management: React Context + Hooks
• HTTP Client: Native fetch with custom API wrapper

Backend

• Framework: FastAPI
• Language: Python 3.10+
• ORM: SQLAlchemy 2.0 (async)
• Database: PostgreSQL 16
• Authentication: JWT (python-jose)
• Password Hashing: Passlib (bcrypt)
• Task Queue: Celery + Redis (planned)
• Scheduler: APScheduler

AI/ML

• Primary Provider: OpenAI GPT-4o-mini
• Alternative: Anthropic Claude 3 Haiku
• Use Cases: Risk translation, attack path generation, security coach

Infrastructure

• Containerization: Docker + Docker Compose
• Reverse Proxy: Nginx (production)
• Process Manager: Uvicorn (ASGI server)
• Database Migrations: Alembic
• PDF Generation: WeasyPrint + Jinja2

---

Project Structure

trustos/
├── frontend/                      # Next.js frontend application
│   ├── src/
│   │   ├── app/                   # Next.js App Router pages
│   │   │   ├── dashboard/         # Executive dashboard
│   │   │   ├── findings/         # Findings management
│   │   │   ├── login/            # Authentication
│   │   │   └── page.tsx          # Root redirect
│   │   ├── components/           # Reusable React components
│   │   ├── hooks/                # Custom React hooks
│   │   │   └── useAuth.ts        # Authentication state
│   │   └── lib/                  # Utility functions
│   │       └── api.ts            # API client
│   ├── public/                   # Static assets
│   ├── package.json              # Dependencies
│   ├── tailwind.config.ts        # Tailwind configuration
│   ├── tsconfig.json             # TypeScript configuration
│   └── next.config.js            # Next.js configuration
│
├── backend/                       # FastAPI backend application
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/           # API endpoints
│   │   │       ├── auth.py       # Authentication
│   │   │       ├── dashboard.py  # Dashboard data
│   │   │       ├── findings.py   # Findings CRUD
│   │   │       ├── reports.py    # Audit reports
│   │   │       ├── attack_paths.py # Attack visualization
│   │   │       ├── footprint.py  # Digital footprint
│   │   │       └── ai.py         # AI endpoints
│   │   ├── core/
│   │   │   ├── config.py         # Configuration settings
│   │   │   └── security.py       # Auth & security utilities
│   │   ├── db/
│   │   │   └── session.py        # Database session
│   │   ├── models/
│   │   │   └── models.py         # SQLAlchemy ORM models
│   │   ├── schemas/
│   │   │   └── schemas.py        # Pydantic schemas
│   │   ├── services/
│   │   │   ├── ai_translator.py  # AI translation service
│   │   │   ├── risk_calculator.py # Risk scoring
│   │   │   └── report_generator.py # PDF generation
│   │   ├── workers/              # Background tasks
│   │   └── main.py               # FastAPI application entry
│   ├── alembic/                  # Database migrations
│   │   ├── versions/             # Migration files
│   │   ├── env.py                # Alembic environment
│   │   └── script.py.mako        # Migration template
│   ├── tests/                    # Backend tests
│   ├── requirements.txt          # Python dependencies
│   ├── seed.py                   # Demo data seeding
│   ├── alembic.ini               # Alembic configuration
│   └── .env.example              # Environment template
│
├── infra/                         # Infrastructure configuration
│   ├── docker-compose.yml        # Local development stack
│   ├── Dockerfile.backend        # Backend container
│   └── Dockerfile.frontend       # Frontend container
│
├── docs/                          # Additional documentation
│   ├── ARCHITECTURE.md           # Detailed architecture docs
│   ├── API.md                    # API reference
│   ├── DEPLOYMENT.md             # Deployment guide
│   └── CONTRIBUTING.md          # Contribution guidelines
│
├── trustos-plan.md               # Detailed build plan and stages
├── README.md                     # This file
└── .gitignore                    # Git ignore rules

---

Quick Start

Setup Flow

graph LR
    A[Clone Repo] --> B[Configure .env]
    B --> C[Start Docker Compose]
    C --> D[Seed Database]
    D --> E[Access Application]
    
    style A fill:#e8f5e9
    style B fill:#fff3e0
    style C fill:#e3f2fd
    style D fill:#f3e5f5
    style E fill:#fce4ec

Prerequisites

Ensure you have the following installed:

• Docker 20.10+ and Docker Compose 2.0+
• Git for version control
• Python 3.10+ (for local development)
• Node.js 18+ and npm 9+ (for local development)
• PostgreSQL 16+ (if not using Docker)

Docker Compose Setup (Recommended)

This is the fastest way to get TrustOS running locally with all dependencies.

1. Clone the repository

   git clone https://gitea.thetempleofdoom.com/drjones/trustos.git
   cd trustos
   

2. Configure environment variables

   cp backend/.env.example backend/.env
   

   Edit backend/.env and configure at minimum:

   # Database (Docker Compose handles this)
   DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@postgres:5432/trustos
   SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@postgres:5432/trustos
   
   # Auth - CHANGE THIS IN PRODUCTION
   SECRET_KEY=changeme-use-openssl-rand-hex-32-in-production
   
   # AI - Optional for demo (features work without it)
   OPENAI_API_KEY=sk-...
   AI_PROVIDER=openai
   

3. Start all services

   cd infra
   docker-compose up --build
   

   This will start:

   • PostgreSQL database on port 5432
   • FastAPI backend on port 8000
   • Next.js frontend on port 3000

4. Initialize the database with demo data

   In a new terminal:

   cd backend
   docker-compose exec backend python seed.py
   

5. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • ReDoc Documentation: http://localhost:8000/redoc

Demo Credentials

The seed script creates a demo tenant "Acme Corp" with three users:

Role	Email	Password
Executive (CEO)	executive@acmecorp.io	TrustOS2024!
IT Admin	it@acmecorp.io	TrustOS2024!
TrustOS Admin	admin@trustos.com	TrustOS-Admin-2024!

Testing AI Features

After logging in with any demo account, try these API endpoints to test the AI-powered features:

1. Get Dashboard

curl -X GET http://localhost:8000/api/v1/dashboard/acme-corp-demo-001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns: Cyber health score, critical issues count, top risks

2. Trigger AI Finding Translation

curl -X POST http://localhost:8000/api/v1/findings/{finding_id}/ai-translate \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: Translation queued (processes asynchronously)

3. Ask AI Security Coach

curl -X POST http://localhost:8000/api/v1/findings/{finding_id}/ai-question \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question":"What are the main risks of this vulnerability?"}'

Returns: AI-generated answer about the finding

4. Generate Attack Path

curl -X POST http://localhost:8000/api/v1/attack-paths/{finding_id}/generate \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: Path generation queued (generates attack vectors)

5. Retrieve Attack Graph

curl http://localhost:8000/api/v1/attack-paths/{finding_id} \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Returns: Graph nodes and edges showing attack vectors

6. Download PDF Report

curl -X POST http://localhost:8000/api/v1/audit-reports/acme-corp-demo-001/pdf-snapshot \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o report.pdf

Downloads: Professional PDF report with findings and scores

Note: AI features work without OpenAI/Anthropic API keys using mock data. Set OPENAI_API_KEY or ANTHROPIC_API_KEY in .env for real AI translations.

Stopping the Services

cd infra
docker-compose down

To remove volumes (delete database data):

docker-compose down -v

---

Development Setup

For active development, it's often easier to run services natively rather than in Docker.

Backend Setup

1. Create a Python virtual environment

   cd backend
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your configuration
   

   Minimum required for local development:

   DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@localhost:5432/trustos
   SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@localhost:5432/trustos
   SECRET_KEY=dev-secret-key-change-in-production
   

4. Set up PostgreSQL

   Using Docker for just the database:

   docker run --name trustos-postgres \
     -e POSTGRES_USER=trustos \
     -e POSTGRES_PASSWORD=trustos_dev \
     -e POSTGRES_DB=trustos \
     -p 5432:5432 \
     -d postgres:16
   

5. Initialize the database

   python seed.py
   

6. Run the backend server

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

   The API will be available at http://localhost:8000

Frontend Setup

1. Install dependencies

   cd frontend
   npm install
   

2. Configure environment variables

   Create .env.local (this file is git-ignored):

   NEXT_PUBLIC_API_URL=http://localhost:8000
   

3. Run the development server

   npm run dev
   

   The frontend will be available at http://localhost:3000

Development Workflow

1. Make changes to frontend or backend code
2. Backend auto-reloads with --reload flag
3. Frontend hot-reloads automatically
4. Access API docs at http://localhost:8000/docs to test endpoints

---

Configuration

Backend Environment Variables

See backend/.env.example for the complete list. Key variables:

Database

DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@postgres:5432/trustos
SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@postgres:5432/trustos

Authentication

# IMPORTANT: Generate a secure random key in production using: openssl rand -hex 32
# Never use the default value in production environments
SECRET_KEY=changeme-use-openssl-rand-hex-32-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=480

AI Configuration

AI_PROVIDER=openai  # or 'anthropic'
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

External APIs

HIBP_API_KEY=...  # Have I Been Pwned for breach data
NVD_API_KEY=...   # National Vulnerability Database

Storage

STORAGE_PATH=/app/storage  # Path for PDF reports and uploads

Email (Optional)

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=...
SMTP_PASSWORD=...
SMTP_FROM=noreply@trustos.com

Frontend Environment Variables

NEXT_PUBLIC_API_URL=http://localhost:8000

For production:

NEXT_PUBLIC_API_URL=https://api.trustos.com

---

Database Migrations

TrustOS uses Alembic for database schema management. In development, tables are auto-created on startup for convenience. For production, always use migrations.

Creating a New Migration

cd backend
alembic revision --autogenerate -m "Description of changes"

Applying Migrations

alembic upgrade head

Rolling Back

alembic downgrade -1

Migration Best Practices

• Always review auto-generated migrations before committing
• Write descriptive migration messages
• Test migrations on a copy of production data
• Never modify existing migrations after they're applied

---

Testing

Backend Tests

cd backend
pytest

Run with coverage:

pytest --cov=app --cov-report=html

Run specific test file:

pytest tests/test_auth.py

Frontend Tests

cd frontend
npm test

Run with coverage:

npm test -- --coverage

Manual Testing

1. API Testing: Use the interactive Swagger UI at http://localhost:8000/docs
2. Frontend Testing: Log in with demo credentials and explore features
3. Integration Testing: Use Docker Compose for full-stack testing

---

Deployment

Production Checklist

Before deploying to production, ensure you have:

• Changed SECRET_KEY to a cryptographically secure random value (openssl rand -hex 32)
• Set strong database passwords
• Configured production database (Supabase, RDS, Neon, etc.)
• Enabled HTTPS/TLS with valid certificates
• Set up proper CORS origins (restrict to your domain)
• Configured AI API keys with appropriate rate limits
• Set up logging and monitoring (Sentry, Datadog, etc.)
• Enabled automated database backups
• Reviewed and updated security headers
• Run Alembic migrations instead of auto-create tables
• Configured environment-specific variables
• Set up CI/CD pipeline
• Configured error tracking
• Set up health check endpoints

Deployment Options

Option 1: Railway (Recommended for simplicity)

Railway supports both PostgreSQL and containerized apps.

1. Connect your GitHub repository to Railway
2. Create a PostgreSQL service
3. Create a backend service (Dockerfile)
4. Create a frontend service (Dockerfile)
5. Add environment variables in Railway dashboard
6. Deploy

Option 2: Render

Render offers PostgreSQL and container hosting.

1. Create a PostgreSQL database on Render
2. Connect backend to Render PostgreSQL
3. Deploy backend as a web service
4. Deploy frontend as a static site
5. Configure environment variables

Option 3: VPS (DigitalOcean, Linode, AWS EC2)

For full control:

1. Set up a VPS with Ubuntu 22.04+
2. Install Docker and Docker Compose
3. Clone repository
4. Configure production .env file
5. Use nginx as reverse proxy
6. Set up SSL with Let's Encrypt
7. Run docker-compose up -d

See docs/DEPLOYMENT.md for detailed VPS deployment instructions.

Environment-Specific Configurations

Development:

• Auto-create tables on startup
• Debug mode enabled
• CORS allowed from localhost
• Logging to console

Production:

• Use Alembic migrations
• Debug mode disabled
• CORS restricted to specific domains
• Logging to file/external service
• Rate limiting enabled

---

Documentation

Project Documentation

• ARCHITECTURE.md - Detailed system architecture, data flow, and design decisions
• API.md - Complete API reference with examples
• DEPLOYMENT.md - Production deployment guides
• CONTRIBUTING.md - Contribution guidelines and development standards

Business Documentation

• BUILD_PLAN.md - Multi-stage build plan and implementation roadmap
• BUSINESS_PLAN.md - Complete business plan, investor memo, and pitch deck outline

API Documentation

When the backend is running, interactive API documentation is available:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

Security

Security Architecture

TrustOS implements defense-in-depth security:

1. Authentication: JWT-based stateless authentication
2. Authorization: Role-based access control (RBAC)
3. Multi-Tenant Isolation: Database-level tenant separation
4. Input Validation: Pydantic schemas for all inputs
5. SQL Injection Prevention: SQLAlchemy ORM with parameterized queries
6. XSS Prevention: React's built-in escaping
7. CSRF Protection: SameSite cookie attributes
8. Secure Headers: CORS, CSP, HSTS configured

Security Best Practices

• Never commit .env files or secrets to git
• Use strong, unique passwords for all services
• Rotate API keys regularly
• Enable audit logging in production
• Implement rate limiting on public endpoints
• Use HTTPS everywhere
• Keep dependencies updated
• Regular security audits
• Principle of least privilege for database users

Data Privacy

• Executive monitoring requires explicit organizational authorization
• All data is tenant-isolated
• No cross-tenant data access
• Audit trail for all data access
• GDPR-compliant data handling practices

---

Troubleshooting

Troubleshooting Flow

graph TD
    Start[Issue Detected] --> CheckLogs{Check Logs}
    CheckLogs -->|Error Message| IdentifyError[Identify Error Type]
    CheckLogs -->|No Error| CheckServices{Check Services}
    
    IdentifyError --> DBError{Database Error?}
    IdentifyError --> APIError{API Error?}
    IdentifyError --> FrontError{Frontend Error?}
    
    DBError -->|Yes| CheckDB[Check DB Connection]
    DBError -->|No| APIError
    
    APIError -->|Yes| CheckAuth[Check Auth Token]
    APIError -->|No| FrontError
    
    FrontError -->|Yes| CheckEnv[Check .env.local]
    FrontError -->|No| CheckServices
    
    CheckDB --> FixDB[Fix DATABASE_URL]
    CheckAuth --> FixAuth[Refresh Token]
    CheckEnv --> FixEnv[Set NEXT_PUBLIC_API_URL]
    
    CheckServices -->|All Running| Restart[Restart Services]
    CheckServices -->|Not Running| Start[Start Services]
    
    FixDB --> Test
    FixAuth --> Test[Test Fix]
    FixEnv --> Test
    Restart --> Test
    Start --> Test
    
    Test -->|Fixed| Done[Issue Resolved]
    Test -->|Not Fixed| Support[Contact Support]
    
    style Start fill:#fce4ec
    style Done fill:#e8f5e9
    style Support fill:#fff3e0

Common Issues

Backend won't start

Problem: ModuleNotFoundError: No module named 'app'

Solution: Ensure you're running from the backend directory:

cd backend
uvicorn app.main:app --reload

Database connection errors

Problem: could not connect to server: Connection refused

Solution:

• Ensure PostgreSQL is running
• Check DATABASE_URL in .env
• Verify database credentials

Frontend can't connect to backend

Problem: Network errors in browser console

Solution:

• Check NEXT_PUBLIC_API_URL in frontend .env.local
• Ensure backend is running on the expected port
• Check CORS configuration in backend

AI features not working

Problem: AI translations return empty or errors

Solution:

• Verify OPENAI_API_KEY or ANTHROPIC_API_KEY is set
• Check API key has credits/quota
• Review backend logs for specific error messages
• Features work without AI, just with raw technical data

Migration errors

Problem: alembic.util.exc.CommandError: Target database is not up to date

Solution:

alembic upgrade head

If that fails, you may need to resolve migration conflicts manually.

Getting Help

1. Check the logs: docker-compose logs or backend console output
2. Review API documentation at /docs
3. Check environment variable configuration
4. Verify all services are running
5. For persistent issues, contact the TrustOS development team

---

Contributing

We welcome contributions to TrustOS! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Write tests for new functionality
5. Ensure all tests pass: pytest and npm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Python: Follow PEP 8, use black for formatting
• TypeScript: Follow ESLint rules, use Prettier for formatting
• Commits: Use conventional commit messages
• Documentation: Update docs for any user-facing changes

---

License

Proprietary - All rights reserved

TrustOS is a commercial product. All rights are reserved by the copyright holders. Unauthorized copying, distribution, or use of this software is strictly prohibited.

---

Support

For technical issues, questions, or partnership inquiries:

• Email: support@trustos.com
• Documentation: https://docs.trustos.com
• Status Page: https://status.trustos.com

---

Acknowledgments

TrustOS is built with open-source technologies:

• Next.js - React framework
• FastAPI - Python web framework
• Tailwind CSS - CSS framework
• shadcn/ui - UI components
• PostgreSQL - Database
• OpenAI - AI services
• Anthropic - AI services

---

TrustOS — The AI Operating System for Cyber Resilience

Making cyber resilience simple, continuous, and understandable for every growing company.

Architecture

TrustOS is a full-stack application with the following components:

• Frontend: Next.js 16 (React) + TypeScript + Tailwind CSS + shadcn/ui
• Backend: Python (FastAPI) + SQLAlchemy 2.0 + Async PostgreSQL
• Database: PostgreSQL 16
• AI Layer: OpenAI GPT-4o-mini or Anthropic Claude 3 Haiku
• Deployment: Docker Compose (local), Railway/Render/VPS (production)

Project Structure

trustos/
├── frontend/          # Next.js frontend application
│   ├── src/
│   │   ├── app/      # Next.js App Router pages
│   │   ├── components/  # React components
│   │   ├── hooks/    # Custom React hooks
│   │   └── lib/      # Utility functions and API client
│   ├── package.json
│   └── tailwind.config.ts
├── backend/           # FastAPI backend application
│   ├── app/
│   │   ├── api/routes/   # API endpoints
│   │   ├── core/         # Configuration and security
│   │   ├── db/           # Database session
│   │   ├── models/       # SQLAlchemy models
│   │   ├── schemas/      # Pydantic schemas
│   │   ├── services/     # Business logic (AI, risk calculator, report generator)
│   │   └── workers/      # Background tasks
│   ├── alembic/          # Database migrations
│   ├── requirements.txt
│   ├── seed.py           # Demo data seeding script
│   └── .env.example
├── infra/              # Docker configuration
│   ├── docker-compose.yml
│   ├── Dockerfile.backend
│   └── Dockerfile.frontend
├── docs/               # Documentation
└── trustos-plan.md     # Detailed build plan and stages

Quick Start (Docker Compose)

Prerequisites

• Docker and Docker Compose installed
• Git

Setup

1. Clone the repository:

git clone <repository-url>
cd trustos

2. Copy environment files:

cp backend/.env.example backend/.env

3. Start all services:

cd infra
docker-compose up --build

4. Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Demo Credentials

The seed script creates a demo tenant "Acme Corp" with the following users:

• Executive (CEO): executive@acmecorp.io / TrustOS2024!
• IT Admin: it@acmecorp.io / TrustOS2024!
• TrustOS Admin: admin@trustos.com / TrustOS-Admin-2024!

Development Setup (Local)

Backend Setup

1. Create a Python virtual environment:

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Initialize the database:

python seed.py

5. Run the backend server:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

1. Install dependencies:

cd frontend
npm install

2. Set up environment variables:

cp .env.example .env.local
# Edit .env.local with NEXT_PUBLIC_API_URL=http://localhost:8000

3. Run the development server:

npm run dev

Database Migrations

TrustOS uses Alembic for database migrations. In development, tables are auto-created on startup. For production, use migrations:

cd backend
alembic revision --autogenerate -m "description"
alembic upgrade head

Key Features

Phase 1: Vault Audit (Current Implementation)

• Executive dashboard with Cyber Health Score
• Top 3 Risks with AI-translated business impact
• Risk trend visualization (90-day history)
• Findings management with remediation tracking
• Digital footprint center for executive exposure
• Multi-role authentication (Executive, IT Admin, TrustOS Admin)
• Vault Audit Report generation with PDF export

Phase 2: Monthly Monitoring (Planned)

• Continuous monitoring engine
• Daily automated assessments
• Certificate expiration monitoring
• CVE monitoring
• Cloud posture checks
• Breach intelligence integration

Phase 3: Full Platform (Planned)

• Attack path visualization
• AI Security Coach
• Executive protection services
• Board reporting
• Advanced integrations

Configuration

Backend Environment Variables

See backend/.env.example for the full list. Key variables:

• DATABASE_URL: PostgreSQL connection string (async)
• SECRET_KEY: JWT signing key (generate with openssl rand -hex 32)
• OPENAI_API_KEY or ANTHROPIC_API_KEY: For AI features
• AI_PROVIDER: openai or anthropic

Frontend Environment Variables

• NEXT_PUBLIC_API_URL: Backend API URL

Security Notes

• All API routes require authentication except /health and /api/v1/auth/login
• Multi-tenant isolation enforced at the database and API level
• Role-based access control (RBAC) for different user types
• Authorization-first approach: only scan explicitly authorized assets
• Secrets should never be committed to git (use .env files, ignored by git)

Testing

Run backend tests:

cd backend
pytest

Run frontend tests:

cd frontend
npm test

Deployment

Production Checklist

• Change SECRET_KEY to a cryptographically secure random value
• Set strong database passwords
• Configure production database (Supabase, RDS, etc.)
• Enable HTTPS/TLS
• Set up proper CORS origins
• Configure AI API keys with appropriate rate limits
• Set up logging and monitoring
• Enable database backups
• Review and update security headers
• Run Alembic migrations instead of auto-create tables

Documentation

• Business Plan: See readplan.txt for the complete business strategy
• Build Plan: See trustos-plan.md for detailed implementation stages
• API Documentation: Available at /docs when backend is running

License

Proprietary - All rights reserved

Support

For technical issues or questions, contact the TrustOS development team.