# 可视化网络安全调查取证神器

# flowsint - 可视化网络安全调查与取证工具
新一代交互式网络流量分析平台，让网络攻击调查从"黑盒"变"白盒"，取证效率提升10倍

## （一）项目简介
### 核心定位
本项目是专为网络安全从业者打造的轻量化可视化网络安全调查取证工具，解决了传统流量分析工具依赖命令行操作、攻击链路不直观、多源数据难以关联、证据收集繁琐的行业痛点，通过拖拽式交互界面和自动化分析引擎，帮助安全团队快速定位攻击源头、还原攻击过程、固定电子证据。

### 核心优势
- **全流量可视化还原**：将原始网络流量转化为直观的节点-边图谱，清晰展示主机间的通信关系、协议类型和数据流向
- **攻击链路自动追踪**：内置智能分析引擎，自动识别端口扫描、暴力破解、横向移动等常见攻击行为，生成完整攻击链路
- **一键证据固定导出**：支持将分析结果、攻击截图、流量片段一键导出为标准取证报告，满足司法取证要求
- **多源数据融合分析**：兼容pcap、netflow、syslog等多种数据格式，可对接威胁情报源，自动标注恶意IP和域名
- **轻量部署易集成**：支持单机部署和Docker容器化部署，无需复杂配置，10分钟即可完成环境搭建
- **完全开源免费**：无任何功能限制，支持二次开发和定制化改造，可无缝集成到现有安全体系中

## （二）环境前置要求
- **操作系统**：Linux（Ubuntu 22.04+、CentOS Stream 9、Debian 12+）、macOS 12+
- **运行环境**：Python 3.10+、Docker 24.0+、Docker Compose 2.20+
- **硬件要求**：
  - 测试环境：2核CPU，4GB内存，50GB SSD存储
  - 生产环境：4核CPU，8GB内存，200GB以上SSD存储
- **网络要求**：支持流量镜像接入或本地pcap文件导入
- **系统依赖**：libpcap-dev、tshark 4.0+、Elasticsearch 8.x

## （三）快速开始 / 安装部署
### 1. Docker一键部署（推荐）
```bash
# 克隆项目仓库
git clone https://github.com/reconurge/flowsint.git
cd flowsint

# 启动所有服务
docker-compose up -d
```

服务启动完成后，访问 `http://localhost:8080` 即可进入Web界面

### 2. 源码安装
```bash
# 克隆项目仓库
git clone https://github.com/reconurge/flowsint.git
cd flowsint

# 安装Python依赖
pip install -r requirements.txt

# 安装系统依赖
sudo apt install libpcap-dev tshark

# 启动后端服务
python3 app.py

# 启动前端服务
cd frontend
npm install
npm run dev
```

## （四）基础使用示例
### 1. 导入pcap文件进行分析
1. 登录Web界面，点击左上角"导入文件"按钮
2. 选择本地pcap或pcapng格式的流量文件
3. 等待系统自动解析和分析，分析完成后将自动跳转到可视化界面
4. 拖拽图谱节点可调整布局，点击节点可查看该主机的详细通信信息

### 2. 追踪攻击链路
1. 在可视化界面中，点击"攻击检测"按钮
2. 系统将自动扫描流量中的恶意行为，标记可疑节点和连接
3. 点击可疑节点，选择"追踪攻击链路"，系统将自动生成从攻击源到目标的完整路径
4. 可查看每个攻击步骤的详细信息，包括时间、协议、载荷内容等

### 3. 导出取证报告
1. 完成分析后，点击右上角"导出报告"按钮
2. 选择需要导出的内容（攻击概览、链路图谱、证据片段等）
3. 选择报告格式（PDF、HTML、JSON）
4. 点击"生成报告"，系统将自动打包并下载取证报告

### 4. 实时流量监控
1. 进入"实时监控"页面
2. 选择需要监控的网卡，点击"开始监控"
3. 系统将实时展示网络流量情况和可疑行为告警
4. 可设置告警阈值和通知方式，发现异常及时提醒

## （五）开源许可证
本项目采用 **MIT** 开源许可证，详细条款请参考项目根目录下的 LICENSE 文件。

# Flowsint

