Waymark
Phishing detection and investigation, with agents that work from the evidence.
The project ↓Waymark helps SOC analysts detect and investigate phishing emails. Built at ODDO BHF Tunis, it brings email analysis, indicator checks, and AI investigation agents into one workspace connected to TheHive.
- The problem
- An analyst needs to assess a reported email, keep its evidence together, and know exactly what changed in the case.
- The solution
- Email analysis and detection rules identify suspicious findings. Reputation checks add context, and investigation agents explain the evidence and propose next steps.
- The outcome
- A working investigation flow from reported email to a reviewed report, approved case actions, and verified records in TheHive.
Inside the system.
How it works.
The complete path
A reported email becomes a review. The analyst investigates, approves the plan, and checks the resulting TheHive record.
Start with the reported email
A TheHive webhook queues the alert. A worker imports the case and reads the attached email for the assigned analyst.
A verdict with its reasons
Email facts feed detection rules and a decision table. The verdict is deterministic; it does not come from a model.
Bring in the supporting checks
Reputation and sandbox results become evidence. Missing or failed checks remain visible, and new results can reopen a review.
Read evidence and propose a next step
Copilot or Bedrock investigates with read-only tools. The agent can draft task notes and propose changes for the analyst.
Approve the exact change
An approved change runs as a job, is read back from TheHive, and leaves a receipt. An uncertain result is held for reconciliation.
Project images.
Technical notes
Detection and investigation are separate
The parser extracts authentication, links, attachments, and sender context. YAML rules and a decision table determine the review verdict. The model’s assessment is kept separate from that result.
Evidence stays attached to the case
Google Safe Browsing, abuse.ch, VirusTotal, IPQualityScore, RDAP, urlscan, and Hybrid Analysis support the investigation. A source that was skipped or failed is shown as such. External URL and file submissions require an analyst action.
Models read and propose
Investigation agents inspect email evidence, explain suspicious findings, and draft case tasks. GitHub Copilot SDK and Amazon Bedrock connect the agents to investigation tools. Specialist agents examine different parts of the evidence, combine their findings, and check that proposals cite their sources.
Review, execute, and verify
Approvals are tied to the case and evidence revisions the analyst reviewed. Each approved change gets a job identity and lease. The application reads the value back from TheHive; an unknown outcome requires reconciliation instead of an automatic retry. Email and case text are treated as untrusted data before reaching a model.
Application design and validation
React and TypeScript power the investigation interface. FastAPI, an arq worker, Redis, and SQLite handle analysis jobs and case data. Nginx provides the TLS entry point, and Docker Compose runs the services together.
Functional walkthroughs covered intake, evidence review, approved and declined proposals, restart recovery, and the resulting TheHive records. The documented suite contains about 3,550 backend tests, with additional interface checks.