soxoj/socid-extractor⛏️ O motor de extração por trás do Maigret: transforme qualquer URL de perfil em um registro OSINT estruturado em mais de 150 sites
# socid_extractor
[](https://pypi.org/project/socid-extractor/)
[](https://pepy.tech/project/socid-extractor)
[](https://pepy.tech/project/socid-extractor)
[](https://github.com/soxoj/socid-extractor/blob/master/LICENSE)
[](https://github.com/soxoj/socid-extractor/actions/workflows/python-package.yml)
[](https://github.com/soxoj/socid-extractor/stargazers)
[](https://github.com/soxoj/socid-extractor/network/members)
> Transforme qualquer página de perfil público em um registro de conta estruturado — nomes de usuário, nomes de exibição, bios, avatares, localizações, datas de entrada, contagens de seguidores, links externos e os **identificadores internos estáveis** que fixam unicamente uma conta através de renomeações, reformulações e exclusões.
`socid_extractor` analisa páginas HTML e respostas de API de mais de 250 esquemas e retorna um dicionário plano e legível por máquina de campos de conta. Não são necessárias chaves de API, nem navegador headless — apenas uma única chamada de função no texto da resposta.
**Por que é útil**
- **IDs estáveis entre serviços.** Obtenha GAIA ID (Google), Facebook UID, Yandex Public ID, Instagram pk e dezenas de outros — valores que sobrevivem a mudanças de nome de usuário e permitem correlacionar contas entre vazamentos, arquivos e índices de mecanismos de busca.
- **Uma interface uniforme.** A mesma chamada `extract()` para Instagram, GitHub, VK, Reddit, Substack, Bluesky, TikTok — sem código de integração específico por plataforma do seu lado.
- **Ontologia de campos.** [Nomes de campos normalizados](https://github.com/soxoj/socid-extractor/blob/master/FIELDS.md) entre plataformas (`username`, `fullname`, `created_at`, `is_verified`, …) para que pipelines downstream não precisem de 130 mapeamentos.
- **Testado em batalha.** Alimenta o [Maigret](https://github.com/soxoj/maigret) e várias outras ferramentas OSINT.
## Instalação
Python: 3.10+.
```sh
pip install socid-extractor
```
Para uma instalação limpa via CLI em uma estação de trabalho:
```sh
pipx install socid-extractor
```
A versão de desenvolvimento mais recente:
```sh
pip install -U git+https://github.com/soxoj/socid-extractor.git
```
## Início rápido
**Como CLI:**
```sh
$ socid_extractor --url https://www.deviantart.com/muse1908
country: France
created_at: 2005-06-16 18:17:41
gender: female
username: Muse1908
website: www.patreon.com/musemercier
links: ['https://www.facebook.com/musemercier', 'https://www.instagram.com/muse.mercier/', 'https://www.patreon.com/musemercier']
tagline: Nothing worth having is easy...
```
**Como uma biblioteca Python:**
```python
import requests
import socid_extractor
r = requests.get('https://www.patreon.com/annetlovart')
print(socid_extractor.extract(r.text))
# {'patreon_id': '33913189', 'patreon_username': 'annetlovart',
# 'fullname': 'Annet Lovart',
# 'links': "['https://www.facebook.com/322598031832479', ...]"}
```
**Dica — execuções em lote:** passe `--skip-fetch-if-no-url-hint` para ignorar a requisição HTTP quando a URL não corresponder a nenhuma dica de site conhecida (mais rápido, mas pode ignorar mecanismos genéricos, como templates de fórum):
```sh
$ socid_extractor --url https://example.com/foo --skip-fetch-if-no-url-hint
```
## Sites suportados
[**Mais de 250 esquemas**, cobrindo aproximadamente 2.000 dos sites verificados pelo Maigret — consulte METHODS.md para a lista completa.](https://github.com/soxoj/socid-extractor/blob/master/METHODS.md)
Uma amostra não exaustiva:
- **Grandes redes:** Facebook (páginas de usuário e de grupo), Instagram, VK.com, OK.ru, Reddit, TikTok, Bluesky, Tumblr, Flickr
- **Ecossistema Google:** contribuições no Google docs/maps (cookies necessários), Google Play, YouTube
- **Mail.ru:** página principal do usuário my.mail.ru, foto, vídeo
- **Plataformas de desenvolvimento / escrita:** GitHub, Stack Overflow (HTML + API), LeetCode, Hashnode, Medium, Substack, Paragraph, WordPress.org, Virgool
- **Fóruns (detectores universais):** Discourse, MediaWiki / wikis Fandom, Mastodon
- **Nicho / vertical:** Chess.com, Roblox, MyAnimeList, Scratch, Wikipedia, DailyMotion, SlideShare, Weebly, Calendly, Amazon Author, Boosty, Warpcast (Farcaster), Fragment (TON/Telegram), Rarible, CSSBattle, lnk.bio, Spatial, TwitchTracker, Max (max.ru)
…e muitos outros.
Para exemplos de dados, consulte [`tests/test_e2e.py`](https://github.com/soxoj/socid-extractor/blob/master/tests/test_e2e.py); para a lógica de parsing, consulte [`socid_extractor/schemes.py`](https://github.com/soxoj/socid-extractor/blob/master/socid_extractor/schemes.py); para a ontologia de campos, consulte [FIELDS.md](https://github.com/soxoj/socid-extractor/blob/master/FIELDS.md).
## Casos de uso
- **Pivote a partir de um perfil para tudo o que você consegue ver.** Uma única chamada retorna as informações visíveis mais os IDs internos ocultos que a plataforma usa nos bastidores. Leitura de contexto: [Week in OSINT — Getting a grasp on Google IDs](https://medium.com/week-in-osint/getting-a-grasp-on-googleids-77a8ab707e43).
- **Rastreie contas através de renomeações, reformulações e exclusões.** IDs estáveis (GAIA, FB UID, Yandex Public ID, Instagram pk, …) permitem reidentificar a mesma pessoa mesmo quando todos os campos visíveis mudaram. Contexto: [Aware Online — User IDs in social-media investigations](https://www.aware-online.com/en/importance-of-user-ids-in-social-media-investigations/).
- **Pesquise por UID entre serviços.** Uma vez que você tenha um identificador estável, pode pivotar para:
- bancos de dados SQL / vazados (dumps de fóruns, dados de violações) onde o UID é a chave de junção,
- índices do Google / Yandex / archive.org que capturaram URLs contendo o UID.
- **Alimente ferramentas OSINT downstream.** Um registro normalizado é muito mais fácil de ingerir do que scrapers por site — usado pelo [Maigret](https://github.com/soxoj/maigret) e ferramentas similares para enriquecimento.
## Uso Comercial
O `socid_extractor` de código aberto é licenciado sob MIT e gratuito para uso comercial sem restrições — mas os parsers de páginas quebram com o tempo à medida que as plataformas alteram seu HTML e APIs, e precisam de manutenção ativa.
Para uso comercial sério — uma API de extração hospedada, ou manutenção dos parsers dos quais seu produto depende — entre em contato: 📧 [email protected]
- API de Extração — integre o `socid_extractor` ao seu produto
## Classificação SOWEL
Mapeia para as seguintes técnicas [SOWEL](https://sowel.soxoj.com/):
- [SOTL-1.4. Analyze Internal Identifiers](https://sowel.soxoj.com/internal-identifiers)
- [SOTL-11.1. Check Outdated And Unused Functionality](https://sowel.soxoj.com/outdated-unused-functionality)
## Ferramentas que usam o socid_extractor
- [**Maigret**](https://github.com/soxoj/maigret) — poderoso namechecker que gera um relatório com todas as informações disponíveis a partir de contas encontradas em mais de 3000 sites.
- [**TheScrapper**](https://github.com/champmq/TheScrapper) — extrai e-mails, números de telefone e contas de redes sociais de um site.
- [**InfoHunter**](https://github.com/sweetnight19/InfoHunter) — ferramenta OSINT de código aberto para pesquisar, coletar e analisar informações online.
- [**YaSeeker**](https://github.com/HowToFind-bot/YaSeeker) — reúne todas as informações disponíveis sobre uma conta Yandex por login/e-mail.
- [**Marple**](https://github.com/soxoj/marple) — extrai resultados de mecanismos de busca para um determinado nome de usuário.
## Veja também
- [**ShareTrace**](https://github.com/soxoj/sharetrace) — a imagem espelhada deste projeto: `socid_extractor` lê uma página de perfil, o ShareTrace recebe um *link de compartilhamento* (TikTok, Instagram, ChatGPT, Discord, Telegram e outros) e descobre quem o criou ou encaminhou, decodificando alguns tokens de compartilhamento offline. Nada para instalar se você só quer experimentar: o [bot do Telegram](https://t.me/sharetrace_bot?start=c29jaWQtZXh0cmFjdG9yOnJlYWRtZQ) mantido pela comunidade ou a [interface web](https://share.whopostedwhat.com/).
## Testes
Instale as dependências extras de teste a partir de [`pyproject.toml`](https://github.com/soxoj/socid-extractor/blob/master/pyproject.toml) e então execute o pytest:
```sh
pip install '.[test]' # pytest, pytest-rerunfailures, pytest-xdist
python3 -m pytest tests/test_e2e.py -n 10 -k 'not cookies' -m 'not github_failed and not rate_limited'
```
Use `pip install '.[dev]'` em vez disso se você também quiser flake8 / mypy / black (o conjunto completo usado pelo CI).
**Todo novo esquema deve ter um teste e2e** em `tests/test_e2e.py` acessando uma URL/API real. Testes unitários com fixtures inline (`tests/test_socid_improvements.py`) também são necessários, mas não substituem a cobertura e2e. Consulte [docs/testing-and-ci.md](https://github.com/soxoj/socid-extractor/blob/master/docs/testing-and-ci.md) para detalhes.
A documentação para desenvolvedores (arquitetura, módulos, CI) está em [docs/](https://github.com/soxoj/socid-extractor/blob/master/docs).
## Contribuindo
Consulte o [guia de contribuição](https://github.com/soxoj/socid-extractor/blob/master/CONTRIBUTING.md) se você quiser adicionar um novo esquema ou corrigir algo.