Shadow Fleet Tracker Light

Monitoramento da frota sombra do Mar Báltico através de dados AIS ao vivo. Observa mais de 1200 embarcações do catálogo War&Sanctions da GUR ucraniana contra o feed WebSocket do AISStream, plota posições em um mapa auto-atualizável, sinaliza proximidade de cabos submarinos e detecta padrões de transbordo Rússia↔Ocidente.

Gratuito, código aberto, executa localmente. Sem nuvem, sem assinatura além de uma chave de API gratuita do AISStream.

Parte da cadeia de ferramentas de inteligência soberana do Former Lab.

Apoie o Former Lab

O Shadow Fleet Tracker Light é construído e mantido pela equipe do Former Lab — computação soberana, construindo ferramentas abertas e focadas em privacidade em hardware antigo sem apoio de capital de risco.

Se esta ferramenta é útil para você, considere apoiar no Patreon. Um plano gratuito está disponível, com teste de 7 dias nos planos pagos. Apoie sempre a Ucrânia!

patreon.com/FormerLab

Postagem no blog sobre o rastreador, capturas de tela e mais: https://www.patreon.com/posts/153285871

Início rápido

git clone https://github.com/FormerLab/shadow-fleet-tracker-light.git
cd shadow-fleet-tracker-light
pip install -r requirements.txt
export AISSTREAM_API_KEY=your_key_here   # free at aisstream.io
python shadow_tracker.py &
uvicorn webserver:app --host 0.0.0.0 --port 8000

Abra http://localhost:8000 — o mapa está em /map.

Usuários do Windows: veja a seção Configuração para a sintaxe de variável de ambiente no PowerShell/cmd.

Usuários Linux/macOS podem usar start.sh. Usuários do Windows podem usar start.bat ou start.ps1 — ambos abrem o rastreador e o painel em janelas separadas e iniciam o navegador automaticamente.

O que faz

• Conecta-se ao WebSocket do AISStream e assina uma caixa delimitadora do Mar Báltico
• Filtra o fluxo contra uma lista de observação de mais de 1200 MMSIs de embarcações provenientes do catálogo da GUR ucraniana (Vessels1.db)
• Plota posições ao vivo e trilhas de rota em um mapa Folium/Leaflet, atualizado a cada 3 minutos
• Alerta quando uma embarcação fica a menos de 10 km de um segmento de cabo (de filtered_cables.kml)
• Detecta navegação lenta — embarcações lentas ou paradas por mais de 20 minutos em uma área fixa
• Detecta padrões de transbordo — embarcações que escalam portos russos e depois hubs ocidentais (ou vice-versa) dentro de 21 dias
• Registra todos os dados de posição no SQLite para análise offline
• Reinicialização a quente a partir do registro de posição — o mapa é preenchido imediatamente na inicialização com as últimas posições conhecidas, sem espera em tela em branco
• Serve um painel FastAPI para inspeção de logs, análise de embarcações, exportação GPX, revisão de transbordo e reprodução interativa de rotas

Mapa

Mapa base escuro do CartoDB com rotas de cabos sobrepostas em verde. Marcadores de embarcações são atualizados a cada 3 minutos com uma contagem regressiva ao vivo para a próxima atualização — a página recarrega automaticamente. Popups mostram MMSI, IMO, bandeira, velocidade, rumo, destino e links diretos para MarineTraffic, VesselFinder e War&Sanctions. Status de sanções do OpenSanctions exibido se uma chave de API estiver configurada.

Os nomes conhecidos de embarcações de Vessels1.db são exibidos imediatamente na primeira aparição, sem esperar por uma mensagem estática AIS.

Na inicialização, o mapa é pré-preenchido com as últimas 24 horas do registro de posição. Embarcações ainda não vistas na sessão atual são mostradas como marcadores cinza com um rótulo 'visto pela última vez Xh atrás' — elas transitam para cor viva à medida que novos pings chegam.

Arquivos

shadow_tracker.py          Main process — WS consumer, map renderer, DB writes
loitering_module.py        Loitering detection and map annotation
transshipment_module.py    Port call detection and Russia↔West transshipment flagging
webserver.py               FastAPI dashboard
gur_scrape.py              One-shot scraper — builds IMO→GUR-ID mapping + full vessel catalogue
check.py                   Preflight checks — Python version, deps, API key, network
start.sh                   Launcher for Linux / macOS
start.bat                  Launcher for Windows (Command Prompt)
start.ps1                  Launcher for Windows (PowerShell)
requirements.txt           Dependencies

Vessels1.db                Watchlist — 1200+ vessels (MMSI + IMO + name where known)
vessel_data_log.db         Position log — runtime, append-only
vessel_static.db           AIS static data cache (name, destination, flag history)
transshipment.db           Port call log and transshipment events
loitering_events.db        Loitering events
filtered_cables.kml        Baltic Sea undersea cable geometry
cables.kml                 Full cable dataset (pre-filter source)
gur_mapping.json           IMO→GUR-ID mapping (produced by gur_scrape.py, optional)
gur_vessels_full.json      Full GUR catalogue — GUR-ID→{imo, mmsi, name, flag} (produced by gur_scrape.py)

