FOFA Sentinel

A modern, hacker-style web application for proactive security reconnaissance using the FOFA API.

English • 简体中文 • 繁體中文

Features • Installation • Documentation • Contributing

Screenshot

FOFA Sentinel Query Interface

Features

• 🔍 Complete FOFA API Integration - All API endpoints supported
• 💾 Query History - Save and manage your search queries
• 📊 Result Storage - Store query results in SQLite database
• 📄 Export Results - Export results in JSON, TXT, or CSV formats
• 🔐 API Key Management - Secure API key storage
• 🎨 Hacker-Style UI - Modern, professional interface with terminal aesthetics

Tech Stack

• Frontend: React + TypeScript + Vite
• Backend: Node.js + Express + TypeScript
• Database: SQLite (better-sqlite3)

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Install dependencies
npm install

# Copy environment file (optional)
cp .env.example .env

# Run development server (both frontend and backend)
npm run dev

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3002 (default, configurable via .env)

First Time Setup

1. Start the application: npm run dev
2. Navigate to the Settings page (CONFIG in sidebar)
3. Enter your FOFA API Key from https://fofa.info/user/personal
4. Click "SAVE" to store your credentials
   • Note: Your email will be automatically retrieved from your account info

Build for Production

npm run build

Running Production Build

After building, you can run the production server:

# Start the server
npm run build:server

# The server will run on port 3002 (or PORT from .env)
# The server will automatically serve the frontend build from dist/client

Docker Deployment

Using Docker Compose (Recommended)

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

The application will be available at http://localhost:3002

Using Docker directly

# Build the image
docker build -t fofa-sentinel .

# Run the container
docker run -d \
  --name fofa-sentinel \
  -p 3002:3002 \
  -v $(pwd)/data:/app/data \
  fofa-sentinel

# View logs
docker logs -f fofa-sentinel

# Stop the container
docker stop fofa-sentinel
docker rm fofa-sentinel

Environment Variables

You can set environment variables in docker-compose.yml or pass them when running:

docker run -d \
  --name fofa-sentinel \
  -p 3002:3002 \
  -e PORT=3002 \
  -v $(pwd)/data:/app/data \
  fofa-sentinel

Note: The database will be persisted in the ./data directory. Make sure this directory exists and has proper permissions.

Documentation

• Environment Variables - Configuration guide
• Troubleshooting - Common issues and solutions
• Contributing - How to contribute
• Changelog - Version history

Project Structure

fofa/
├── src/
│   ├── server/          # Backend server
│   │   ├── index.ts     # Server entry point
│   │   ├── routes/      # API routes
│   │   ├── db/          # Database setup
│   │   └── services/    # Business logic
│   ├── client/          # Frontend React app
│   │   ├── components/  # React components
│   │   ├── pages/       # Page components
│   │   ├── hooks/       # Custom hooks
│   │   └── utils/       # Utilities
│   └── shared/          # Shared types
├── docs/                # Documentation
├── .github/             # GitHub templates and workflows
├── data/                # SQLite database files
└── public/              # Static assets

API Endpoints

FOFA API Wrapper

• POST /api/fofa/search - Search hosts
• POST /api/fofa/stats - Get statistics
• POST /api/fofa/host - Host aggregation
• GET /api/fofa/account - Account information
• POST /api/fofa/search-after - Search after (pagination)

Application API

• GET /api/history - Get query history
• GET /api/history/:id - Get specific query
• DELETE /api/history/:id - Delete query
• GET /api/results/:id - Get query results
• POST /api/export/:id - Export results as TXT
• POST /api/config/key - Save API key
• GET /api/config/key - Get API key (masked)

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• FOFA - For providing the excellent security search engine API
• Design inspiration from terminal and hacker aesthetics

Support

If you find this project helpful, please consider giving it a ⭐ on GitHub!

---

Made with ❤️ by the FOFA Sentinel contributors