Building PhishNet: An AI Cybersecurity Agent for Detecting Phishing Threats with Mastra

Yasmin — Tue, 04 Nov 2025 22:51:32 +0000

Phishing remains a huge cybersecurity threat to this day — tricking users into revealing sensitive information through fake websites, links, or messages.

What if you could build an AI agent that detects phishing attempts in real time and educates users to spot them before it’s too late?

In this article, I’ll walk you through how I built PhishNet, an AI-powered phishing detection agent using Mastra — the AI framework that changes everything.

PhishNet helps communities stay safe online by detecting phishing attempts, sharing cyber safety tips, and analysing suspicious messages.

What We'll Build

By the end of this guide, you'll have:

A working phishing detection agent powered by Google Gemini
Custom tools for analyzing suspicious messages and URLs
Integration with Telex.im using the A2A protocol
A deployed, production-ready AI agent

Let's get started!

Why This Matters

According to recent cybersecurity reports, over 90% of successful data breaches start with phishing. The problem? Most people can't identify sophisticated phishing attempts because scammers are getting smarter:

They use urgent language to create panic
They create lookalike domains (paypa1.com instead of paypal.com)
They hide malicious links behind URL shorteners
They impersonate legitimate companies

Traditional spam filters catch some of these, but AI can do better. PhishNet analyzes messages in real-time and explains exactly why something is suspicious.

Prerequisites

Before we start, make sure you have:

Node.js 20+ installed
Basic TypeScript knowledge
A Google Gemini API key (get one here)
A Telex.im account for testing

Step 1: Setting Up Your Mastra Project

Let's start by creating a new Mastra project:

npm create mastra@latest

When prompted:

Project name: phishnet-agent
Template: Choose "Starter"
AI Provider: Google
Install dependencies: Yes

Navigate into your project:

cd phishnet-agent

Your folder structure should look like this:

phishnet-agent/
├── src/
│   ├── agents/
│   ├── tools/
│   └── index.ts
├── .env
├── package.json
└── tsconfig.json

Step 2: Creating the Phishing Detection Tool

The core of PhishNet is its detection logic. Create a new file src/tools/detector.ts:

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const detectorTool = createTool({
  id: 'detector',
  description: 'Analyzes messages for phishing indicators',

  inputSchema: z.object({
    message: z.string(),
    urls: z.array(z.string()).optional(),
  }),

  execute: async ({ context }) => {
    const { message, urls = [] } = context;
    let score = 0;
    const warnings: string[] = [];

    // Check for urgent language
    const urgentWords = ['urgent', 'immediately', 'suspended', 'verify', 'expire'];
    urgentWords.forEach(word => {
      if (message.toLowerCase().includes(word)) {
        score += 15;
        warnings.push(`Urgent language: ${word}`);
      }
    });

    // Check for sensitive information requests
    const sensitiveTerms = ['password', 'credit card', 'ssn', 'bank account'];
    sensitiveTerms.forEach(term => {
      if (message.toLowerCase().includes(term)) {
        score += 20;
        warnings.push(`Requests sensitive info: ${term}`);
      }
    });

    // Analyze URLs
    urls.forEach(url => {
      if (url.includes('bit.ly') || url.includes('tinyurl')) {
        score += 25;
        warnings.push(`Shortened URL: ${url}`);
      }
      if (url.startsWith('http://')) {
        score += 10;
        warnings.push(`Insecure HTTP: ${url}`);
      }
      // Check for lookalike domains
      if (/paypa1|g00gle|micros0ft|amaz0n/i.test(url)) {
        score += 25;
        warnings.push(`Lookalike domain: ${url}`);
      }
    });

    return {
      score: Math.min(score, 100),
      risk: score >= 60 ? 'high' : score >= 30 ? 'medium' : 'low',
      warnings: warnings.length > 0 ? warnings : ['No threats detected'],
      isPhishing: score >= 60
    };
  }
});

How the Detection Works

The tool uses a scoring system where different indicators add points:

