OSINTER API

Open Source INTelligence Engine

Uma API de OSINT (Open Source Intelligence) 100% própria que busca usernames em múltiplas plataformas simultaneamente, com arquitetura assíncrona, rate limiting por plano e suporte a webhooks.

O que faz?

Dado um username (ex: john_doe), a OSINTER API verifica em quais plataformas esse usuário existe, retornando:

Todos os sites onde o perfil foi encontrado
URLs diretas para cada perfil encontrado
Progresso parcial enquanto busca
Suporte a webhooks para notificação quando concluído
Resultados armazenados temporariamente (1 hora no Redis)

Quantidade de Sites

Versão	Quantidade
Anterior	30+ sites
Atual	410+ sites (globais e brasileiros)

Pré-requisitos

Node.js 20+
Redis 7+
Docker e Docker Compose (recomendado)

Instalação

1. Clone o repositório

git clone <repository-url>
cd osinter

2. Configure as variáveis de ambiente

cp .env.example .env

Edite o arquivo .env conforme necessário.

3. Execute com Docker Compose

# Desenvolvimento
docker-compose up

# Produção
docker-compose -f docker-compose.prod.yml up -d

Ou execute localmente

# Instale dependências
npm install

# Inicie o Redis (se não estiver rodando)
redis-server

# Inicie a API
npm run start:dev

# Em outro terminal, inicie o Worker
npm run start:dev -- --entryFile src/worker

Variáveis de Ambiente

Variável	Descrição	Padrão
`PORT`	Porta da API	`3000`
`NODE_ENV`	Ambiente	`development`
`API_PREFIX`	Prefixo da API	`/api/v1`
`REDIS_HOST`	Host do Redis	`localhost`
`REDIS_PORT`	Porta do Redis	`6379`
`REDIS_PASSWORD`	Senha do Redis	(vazio)
`OSINTER_TIMEOUT`	Timeout por site (ms)	`15000`
`OSINTER_CONCURRENCY`	Requisições simultâneas	`10`
`FREE_TIER_LIMIT`	Limite plano Free	`10`
`BASIC_TIER_LIMIT`	Limite plano Basic	`100`
`PRO_TIER_LIMIT`	Limite plano Pro	`1000`
`ENTERPRISE_TIER_LIMIT`	Limite plano Enterprise	`10000`
`WEBHOOK_TIMEOUT`	Timeout webhook (ms)	`5000`
`WEBHOOK_RETRY_ATTEMPTS`	Tentativas retry	`3`
`API_KEY_SALT`	Salt para geração de keys	`my-super-secret-salt`

Gerando API Keys para Teste

npm run seed:api-keys

Isso irá gerar 4 API keys, uma para cada plano:

osinter_free_xxx...        (10 buscas/mês)
osinter_basic_xxx...       (100 buscas/mês)
osinter_pro_xxx...         (1000 buscas/mês)
osinter_enterprise_xxx...  (10000 buscas/mês)

Endpoints da API

Autenticação

Todos os endpoints protegidos exigem o header X-API-Key.

`POST /api/v1/search`

Inicia uma busca por username.

Request:

curl -X POST http://localhost:3000/api/v1/search \
  -H "X-API-Key: osinter_free_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "webhookUrl": "https://meusite.com/webhook"
  }'

Body:

Campo	Tipo	Obrigatório	Descrição
`username`	`string`	Sim	Username para buscar
`webhookUrl`	`string`	Não	URL para receber resultado quando pronto

Response (202 Accepted):

{
  "jobId": "osinter_550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "checkStatusUrl": "/api/v1/result/osinter_550e8400-e29b-41d4-a716-446655440000",
  "estimatedTime": "45-90 seconds"
}

`GET /api/v1/result/:jobId`

Consulta o status/resultado de uma busca.

Request:

curl -X GET http://localhost:3000/api/v1/result/osinter_abc-123-def \
  -H "X-API-Key: osinter_free_abc123..."

Response (Em processamento):

{
  "jobId": "osinter_abc-123-def",
  "status": "processing",
  "progress": 45,
  "processedSites": 14,
  "totalSites": 410,
  "partialResults": [
    { "site": "GitHub", "url": "https://github.com/john_doe", "found": true }
  ]
}

