FortressAI is a full-stack cybersecurity platform with two operating modes in one repo:

• Demo mode: original attack-response-log simulation flow for presentations
• Demo link: https://fortress-ai-delta.vercel.app/
• Guardian mode: production-oriented blockchain wallet security for individuals and SMEs

The Guardian extension is focused on wallet drain prevention, phishing detection, risky approvals, malicious contract analysis, and real-time alerting.

• Frontend: Next.js 14 (TypeScript)
• Backend: FastAPI (Python)
• Realtime: Socket.IO + WebSocket endpoints
• Queue: Celery + Redis
• Database: PostgreSQL 16 + TimescaleDB
• Infra: Docker Compose (local), Kubernetes/EKS manifests (production)

• Recon / simulate / respond / log API pipeline
• Live dashboard at /demo
• Metrics websocket at /ws/status

• JWT auth (/guardian/auth/register, /guardian/auth/login)
• Wallet monitoring (/guardian/monitor-wallet)
• Token approval scanner (/guardian/scan-approvals)
• Smart contract analyzer (/guardian/analyze-contract)
• Phishing URL checker (/guardian/check-phishing)
• Alert management (/guardian/alerts, alert actions)
• SIEM / IDS / firewall ingestion endpoints
• Real-time alert push over Socket.IO (alerts:update)

Implemented with real API/service paths and cache fallbacks:

• Etherscan API (tx history and contract metadata)
• GoPlus Security API (address/token risk signals)
• MetaMask eth-phishing-detect feed
• PhishTank feed
• ELK-compatible ingest hook (ELASTIC_INGEST_URL, optional)
• Alert providers via Celery queue:
  • Discord webhook
  • Telegram bot
  • SendGrid email
  • Twilio SMS

frontend (Next.js)
  /demo       -> legacy cyber demo UI
  /guardian   -> blockchain security dashboard

backend (FastAPI + Socket.IO ASGI app)
  /scan, /simulate, /tunnel, /log
  /guardian/*
  /ws/status
  Socket.IO event: alerts:update

services
  blockchain_guardian.py  -> monitor/scan/analyze/check logic
  integrations.py         -> Etherscan/GoPlus/phishing feeds
  alerts.py               -> alert persistence + SIEM + realtime emit
  notifications.py        -> provider fanout (Discord/Telegram/SendGrid/Twilio)

tasks (Celery)
  guardian scans
  alert delivery with retries

.
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── realtime.py
│   │   ├── routers/
│   │   │   ├── api.py
│   │   │   └── guardian.py
│   │   ├── services/
│   │   ├── tasks.py
│   │   └── ws/socket.py
│   └── tests/
├── frontend/
│   ├── app/
│   │   ├── demo/page.tsx
│   │   └── guardian/page.tsx
│   └── lib/
├── infra/
│   └── k8s/
├── scripts/
└── docker-compose.yml

• GitHub-safe template: .env.example
• Local secrets file (git-ignored): .env
• Kubernetes secret template: infra/k8s/guardian-secrets.example.yaml
• Real local .env path in this workspace: /workspaces/FortressAI/.env

Create local env from template:

cp .env.example .env

docker compose up --build

Services:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• Postgres: localhost:5432
• Redis: localhost:6379

• Demo: http://localhost:3000/demo
• Guardian: http://localhost:3000/guardian

On backend startup, FortressAI seeds two default Guardian users if they do not already exist:

• demo.hk@fortressai.local / Fortress123! (region HK)
• demo.ke@fortressai.local / Fortress123!

• DATABASE_URL
• REDIS_URL
• JWT_SECRET_KEY

• ETHERSCAN_API_KEY
• ETHERSCAN_BASE_URL (optional override)
• GOPLUS_BASE_URL (optional override)
• METAMASK_PHISHING_URL (optional override)
• PHISHTANK_FEED_URL (optional override)

• ELASTIC_INGEST_URL (optional)
• AWS_SECURITY_HUB_ENABLED (optional)
• AWS_REGION (optional)

• DISCORD_WEBHOOK_URL
• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• SENDGRID_API_KEY
• ALERT_EMAIL_FROM
• ALERT_EMAIL_TO
• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_FROM_NUMBER
• TWILIO_TO_NUMBER

Base URL: http://localhost:8000

• POST /scan
• POST /simulate
• POST /tunnel
• POST /log
• GET /status

• POST /guardian/auth/register
• POST /guardian/auth/login
• GET /guardian/auth/me
• POST /guardian/monitor-wallet
• POST /guardian/scan-approvals
• POST /guardian/analyze-contract
• POST /guardian/check-phishing
• GET /guardian/alerts
• POST /guardian/alerts/{alert_id}/action
• POST /guardian/ingest/siem
• POST /guardian/ingest/ids
• POST /guardian/ingest/firewall
• GET /guardian/startup-check
• GET /guardian/telegram/chat-id
• GET /guardian/telegram/recent-updates
• POST /guardian/telegram/discover-chat-id
• POST /guardian/telegram/store-chat-id

• WS /ws/status (legacy metrics)
• Socket.IO namespace default at /socket.io
• Socket.IO auth: auth.token = <JWT>
• Event emitted by backend: alerts:update

Alert fanout is queued through Celery task:

• tasks.alert.deliver

Retry strategy:

• Exponential backoff
• Jitter enabled
• Max retries: 5

cd frontend
npm test -- --watch=false
npm run build

pip install -r backend/requirements.txt
pytest -q backend/tests

Run unit-focused tests only:

pytest -q backend/tests -m "not integration"

Run integration tests only:

pytest -q backend/tests -m integration

Discover chat IDs from recent updates and persist one to .env:

python scripts/telegram_chat_id_helper.py --save-env

Choose a specific chat ID instead of latest:

python scripts/telegram_chat_id_helper.py --choose <chat_id> --save-env

Current backend tests include:

• Guardian route behavior
• Risk-scoring paths
• Socket.IO JWT connect + alerts:update emission flow
• Network-level Socket.IO AsyncClient integration test against live Uvicorn app

Use:

scripts/deploy_eks_5min.sh

Required env:

• AWS_ACCOUNT_ID

Optional env:

• AWS_REGION
• IMAGE_TAG
• K8S_NAMESPACE
• ECR_REPO_BACKEND
• ECR_REPO_FRONTEND

Use infra/k8s/guardian-secrets.example.yaml as the starting point for cluster secrets.

• Private keys are never stored.
• Wallet monitoring is consent-based via registered wallet addresses.
• Sensitive integration credentials are expected from env or Kubernetes secrets.
• API middleware includes request rate limiting.

• Some provider features require API keys and may fallback to cache/partial signals without them.
• Contract analysis currently combines explorer metadata + risk feeds + heuristic checks, not full symbolic execution in cluster by default.
• Legacy demo tests may reference older UI labels; Guardian tests are separate.