Fix code issues and add missing documentation
- Fix duplicate tenant_id parameter in seed.py (line 148) - Add security warning to SECRET_KEY in .env.example - Create comprehensive README.md with setup instructions - Add Alembic configuration files (alembic.ini, env.py, script.py.mako) - Create initial database migration for all tables - Document project structure, features, and deployment checklist
This commit is contained in:
drjones
240
README.md
Normal file
240
README.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd trustos
|
||||
```
|
||||
|
||||
2. Copy environment files:
|
||||
```bash
|
||||
cp backend/.env.example backend/.env
|
||||
```
|
||||
|
||||
3. Start all services:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
cd backend
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Set up environment variables:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your configuration
|
||||
```
|
||||
|
||||
4. Initialize the database:
|
||||
```bash
|
||||
python seed.py
|
||||
```
|
||||
|
||||
5. Run the backend server:
|
||||
```bash
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### Frontend Setup
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Set up environment variables:
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
# Edit .env.local with NEXT_PUBLIC_API_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
3. Run the development server:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Database Migrations
|
||||
|
||||
TrustOS uses Alembic for database migrations. In development, tables are auto-created on startup. For production, use migrations:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
cd backend
|
||||
pytest
|
||||
```
|
||||
|
||||
Run frontend tests:
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user