GigaChad GRC

A comprehensive, modular, containerized Governance, Risk, and Compliance (GRC) platform built with modern technologies. Manage your entire security program from compliance tracking to risk management, third-party assessments, and external audits.

---

Quick Start

Prerequisites

Requirement	Minimum	Notes
Docker Desktop	v4.0+	Download for Mac / Windows (requires WSL 2) / Linux: curl -fsSL https://get.docker.com | sh
RAM	8 GB	16 GB recommended
CPU	4 cores	8 cores recommended
Disk	10 GB free	20 GB recommended

No Node.js, npm, or other development tools required. Everything runs inside Docker containers.

Start the Platform

git clone https://github.com/grcengineering/gigachad-grc.git
cd gigachad-grc
./start.sh

Windows users: Run start.bat instead.

./start.sh handles everything automatically:

1. Checks that Docker is installed and running
2. Generates a .env file with secure random secrets (if one doesn't exist)
3. Builds and starts all containers with docker compose up
4. Opens your browser to http://localhost:3000

First run takes 3-5 minutes while Docker builds the images. Subsequent starts take ~30 seconds.

Log In

When the browser opens to http://localhost:3000, click the "Dev Login" button. No username or password needed. This bypasses Keycloak SSO and uses a local development account.

Important: The Dev Login button only appears when VITE_ENABLE_DEV_AUTH=true is set in your .env file. The ./start.sh script sets this automatically. If you created your .env manually, you must add this variable yourself.

Manage the Platform

Command	Description
./start.sh	Start the platform
./start.sh stop	Stop all services
./start.sh logs	View live logs
./start.sh status	Check service health
./start.sh reset	Stop and remove all containers and volumes

---

Manual Setup (Alternative)

If you prefer to run docker compose directly instead of using ./start.sh, you must create a valid .env file first. The .env.example file contains placeholder values that will not work as-is.

Step 1: Generate Secrets and Create .env

cp .env.example .env

Then replace every placeholder value in .env with real secrets:

# Generate and replace ENCRYPTION_KEY
openssl rand -hex 32

# Generate and replace JWT_SECRET, SESSION_SECRET
openssl rand -base64 64

# Generate and replace POSTGRES_PASSWORD, REDIS_PASSWORD,
# MINIO_ROOT_PASSWORD, GRAFANA_ADMIN_PASSWORD,
# KEYCLOAK_ADMIN_PASSWORD, PHISHING_TRACKING_SECRET
openssl rand -base64 24

After generating your POSTGRES_PASSWORD, update the DATABASE_URL to match:

DATABASE_URL=postgresql://grc:YOUR_GENERATED_PASSWORD@localhost:5433/gigachad_grc

Set VITE_ENABLE_DEV_AUTH=true to enable the Dev Login button (required for local use without Keycloak HTTPS).

Step 2: Required Environment Variables

Docker Compose will refuse to start if any of these variables are missing or empty:

Variable	Description	Example Value
POSTGRES_USER	Database username	grc
POSTGRES_PASSWORD	Database password	(generate with openssl)
REDIS_PASSWORD	Redis password	(generate with openssl)
MINIO_ROOT_USER	RustFS/S3 storage username	rustfsadmin
MINIO_ROOT_PASSWORD	RustFS/S3 storage password	(generate with openssl)
KEYCLOAK_ADMIN_PASSWORD	Keycloak admin password	(generate with openssl)
ENCRYPTION_KEY	AES encryption key (64 hex chars)	(generate with openssl)
PHISHING_TRACKING_SECRET	Phishing module signing secret	(generate with openssl)
GRAFANA_ADMIN_USER	Grafana admin username	admin
GRAFANA_ADMIN_PASSWORD	Grafana admin password	(generate with openssl)

Step 3: Start

docker compose up -d --build

Wait 2-3 minutes on first run, then open http://localhost:3000.

---

Troubleshooting

GRAFANA_ADMIN_USER is required or GRAFANA_ADMIN_PASSWORD is required

Your .env file is missing Grafana credentials. Add:

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=your_secure_password

Or use ./start.sh which generates these automatically.

Page redirects to localhost:8080/realms/gigachad-grc/... and fails

Keycloak requires HTTPS, which is not available in local Docker development. The fix is to use Dev Login mode instead:

1. Set VITE_ENABLE_DEV_AUTH=true in your .env
2. Rebuild the frontend: docker compose up -d --build frontend
3. Open http://localhost:3000 and use the "Dev Login" button

The ./start.sh script enables this automatically.

Cannot access 'N' before initialization (recharts error)

This was a Vite code-splitting issue that has been fixed. Pull the latest code:

git pull origin main
./start.sh

Port already in use

Another process is using one of the required ports. Check with:

# macOS/Linux
lsof -i :3000

# Stop existing GigaChad containers
./start.sh stop

Docker is not running

Cannot connect to the Docker daemon

Start Docker Desktop and wait for it to fully initialize before running ./start.sh.

Resetting everything

To completely reset (removes all data, volumes, and containers):

docker compose down -v
./start.sh

Warning: docker compose down -v deletes all database data, evidence files, and cached sessions. Run backups first if you have data to preserve.

---

Access Points

Service	URL	Credentials
Frontend	http://localhost:3000	Click "Dev Login"
Controls API	http://localhost:3001/api/docs	Swagger UI
Frameworks API	http://localhost:3002/api/docs	Swagger UI
Grafana	http://localhost:3003	Set in .env
Policies API	http://localhost:3004/api/docs	Swagger UI
TPRM API	http://localhost:3005/api/docs	Swagger UI
Trust API	http://localhost:3006/api/docs	Swagger UI
Audit API	http://localhost:3007/api/docs	Swagger UI
Keycloak Admin	http://localhost:8080	Set in .env
Traefik Dashboard	http://localhost:8090	None
RustFS Console	http://localhost:9001	Set in .env
Prometheus	http://localhost:9090	None
PostgreSQL	localhost:5433	Set in .env
Redis	localhost:6380	Set in .env

---

System Requirements

Minimum (development/demo)

• Docker Desktop 4.0+
• 8 GB RAM, 4 CPU cores, 10 GB disk
• macOS, Windows (WSL 2), or Linux

Recommended (development)

• 16 GB RAM, 8 cores, 20 GB disk
• SSD storage for faster Docker builds

Production

See the Deployment Guide and Production Deployment Checklist.

---

Platform Overview

GigaChad GRC is a complete enterprise GRC solution organized into specialized modules:

Module	Description
Compliance	Controls library, framework readiness (SOC 2, ISO 27001, NIST CSF, PCI DSS, HIPAA), evidence collection, cross-framework mapping
Risk Management	Risk register, likelihood/impact scoring, heatmaps, treatment tracking, scenario modeling, risk workflows
Policies	Policy lifecycle management with versioning, approval workflows, review scheduling
Third-Party Risk (TPRM)	Vendor management, security assessments, contract lifecycle, SLA tracking
Trust	Security questionnaires, knowledge base, public-facing trust center portal
Audit	Internal/external audit management, evidence requests, findings, auditor portal, FieldGuide integration
Tools	Security awareness training, phishing simulations, certificate management
AI & Automation	AI-powered risk scoring, auto-categorization, smart search, MCP server integration
Integrations	AWS, Azure, GitHub, Okta, Google Workspace, Jamf, and 40+ connectors for automated evidence collection
Administration	User management, RBAC, audit logging, risk configuration, system health monitoring

For detailed module documentation including API endpoints, see the API Reference.

---

Architecture

                           ┌─────────────────────────────────┐
                           │       Traefik API Gateway       │
                           │         (Ports 80/443)          │
                           └──────────┬──────────────────────┘
                                      │
          ┌───────────┬───────────┬────┴────┬───────────┬───────────┬───────────┐
          │           │           │         │           │           │           │
     Controls    Frameworks   Policies    TPRM       Trust       Audit     Frontend
      :3001        :3002       :3004     :3005      :3006       :3007       :3000
          │           │           │         │           │           │
          └───────────┴───────────┴────┬────┴───────────┴───────────┘
                                       │
                              Shared Library
                    (Prisma, Auth, Storage, Events, Types)
                                       │
               ┌───────────┬───────────┼───────────┐
               │           │           │           │
          PostgreSQL     Redis     Keycloak     RustFS
            :5433        :6380      :8080     :9000/:9001

Tech Stack

• Backend: Node.js 20 + TypeScript with NestJS
• Frontend: React + TypeScript with Vite, TailwindCSS
• Database: PostgreSQL 16 with Prisma ORM
• Authentication: Keycloak (SSO, RBAC) with dev-mode bypass
• API Gateway: Traefik v3
• Cache: Redis
• Storage: RustFS (S3-compatible, Apache 2.0 -- github.com/rustfs/rustfs)
• Monitoring: Prometheus + Grafana
• Containers: Docker with Docker Compose

---

Documentation

Getting Started

Document	Description
Getting Started Guide	Complete setup guide with screenshots for all skill levels
Quick Start Guide	Fast-track setup for experienced users
Demo & Sandbox	One-click demo setup with sample data
Troubleshooting	Common issues and solutions

Core Documentation

Document	Description
Architecture Guide	System architecture, API gateway, microservices, network topology
API Reference	Complete API documentation with endpoints and examples
Configuration Reference	Environment variables, service configuration, database
Development Guide	Local setup, project structure, coding standards, testing
Deployment Guide	Production deployment, CI/CD, monitoring, backups
Database Schema	All Prisma models, enums, and entity relationships
Shared Library	Auth, storage, events, utils, and shared types

Security

Document	Description
Security Policy	Vulnerability reporting and policies
Security Model	Authentication, authorization, and hardening
Permissions Matrix	Role-based access control definitions

Operations

Document	Description
Environment Configuration	Detailed environment variable reference
Module Configuration	Enable/disable platform modules
Production Deployment	Production-ready deployment checklist
Remote Deployment	Deploying on remote servers, VMs, or LAN
Monitoring	Prometheus + Grafana setup

---

Project Structure

gigachad-grc/
├── frontend/                 # React SPA (Vite + TailwindCSS)
├── services/
│   ├── shared/               # Shared library (Prisma, auth, storage, types)
│   ├── controls/             # Controls, evidence, integrations, risk, audit logging
│   ├── frameworks/           # Framework assessments and readiness
│   ├── policies/             # Policy lifecycle management
│   ├── tprm/                 # Vendor risk, assessments, contracts
│   ├── trust/                # Questionnaires, knowledge base, trust center
│   └── audit/                # Audit management, findings, auditor portal
├── mcp-servers/              # MCP server integrations (evidence, compliance, AI)
├── gateway/                  # Traefik API gateway configuration
├── monitoring/               # Prometheus + Grafana configuration
├── deploy/                   # Production deployment configs
├── terraform/                # Infrastructure as Code
├── docker-compose.yml        # Container orchestration
├── .env.example              # Environment variable template
├── start.sh                  # One-command startup script
└── start.bat                 # Windows startup script

---

License

This project is licensed under the Elastic License 2.0 (ELv2).

You CAN: Use internally for commercial purposes, modify for your own use, self-host, contribute improvements.

You CANNOT: Offer as a hosted/managed service, sell the software, create a competing commercial product, remove license notices.

See LICENSE for complete terms.

Contributing

We welcome contributions. Please read the Contributing Guide and Code of Conduct.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the coding standards
4. Run tests (npm test)
5. Submit a pull request

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report vulnerabilities