Lista de Observação

Vessels1.db é a lista canônica de embarcações rastreadas. Mais de 1200 entradas provenientes do catálogo War&Sanctions da GUR ucraniana, cobrindo petroleiros e cargueiros identificados como parte da frota sombra russa ou implicados em atividades híbridas no Báltico.

A lista inclui embarcações recentemente apreendidas ou interceptadas por autoridades do Báltico:

Os MMSIs são corrigidos com base nos dados AIS atuais — as embarcações da frota sombra mudam de bandeira com frequência. O arquivo update_vessels_2026_03.sql documenta todas as alterações com fontes.

A lista de observação é intencionalmente aberta. Adicione embarcações diretamente ao Vessels1.db enquanto o rastreador estiver em execução — elas serão detectadas em até 5 minutos sem necessidade de reinicialização.

Linux / macOS:

sqlite3 Vessels1.db "INSERT OR IGNORE INTO vessels (mmsi, imo, name) VALUES ('123456789', '9999999', 'VESSEL NAME');"

Windows (no sqlite3 CLI needed):

import sqlite3
conn = sqlite3.connect("Vessels1.db")
conn.execute("INSERT OR IGNORE INTO vessels (mmsi, imo, name) VALUES ('123456789', '9999999', 'VESSEL NAME')")
conn.commit()
conn.close()

Modelo de Dados

Vessels1.db — lista de observação

vessels(mmsi TEXT PK, imo TEXT, name TEXT, destination TEXT)

vessel_data_log.db — registro de posição

vessel_data_log(timestamp, mmsi, name, imo, destination, speed, heading, latitude, longitude, cable_alert)

Somente anexação. Escrito a cada ciclo de renderização do mapa.

vessel_static.db — cache de dados estáticos AIS

vessel_static(mmsi TEXT PK, name TEXT, imo TEXT, destination TEXT, flag TEXT)
flag_history(id, mmsi, flag, timestamp)

Preenchido a partir de mensagens AIS ShipStaticData ao vivo. Tem prioridade sobre os nomes de Vessels1.db uma vez recebido. flag_history registra cada mudança de bandeira com um timestamp — eventos de mudança de bandeira são registrados e exibidos na página por embarcação.

loitering_events.db — registro de navegação lenta (criado em tempo de execução)

loitering_events(id, mmsi, timestamp, latitude, longitude, near_cable)

transshipment.db — registro de escalas e transbordo (criado em tempo de execução)

port_calls(id, mmsi, name, port, port_type, entry_ts, exit_ts, min_speed)
transshipment_events(id, mmsi, name, direction, from_port, from_exit_ts,
                     to_port, to_entry_ts, days_between, detected_ts)

Requisitos

• Python 3.11 ou mais recente — python.org/downloads
• Uma chave de API AISStream — gratuita em aisstream.io (registre-se e copie sua chave do painel)
• As dependências em requirements.txt

Scripts de Inicialização

A maneira mais fácil de executar o rastreador. Cada script instala dependências, executa verificações preliminares e inicia ambos os processos.

Linux / macOS:

chmod +x start.sh
export AISSTREAM_API_KEY=your_key_here
./start.sh

Windows (PowerShell):

$env:AISSTREAM_API_KEY = "your_key_here"
.\start.ps1

Windows (Command Prompt):

set AISSTREAM_API_KEY=your_key_here
start.bat

Todos os três scripts executam check.py primeiro — uma verificação preliminar que verifica a versão do Python, dependências, arquivos de dados, chave de API e acessibilidade de rede, com mensagens de erro claras se algo estiver faltando.

Você também pode executar a verificação preliminar por conta própria a qualquer momento:

python check.py

Configuração (manual)

1. Clone e instale dependências

git clone https://github.com/FormerLab/shadow-fleet-tracker-light.git
cd shadow-fleet-tracker-light
pip install -r requirements.txt

No Ubuntu 22.04+ e Debian 12+ você pode obter um erro de "ambiente gerenciado externamente" do pip. Os scripts de inicialização lidam com isso automaticamente criando um ambiente virtual — basta executar start.sh e ele cuida disso. Se instalar manualmente, crie um venv primeiro:

python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows
pip install -r requirements.txt

2. Defina sua chave de API AISStream

Linux / macOS:

export AISSTREAM_API_KEY=your_key_here
export OPENSANCTIONS_API_KEY=your_key_here  # opcional

Windows (Command Prompt):

set AISSTREAM_API_KEY=your_key_here
set OPENSANCTIONS_API_KEY=your_key_here

Windows (PowerShell):

$env:AISSTREAM_API_KEY = "your_key_here"
$env:OPENSANCTIONS_API_KEY = "your_key_here"

3. Execute o rastreador e o painel em dois terminais separados

Terminal 1 — o consumidor do feed AIS:

python shadow_tracker.py

Terminal 2 — o painel web:

uvicorn webserver:app --host 0.0.0.0 --port 8000

4. Abra o painel

http://localhost:8000

O mapa ao vivo está em http://localhost:8000/map e atualiza a cada 3 minutos. Na primeira execução, o mapa é renderizado imediatamente a partir de qualquer histórico de posição já no banco de dados — sem espera em tela em branco.

Chaves de API

Sem OPENSANCTIONS_API_KEY o rastreador funciona normalmente — os selos de sanções são simplesmente omitidos dos popups do mapa.

Configuração

Todos os parâmetros ajustáveis estão no topo de shadow_tracker.py:

Variáveis de ambiente:

OpenSanctions é gratuito para uso não comercial — registre-se em opensanctions.org/api. Sem uma chave, o rastreador funciona normalmente; campos de sanções são omitidos dos popups.

Links diretos do War&Sanctions (opcional)

war-sanctions.gur.gov.ua é o catálogo público da GUR ucraniana de embarcações da frota sombra e sancionadas. Cada embarcação tem uma página numerada com histórico de escalas, mapas e detalhes de sanções.

gur_scrape.py constrói um mapeamento local IMO→GUR-ID ao rastrear o catálogo uma vez:

python gur_scrape.py

Isso produz gur_mapping.json. O rastreador o carrega na inicialização e usa links diretos (/en/transport/ships/{id}) nos popups do mapa quando disponíveis, recorrendo a uma pesquisa no site do Google para embarcações ainda não no catálogo.

O rastreamento cobre ~1600 entradas a 1,5 s/requisição (~40 min). Reexecute ocasionalmente conforme o catálogo cresce — use --start para retomar de um ID específico:

python gur_scrape.py --start 1580

Para depurar uma única página:

python gur_scrape.py --probe 1517

gur_mapping.json é recarregado automaticamente a cada 5 minutos junto com a lista de observação — sem necessidade de reinicialização do rastreador após um novo rastreamento.

Limiares de navegação lenta em loitering_module.py:

Configurações de transbordo em transshipment_module.py:

Zonas portuárias cobertas:

Painel

Página por embarcação

Cada página de embarcação (/vessel/<mmsi>) mostra:

• Reprodução de rota — mapa interativo Leaflet com reprodução/pausa/reinicialização e controle de velocidade. A trilha constrói ponto a ponto; o marcador fica vermelho em pings de alerta de cabo
• Resumo — primeira/última visualização, total de pings, contagem de alertas de cabo, contagem de lacunas AIS, destinos observados
• Apagões AIS — qualquer lacuna ≥60 minutos sinalizada com timestamps de início/fim e duração
• Proximidade de cabo — porcentagem de pings onde o alerta de cabo estava ativo
• Deriva de dados estáticos — mudanças de nome, mudanças de bandeira com datas, histórico de destino. A mudança de bandeira é uma tática primária de evasão da frota sombra
• Exportação GPX — trilha completa com timestamps, carregável em qualquer ferramenta GIS

Página de transbordo

Sinaliza dois padrões inferidos a partir de dados de posição:

• RU→WEST — embarcação escalou um porto russo e depois um hub ocidental dentro de 21 dias. Potencial lavagem de carga para cadeias de suprimentos europeias
• WEST→RU — embarcação escalou um hub ocidental e depois um porto russo dentro de 21 dias. Potencial fluxo de mercadorias europeias para leste em território sancionado

As escalas de porto são inferidas a partir de pings de posição — nenhuma API externa necessária. Uma embarcação deve estar dentro de uma zona portuária a <1,5 kn por pelo menos 2 pings para registrar uma escala. Isso mostra um padrão, não um veredicto.

Dados de Cabo

filtered_cables.kml é derivado de conjuntos de dados de código aberto e é aproximado — não adequado para cálculos precisos de proximidade. O limiar de alerta de 10 km leva em conta essa margem. Contribuições de geometria de cabo melhorada são bem-vindas.

Notas de Arquitetura

O rastreador executa um único loop assíncrono sobre o fluxo WebSocket. O estado é mantido em memória (vessel_info, static_cache) e gravado no SQLite a cada ciclo de renderização. O mapa é escrito atomicamente via os.replace para evitar servir um arquivo parcial.

Na inicialização, warm_restart() lê as últimas WARM_RESTART_HOURS horas de vessel_data_log.db e pré-popula vessel_info antes que o WebSocket conecte. O mapa inicial é renderizado imediatamente. Posições obsoletas são visualmente diferenciadas (marcadores cinza, trilhas atenuadas) e transitam para cor viva à medida que novos pings chegam.

A lista de observação e gur_mapping.json são recarregados do disco a cada 5 minutos — embarcações podem ser adicionadas e o mapeamento GUR pode ser rastreado novamente enquanto o rastreador está em execução, sem reinicialização.

O servidor web é stateless e lê diretamente dos arquivos SQLite — sem memória compartilhada com o processo do rastreador.

Estado