AEGIS Scam Guard

architecture-pro
gcp-console
gcp-logs-webhook-message-sent
whatsapp-scam-verdict

Inspiration

Scam messages can harm people before they have time to ask for help. A fake bank alert, a phishing link, an impersonation message, or a suspicious image can pressure someone into clicking, sharing private information, or sending money.

AEGIS Scam Guard was built to protect people at the exact moment they need help: inside WhatsApp, where many scam messages already arrive.

What it does

AEGIS Scam Guard is an AI-powered WhatsApp safety assistant. A user forwards a suspicious message, link, image, or voice note to the bot, and AEGIS replies with a clear scam-risk explanation.

The bot explains:

Whether the content looks safe, suspicious, or scam-like
What warning signs were detected
Why the message may be risky
What the user should do next

The goal is to make scam detection understandable for everyday people, not only cybersecurity experts.

How we built it

AEGIS is built as a real cloud-based AI system.

The platform uses:

WhatsApp Business Cloud API for user interaction
Python and FastAPI for backend services
Google Cloud Run for deployed services
Pub/Sub for asynchronous message processing
Google ADK and Gemini for agent reasoning
Firestore for case state and scam-pattern memory
Cloud KMS and Secret Manager for privacy and secure contact handling
React and Vite for the public project website
Terraform and Docker for deployment infrastructure

When a user sends a message, the ingestion service verifies the webhook, normalizes the content, and publishes it to Pub/Sub. The agent service then analyzes the report, stores the result, and sends a plain-language reply back to WhatsApp.

What makes it useful

AEGIS focuses on accessibility. A user does not need to install a new app, understand cybersecurity terms, or know how to inspect a link manually. They can simply forward a message and get a readable safety explanation.

This is especially useful for students, families, older adults, and anyone who may not have immediate access to technical help.

Challenges we faced

The hardest part was making the project work like a real deployed system instead of a simple demo.

We worked through:

Real WhatsApp webhook setup
Media handling for images and voice notes
Cloud Run deployment
Pub/Sub message flow
Gemini/Vertex AI quota limits
Firestore state storage
Privacy-safe user identification
Logs and production proof for judges

One important production issue was that image messages reached the backend, but the AI model could hit a quota limit and fail before replying. We fixed this by adding a fallback response so users are not left without feedback.

What we learned

We learned that social-good AI needs more than a model. It needs reliability, clear communication, privacy protection, and a workflow that normal users can actually use.

We also learned how important it is to design AI tools around real user behavior. People already receive scams on WhatsApp, so AEGIS meets them there instead of asking them to move to a separate security tool.