RoleFlux

AI-Powered GCP Cloud Detection & Response (CDR) Platform

RoleFlux is a 100% serverless, event-driven CDR platform that intercepts real-time Google Cloud (GCP) Audit Logs, evaluates them through a deterministic Python detection engine, maps threats to MITRE ATT&CK, and leverages Vertex AI (Gemini) to generate human-readable SOC Incident Reports.

---

Core Features

• "Detection Engine First, AI Second" Architecture: Avoids LLM hallucinations by using a strict, deterministic Python engine to calculate Risk Scores (0-100) before ever involving AI.
• 100% Serverless & Event-Driven: Deployed entirely on GCP using Pub/Sub, Log Sinks, and Cloud Functions (Gen2). Zero servers to manage.
• MITRE ATT&CK Mapping: Automatically maps detected anomalous IAM activity to specific MITRE tactics (e.g., T1098 - Account Manipulation).
• Vertex AI (Gemini) Triage: Generates sharp, 2-sentence executive summaries and provides exact gcloud remediation commands for the responding engineer.
• Next.js Command Center: A premium, dark-themed dashboard connecting directly to a BigQuery data lake for real-time threat visualization.
• Built-in Attack Simulator: Comes with a Purple Teaming Python suite to safely simulate and inject fake GCP attacks into the pipeline for testing.
• DevSecOps Ready: Includes a GitHub Actions CI/CD pipeline with Terraform Workspaces (Staging/Prod) and Keyless Workload Identity Federation.

---

Architecture

1. GCP Cloud Audit Logs capture Admin Activity (e.g., SetIamPolicy).
2. Log Router Sink filters for critical IAM events and pushes them to a Pub/Sub Topic.
3. Cloud Functions (Python) pulls the log, runs deterministic rules, scores the risk, and queries Vertex AI.
4. The structured incident report is saved to a BigQuery Data Lake.
5. Critical alerts are pushed instantly to a Slack Webhook.
6. The Next.js Dashboard queries BigQuery to visualize the environment.

---

Getting Started

Prerequisites

• Google Cloud Platform (GCP) Project with billing enabled
• Terraform installed (v1.5+)
• Python 3.11+
• Node.js 18+ (for Dashboard)
• gcloud CLI installed and authenticated

1. Quick Bootstrap

We provide a setup script to initialize your local Python virtual environment and install dependencies.

chmod +x setup.sh
./setup.sh

2. Infrastructure Deployment (Terraform)

RoleFlux uses Terraform workspaces to manage Staging and Production environments.

cd terraform/
terraform init

# Create and select a workspace
terraform workspace new prod

# Deploy the infrastructure
terraform apply -var="project_id=YOUR_PROJECT_ID" -var="environment=prod" -var="slack_webhook_url=YOUR_SLACK_WEBHOOK"

3. Running the Dashboard

cd dashboard/web
npm install
npm run dev

Navigate to http://localhost:3000 to view the Command Center.

4. Simulating Attacks (Purple Teaming)

Generate realistic, mock GCP Audit Logs to test the detection engine.

source venv/bin/activate
python3 attack-simulator/run_simulation.py

---

Screenshots in Action

The Command Center Dashboard

Live visualization of threats querying directly from BigQuery

Alerts & Investigations

Deep dive into JSON payloads and MITRE ATT&CK mappings

AI Triage & Slack Integration

Real-time Gemini SOC Analyst generating exact `gcloud` remediation commands

Purple Team Attack Simulator

Injecting realistic GCP Audit Logs straight from the CLI

---

Contributing

We welcome contributions from the community! Whether it's adding new detection rules, improving the UI, or expanding to AWS/Azure.

Please see our CONTRIBUTING.md for detailed guidelines on how to submit pull requests, report issues, and set up your local development environment.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Engineered with Security in Mind by Mohamed Medjahdi