AI-native hybrid cybersecurity platform unifying recon, scanning, AI analysis, reporting, collaboration, and local-agent execution across STATIC, DYNAMIC, and LOCAL operation modes.
⚠️ Authorized & Ethical Use Only. CosmicSec is designed exclusively for ethical cybersecurity research, authorized penetration testing, and blue-team training. See LICENSE for full terms.
CosmicSec is a hybrid, AI-powered cybersecurity intelligence platform that unifies vulnerability scanning, recon, threat analysis, reporting, and team collaboration into a single, modern platform built on microservices.
It serves multiple user modes via a single intelligent gateway — see the active mode and delivery plan in ROADMAP.md for the current picture:
| Mode | User | Runs On | Access |
|---|---|---|---|
STATIC |
Public / Unregistered | Server (pre-rendered) | Landing, feature demo, guest sandbox |
DYNAMIC |
Registered Dashboard User | Cloud / self-hosted | Full dashboard, real-time scans, AI, reports |
LOCAL |
CLI / Local-Agent User | User's own machine | Terminal agent, local tool orchestration, optional cloud sync |
LOCAL_WEB |
Isolated browser user | Local server | Full web UI with zero cloud egress |
| + more | Mobile, Desktop, SDK, ChatOps | Various | See roadmap for planned modes |
| Category | Capabilities |
|---|---|
| 🛡️ Hybrid Architecture | HybridRouter: STATIC / DYNAMIC / LOCAL / DEMO / EMERGENCY modes via one gateway |
| 🤖 AI-Powered Analysis | LangChain + LangGraph workflows, MITRE ATT&CK mapping, zero-day prediction, RAG knowledge base |
| 🔍 Recon Engine | DNS enum, Shodan, VirusTotal, crt.sh, RDAP, passive OSINT |
| 📡 Distributed Scanning | Multi-engine scanner (nmap, nikto, nuclei), Celery tasks, smart orchestration, continuous monitoring |
| 📊 Rich Reporting | PDF, DOCX, JSON, CSV, HTML; SOC 2, PCI-DSS, HIPAA templates; topology/heatmap/attack-path viz |
| 👥 Team Collaboration | Real-time WebSocket rooms, presence, @mentions, threaded edits |
| 🔌 Plugin Ecosystem | Plugin SDK + official plugins (nmap, metasploit, Jira, Slack, report exporters) |
| 🔐 Enterprise Auth | JWT, OAuth2, TOTP/2FA, Casbin RBAC, per-user rate limiting, WAF middleware |
| 💻 CLI Local Agent | Discovers & orchestrates local tools (nmap, nikto, sqlmap, metasploit), streams to cloud |
| 📦 Multi-language SDKs | Python, TypeScript (@cosmicsec/sdk), Go — 13–14 methods, JWT + API-key auth |
| 📈 Observability | Prometheus, Grafana, Loki, Jaeger, OpenTelemetry, Sentry integration |
| 🏗️ IaC | Terraform (AWS RDS/ElastiCache/EKS), Helm chart, ArgoCD GitOps, Traefik v3 TLS |
┌──────────────────────────────────────────────────────────────────────────┐
│ USER LAYER │
│ [Public Browser] [Auth'd Browser] [CLI Terminal / IDE] │
│ STATIC mode DYNAMIC mode LOCAL mode │
└────────┬──────────────────────┬──────────────────────────┬───────────────┘
│ │ │
▼ ▼ │
┌──────────────────────────────────────────────┐ │
│ Traefik v3 (Edge Gateway) │ │
│ TLS · Rate Limit · WAF · Load Balance │ │
└──────────────────────┬───────────────────────┘ │
│ ▼
┌──────────────────────────────────────────────────────────────────────────┐
│ CosmicSec API Gateway (:8000) │
│ HybridRouter · RBAC · WebSocket hub · Per-user rate limit │
│ Structured logging · OpenTelemetry · GraphQL runtime · WAF │
└───────────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────┼────────────────────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌───────────────────────────────────┐ ┌─────────────────────┐
│ Static Profiles│ │ Backend Microservices │ │ CLI Local Agent │
│ (instant mock │ │ Auth · Scan · AI · Recon │ │ (Python + Rust) │
│ responses) │ │ Report · Collab · Plugins │ │ nmap/nikto/sqlmap │
└─────────────────┘ │ Integration · BugBounty · Phase5 │ │ streams JSON → │
│ Notification · AdminService │ │ WebSocket / REST │
└────────────────┬──────────────────┘ └─────────────────────┘
│
┌────────────────────────────┼───────────────────────────────────┐
▼ ▼ ▼
PostgreSQL MongoDB + Redis Elasticsearch
(core data) (OSINT / cache) (logs / search)
| Service | Port | Description |
|---|---|---|
| API Gateway | 8000 | HybridRouter, RBAC, WebSocket, rate limiting, Prometheus, GraphQL |
| Auth Service | 8001 | JWT, OAuth2, TOTP/2FA, Casbin RBAC, session management |
| Scan Service | 8002 | Distributed scanner, smart orchestration, continuous monitoring, Celery |
| AI Service | 8003 | LangChain + LangGraph, ChromaDB, MITRE ATT&CK, anomaly detection, Ollama |
| Recon Service | 8004 | DNS, Shodan, VirusTotal, crt.sh, RDAP passive recon |
| Report Service | 8005 | Multi-format reports, compliance templates, attack-path visualization |
| Collab Service | 8006 | WebSocket rooms, presence tracking, team chat, @mentions |
| Plugin Registry | 8007 | Plugin SDK, official plugins (nmap, metasploit, Jira, Slack) |
| Integration Svc | 8008 | SIEM (Splunk/Elastic), third-party integrations hub |
| Bug Bounty Svc | 8009 | HackerOne / Bugcrowd / Intigriti, submission workflow |
| Phase 5 / SOC | 8010 | SOC ops, incident response, SAST, DevSecOps CI gates |
| Agent Relay | 8011 | CLI agent WebSocket hub, task dispatch |
| Notification Svc | 8012 | Email, Slack, webhook notifications |
- Python 3.11+
- Docker & Docker Compose v2
- Node.js 22+ (for frontend development)
git clone https://github.com/mufthakherul/CosmicSec.git
cd CosmicSec
# Copy environment template
cp .env.example .env
# Edit .env with your configuration
# Install Python dependencies
pip install -r requirements.txtdocker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --buildWhen running from different working directories, use the helper script to always target the repository root:
# Start dev stack
.\scripts\compose-dev.ps1 -Action up -Detached
# Rebuild one service from scratch and restart it
.\scripts\compose-dev.ps1 -Action rebuild -Services collab-service
# If you accidentally run "build -d", this helper auto-corrects to up -d --build
.\scripts\compose-dev.ps1 -Action build -Detached
# Build with automatic retry and BuildKit fallback when Docker returns EOF/500 errors
.\scripts\docker-build-safe.ps1 -NoCache -Services collab-service| Service | URL |
|---|---|
| API Gateway | http://localhost:8000 |
| Frontend (dev) | http://localhost:3000 |
| Grafana | http://localhost:3001 |
| Prometheus | http://localhost:9090 |
| Traefik dashboard | http://localhost:8080 |
cd frontend
npm install
npm run dev
# Optional: generate bundle report at frontend/dist/stats.html
npm run analyze
# Component library (Storybook)
npm run storybook
# Static Storybook build
npm run build-storybookWhen GitHub Pages is enabled for this repository, Storybook deploys from CI at:
https://mufthakherul.github.io/CosmicSec/
and can be mounted under a /storybook/ path depending on Pages configuration.
# npm global launcher (installs/runs Python CLI automatically)
npm install -g @mufthakherul/cosmicsec-agent-cli
cosmicsec --help
# or direct Python editable install
cd cli/agent
pip install -e .
cosmicsec --help# API Gateway
uvicorn services.api_gateway.main:app --port 8000 --reload
# Auth Service
uvicorn services.auth_service.main:app --port 8001 --reload# Python backend tests
pytest tests/ -v --cov=services --cov-report=term-missing
# Frontend unit tests
cd frontend && npm run test
# Frontend E2E tests
cd frontend && npm run test:e2e# Python
ruff check .
ruff format .
# Frontend
cd frontend && npx tsc --noEmitCosmicSec provides official SDKs for three languages:
| SDK | Package | Methods |
|---|---|---|
| TypeScript | sdk/typescript/ (@cosmicsec/sdk) |
14 typed methods + AgentWebSocketClient |
| Python | sdk/python/ |
httpx sync client, runtime envelope parser |
| Go | sdk/go/ |
13 methods, JWT + API-key auth, envelope unwrapping |
CosmicSec supports community plugins via the Plugin SDK. See sdk/ and plugins/ for examples.
from plugins.sdk import PluginBase
class MyPlugin(PluginBase):
name = "my-plugin"
version = "1.0.0"
async def run(self, context):
# Your plugin logic here
...See the full maintained structure map: docs/DIRECTORY_STRUCTURE.md
CosmicSec/
├── services/ # 13 FastAPI microservices + shared common modules
├── cosmicsec_platform/ # Shared middleware: HybridRouter, static profiles, policies
├── frontend/ # React 19 + TypeScript + Vite + TailwindCSS v4
├── cli/ # Local agent package (Python) + CLI assets
├── ingest/ # Rust high-speed ingest pipeline
├── sdk/ # Python / TypeScript / Go SDKs
├── plugins/ # Plugin SDK + official plugins
├── infrastructure/ # Terraform, Traefik, ArgoCD
├── helm/ # Kubernetes Helm chart
├── alembic/ # Database migrations
├── tests/ # Unit, integration, e2e tests (1260+ lines)
└── docs/ # Architecture docs, guides, visual assets
| Standard | Status |
|---|---|
| OWASP Top 10 | Addressed in scan templates |
| NIST CSF | Report templates available |
| SOC 2 | Compliance readiness dashboard |
| PCI-DSS | Compliance readiness dashboard |
| HIPAA | Compliance readiness dashboard |
| ISO 27001 | Report templates available |
| MITRE ATT&CK | AI analysis fully mapped |
We welcome contributions from the security community! Please read CONTRIBUTING.md before submitting pull requests.
See the Current Roadmap for the active implementation plan and contribution opportunities.
Found a vulnerability? Please follow our responsible disclosure policy — do not open a public GitHub issue for security vulnerabilities.
Security scanning is automated via GitHub CodeQL (Python + TypeScript) on every push and weekly schedule.
Licensed under a Custom MIT License with Ethical Use & AI Restriction Clauses. See LICENSE.
TL;DR: Free for ethical cybersecurity research, education, and authorized engagements. Commercial use and offensive/unethical use require explicit written permission.
Mufthakherul Islam Miraz
- Website: mufthakherul.github.io
- Email: mufthakherul_cybersec@s6742.me
CosmicSec is built on the shoulders of giants in the open-source security community. We gratefully acknowledge FastAPI, LangChain, Celery, MITRE ATT&CK, React, Rust, and all contributors whose work makes this platform possible.