flowsint README

The project's README from github.com/reconurge/flowsint. As one markdown file: README.md.

Flowsint

License Ethical Software Buy Me A Coffee Ko-fi Discord

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

Ethics: Please read ETHICS.md for responsible use guidelines.

hero-dark

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:

Linux / macOS

1. Install pre-requisites

2. Run install command

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

Windows

No Make needed. Works in both Command Prompt (cmd) and PowerShell.

1. Install pre-requisites

2. Clone and set up environment files

git clone https://github.com/reconurge/flowsint.git
cd flowsint

copy .env.example .env
copy .env.example flowsint-api\.env
copy .env.example flowsint-core\.env
copy .env.example flowsint-app\.env

3. Start

docker compose -f docker-compose.prod.yml up -d

This pulls the pre-built images from GitHub Container Registry — no local build needed.

First login

Then go to 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.

Deploy on a network (team / server)

The same setup works out of the box on a server: the frontend serves the UI and proxies all API calls internally, so no extra configuration is needed for clients.

git clone https://github.com/reconurge/flowsint.git
cd flowsint
cp .env.example .env
# Edit .env — see "Before exposing to a network" below
docker compose -f docker-compose.prod.yml up -d

Anyone on the network can then access Flowsint at http://<server-ip>:5173.

Before exposing to a network, change the default secrets in .env:

Also add your server hostname/IP to the Host-header allowlist in flowsint-app/nginx.conf (look for map $http_host $is_flowsint_host). The default allowlist accepts only localhost / 127.0.0.1 / [::1], which defends single-user installs against DNS rebinding; LAN and public deploys must opt-in their own hostname. Two commented-out template lines in the same map block show the format.

Only port 5173 is exposed to the network. PostgreSQL, Redis, Neo4j and the API are bound to 127.0.0.1 on the server and reachable only through the frontend proxy.

To pin a specific version instead of latest, set FLOWSINT_VERSION in .env (e.g. FLOWSINT_VERSION=1.2.10).

HTTPS (recommended beyond a trusted LAN): put any reverse proxy in front of port 5173. Example with Caddy:

flowsint.example.com {
    reverse_proxy 127.0.0.1:5173
}

When fronting with a reverse proxy, also bind the app port to localhost in docker-compose.prod.yml ("127.0.0.1:5173:8080") so clients can only go through HTTPS.

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

IP Enrichers

ASN Enrichers

CIDR Enrichers

Social Media Enrichers

Organization Enrichers

Cryptocurrency Enrichers

Website Enrichers

Email Enrichers

Phone Enrichers

Individual Enrichers

Integration Enrichers

Project structure

The project is organized into autonomous modules:

Core modules

Module dependencies

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

Development setup

Prerequisites

Run

Linux / macOS (requires Make):

make dev

Windows (cmd or PowerShell, no Make — create the .env files first, see Get started):

docker compose -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.dev.yml logs -f

Development

The app is accessible at http://localhost:5173.

Module details

flowsint-core

Core utilities and base classes used by all other modules:

flowsint-types

Pydantic models for all data types:

flowsint-enrichers

Enricher modules that process data:

flowsint-api

FastAPI server providing:

flowsint-app

Frontend application.

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:

# 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 uv for dependency management
  3. Write tests for new functionality
  4. Update documentation as needed
  5. See CONTRIBUTING.md for the checks to run before committing

Ethics: Please read ETHICS.md for responsible use guidelines.

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

It was created to assist:

Flowsint must not be used for:

Any misuse of this software is strictly prohibited and goes against the ethical principles defined in ETHICS.md.

❤️ Support

Buy Me A Coffee Ko-fi

flowsint (reconurge/flowsint)

reconnaissance
Searching Database…

9.8K ·GitHub
Flowsint
What is this?Flowsint is an open-source, graph-based OSINT investigation tool that lets analysts explore relationships between people, domains, IPs, organizations and more through a visual graph interface with automated enrichers.
Is this a hosted service or something I run myself?It is a self-hosted web application you run with Docker on your own machine or server; there is no cloud-hosted version.
How do I get it running?Install Docker (plus Make on Linux/macOS, or Git on Windows), clone the repo, set up the .env files, then run the provided install/start command, which pulls pre-built images from the GitHub Container Registry.
Do I need anything besides Docker?On Linux/macOS you also need Make; on Windows you need Docker Desktop (running) and Git, but Make is not required there.
Is this ready for production use?The project is still in early development with incomplete test suites per module, and you must change the default secrets (AUTHSECRET, MASTERVAULTKEYV1, NEO4JPASSWORD) before exposing it beyond localhost.
Who is this meant for, and are there usage restrictions?It targets cybersecurity researchers, journalists, OSINT investigators, and law enforcement/fraud teams; it explicitly forbids unauthorized surveillance, doxxing, or political manipulation.
Where does my investigation data go?Nothing leaves your machine by default — PostgreSQL, Redis, Neo4j and the API all run locally, and the project stresses that OSINT work needs a high level of privacy.
What kinds of enrichers does it ship with out of the box?It includes enrichers for domains, IPs, ASNs, CIDRs, social media (Maigret username search), organizations, crypto wallets, websites, emails and phone numbers — covering things like DNS resolution, WHOIS lookups, subdomain discovery, breach checks and wallet transaction/NFT lookups.
Can a whole team share one Flowsint instance?Yes — the same Docker setup works on a server, with the frontend proxying all API calls internally so anyone on the network can access it; you should still change the default secrets and front it with HTTPS via a reverse proxy before exposing it.
How is the codebase organized?It's split into modular packages: flowsint-core (utilities, orchestrator, vault), flowsint-types (Pydantic models), flowsint-enrichers (scanning logic), flowsint-api (FastAPI server) and flowsint-app (frontend).
Is there a default login to get started?No — there are no default credentials or accounts; you create your own account the first time you log in.
What are similar projects?bbot, theHarvester, Decepticon, redStackPRO, spiderfoot, redamon, maigret, OneForAll
Which topics is it in?investigation, recon, neo4j, graph-database, threat-intelligence, reconnaissance, graph, osint, dns, pentesting, fastapi, penetration-testing
Creator
reconurge
Size
63.8 MB
Stars
9.8K
Updated
CommitSep 24Releasev1.2.13Oct 03
Age
1y
Commits · 90 Days