Response (Concluído):

{
  "jobId": "osinter_abc-123-def",
  "status": "completed",
  "completedAt": "2026-01-15T10:30:00Z",
  "processingTimeMs": 45200,
  "totalSitesSearched": 410,
  "totalFound": 47,
  "results": [
    { "site": "GitHub", "url": "https://github.com/john_doe" },
    { "site": "Twitter", "url": "https://twitter.com/john_doe" },
    { "site": "Reddit", "url": "https://reddit.com/user/john_doe" }
  ]
}

`GET /api/v1/health`

Health check completo (API, Redis, Queue).

curl http://localhost:3000/api/v1/health

`GET /api/v1/health/live`

Liveness probe (simples).

`GET /api/v1/health/ready`

Readiness probe.

`POST /api/v1/auth/create`

Cria uma nova API Key (para administração).

Request:

curl -X POST http://localhost:3000/api/v1/auth/create \
  -H "Content-Type: application/json" \
  -d '{"tier": "pro"}'

Response:

{
  "keyId": "550e8400-e29b-41d4-a716-446655440000",
  "key": "osinter_pro_550e8400-e29b-41d4-a716-446655440000",
  "tier": "pro",
  "createdAt": "2026-01-15T10:30:00Z"
}

`GET /api/v1/sites`

Lista todos os sites suportados pela engine.

curl http://localhost:3000/api/v1/sites \
  -H "X-API-Key: osinter_free_abc123..."

Webhook

Se fornecido webhookUrl no POST /search, a API enviará um POST quando a busca for concluída:

Payload enviado:

{
  "event": "search.completed",
  "jobId": "osinter_abc-123-def",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "status": "completed",
    "completedAt": "2026-01-15T10:30:00Z",
    "processingTimeMs": 45200,
    "totalSitesSearched": 410,
    "totalFound": 47,
    "results": [...]
  }
}

Headers:

Content-Type: application/json
X-OSINTER-Webhook: 1

OSINTER Engine: Estratégias de Detecção

Métodos HTTP Suportados

Método	Descrição
`GET`	Requisição GET padrão
`HEAD`	Requisição HEAD (apenas cabeçalhos)
`POST`	Requisição POST com body
`PUT`	Requisição PUT com body

Estratégias de Detecção

Estratégia	Descrição
`status200`	Status 200-299 = perfil existe
`status404`	Status NÃO 404 = perfil existe
`contentNotFound`	Se texto NÃO contiver "not found"
`contentFound`	Se texto CONTIVER determinado conteúdo
`redirect`	Detecta redirecionamentos suspeitos
`custom`	Validação programática personalizada

Funcionalidades Avançadas

Feature	Descrição
`headers`	Headers customizados por site
`payload`	Body para requisições POST/PUT
`errorTypes[]`	Múltiplos critérios de "não encontrado"
`urlProbe`	URL separada para probing vs URL pública
`regexCheck`	Valida username antes de consultar
`errorCode`	Código HTTP customizado de erro

Planos e Rate Limits

Plano	Limite Mensal	Formato da Key
Free	10 buscas	`osinter_free_{uuid}`
Basic	100 buscas	`osinter_basic_{uuid}`
Pro	1000 buscas	`osinter_pro_{uuid}`
Enterprise	10000 buscas	`osinter_enterprise_{uuid}`

Quando o limite é excedido:

{
  "statusCode": 429,
  "message": "Monthly limit exceeded for plan BASIC. Used: 100/100",
  "error": "Too Many Requests"
}

Estrutura do Projeto