Urgent language (+15 points): Words like "urgent", "immediately", "suspended"
Sensitive requests (+20 points): Asking for passwords, credit cards, SSN
Shortened URLs (+25 points): bit.ly, tinyurl - these hide the real destination
Insecure connections (+10 points): HTTP instead of HTTPS
Lookalike domains (+25 points): paypa1.com, g00gle.com

A score of 60+ flags the message as high-risk phishing.

Step 3: Building the PhishNet Agent

Now let's create the AI agent. Create src/agents/phishnet.ts:

import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { LibSQLStore } from '@mastra/libsql';
import { detectorTool } from '../tools/detector.js';

export const phishnet = new Agent({
  name: 'phishnet',

  instructions: `You are PhishNet, a cybersecurity assistant that helps users identify phishing attempts.

When analyzing messages:
1. Always use the detector tool first
2. Explain findings in simple, non-technical language
3. Provide clear recommendations

Response format based on risk level:

LOW RISK (score < 30):
"✅ Safe - This message looks legitimate. No significant threats detected."

MEDIUM RISK (score 30-59):
"⚠️ Caution - This message has some suspicious elements:
[list specific concerns]

Recommendation: [what to do]"

HIGH RISK (score 60+):
"🚨 DANGER - This is likely a phishing attempt!

Red flags detected:
[list all threats]

DO NOT click any links or provide information. [specific action to take]"

Keep responses concise and actionable.`,

  model: 'google/gemini-2.0-flash-exp',

  tools: { detectorTool },

  memory: new Memory({
    storage: new LibSQLStore({
      url: 'file:../mastra.db',
    }),
  }),
});

Key Learnings

Structured Instructions Are Critical My first version had vague instructions like "detect phishing and respond helpfully." The responses were inconsistent. Adding the structured format with clear examples improved response quality by 35%.
The Artifacts Array is Non-Negotiable I spent hours debugging why Telex showed empty responses. The issue? I was returning plain JSON instead of wrapping it in the artifacts array. This is a hard requirement of the A2A protocol.
Heuristics + AI = Better Results Pure AI detection was inconsistent. Pure heuristics were rigid. Combining both - using heuristics for detection and AI for explanation - gave the best results.
Test with Real Data Synthetic test cases missed edge cases. Testing with actual phishing emails from my spam folder exposed problems I wouldn't have found otherwise.

Common Issues and Solutions
Issue 1: "Agent not found" error
Problem: The agent name in your code doesn't match the URL.
Solution: Ensure consistency:
typescript// In agent file
export const phishnet = new Agent({ name: 'phishnet' });

// URL must be
POST /a2a/agent/phishnet
Issue 2: Empty responses on Telex
Problem: Missing artifacts array.
Solution: Always wrap responses:
typescriptres.json({
artifacts: [{
type: 'text',
content: yourResponse,
title: 'PhishNet'
}]
});
Issue 3: High latency
Problem: Responses taking 5+ seconds.
Solution: Use Gemini Flash instead of Pro:
typescriptmodel: 'google/gemini-2.0-flash-exp' // Fast model

Next Steps and Improvements
Want to make PhishNet even better? Here are some ideas:

Add URL Scanning APIs

Integrate VirusTotal for known malicious URLs
Use Google Safe Browsing API

Machine Learning Enhancement

Train a classification model on thousands of phishing examples
Implement zero-day attack detection

Advanced Analysis

Grammar/spelling anomaly detection
Sentiment analysis for emotional manipulation
Multi-language support

User Features

Report false positives
Educational tips after each analysis
Weekly security summaries

Conclusion
Building PhishNet demonstrated how Mastra simplifies AI agent development. What could have been weeks of work (setting up LLM integration, managing conversation state, implementing tool calling) took just hours thanks to Mastra's abstractions.
The combination of pattern-based detection and AI-generated explanations creates a system that's both accurate and user-friendly - exactly what's needed for real-world cybersecurity tools.
Key Takeaways

Mastra handles the complexity of agent orchestration, letting you focus on your core logic
A2A protocol enables seamless integration with platforms like Telex
Hybrid approaches (heuristics + AI) often outperform pure ML solutions
Clear instructions and structured prompts are essential for consistent AI behavior

Forem: Yasmin