Skip to content

Commit cfd6738

Browse files
MSVCP140MSVCP140
committed
feat: implement advanced UI with 3D ThreatGlobe and add GSoC contribution guide
1 parent 1c8c22d commit cfd6738

7 files changed

Lines changed: 1070 additions & 83 deletions

File tree

‎GSOCCONTRIBUTING.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# GSoC Contribution Guide – **AI‑Powered‑Security‑Monitoring‑Threat‑Detection‑Platform**
2+
3+
> **Purpose** – This document provides a *deep‑dive* workflow for students, mentors, and maintainers who want to contribute to this repository as part of **Google Summer of Code 2026**. It extends the generic `CONTRIBUTING.md` with GSoC‑specific expectations, tooling, and deliverables.
4+
5+
---
6+
7+
## 1️⃣ Prerequisites & Environment
8+
9+
| Item | Recommended Version | Why it matters |
10+
|------|--------------------|----------------|
11+
| **Node.js** | `>=20.0.0` (LTS) | Modern ES‑modules, better performance |
12+
| **npm / yarn** | `>=9.0.0` | Deterministic lockfiles |
13+
| **Docker** | `>=24.0` | Guarantees reproducible builds across OSes |
14+
| **Git** | `>=2.40` | Required for signed commits & PR workflow |
15+
| **Python** | `3.11` (optional) | Used by some CI scripts for linting |
16+
| **VS Code** | Latest + extensions: ESLint, Prettier, GitLens | Consistent developer experience |
17+
| **Windows PowerShell** | Run Docker commands in PowerShell or Git Bash; ensure execution policy allows scripts (`Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`). | Improves Windows dev experience |
18+
19+
20+
### 1.1 Local Development (Docker‑first)
21+
```bash
22+
# Clone the repo (fork first)
23+
git clone https://github.com/<your‑username>/AI-Powered-Security-Monitoring-Threat-Detection-Platform.git
24+
cd AI-Powered-Security-Monitoring-Threat-Detection-Platform
25+
26+
# Build the dev container (Dockerfile is in the repo root)
27+
docker build -t ai‑security‑dev .
28+
# Run the container with hot‑reload
29+
docker run -it --rm -p 3000:3000 -v "$(pwd):/app" ai‑security‑dev
30+
```
31+
The app will be reachable at `http://localhost:3000`. All linting, type‑checking, and tests run inside the container, ensuring a uniform environment.
32+
33+
---
34+
35+
## 2️⃣ Selecting a GSoC Project Idea
36+
37+
1. **Browse the official GSoC ideas** – located in `ideas/` or on the organization’s GSoC page.
38+
2. **Map your skill set** – e.g.,
39+
- *Machine Learning*: anomaly detection, model compression.
40+
- *Frontend*: glass‑morphism UI, real‑time visual analytics.
41+
- *DevOps*: GitHub Actions, Docker‑Compose orchestration.
42+
3. **Validate scope** – ensure the idea can be delivered within the 12‑week GSoC window (≈ 300 hrs).
43+
4. **Create a proposal issue** – title it `GSoC: <Your Idea Title>` and add the **GSoC‑Proposal‑Template** (see Section 4).
44+
45+
> **If you cannot find a suitable idea**, feel free to propose a *new* one following the same template; maintainers will review and label it appropriately.
46+
47+
---
48+
49+
## 3️⃣ Mentor Engagement & Communication Plan
50+
51+
| Communication Channel | Frequency | Content |
52+
|-----------------------|-----------|---------|
53+
| **Weekly Sync (Zoom/Meet)** | Every Friday 10 AM IST | Progress demo, blockers, next‑step plan |
54+
| **Slack / Discord** | Daily (as needed) | Quick questions, code snippets |
55+
| **GitHub Issues/PRs** | Continuous | Formal record of decisions, review comments |
56+
| **Monthly Report (Google Docs)** | End of month | Summary of achievements, metrics, risk assessment |
57+
58+
**Best Practices**
59+
- Keep a *shared* Google Sheet with milestones, owners, and status.
60+
- Tag mentors in PRs using `@mentor‑handle`.
61+
- Record all demo sessions and upload to the shared drive for future reference.
62+
63+
---
64+
65+
## 4️⃣ GSoC Proposal Template (Markdown)
66+
```markdown
67+
# Project Title
68+
69+
## 1️⃣ Motivation & Impact
70+
*Why does this feature matter for a security‑monitoring platform?* Include statistics, threat models, or user‑story examples.
71+
72+
## 2️⃣ Goals & Deliverables
73+
| Milestone | Description | Acceptance Criteria |
74+
|----------|-------------|---------------------|
75+
| **M1** | Data‑ingestion pipeline (Kafka → Node.js) | Unit tests ≥ 90 % coverage, end‑to‑end demo |
76+
| **M2** | Real‑time anomaly detection model (TensorFlow.js) | Latency < 200 ms per event |
77+
| **M3** | UI visualisation (glass‑morphism dashboard) | Responsive, dark‑mode, accessibility WCAG AA |
78+
| **M4** | CI/CD automation (GitHub Actions) | Automated lint, test, build, and Docker image publish |
79+
80+
## 3️⃣ Technical Approach
81+
- **Architecture Diagram** (Mermaid):
82+
```mermaid
83+
flowchart LR
84+
A[Kafka] --> B[Node.js Service]
85+
B --> C[TensorFlow.js Model]
86+
C --> D[React Dashboard]
87+
D --> E[Supabase Storage]
88+
```
89+
- **Key Libraries**: `kafkajs`, `@tensorflow/tfjs`, `react‑router`, `styled‑components`.
90+
- **Data Flow**: Explain how events are consumed, processed, and visualised.
91+
92+
## 4️⃣ Timeline (Gantt‑style)
93+
| Week | Activity |
94+
|------|----------|
95+
| 1‑2 | Environment setup, baseline tests |
96+
| 3‑4 | Implement data‑ingestion service |
97+
| 5‑6 | Build and train anomaly model |
98+
| 7‑8 | UI dashboard prototype |
99+
| 9‑10| CI/CD pipelines & Docker images |
100+
| 11‑12| Documentation, final demo, hand‑over |
101+
102+
## 5️⃣ Risks & Mitigations
103+
- **Model latency** – Profile with Chrome DevTools; fallback to a lightweight heuristic.
104+
- **Data privacy** – Encrypt data at rest using Supabase policies.
105+
- **Scope creep** – Keep milestones atomic; defer optional features to post‑GSoC.
106+
107+
## 6️⃣ Testing & Verification
108+
- **Unit Tests** – `jest` + `ts-jest` for all TypeScript modules.
109+
- **Integration Tests** – `supertest` for API endpoints.
110+
- **E2E Tests** – `cypress` covering UI flows (login → dashboard).
111+
- **Performance Benchmarks** – Use `autocannon` for API load testing.
112+
113+
---
114+
```
115+
Save this template as `gsoc_proposal_<your‑name>.md` and reference it in the issue description.
116+
117+
---
118+
119+
## 5️⃣ Development Workflow (Advanced)
120+
1. **Fork → Clone** the repo (use the Docker dev container).
121+
2. **Create a feature branch** per milestone, e.g., `gsoc-m1-data-ingestion`.
122+
3. **Commit style** – Follow Conventional Commits (`feat:`, `fix:`, `perf:`). Enable `commitlint` in the CI.
123+
4. **Run the full test suite** before pushing:
124+
```bash
125+
npm run lint && npm run test:coverage && npm run build
126+
```
127+
5. **Open a Pull Request** targeting `main`.
128+
- **PR Title**: `gsoc-m1: Data ingestion pipeline`
129+
- **PR Description**: Include the milestone number, a short summary, and a link to the related issue.
130+
- **Checklist** (copy‑paste):
131+
```markdown
132+
- [ ] Follows `CONTRIBUTING.md` & `CODE_OF_CONANDARD.md`
133+
- [ ] Unit & integration tests added (≥ 90 % coverage)
134+
- [ ] Documentation updated (`docs/` or README)
135+
- [ ] CI passes (GitHub Actions)
136+
- [ ] Demo video attached (optional but encouraged)
137+
```
138+
6. **CI/CD** – The repository ships a GitHub Actions workflow ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) that runs lint, tests, builds Docker image, and pushes the image to GitHub Packages on merge.
139+
7. **Release Process** – After the final milestone, a maintainers‑only workflow tags a release (`vX.Y‑gsoc‑<name>`) and publishes the Docker image.
140+
141+
---
142+
143+
## 6️⃣ Advanced Testing Strategy
144+
- **Static Analysis** – `eslint`, `prettier`, `typescript` strict mode (`noImplicitAny`).
145+
- **Security Scanning** – `npm audit`, `snyk` integrated in CI.
146+
- **Performance Profiling** – Use `clinic.js` for Node services and Chrome DevTools for the React UI.
147+
- **Accessibility** – Run `axe-core` in CI; aim for WCAG AA compliance.
148+
- **Cross‑Browser Testing** – Cypress runs on Chrome, Firefox, and Edge via the `cypress-browser` plugin.
149+
150+
---
151+
152+
## 7️⃣ Documentation & Knowledge Transfer
153+
- **Typedoc** – Generate API docs (`npm run docs`) and host them on GitHub Pages.
154+
- **Architecture Docs** – Keep `docs/architecture.md` up‑to‑date with Mermaid diagrams.
155+
- **On‑boarding Guide** – Add a `docs/onboarding.md` for future contributors.
156+
- **Post‑GSoC Handover** – Create a `gsoc‑handover.md` summarising:
157+
- What was built, where the code lives.
158+
- Open issues & future work.
159+
- Metrics (performance, coverage).
160+
161+
---
162+
163+
## 8️⃣ Final Deliverables Checklist
164+
- [ ] All milestone PRs merged and CI green.
165+
- [ ] Release tag `vX.Y‑gsoc‑<your‑name>` created.
166+
- [ ] Demo video (2‑3 min) uploaded to the shared drive.
167+
- [ ] `gsoc‑handover.md` committed to `docs/`.
168+
- [ ] Final GSoC report submitted on the portal with links to PRs, demo, and handover.
169+
170+
---
171+
172+
## 🎉 Ready to Start?
173+
Follow the steps above, keep communication transparent, and you’ll have a *premium*, production‑ready contribution that stands out in the GSoC community. Good luck, and happy coding! 🚀
174+
175+
---
176+
177+
*All contributions are made under the project's **MIT License**.*

