Fluxion

<div align="center"> <h1>🔐 Fluxion</h1> <p><strong>Unified Vulnerability Intelligence Platform</strong></p> <img src="https://pub-2ebec616d3dd4d0d8d03bde45130a0ee.r2.dev/back_image.jpg" alt="Fluxion Banner" style="max-width: 100%; margin-bottom: 16px;" /> <p> <a href="#features">Features</a> • <a href="#tech-stack">Tech Stack</a> • <a href="#getting-started">Getting Started</a> • <a href="#installation">Installation</a> • <a href="#api-documentation">API Docs</a> • <a href="#contributing">Contributing</a> • <a href="#license">License</a> </p> <p> <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version"> <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"> </p> </div>

---

📖 About

Fluxion is a comprehensive, open-source vulnerability intelligence and management platform designed to help security teams centralize, track, and manage their security operations. It provides a unified interface for managing assets, vulnerabilities, security reports, and knowledge base articles, making it easier for organizations to maintain a strong security posture.

Key Highlights

• 🎯 Centralized Vulnerability Management - Track and manage vulnerabilities across your entire infrastructure
• 🏢 Multi-Workspace Support - Organize assets and vulnerabilities by workspaces and projects
• 📊 Comprehensive Reporting - Generate detailed security reports and analytics
• 🔍 Asset Discovery & Management - Track all your digital assets in one place
• 📚 Knowledge Base - Build and maintain your security knowledge repository
• 🔔 Activity Tracking - Monitor all security-related activities and changes
• 🔐 Enterprise Security - Built-in authentication and authorization
• 🚀 Modern Tech Stack - React + TypeScript frontend with FastAPI backend

---

✨ Features

Core Functionality

• Workspace & Project Management

  • Create and manage multiple workspaces
  • Organize projects within workspaces
  • Role-based access control

• Asset Management

  • Track web applications, APIs, networks, and cloud resources
  • Associate assets with projects and workspaces
  • Monitor asset status and criticality

• Vulnerability Management

  • Comprehensive vulnerability tracking and classification
  • CVSS scoring and severity assessment
  • Vulnerability lifecycle management (Open, In Progress, Resolved, etc.)
  • Link vulnerabilities to affected assets

• Security Services

  • Manage various security service types
  • Track service status and completion
  • Associate services with projects

• Reporting & Analytics

  • Generate detailed security reports
  • Track report status and types
  • Export capabilities for compliance

• Knowledge Base

  • Create and manage security articles
  • Categorize knowledge by type and status
  • Build institutional security knowledge

• User Management

  • User authentication and authorization
  • Role-based permissions
  • Telegram integration for notifications

---

🛠️ Tech Stack

Frontend

• Framework: React 18 with TypeScript
• Build Tool: Vite 5
• UI Components: Radix UI primitives
• Styling: Tailwind CSS with custom theme
• Forms: React Hook Form with Zod validation
• Data Fetching: TanStack Query (React Query)
• Routing: React Router v6
• Charts: Recharts
• State Management: React Context API
• HTTP Client: Axios

Backend

• Framework: FastAPI
• Database: MySQL 8.0
• ORM: SQLModel
• Authentication: JWT with python-jose
• Password Hashing: Passlib with bcrypt
• Migrations: Alembic
• Validation: Pydantic
• ASGI Server: Uvicorn

DevOps & Infrastructure

• Containerization: Docker & Docker Compose
• Web Server: Nginx (for frontend)
• Database: MySQL 8.0
• Python Version: 3.11+
• Node Version: 18+

---

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Docker (v20.10+) and Docker Compose (v2.0+)
• Node.js (v18+) and npm or bun
• Python (v3.11+)
• Git

Quick Start with Docker

The fastest way to get Fluxion up and running is using Docker Compose:

# Clone the repository
git clone https://github.com/TinyActive/fluxion.git
cd fluxion

# Edit docker-compose.yml to update configuration
# IMPORTANT: Change the following before running:
# 1. Database passwords (MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, DB_PASSWORD)
# 2. SECRET_KEY for JWT tokens
# 3. CORS_ORIGINS to match your domain/IP
# 4. VITE_API_BASE_URL in frontend build args
# 5. TELEGRAM_BOT_TOKEN (optional)

# Start all services
docker-compose up -d

# Wait for services to be healthy (may take 1-2 minutes)
docker-compose ps

