Skip to content

PROJECT_CONTEXT.md

Latest commit

 

History

History
1096 lines (698 loc) · 13.5 KB

PROJECT_CONTEXT.md

File metadata and controls

1096 lines (698 loc) · 13.5 KB
Raw

PROJECT_CONTEXT.md

Project Name

SOCMINT AI Autonomous Social Media Intelligence & Digital Identity Correlation Platform

Vision

SOCMINT AI is an AI-powered investigation platform designed to assist authorized investigators in discovering, correlating, analyzing, and visualizing publicly available digital footprints across social media platforms and open-source intelligence (OSINT) sources.

The platform autonomously collects public information, correlates identities across platforms, builds behavioral profiles, analyzes relationships, generates confidence-based identity matches, and produces investigation-ready reports while maintaining strict ethical, legal, and privacy boundaries.

The system focuses exclusively on publicly available information and does not access private, restricted, or unauthorized data sources.

Problem Statement Alignment

The platform addresses:

  1. Identity Discovery
  2. Cross-Platform Identity Correlation
  3. Behavioral Analysis
  4. Content Intelligence
  5. Relationship Analysis
  6. Timeline Reconstruction
  7. Investigation Reporting

Additional Innovation:

  1. Multi-Agent Investigation System
  2. AI-Powered Identity Confidence Engine
  3. Visual Identity Matching
  4. Autonomous Investigation Planning
  5. Explainable Correlation Reasoning
  6. Graph Intelligence Engine

High-Level Architecture

Frontend ↓ API Gateway ↓ Node.js Backend ↓ FastAPI AI Services ↓ Databases + Search Layer ↓ OSINT Connectors ↓ Visualization Engine

Technology Stack

Frontend

Framework: Next.js 16

Language: TypeScript

Styling: TailwindCSS ShadCN UI

State Management: Zustand

Charts: Recharts

Graph Visualization: React Flow Cytoscape.js

Authentication: NextAuth

Backend API Layer

Runtime: Node.js

Framework: Express.js

Responsibilities:

  • Authentication
  • Authorization
  • Case Management
  • User Management
  • API Gateway
  • Audit Logging
  • Report Generation
  • Rate Limiting
  • Data Validation

AI Backend

Framework: FastAPI

Responsibilities:

  • Identity Correlation
  • NLP Analysis
  • Image Analysis
  • Similarity Scoring
  • Behavioral Analytics
  • Timeline Generation
  • Agent Orchestration

Databases

MongoDB

Purpose:

  • Users
  • Sessions
  • Cases
  • Investigation Reports
  • Settings
  • Audit Logs

Collections:

users sessions cases reports audit_logs organizations

Neo4j

Purpose:

Identity Relationship Graph

Stores:

  • Accounts
  • Emails
  • Usernames
  • Platforms
  • Connections
  • Communities

Graph Example:

Username → Instagram

Username → GitHub

Username → Reddit

Instagram → Mentioned User

GitHub → Organization

Redis

Purpose:

  • Cache
  • Session Storage
  • Agent State
  • Job Queue

MinIO / S3

Purpose:

  • Profile Images
  • Investigation Reports
  • Exported Evidence
  • Generated PDFs

AI Multi-Agent System

Stage 1

Discovery Agent

Responsibilities:

  • Username Search
  • Email Search
  • Phone Search
  • URL Discovery

Outputs:

Potential Accounts

Stage 2

Enrichment Agent

Responsibilities:

  • Profile Metadata Enrichment
  • Platform API Data Retrieval
  • Profile Detail Augmentation

Outputs:

Enriched Profiles

Stage 3

Content Intelligence Agent

Responsibilities:

  • Topic Extraction
  • Keyword Detection
  • Sentiment Analysis
  • Language Detection
  • Writing Style Analysis

Outputs:

Content Profile

Stage 4

Behavior Analysis Agent

Responsibilities:

  • Posting Frequency
  • Active Hours
  • Activity Gaps
  • Behavioral Consistency

Outputs:

Behavioral Profile

Stage 5

Visual Intelligence Agent

Responsibilities:

  • Profile Image Analysis
  • Reverse Image Matching
  • CLIP Embeddings
  • Face Similarity Analysis

Outputs:

Visual Match Confidence

Stage 6

Relationship Intelligence Agent

Responsibilities:

  • Mention Analysis
  • Community Detection
  • Mutual Connections
  • Network Clustering

Outputs:

Relationship Graph

Stage 7

Identity Correlation Agent

Responsibilities:

  • Username Similarity
  • Bio Similarity
  • Profile Similarity
  • Metadata Correlation
  • Consumes content/behavior/visual/relationship outputs

Outputs:

Identity Match Score

Stage 8