‎frontend/app/globals.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@tailwind base;
2+
@tailwind components;
3+
@tailwind utilities;

‎frontend/app/layout.tsx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import './globals.css';
2+
3+
export const metadata = {
4+
title: 'AI Security Monitor',
5+
description: 'Advanced UI Dashboard',
6+
};
7+
8+
export default function RootLayout({ children }: { children: React.ReactNode }) {
9+
return (
10+
<html lang="en">
11+
<head />
12+
<body className="bg-gray-900 text-white font-sans">
13+
{children}
14+
</body>
15+
</html>
16+
);
17+
}

‎frontend/components/Dashboard.tsx‎

Lines changed: 58 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import React, { useEffect, useState } from 'react';
2-
import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer, BarChart, Bar } from 'recharts';
3-
import { AlertCircle, Shield, Activity, Lock } from 'lucide-react';
2+
import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
3+
import { AlertCircle, Shield, Activity } from 'lucide-react';
4+
import ThreatGlobe from './ThreatGlobe';
45

56
interface Log {
67
id: number;
@@ -13,84 +14,88 @@ interface Log {
1314
details: string;
1415
}
1516

16-
const Dashboard = () => {
17+
const Dashboard: React.FC = () => {
1718
const [logs, setLogs] = useState<Log[]>([]);
1819
const [stats, setStats] = useState({ total: 0, threats: 0, active_anomalies: 0 });
1920

2021
useEffect(() => {
2122
const fetchLogs = async () => {
2223
try {
2324
const response = await fetch('http://localhost:8000/logs/');
24-
const data = await response.json();
25+
const data: Log[] = await response.json();
2526
setLogs(data);
26-
27-
// Calculate stats
28-
const threats = data.filter((l: Log) => l.event_type !== 'Normal').length;
29-
setStats({
30-
total: data.length,
31-
threats: threats,
32-
active_anomalies: data.filter((l: Log) => l.event_type === 'Malware Detected' || l.event_type === 'DoS').length
33-
});
27+
const threats = data.filter(l => l.event_type !== 'Normal').length;
28+
const active = data.filter(l => l.event_type === 'Malware Detected' || l.event_type === 'DoS').length;
29+
setStats({ total: data.length, threats, active_anomalies: active });
3430
} catch (error) {
3531
console.error('Error fetching logs:', error);
3632
}
3733
};
38-
3934
fetchLogs();
40-
const interval = setInterval(fetchLogs, 2000); // Poll every 2 seconds
35+
const interval = setInterval(fetchLogs, 2000);
4136
return () => clearInterval(interval);
4237
}, []);
4338

4439
const chartData = logs.slice(0, 20).reverse().map(log => ({
4540
time: new Date(log.timestamp).toLocaleTimeString(),
4641
bytes: log.bytes_transferred,
47-
threat: log.event_type !== 'Normal' ? 1 : 0
42+
threat: log.event_type !== 'Normal' ? 1 : 0,
4843
}));
4944

5045
return (
51-
<div className="p-6 bg-gray-900 min-h-screen text-white font-sans">
52-
<header className="mb-8 flex justify-between items-center">
53-
<h1 className="text-3xl font-bold flex items-center gap-2">
54-
<Shield className="text-blue-500" /> AI Security Monitor
55-
</h1>
56-
<div className="flex gap-4">
57-
<div className="bg-gray-800 p-4 rounded-lg flex items-center gap-3">
58-
<Activity className="text-green-400" />
59-
<div>
60-
<p className="text-gray-400 text-sm">Total Traffic</p>
61-
<p className="text-2xl font-bold">{stats.total}</p>
46+
<div className="min-h-screen bg-gradient-to-br from-gray-900 via-gray-800 to-gray-700 text-white font-sans p-6 backdrop-blur-sm">
47+
{/* Glass‑morphism container */}
48+
<div className="bg-white/5 rounded-xl border border-white/10 shadow-xl p-6 backdrop-blur-sm">
49+
{/* Header */}
50+
<header className="mb-8 flex justify-between items-center">
51+
<h1 className="text-3xl font-bold flex items-center gap-2">
52+
<Shield className="text-blue-400" /> AI Security Monitor
53+
</h1>
54+
<div className="flex gap-4">
55+
<div className="bg-white/10 p-4 rounded-lg flex items-center gap-3">
56+
<Activity className="text-green-400" />
57+
<div>
58+
<p className="text-gray-300 text-sm">Total Traffic</p>
59+
<p className="text-2xl font-bold">{stats.total}</p>
60+
</div>
6261
</div>
63-
</div>
64-
<div className="bg-gray-800 p-4 rounded-lg flex items-center gap-3">
65-
<AlertCircle className="text-red-500" />
66-
<div>
67-
<p className="text-gray-400 text-sm">Threats Detected</p>
68-
<p className="text-2xl font-bold">{stats.threats}</p>
62+
<div className="bg-white/10 p-4 rounded-lg flex items-center gap-3">
63+
<AlertCircle className="text-red-400" />
64+
<div>
65+
<p className="text-gray-300 text-sm">Threats Detected</p>
66+
<p className="text-2xl font-bold">{stats.threats}</p>
67+
</div>
6968
</div>
7069
</div>
71-
</div>
72-
</header>
70+
</header>
7371

74-
<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
75-
{/* Network Traffic Chart */}
76-
<div className="bg-gray-800 p-6 rounded-lg shadow-lg">
77-
<h2 className="text-xl font-semibold mb-4">Network Traffic (Bytes)</h2>
78-
<div className="h-64">
79-
<ResponsiveContainer width="100%" height="100%">
80-
<LineChart data={chartData}>
81-
<CartesianGrid strokeDasharray="3 3" stroke="#374151" />
82-
<XAxis dataKey="time" stroke="#9CA3AF" />
83-
<YAxis stroke="#9CA3AF" />
84-
<Tooltip contentStyle={{ backgroundColor: '#1F2937', border: 'none' }} />
85-
<Line type="monotone" dataKey="bytes" stroke="#3B82F6" strokeWidth={2} dot={false} />
86-
</LineChart>
87-
</ResponsiveContainer>
72+
{/* Main Grid */}
73+
<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
74+
{/* 3D Threat Globe */}
75+
<div className="bg-white/5 rounded-xl border border-white/10 shadow-xl p-4 backdrop-blur-sm">
76+
<h2 className="text-xl font-semibold mb-2 text-gray-200">Global Threat Landscape</h2>
77+
<ThreatGlobe />
78+
</div>
79+
{/* Network Traffic Chart */}
80+
<div className="bg-white/5 rounded-xl border border-white/10 shadow-xl p-4 backdrop-blur-sm">
81+
<h2 className="text-xl font-semibold mb-4 text-gray-200">Network Traffic (Bytes)</h2>
82+
<div className="h-64">
83+
<ResponsiveContainer width="100%" height="100%">
84+
<LineChart data={chartData}>
85+
<CartesianGrid strokeDasharray="3 3" stroke="#374151" />
86+
<XAxis dataKey="time" stroke="#9CA3AF" />
87+
<YAxis stroke="#9CA3AF" />
88+
<Tooltip contentStyle={{ backgroundColor: '#1F2937', border: 'none' }} />
89+
<Line type="monotone" dataKey="bytes" stroke="#3B82F6" strokeWidth={2} dot={false} />
90+
</LineChart>
91+
</ResponsiveContainer>
92+
</div>
8893
</div>
8994
</div>
9095

91-
{/* Recent Logs */}
92-
<div className="bg-gray-800 p-6 rounded-lg shadow-lg overflow-hidden">
93-
<h2 className="text-xl font-semibold mb-4">Recent Alerts</h2>
96+
{/* Recent Alerts */}
97+
<div className="mt-8 bg-gray-800 p-6 rounded-lg shadow-lg overflow-hidden">
98+
<h2 className="text-xl font-semibold mb-4 text-gray-200">Recent Alerts</h2>
9499
<div className="overflow-y-auto h-64">
95100
<table className="w-full text-left">
96101
<thead>
@@ -102,14 +107,13 @@ const Dashboard = () => {
102107
</tr>
103108
</thead>
104109
<tbody>
105-
{logs.slice(0, 10).map((log) => (
110+
{logs.slice(0, 10).map(log => (
106111
<tr key={log.id} className="border-b border-gray-700/50 hover:bg-gray-700/30">
107112
<td className="py-2 text-sm text-gray-300">{new Date(log.timestamp).toLocaleTimeString()}</td>
108113
<td className="py-2 text-sm font-medium">{log.event_type}</td>
109114
<td className="py-2 text-sm text-gray-300">{log.source_ip}</td>
110115
<td className="py-2">
111-
<span className={`px-2 py-1 rounded text-xs ${log.event_type === 'Normal' ? 'bg-green-900 text-green-300' : 'bg-red-900 text-red-300'
112-
}`}>
116+
<span className={`px-2 py-1 rounded text-xs ${log.event_type === 'Normal' ? 'bg-green-900 text-green-300' : 'bg-red-900 text-red-300'}`}>
113117
{log.event_type === 'Normal' ? 'Safe' : 'Critical'}
114118
</span>
115119
</td>

‎frontend/components/ThreatGlobe.tsx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import React, { Suspense } from 'react';
2+
import { Canvas } from '@react-three/fiber';
3+
import { OrbitControls, Stars, Sphere, useTexture } from '@react-three/drei';
4+
5+
// Simple Earth globe with texture (public domain image)
6+
const Earth = () => {
7+
const [colorMap] = useTexture([
8+
'https://raw.githubusercontent.com/creativetimofficial/public-assets/master/soft-ui-dashboard-pro/assets/img/earth.jpg',
9+
]);
10+
return (
11+
<Sphere args={[1, 64, 64]}>
12+
<meshStandardMaterial map={colorMap} metalness={0.1} roughness={0.9} />
13+
</Sphere>
14+
);
15+
};
16+
17+
const ThreatGlobe: React.FC = () => {
18+
return (
19+
<div className="w-full h-64">
20+
<Canvas camera={{ position: [0, 0, 3] }}>
21+
<ambientLight intensity={0.5} />
22+
<directionalLight position={[5, 5, 5]} intensity={1} />
23+
<Suspense fallback={null}>
24+
<Earth />
25+
</Suspense>
26+
<OrbitControls enableZoom={true} />
27+
<Stars radius={100} depth={50} count={5000} factor={4} saturation={0} fade />
28+
</Canvas>
29+
</div>
30+
);
31+
};
32+
33+
export default ThreatGlobe;

0 commit comments

Comments
 (0)