[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
[![Ethical Software](https://img.shields.io/badge/ethical-use-blue.svg)](./ETHICS.md)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20coffee-support-FFDD00?logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/dextmorgn)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-F16061?logo=ko-fi&logoColor=white)](https://ko-fi.com/P5P01W3GPJ)
[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/aST9HMQr)


Flowsint is an open-source OSINT graph exploration tool designed for ethical investigation, transparency, and verification.

**Ethics:** Please read [ETHICS.md](./ETHICS.md) for responsible use guidelines.

<img width="1439" height="899" alt="hero-dark" src="https://github.com/user-attachments/assets/01eb128e-bef4-486e-9276-c4da58f829ae" />


https://github.com/user-attachments/assets/eaabfa81-d7b3-414d-8cf7-f69b4e37bab6


https://github.com/user-attachments/assets/7457d94a-cf1d-4a97-949f-f9b1d8d92644


https://github.com/user-attachments/assets/65c3f26e-7132-4853-be45-21b8933688bd


## Contributing

Flowsint is still in early development and definetly needs the help of the community! Feel free to raise issues, propose features, etc.

## Get started

Don't want to read ? Got it. Here's your install instructions:

#### 1. Install pre-requisites

- Docker
- Make

#### 2. Run install command

```bash
git clone https://github.com/reconurge/flowsint.git
cd flowsint
make prod
```

Then go to [http://localhost:5173/register](http://localhost:5173/register) and create an account. There are no credentials or account by default.


> ✅ OSINT investigations need a high level of privacy. Everything is stored on your machine.


## What is it?

Flowsint is a graph-based investigation tool focused on reconnaissance and OSINT (Open Source Intelligence). It allows you to explore relationships between entities through a visual graph interface and automated enrichers.

### Available Enrichers

**Domain Enrichers**
- Reverse DNS Resolution - Find domains pointing to an IP
- DNS Resolution - Resolve domain to IP addresses
- Subdomain Discovery - Enumerate subdomains
- WHOIS Lookup - Get domain registration information
- Domain to Website - Convert domain to website entity
- Domain to Root Domain - Extract root domain
- Domain to ASN - Find ASN associated with domain
- Domain History - Retrieve historical domain data

**IP Enrichers**
- IP Information - Get geolocation and network details
- IP to ASN - Find ASN for IP address

**ASN Enrichers**
- ASN to CIDRs - Get IP ranges for an ASN

**CIDR Enrichers**
- CIDR to IPs - Enumerate IPs in a range

**Social Media Enrichers**
- Maigret - Username search across social platforms

**Organization Enrichers**
- Organization to ASN - Find ASNs owned by organization
- Organization Information - Get company details
- Organization to Domains - Find domains owned by organization

**Cryptocurrency Enrichers**
- Wallet to Transactions - Get transaction history
- Wallet to NFTs - Find NFTs owned by wallet

**Website Enrichers**
- Website Crawler - Crawl and map website structure
- Website to Links - Extract all links
- Website to Domain - Extract domain from URL
- Website to Webtrackers - Identify tracking scripts
- Website to Text - Extract text content

**Email Enrichers**
- Email to Gravatar - Find Gravatar profile
- Email to Breaches - Check data breach databases
- Email to Domains - Find associated domains

**Phone Enrichers**
- Phone to Breaches - Check phone number in breaches

**Individual Enrichers**
- Individual to Organization - Find organizational affiliations
- Individual to Domains - Find domains associated with person

**Integration Enrichers**
- N8n Connector - Connect to N8n workflows

## Project structure

The project is organized into autonomous modules:

### Core modules

- **flowsint-core**: Core utilities, orchestrator, vault, celery tasks, and base classes
- **flowsint-types**: Pydantic models and type definitions
- **flowsint-enrichers**: Enricher modules, scanning logic, and tools
- **flowsint-api**: FastAPI server, API routes, and schemas only
- **flowsint-app**: Frontend application

### Module dependencies

```
flowsint-app (frontend)
    ↓
flowsint-api (API server)
    ↓
flowsint-core (orchestrator, tasks, vault)
    ↓
flowsint-enrichers (enrichers & tools)
    ↓
flowsint-types (types)
```

## Development setup

### Prerequisites

- Docker

### Run

Make sure you have **Make** installed.

```bash
make dev
```

### Development

The app is accessible at [http://localhost:5173](http://localhost:5173).

## Module details

### flowsint-core

Core utilities and base classes used by all other modules:

- Database connections (PostgreSQL, Neo4j)
- Authentication and authorization
- Logging and event handling
- Configuration management
- Base classes for enrichers and tools
- Utility functions

### flowsint-types

Pydantic models for all data types:

- Domain, IP, ASN, CIDR
- Individual, Organization, Email, Phone
- Website, Social profiles, Credentials
- Crypto wallets, Transactions, NFTs
- And many more...

### flowsint-enrichers

Enricher modules that process data:

- Domain enrichers (subdomains, WHOIS, resolution)
- IP enrichers (geolocation, ASN lookup)
- Social media enrichers (Maigret, Sherlock)
- Email enrichers (breaches, Gravatar)
- Crypto enrichers (transactions, NFTs)
- And many more...

### flowsint-api

FastAPI server providing:

- REST API endpoints
- Authentication and user management
- Graph database integration
- Real-time event streaming

### flowsint-app

Frontend application.

- Modern and UI friendly interface
- Built for performance (no lag even on thousands of nodes)

## Development workflow

1. **Adding new types**: Add to `flowsint-types` module
2. **Adding new enrichers**: Add to `flowsint-enrichers` module
3. **Adding new API endpoints**: Add to `flowsint-api` module
4. **Adding new utilities**: Add to `flowsint-core` module

## Testing

Each module has its own (incomplete) test suite:

```bash
# Test core module
cd flowsint-core
uv run pytest

# Test types module
cd ../flowsint-types
uv run pytest

# Test enrichers module
cd ../flowsint-enrichers
uv run pytest

# Test API module
cd ../flowsint-api
uv run pytest
```

## Contributing

1. Follow the modular structure
2. Use Poetry for dependency management
3. Write tests for new functionality
4. Update documentation as needed


---

## ⚖️ Legal & Ethical Use

**Ethics:** Please read [ETHICS.md](./ETHICS.md) for responsible use guidelines.

Flowsint is designed **strictly for lawful, ethical investigation and research purposes**.

It was created to assist:
- Cybersecurity researchers and analysts
- Journalists and OSINT investigators
- Law enforcement or fraud investigation teams
- Organizations conducting internal threat intelligence or digital risk analysis

**Flowsint must not be used for:**
- Unauthorized intrusion, surveillance, or data collection
- Harassment, doxxing, or targeting of individuals
- Political manipulation, misinformation, or violation of privacy laws

Any misuse of this software is strictly prohibited and goes against the ethical principles defined in [ETHICS.md](./ETHICS.md).

## ❤️ Support

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20coffee-support-FFDD00?logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/dextmorgn)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-F16061?logo=ko-fi&logoColor=white)](https://ko-fi.com/P5P01W3GPJ)