Source Verification Agent

Responsibilities:

  • Source Reliability Scoring
  • Per-Profile Trust Assessment
  • Verification Status Gating

Outputs:

Verified Sources

Stage 9

Investigation Report Agent

Responsibilities:

  • Summarization
  • Confidence Calculation
  • Report Generation

Outputs:

SOCMINT Investigation Report

Identity Confidence Engine

Weighted Scoring Model

Username Similarity = 15%

Profile Image Similarity = 20%

Bio Similarity = 10%

Shared Links = 10%

Behavior Similarity = 10%

Content Similarity = 15%

Relationship Similarity = 10%

Content Embedding = 10%

Final Score = 100%

Confidence Levels

86-100 = Very High Confidence

71-85 = High Confidence

51-70 = Moderate Confidence

26-50 = Low Confidence

0-25 = Weak Evidence

False Positive Guard Layer

The false_positive_guard.py module acts as the gating mechanism for the entire scoring system. It validates and downgrades suspicious matches before they inflate confidence scores.

validate_visual_match

Validates image similarity matches:

  • Excluded images (defaults/placeholders/logos) are zeroed out
  • Requires similarity_score >= 85, or hash_score > 95 with reuse detection
  • With face detection, requires face_score >= 75

validate_relationship_match

Validates relationship edges:

  • Same-platform edges require confidence >= 10
  • Cross-platform evidence (shared_links, mentions, follower/following) requires confidence >= 20

validate_correlation_score

Downgrades unreliable correlation signals:

  • Generic/auto-generated usernames: score multiplied by 0.3
  • Empty/placeholder bios: score zeroed out
  • Single-source shared links: score zeroed out

confidence_tier

Maps a numeric score (0-100) to a tier label using the same thresholds as scoring.confidence_level:

  • 86-100 → Very High Confidence
  • 71-85 → High Confidence
  • 51-70 → Moderate Confidence
  • 26-50 → Low Confidence
  • 0-25 → Weak Evidence

Security Architecture

Authentication

JWT Access Tokens

Refresh Tokens

Session Rotation

MFA Support

Password Hashing:

Argon2

Authorization

RBAC

Roles:

Admin

Investigator

Analyst

Viewer

API Security

Helmet

CORS

Rate Limiting

Input Validation

Request Signing

CSRF Protection

API Versioning

Data Security

AES-256 Encryption

TLS 1.3

Encrypted Backups

Secret Rotation

Environment Isolation

Audit & Compliance

Immutable Audit Logs

Activity Tracking

Case Access Tracking

Evidence Traceability

Investigation History

OSINT Data Sources

Public Sources Only

Social Platforms

Forums

Blogs

Public Communities

Public Profiles

Public Search Engines

Open Web Sources

No private account access.

No credential stuffing.

No unauthorized access.

No bypassing platform restrictions.

Visualization Layer

Identity Graph

Relationship Graph

Timeline View

Platform Activity Heatmap

Keyword Dashboard

Behavior Dashboard

Investigation Dashboard

Report Generation

PDF Export

Evidence Summary

Identity Confidence Score

Timeline Analysis

Relationship Analysis

Behavior Analysis

Source References

Limitations

Investigator Notes

Future Enhancements

Agent-to-Agent Collaboration

Voice-Based Investigation Assistant

Real-Time Monitoring

Dark Web Intelligence Module

Threat Actor Profiling

Cross-Language Identity Correlation

Deepfake Detection

Multi-Modal Intelligence Engine

Autonomous Investigation Planner

Predictive Relationship Discovery

Expected Outcome

An investigator enters:

  • Username
  • Email
  • Phone Number
  • Profile URL
  • Profile Image

The system autonomously:

  1. Discovers public accounts
  2. Correlates identities
  3. Performs image analysis
  4. Analyzes behavior
  5. Builds relationship graphs
  6. Generates timelines
  7. Produces investigation reports
  8. Explains correlation reasoning

Result:

A complete AI-powered SOCMINT investigation workspace capable of transforming fragmented online footprints into structured, explainable intelligence. If we treat this as a real production system used by a State Cyber Crime Department, National Investigation Agency, Intelligence Unit, CBI-like organization, or Corporate Threat Intelligence Center, then the hierarchy becomes much more structured.

The biggest mistake most people make is thinking:

Admin
↓
User

Real investigative systems are organized around:

  • Jurisdiction
  • Chain of command
  • Evidence integrity
  • Need-to-know access
  • Auditability

National Level Hierarchy