# Run database migrations
docker-compose exec backend alembic upgrade head

# Create initial admin user (optional)
docker-compose exec backend python -m app.initial_data

The application will be available at:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8000
• API Docs (Swagger): http://localhost:8000/api/v1/docs
• API Docs (ReDoc): http://localhost:8000/api/v1/redoc

---

📦 Installation

Option 1: Docker Compose (Recommended)

1. Clone the repository

   git clone https://github.com/TinyActive/fluxion
   cd fluxion
   

2. Configure environment variables

   Edit docker-compose.yml file and update the following environment variables:

   Database service:

   environment:
     MYSQL_ROOT_PASSWORD: your_secure_root_password  # Change this
     MYSQL_DATABASE: vuls_db
     MYSQL_USER: vuls_user
     MYSQL_PASSWORD: your_secure_password  # Change this
   

   Backend service:

   environment:
     DB_HOST: db
     DB_CONNECTION: mysql
     DB_PORT: 3306
     DB_DATABASE: vuls_db
     DB_USERNAME: vuls_user
     DB_PASSWORD: your_secure_password  # Must match MYSQL_PASSWORD
     SECRET_KEY: "your_random_secret_key_here"  # Change this
     CORS_ORIGINS: '["http://localhost:8080", "http://127.0.0.1:8080"]' # Change this
     TELEGRAM_BOT_TOKEN: "your_telegram_bot_token"  # Optional
     AUTH_ENABLED: "True"
   

   Frontend service:

   build:
     context: .
     dockerfile: Dockerfile
     args:
       - VITE_API_BASE_URL=http://localhost:8000/api/v1  # Update to your API URL
   

3. Start the services

   docker-compose up -d
   

Option 2: Local Development

Backend Setup

1. Navigate to backend directory

   cd backend
   

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Create .env file

   DB_CONNECTION=mysql
   DB_HOST=localhost
   DB_PORT=3306
   DB_DATABASE=vuls_db
   DB_USERNAME=root
   DB_PASSWORD=your_password
   SECRET_KEY=your_secret_key
   TELEGRAM_BOT_TOKEN=optional_bot_token
   AUTH_ENABLED=True
   

5. Run migrations

   alembic upgrade head
   

6. Start the backend server

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

Frontend Setup

1. Navigate to project root

   cd ..  # from backend directory
   

2. Install dependencies

   npm install
   # or using bun
   bun install
   

3. Configure API endpoint

   Create .env file in the root directory:

   VITE_API_BASE_URL=http://localhost:8000/api/v1
   

4. Start the development server

   npm run dev
   # or using bun
   bun run dev
   

5. Access the application

   Open your browser and navigate to http://localhost:5173

Database Setup (MySQL)

If running locally without Docker, you'll need to set up MySQL:

# Install MySQL 8.0
# Create database
mysql -u root -p
CREATE DATABASE vuls_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'vuls_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON vuls_db.* TO 'vuls_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

---

🎮 Usage

Default Login

After initial setup, you can login with the default credentials:

• Username: admin@vuls.local
• Password: admin

Key Workflows

1. Create a Workspace

   • Navigate to Workspaces page
   • Click "New Workspace"
   • Fill in workspace details

2. Add a Project

   • Select a workspace
   • Create a new project within the workspace
   • Define project scope and objectives

3. Register Assets

   • Navigate to Assets page
   • Add web applications, APIs, or other digital assets
   • Associate assets with projects

4. Track Vulnerabilities

   • Create vulnerability entries
   • Set severity and CVSS scores
   • Link to affected assets
   • Update status as remediation progresses

5. Generate Reports

   • Navigate to Reports page
   • Create comprehensive security reports
   • Track report status and distribution

6. Build Knowledge Base

   • Document security findings
   • Create reusable security articles
   • Categorize by type and status

---

📚 API Documentation

Interactive API Documentation

Once the backend is running, you can explore the API using:

• Swagger UI: http://localhost:8000/api/v1/docs
• ReDoc: http://localhost:8000/api/v1/redoc

API Endpoints

Authentication

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/register - User registration
• GET /api/v1/auth/me - Get current user

Workspaces

• GET /api/v1/workspaces - List all workspaces
• POST /api/v1/workspaces - Create workspace
• GET /api/v1/workspaces/{id} - Get workspace details
• `PUT /api/v1/workspaces/{i