osinter-api/
├── src/
│   ├── main.ts                 # Entry point da API
│   ├── worker.ts               # Entry point do Worker
│   ├── app.module.ts           # Módulo principal
│   ├── config/                 # Configurações e validação
│   ├── common/                 # Guards, Interceptors, Filters
│   ├── engine/                 # OSINTER Engine (coração)
│   │   ├── osinter.engine.ts   # Engine principal de busca
│   │   ├── http-client.ts      # HTTP com timeout/retry
│   │   ├── user-agent.ts       # User agents rotativos
│   │   └── validators.ts       # Estratégias de detecção
│   └── modules/
│       ├── osinter/            # Módulo de busca
│       │   ├── constants/
│       │   │   └── sites-list.ts   # 410+ sites
│       │   ├── interfaces/
│       │   ├── osinter.controller.ts
│       │   ├── osinter.service.ts
│       │   ├── osinter.processor.ts
│       │   └── osinter.module.ts
│       ├── auth/               # Módulo de autenticação/API keys
│       └── health/             # Health checks
├── test/
│   ├── unit/                   # Testes unitários
│   ├── e2e/                    # Testes end-to-end
│   └── mocks/                  # Mocks para testes
├── docker/
│   ├── Dockerfile.api          # Multi-stage build
│   └── Dockerfile.worker       # Multi-stage build
├── docker-compose.yml          # Dev
├── docker-compose.prod.yml     # Prod
├── eslint.config.mjs           # ESLint strict
└── package.json

Testes

# Testes unitários
npm run test

# Testes em watch mode
npm run test:watch

# Cobertura
npm run test:cov

# Testes e2e
npm run test:e2e

# Lint e Typecheck
npm run lint
npm run typecheck

Características Técnicas

Arquitetura

API REST com NestJS + TypeScript
Fila assíncrona com BullMQ + Redis
Worker separado para processamento
Dados temporários expiram após 1 hora no Redis
Multi-stage Docker builds otimizados

OSINTER Engine

410+ sites configurados
Suporte a GET, HEAD, POST, PUT
Headers customizados por site
Request payload para POST/PUT
Múltiplas estratégias de detecção
Sistema de errorTypes[] para evitar falsos positivos
urlProbe separada para API interna vs URL pública
Validação de username via regexCheck

Resiliência

Timeout por requisição configurável
User agents rotativos para evitar bloqueios
Headers realistas (Accept, Accept-Language, etc)
Tratamento robusto de erros

Segurança

API Keys com validação por regex
Rate limiting por plano
Guards de autenticação e rate limit
Interceptors para logging

Possíveis Problemas

1. Redis não conecta

Verifique:

Redis está rodando?
Host/porta corretos no .env?
Senha configurada se necessária?

2. Sites retornam 403/429

Isso é normal - alguns sites bloqueiam requisições automatizadas. A OSINTER Engine usa:

User agents rotativos
Headers realistas
Timeouts adequados

3. Worker não processa jobs

Verifique:

Worker está rodando?
Conectado ao mesmo Redis da API?
Queue name é o mesmo?

4. Docker Build falha com "nest: not found"

Corrigido! Os Dockerfiles agora usam multi-stage build adequado:

Builder: npm ci (todas deps) → npm run build
Final: npm ci --only=production → copia apenas /dist

Licença

MIT

Aviso Legal

Esta ferramenta é para fins educacionais e de pesquisa. Use-a de forma responsável e em conformidade com os Termos de Serviço de cada site consultado.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docker		docker
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.env.test		.env.test
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

OSINTER API

O que faz?

Quantidade de Sites

Pré-requisitos

Instalação

1. Clone o repositório

2. Configure as variáveis de ambiente

3. Execute com Docker Compose

Ou execute localmente

Variáveis de Ambiente

Gerando API Keys para Teste

Endpoints da API

Autenticação

POST /api/v1/search

GET /api/v1/result/:jobId

GET /api/v1/health

GET /api/v1/health/live

GET /api/v1/health/ready

POST /api/v1/auth/create

GET /api/v1/sites

Webhook

OSINTER Engine: Estratégias de Detecção

Métodos HTTP Suportados

Estratégias de Detecção

Funcionalidades Avançadas

Planos e Rate Limits

Estrutura do Projeto

Testes

Características Técnicas

Arquitetura

OSINTER Engine

Resiliência

Segurança

Possíveis Problemas

1. Redis não conecta

2. Sites retornam 403/429

3. Worker não processa jobs

4. Docker Build falha com "nest: not found"

Licença

Aviso Legal

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /api/v1/search`

`GET /api/v1/result/:jobId`

`GET /api/v1/health`

`GET /api/v1/health/live`

`GET /api/v1/health/ready`

`POST /api/v1/auth/create`

`GET /api/v1/sites`

Packages