Platform Owner
│
├── National Administrator
│
├── State Administrator
│   │
│   ├── Regional Administrator
│   │   │
│   │   ├── Unit Commander
│   │   │   │
│   │   │   ├── Senior Investigator
│   │   │   ├── Investigator
│   │   │   ├── Intelligence Analyst
│   │   │   ├── Digital Forensics Officer
│   │   │   └── OSINT Analyst
│   │   │
│   │   ├── Legal Reviewer
│   │   └── Compliance Auditor
│   │
│   └── State Auditor
│
└── National Security Auditor

1. Platform Owner

Usually the technology provider.

Responsibilities:

  • Infrastructure
  • Security updates
  • Disaster recovery
  • Platform maintenance

Cannot:

  • View investigation data
  • Open cases
  • Read intelligence reports

This separation is critical.

2. National Administrator

Highest authority.

Examples:

  • National Cyber Crime Bureau
  • Ministry Cyber Division
  • National Intelligence Authority

Permissions:

  • Create states
  • Allocate budgets
  • Define policies
  • Create state administrators

Can view:

  • Metrics
  • Statistics

Cannot modify evidence.

3. State Administrator

Example:

Tamil Nadu Cyber Crime Wing

Permissions:

  • Create districts/regions
  • Create units
  • Assign commanders
  • Manage state investigators

Can see only state data.

4. Regional Administrator

Example:

Chennai Zone

Permissions:

  • Manage multiple units
  • Allocate resources
  • Escalate cases

5. Unit Commander

Example:

Cyber Crime Inspector

This is where investigations begin.

Permissions:

  • Create cases
  • Approve investigations
  • Assign investigators
  • Review findings
  • Approve reports

6. Senior Investigator

Handles critical investigations.

Permissions:

  • Lead investigations
  • Merge identity profiles
  • Validate evidence
  • Approve AI findings

7. Investigator

Most common user.

Permissions:

  • Create investigation
  • Search identifiers
  • Run AI agents
  • Add evidence
  • Create reports

Cannot close high-risk cases.

8. Intelligence Analyst

Focuses on analysis.

Permissions:

  • View case
  • Run analytics
  • Build profiles
  • Create intelligence summaries

Cannot modify evidence.

9. OSINT Analyst

Specialized role.

Permissions:

  • Collect public intelligence
  • Validate sources
  • Enrich profiles

Cannot approve findings.

10. Digital Forensics Officer

Permissions:

  • Analyze devices
  • Import evidence
  • Verify authenticity

Cannot modify investigations.

11. Legal Reviewer

Ensures legality.

Permissions:

  • Review evidence
  • Review warrants
  • Review privacy compliance

Can reject evidence.

12. Compliance Auditor

Permissions:

  • Read-only
  • Audit investigations
  • Review access history

Cannot change anything.

Registration Model

Public Registration

DISABLED

Never allowed.

User Creation Flow

National Admin
↓
Creates State Admin
↓
State Admin
↓
Creates Regional Admin
↓
Regional Admin
↓
Creates Unit Commander
↓
Commander
↓
Invites Investigators

Registration Lifecycle

Step 1

Commander creates user

Name
Official Email
Employee ID
Role
Unit

Step 2

System verifies

Email Domain

@gov.in
@tnpolice.gov.in
@agency.gov

Step 3

Invitation sent

Temporary Token
24-hour validity

Step 4

User completes onboarding

Password
MFA
Security Questions
Hardware Key (optional)

Step 5

Supervisor Approval

Pending
↓
Approved
↓
Active

Case-Level Access

Even if a user exists:

Investigator

they still cannot access all investigations.

Access is:

Organization
↓
Region
↓
Unit
↓
Case

Example:

Case #TN-CC-2026-001

Assigned:

Commander
Investigator A
Investigator B
Analyst C

Only these users can see it.

Evidence Approval Chain

Investigator
↓
Senior Investigator
↓
Commander
↓
Evidence Locked

After locking:

Read Only

No edits.

Authentication Security

Required:

  • Password (Argon2id)
  • MFA (TOTP)
  • Device Fingerprinting
  • IP Monitoring
  • Session Rotation
  • Hardware Security Key Support (FIDO2/WebAuthn)
  • Audit Logging

Emergency Roles

Real systems also have:

Incident Commander

Temporary role during emergencies.

And:

Break Glass Administrator

Used only when urgent access is required.

Every action is logged and reviewed later.

For your architecture, I would implement a multi-tenant government hierarchy:

National Admin
↓
State Admin
↓
Regional Admin
↓
Unit Commander
↓
Senior Investigator
↓
Investigator
↓
Intelligence Analyst
↓
OSINT Analyst
↓
Digital Forensics Officer

Separate Branch:

Compliance Auditor
State Auditor
National Auditor

This mirrors how actual intelligence, cybercrime, and law-enforcement information systems are structured, with strict role separation, approval chains, and evidence integrity controls.