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.

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.