Sentra

A Community-Powered Cyber Threat Monitoring System

Sentra is a cybersecurity platform designed to crowdsource cyber threat reporting while safeguarding user privacy. The system combines breach detection, user alerts, threat submissions, automated validation using services like VirusTotal, and optional escalation to government agencies such as CERT.

This community-driven model aims to strengthen cyber resilience through transparency, quick threat visibility, and responsible disclosure.

Features

User Management

• Secure Authentication: Sign up & login with JWT-based session management
• Email Verification: Optional email verification for enhanced security
• Profile Management: Comprehensive user profile with breach history
• Privacy-First: User identity protection throughout the reporting process

Breach Detection

• Automated Scanning: Email breach detection via HaveIBeenPwned (HIBP) API
• Real-time Monitoring: Scans performed on signup and email changes
• Historical Tracking: Complete breach history logging and user alerts
• Instant Notifications: Immediate alerts when breaches are detected

Threat Reporting

• Easy Submission: Report cyber threats with title, description, screenshots, and links
• Status Tracking: Monitor submission status
• Evidence Support: Upload screenshots and provide detailed descriptions
• Community Impact: Contribute to collective cybersecurity knowledge

Automated Threat Validation

• VirusTotal Integration: Automatic URL/IP validation using VirusTotal API
• Smart Classification: Auto-classify threats based on scan results
• Manual Override: Admin panel for manual review and status updates
• Transparent Process: Clear justification for all validation decisions

Smart Notifications

• In-App Alerts: Real-time notifications for breach detection and report updates
• Status Updates: Automatic updates on threat report progress

CERT Integration

• Government Reporting: Seamless escalation to CERT agencies
• Multiple Formats: Export verified threats as PDF
• Institutional Ready: Designed for both public and institutional use
• Compliance Support: Meets government reporting requirements

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │    Database     │
│   (React)       │    │  (Ballerina)    │    │ (PostgreSQL/    │
│                 │◄──►│                 │◄──►│     MySQL)      │
│ • Auth Pages    │    │ • HTTP Services │    │ • Users         │
│ • Profile       │    │ • REST APIs     │    │ • Reports       │
│ • Threat Form   │    │ • Email Service │    │ • Notifications │
│ • Admin Panel   │    │ • Validation    │    │ • BreachLogs    │
│ • Notifications │    │ • CERT Export   │    │ • Admins        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ External APIs   │
                    │ • VirusTotal    │
                    │ • HIBP          │
                    │ • CERT Services │
                    └─────────────────┘

Technology Stack

• Frontend: React
• Backend: Ballerina
• Database: MySQL
• Authentication: JWT
• External APIs: VirusTotal, HaveIBeenPwned
• Notifications: In-app alerts

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v16 or higher)
• Ballerina (latest version)
• MySQL
• Git

Required API Keys

You'll need to obtain API keys for:

• VirusTotal API
• HaveIBeenPwned API

Quick Start

1. Clone following Repositories

git clone https://github.com/200OK-Sentra/Sentra_Backend.git
git clone https://github.com/200OK-Sentra/sentra-frontend.git

2. Setup Backend (Ballerina)

cd backend

Create a Config.toml file:

[database]
host = "localhost"
port = 5432
name = "sentra_db"
username = "your_db_user"
password = "your_db_password"

[apis]
hibp_api_key = "your_hibp_api_key"
virustotal_api_key = "your_virustotal_api_key"

[email]
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_username = "your_email@gmail.com"
smtp_password = "your_app_password"

[jwt]
secret = "your_jwt_secret_key"

Install dependencies and run:

bal build
bal run

3. Setup Frontend (React)

cd frontend
npm install
npm run dev

4. Database Setup

Run the SQL script provided in the database folder to create the database and tables:

mysql -u <username> -p < database/schema.sql

Replace with your MySQL username. You will be prompted for your password. This will create the sentra_db database and all required tables automatically.

API Documentation

Authentication

Sign Up

POST /test/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "John Doe"
}

Login

POST /test/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Get Authenticated User

GET /test/auth
Authorization: Bearer {JWT_TOKEN}

Threat Reporting

Submit Threat Report

POST /reports/submit?userId={USER_ID}
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "title": "Malware Infection Report",
  "threat_type": "Malware",
  "priority_level": "Medium",
  "links": [
    "http://malicious-site.com/download",
    "http://infected-example.com/installer"
  ],
  "source_discovered": "Detected by endpoint antivirus during routine scan.",
  "detailed_description": "The malware attempts to steal user credentials and encrypt sensitive files. It spreads through downloaded installers from untrusted websites.",
  "evidence": "iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAD..." 
}

Get User Reports

GET /reports/user
Authorization: Bearer {JWT_TOKEN}

Get All Reports

GET /reports

Validation

Update Report Status

PUT /report/{id}/validate
Authorization: Bearer {ADMIN_JWT_TOKEN}
Content-Type: application/json

{
  "status": "Validated",
  "remarks": "Confirmed malicious via VirusTotal scan",
  "validatedBy": "admin_001"
}

User Roles

Role	Access Level	Description
User	Submit threats, view own history	Community members who report threats
Admin	Validate reports, manage users	Platform moderators who review submissions
CERT Viewer	Read-only validated threats	Government agencies accessing verified threats

Example Workflow

1. User Registration → Email automatically checked for breaches via HIBP
2. Breach Detection → User notified if email found in any data breaches
3. Threat Submission → User reports suspicious activity with evidence
4. Automated Validation → System scans URLs/IPs using VirusTotal
5. Admin Review → Manual verification for edge cases
6. CERT Notification → Validated threats exported to government agencies
7. Community Feedback → Users notified when their reports help stop threats

Manual Testing with Postman

Import the provided Postman collection for comprehensive API testing:

1. Authentication Flow: Test signup, login, and JWT validation
2. Breach Detection: Verify HIBP integration
3. Threat Submission: Test report creation and validation
4. Admin Operations: Validate admin panel functionality
5. CERT Export: Test government agency integration

Security Considerations

• Password Security: Bcrypt hashing with salt rounds
• JWT Management: Secure token generation and validation
• API Rate Limiting: Protection against abuse
• Input Validation: Sanitization of all user inputs
• Privacy Protection: User anonymization in CERT exports
• Secure Communications: HTTPS everywhere, encrypted data transmission

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add tests for new features
• Update documentation for API changes
• Ensure all security checks pass
• Test with sample data before submitting

📈 Future Enhancements

• AI-Powered Validation: Machine learning models for threat classification
• Real-time Dashboard: Live threat monitoring for CERT agencies
• Gamification: User rewards system for valid threat submissions
• Browser Extension: One-click threat reporting from any website
• Mobile App: iOS/Android apps for on-the-go reporting
• Advanced Analytics: Threat trend analysis and prediction
• API Integrations: Support for more security vendors and tools

Acknowledgments

• HaveIBeenPwned: For providing breach detection services
• VirusTotal: For automated threat validation
• Ballerina Community: For the excellent backend framework
• React Team: For the robust frontend framework
• Security Researchers: Who inspire community-driven cybersecurity

---

Empowering communities to fight cyber threats together