🛡 GuardianX

AI-powered cyber asset management, vulnerability intelligence, and predictive defense platform

GuardianX is a unified cybersecurity platform for asset discovery, vulnerability assessment, AI-assisted triage, risk analysis, and proactive defense monitoring. It combines scanning, threat intelligence, workflow automation, and analytical dashboards into a single operational stack.

---

✨ Features

• Asset and inventory management
• Network discovery and reconnaissance visibility
• Nmap-based scanning with scheduling
• Attack surface management
• CVE enrichment and vulnerability intelligence
• Threat intelligence and phishing analysis
• Risk scoring and prioritization
• AI security copilot with OpenAI, Gemini, Ollama, or rules-based behavior
• Executive reporting and SOC reporting workflows
• Authentication, role-based access control, and admin operations
• Alerts, incidents, notifications, and activity history
• VirusTotal integration with bring-your-own-key support
• Predictive defense / network attack forecasting from CSV telemetry exports
• Explainable AI evidence for risk drivers such as packet-rate acceleration, SYN concentration, port dispersion, and source diversity
• Per-upload analysis tracking with content hashes and dataset fingerprints
• Honest fail-closed model validation when model artifacts are unavailable or invalid

---

🏗 Architecture

                      Users
                        │
                        ▼
                React Frontend
                        │
                FastAPI Backend
                        │
      ┌───────────────────────────────────────────────┐
      │ Authentication / RBAC                         │
      │ Asset & Scan Management                       │
      │ Vulnerability Intelligence                    │
      │ Risk Engine / AI Copilot                      │
      │ Predictive Defense / Attack Forecast         │
      │ CSV Telemetry Analysis + Explainable AI       │
      │ SOC, Reports, Notifications                   │
      └───────────────────────────────────────────────┘
                        │
                PostgreSQL Database

How it works

1. Teams upload a real flow-export CSV or telemetry dataset.
2. GuardianX validates the file and parses timestamped network records.
3. The backend groups events into temporal windows and extracts interpretable traffic features.
4. If trained model artifacts are available, the GRU-based flow is used for inference.
5. If the artifacts are missing or invalid, the system remains fail-closed and reports the setup state instead of pretending to have a valid model.
6. The response includes a risk score, forecast timeline, explainability, dataset provenance, and analysis history for review.

---

⚙ Technology Stack

Backend

• Python 3.13 + FastAPI
• SQLAlchemy + Alembic
• PostgreSQL 16
• JWT auth and refresh-token handling
• Nmap scan engine

Frontend

• React 19 + TypeScript
• Vite
• Tailwind-inspired UI styling
• Recharts-based visualization

Intelligence and Security

• NVD, KEV, EPSS-based vulnerability enrichment
• Threat intelligence and phishing analysis
• AI-assisted risk evaluation
• Forecasting pipeline based on temporal traffic data and explainable features

---

📂 Project Structure

GuardianX/
├── backend/                 # FastAPI application and tests
├── guardianx-frontend/      # React + TypeScript frontend
├── docs/                    # Architecture, deployment, and developer docs
├── infrastructure/           # Docker / Compose deployment assets
├── tests/                   # installer and platform-level checks
├── LICENSE
├── SECURITY.md
├── README.md
├── install.sh
├── guardianx
└── guardianx.lib.sh

---

🚀 Quick Start

Requirements

• Docker
• Docker Compose

No local Python, PostgreSQL, Node.js, or Nmap installation is required for the default self-contained setup.

One-command install

git clone <repository>
cd GuardianX
./install.sh

This bootstraps the stack and starts the application locally. Typical endpoints include:

• Web UI: http://localhost:8080
• API docs: http://localhost:8080/api/docs

Default local admin login

For the local demo/deployment flow, use these credentials after the first-time setup is completed:

• Username / email: anishkumar9905287@gmail.com
• Password: anishkumar9905287@gmail.com

This is the admin account used for local GuardianX testing and live verification.

Environment files

Create the required environment files before starting the stack:

cp infrastructure/compose/.env.example infrastructure/compose/.env
cp backend/.env.example backend/.env
cp guardianx-frontend/.env.example guardianx-frontend/.env

If you are using the preconfigured local stack from this repository, the app already includes the working values in the generated .env files for the Docker deployment and local admin login.

Docker stack startup

cd infrastructure/compose
docker compose up -d --build

Then open:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8080/api/docs

Management commands

./guardianx status
./guardianx logs
./guardianx logs backend
./guardianx update
./guardianx doctor
./guardianx stop
./guardianx uninstall

---

Development

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Frontend

cd guardianx-frontend
npm install
npm run dev

---

📚 Documentation

• API Reference
• Architecture
• Deployment Guide
• Developer Guide
• Contributing
• Vulnerability Intelligence
• Threat Intelligence
• VirusTotal Integration

---

📌 Current Status

GuardianX is in a mature release-candidate stage with the main platform features and the predictive defense workflow already in place. The system keeps earlier security modules intact while expanding into evidence-based cyber forecasting.

Included capabilities

• Auth and identity flow with admin setup and password reset
• Role-based access control
• Asset management and Nmap scanning
• Threat and vulnerability intelligence
• AI assistance and executive reporting
• SOC workflows, alerts, and activity tracking
• Predictive defense dashboard with CSV upload and forecast evidence
• Honest fail-closed behavior when model artifacts are missing or invalid

---

🤝 Contributing

Contributions are welcome. Please read docs/CONTRIBUTING.md.

---

🔒 Security

Please review SECURITY.md before deployment or contribution.

---

License

GuardianX is licensed under the Apache License 2.0.

Copyright © 2026 Team PHOENIX.

See LICENSE for the full text.

---

GuardianX

Protect. Detect. Secure.