The Problem That Made Us Build This
Phishing emails are getting much harder to identify.
They’re no longer the obvious scam messages with bad grammar or strange formatting. A lot of them look completely normal, with proper structure, clean language, and sometimes even convincing enough to make you pause and think before deciding whether they’re real or not.
While exploring this area, we came across several examples where it wasn’t immediately clear whether an email was genuine or malicious. That’s where the problem really stood out. Traditional spam filters and basic rule-based systems can catch simple cases, but they struggle with more realistic and well-crafted phishing attempts.
This made us realize that just relying on keywords or static rules isn’t enough anymore.
We needed a system that could look at an email from multiple angles and give a more reliable decision. More importantly, it should also explain what exactly makes an email suspicious instead of just labeling it.
That’s what led us to build TrustShield AI.
Team Members
This project was developed by:
We would like to express our sincere gratitude to @chanda_rajkumar for their valuable guidance and support throughout this project.
Their insights into system design, architecture, and development played a key role in shaping TrustShield AI.
What We Built
Once we understood the problem, the next step was figuring out how to actually solve it.
We didn’t want to build just another spam filter.
We wanted something that works in real time and actually helps users understand what’s going on.
That’s how TrustShield AI came in.
It’s a phishing detection system that runs directly inside your email and combines multiple approaches instead of relying on just one.
Here’s what we used:
- Machine Learning for classification
- URL analysis to detect suspicious links
- Rule-based checks for known phishing patterns
- Emotional tone detection (urgency, fear, etc.)
- AI-generated explanations to make results understandable
Everything runs together and gives a verdict in under a second.
TrustShield does not replace human judgement — it helps users make better decisions faster.
How It Actually Works
From the user side, everything feels simple — you open an email and instantly get a result.
But internally, a few important steps happen.
First, the Chrome extension reads the email content, extracts links, and sends this data to the backend.
Once the request reaches the backend, multiple checks run in parallel:
- a machine learning model predicts phishing probability
- URL analysis checks for suspicious or risky links
- rule-based logic detects common phishing patterns
- emotional signals identify urgency or pressure tactics
Each of these modules gives its own score.
These scores are then combined into a final trust score using a weighted approach. If the score crosses a certain threshold, the email is flagged as phishing.
Instead of just showing a result, the system also generates a short explanation so the user understands why the email is risky.
All of this happens in under a second, so the user gets real-time feedback without any delay.
System Architecture
The overall system is designed using a simple three-layer structure to keep things organized and scalable.
Presentation Layer – This includes the Chrome extension and the SOC dashboard. It’s where users interact with the system and see the phishing alerts, scores, and explanations.
Application Layer – This is the core of the system. It consists of the Flask backend, detection engine, and the explanation module. All the analysis, scoring, and decision-making happens here.
Data Layer – MongoDB is used to store all analyzed emails along with their results. This helps in tracking past activity and also supports continuous learning.
These layers work together in a pipeline: the extension captures the email, the backend processes it using multiple detection techniques, and the results are stored and displayed instantly.
Architecture Diagram
Figure 1. Overall system flow.
Technology Stack
We kept the tech stack simple and fully open-source, focusing on tools that are reliable and easy to work with.
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | HTML, CSS, JavaScript | Used to build the dashboard and UI |
| Backend | Flask (Python), asyncio | Handles API requests and processing |
| Database | MongoDB (PyMongo) | Stores email data and analysis results |
| Machine Learning | scikit-learn, pandas, numpy | Used for training and prediction |
| LLM | Ollama (phi model) | Generates explanations for detected emails |
| Browser Integration | Chrome Extension (Manifest V3) | Enables real-time detection inside email clients |
Instead of using heavy frameworks, we focused on lightweight and efficient tools.
This helped us keep the system fast, easy to deploy, and suitable for real-time phishing detection without needing high-end infrastructure.
Detection Engine
This is the core part of the system where most of the actual decision-making happens.
At first, we tried relying only on a machine learning model, but it wasn’t enough on its own. So instead of depending on a single approach, we combined multiple detection methods.
Every email goes through several checks:
- A machine learning model predicts the likelihood of phishing
- URL analysis looks for suspicious or risky links
- Rule-based logic checks for common phishing patterns
- Emotional signals detect urgency or pressure in the content
- Behavioural checks identify unusual sender activity
Each of these modules produces a score based on what it detects.
These scores are then combined using a weighted approach to generate a final trust score. If the score crosses a certain threshold, the email is flagged as phishing.
To make the result more useful, the system also generates a short explanation describing what made the email suspicious. This helps users understand the reasoning instead of just seeing a warning.
Overall, this multi-layered approach makes the detection more reliable compared to using a single model.
Detection Layers
Instead of relying on a single method, we designed the system to analyze emails using multiple layers.
Each layer focuses on a different aspect of the email, which makes the overall detection more reliable.
| Layer | Weight | What it checks |
|---|---|---|
| Machine Learning | 0.30 | Predicts phishing probability based on email content |
| URL Intelligence | 0.30 | Detects suspicious links, domains, and URL patterns |
| Rule Engine | 0.25 | Identifies common phishing patterns like urgency or fake offers |
| Emotional Analysis | 0.15 | Looks for fear, urgency, or pressure in the message |
| Behavioural Checks | 0.05 | Detects unusual sender behavior or anomalies |
| Attachment Analysis | 0.10 | Checks risky file types or suspicious attachments |
Each of these layers produces a score between 0 and 1 based on its analysis.
Instead of treating them equally, we assign weights depending on how important each signal is. For example, machine learning and URL analysis have higher influence, while behavioral checks act as supporting signals.
All these scores are then combined into a final trust score, which determines whether the email is safe or phishing.
This layered approach helps reduce false positives and makes the system more robust compared to relying on a single detection technique.
Backend Processing
Figure 2. Parallel processing.
This part shows how the backend handles email analysis. Instead of running everything sequentially, the system uses asynchronous execution to run multiple checks at the same time. This helps reduce delay and keeps the response fast.
Figure 3. Fusion scoring.
Each detection layer produces a score, and these are combined using a weighted approach. Additional risk factors like financial keywords or urgency can increase the final score, making the system more sensitive to high-risk emails.
Figure 4. URL analysis.
This module checks links inside the email for suspicious patterns such as risky domains, shortened URLs, or IP-based links. These signals contribute to identifying phishing attempts.
Figure 5. Final output.
After all checks are completed, the system returns a structured response including classification, trust score, risk level, and an explanation. This is what gets displayed to the user in real time.
SOC Dashboard
Figure 6. Monitoring interface.
This is the main dashboard used to monitor the system in real time. It shows key metrics like total emails scanned, phishing detected, legitimate emails, and overall detection accuracy. It also provides a quick input box to manually analyze suspicious emails.
Figure 6.1. Activity view.
This view displays recent email activity along with their classification (clean, high, critical). It also shows risk distribution and model-related information such as the active model, last retraining time, and accuracy, giving better visibility into system performance.
Browser Extension
Figure 7. Inline detection.
The browser extension analyzes emails directly inside Gmail and shows the result inline. It displays the trust score, confidence level, and a short explanation highlighting why the email is considered risky.
For high-risk emails, a prominent warning is shown to the user. It clearly marks the email as phishing and provides actions like “Mark as Safe” or “Keep Blocked”, helping users take immediate decisions.
How MongoDB Powers the System
One of the key components of our system is how we handle and store data, and this is where MongoDB plays an important role.
Every email that gets analyzed — whether through the dashboard or the browser extension — is stored in MongoDB along with its results. This includes details like the email content, classification (phishing or legitimate), confidence score, risk level, and timestamp.
We chose MongoDB mainly because of its flexible document-based structure. Unlike traditional relational databases, it doesn’t require a fixed schema, which makes it easier to store and manage different types of email data. Since emails can vary a lot in format, content, and structure, this flexibility helped us avoid unnecessary complexity.
Another advantage is how easily it integrates with our backend. Using PyMongo, we were able to store and retrieve data efficiently without adding extra overhead to the system.
Over time, this stored data becomes a growing collection of real-world email samples. Instead of relying only on pre-existing datasets, we now have data generated from actual usage. This can later be used for retraining the model, improving detection accuracy, and adapting to new phishing techniques.
In simple terms, MongoDB is not just acting as a database in our system — it also serves as the foundation for continuous learning and improvement.
We also used MongoDB’s aggregation pipeline to process and structure data efficiently. Operations like sorting, limiting results, and transforming fields were handled directly within the database using stages such as $addFields, $sort, $limit, and $project.
This allowed us to prepare clean and structured data for the dashboard and application without adding extra processing logic in the backend.
Figure 8.1. Logs.
This represents how retraining is tracked over time, including when it was performed and how many samples were used.
Figure 8.2. Legit email.
An example of a normal email stored in the database along with its classification, confidence score, and explanation.
Figure 8.3. Phishing email.
An example of a high-risk phishing email showing strong detection signals and detailed explanation.
Challenges We Faced
While building TrustShield AI, we ran into a few practical challenges that helped us understand the complexity of real-world systems.
One of the main challenges was handling the variety of email formats. Emails don’t follow a fixed structure, and extracting meaningful information like links and content consistently was not always straightforward.
Another issue was balancing accuracy and performance. Running multiple detection layers improves reliability, but it can also increase response time. We had to optimize the backend to ensure everything runs fast enough for real-time use.
We also faced challenges in tuning the scoring system. Deciding how much weight to give each detection layer required multiple iterations and testing with different types of emails.
Integrating different components — the extension, backend, machine learning models, and database — was another learning experience. Ensuring smooth communication between all parts took careful debugging and testing.
Overall, these challenges helped us improve both the system and our understanding of building scalable, real-time applications.
What We Learned
Building this project gave us a much clearer understanding of how complex phishing detection actually is.
At first, we assumed a single machine learning model would be enough. But as we explored more real-world examples, it became clear that phishing detection needs multiple perspectives — not just text analysis, but also links, patterns, and even the tone of the message.
Another important takeaway was the importance of explainability. Just showing a “phishing” label is not very helpful unless the user understands why the email is risky. Adding explanations made the system much more practical and user-friendly.
We also realized how important real-time performance is. Even a small delay can affect usability, so designing the system to run efficiently was just as important as making it accurate.
Overall, this project helped us move beyond theory and understand how real-world cybersecurity systems are actually built and deployed.
Try It Yourself
https://github.com/Tejus468/pfsd_project
Demo Video
Top comments (0)