FraudLensAI

An autonomous fraud investigation agent built with Node.js, Neo4j, Tavily Search API, and Fastino AI.

Features

• POST /investigate — Accepts a suspicious entity (email, phone, crypto wallet, or domain) and runs a 4-step autonomous investigation:
  1. OSINT search via Tavily API (scam mentions, complaints, reputation signals)
  2. Store entity as a node in Neo4j graph database
  3. Extract and link related entities (domains, emails, wallets) as graph relationships
  4. Score fraud risk and generate explanation via Fastino AI
• GET /health — Liveness check endpoint
• Web UI (/) — Browser interface for submitting investigations and viewing risk score, evidence, and graph connections
• Demo mode fallback — If integrations are not configured, POST /investigate returns simulated investigation data so the frontend remains usable

Tech Stack

Concern	Technology
Runtime	Node.js + Express
Graph database	Neo4j
OSINT search	Tavily Search API
AI risk scoring	Fastino AI
HTTP client	Axios
Config	dotenv

Project Structure

├── app.js                    # Express entry point
├── routes/
│   ├── health.js             # GET /health
│   └── investigate.js        # POST /investigate (orchestration)
├── services/
│   ├── tavilyService.js      # Tavily OSINT search
│   ├── fastinoService.js     # Fastino AI risk scoring
│   └── neo4jService.js       # Neo4j graph operations
├── db/
│   └── neo4jDriver.js        # Neo4j driver singleton
├── utils/
│   ├── entityExtractor.js    # Extract related entities from OSINT results
│   ├── riskLevel.js          # riskScore → riskLevel helper
│   └── logger.js             # Step-by-step investigation logger
├── public/
│   ├── index.html            # Frontend page
│   ├── styles.css            # Frontend styles
│   └── frontend.js           # Frontend logic
└── .env.example              # Environment variable template

Setup

Prerequisites

• Node.js 18+
• A running Neo4j instance (local or Neo4j Aura)
• Tavily API key
• Fastino AI API key

Installation

git clone https://github.com/siddz415/FraudLensAI.git
cd FraudLensAI
npm install
cp .env.example .env
# Edit .env and fill in your credentials
npm start

Environment Variables

Variable	Description
TAVILY_API_KEY	Tavily Search API key
FASTINO_API_KEY	Fastino AI API key
NEO4J_URI	Neo4j connection URI (e.g. bolt://localhost:7687)
NEO4J_USER	Neo4j username
NEO4J_PASSWORD	Neo4j password
DEMO_MODE	Force demo responses (true or false)
PORT	Server port (default: 3000)

Web Interface

After starting the server, open:

http://localhost:3000/

Use the form to submit an entity type and value. The UI calls POST /investigate and displays:

• risk score and risk level
• AI-generated summary
• evidence snippets
• graph connections

If required credentials are missing, the endpoint automatically responds with simulated demo data. Set DEMO_MODE=true in .env to force demo responses even when credentials are present.

API Reference

GET /health

Returns service liveness status.

Response:

{
  "status": "ok",
  "service": "FraudLensAI",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

POST /investigate

Runs the full fraud investigation flow.

Request body:

{
  "type": "email | phone | wallet | domain",
  "value": "suspicious@example.com"
}

Response:

{
  "entity": "suspicious@example.com",
  "riskScore": 82,
  "riskLevel": "Critical",
  "summary": "This email address has been linked to multiple phishing campaigns...",
  "evidence": ["User reports on ScamAdviser indicate...", "..."],
  "graphConnections": [
    { "value": "evil-domain.com", "type": "domain" },
    { "value": "0xABCDEF...", "type": "wallet" }
  ]
}

Risk levels:

Score range	Level
0–39	Low
40–59	Medium
60–79	High
80–100	Critical

Deployment (Render)

1. Push the repository to GitHub.
2. Create a new Web Service on Render.
3. Set Build Command: npm install
4. Set Start Command: npm start
5. Add all environment variables from .env.example in the Render dashboard.