Osint Investigation

Фреймворк OSINT-расследований по публичным записям — корпоративные отчёты SEC EDGAR, контракты USAspending, лоббизм в Сенате, санкции OFAC, офшорные утечки ICIJ, записи о недвижимости в Нью-Йорке (ACRIS), реестры OpenCorporates, судебные записи CourtListener, архивы Wayback Machine, Wikipedia + Wikidata, мониторинг новостей GDELT. Разрешение сущностей по разным источникам, кросс-ссылочный анализ, корреляция по времени, цепочки доказательств. Только стандартная библиотека Python.

Метаданные навыка

Источник	Опционально — установка через vibeos skills install official/research/osint-investigation
Путь	optional-skills/research/osint-investigation
Версия	0.1.0
Автор	VibeOS (адаптировано из ShinMegamiBoson/OpenPlanter, MIT)
Платформы	linux, macos, windows
Теги	osint, investigation, public-records, sec, sanctions, corporate-registry, property, courts, due-diligence, journalism
Связанные навыки	domain-intel, arxiv

Справочник: полный SKILL.md

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это инструкции, которые видит агент, когда навык активен.

OSINT Investigation — Перекрёстная проверка публичных записей

Фреймворк для OSINT-расследований по публичным записям: государственные контракты, корпоративные отчёты, лоббизм, санкции, офшорные утечки, записи о недвижимости, судебные записи, веб-архивы, базы знаний и глобальные новости. Разрешение сущностей из разнородных источников, построение кросс-ссылок с явной степенью уверенности, выполнение статистических тестов времени и формирование структурированных цепочек доказательств.

Только стандартная библиотека Python. Без установки. Работает на Linux, macOS, Windows. Большинство источников работают без API-ключа (у OpenCorporates есть опциональный бесплатный токен, повышающий лимиты запросов).

Адаптировано из проекта ShinMegamiBoson/OpenPlanter (лицензия MIT); расширено для охвата источников по идентичности / недвижимости / судебным делам / архивам / новостям, которые не были затронуты в оригинале.

Когда использовать этот навык

Используйте, когда пользователь просит:

• «проследить за деньгами» — государственные контракты, лоббизм → законодательство, санкции
• корпоративная проверка (due diligence) — кто контролирует компанию X, где она зарегистрирована, кто входит в совет директоров, какие отчёты подавались
• проверка санкций — находится ли сущность X в списке OFAC SDN, офшорных утечках ICIJ
• расследование «pay-to-play» — подрядчики с офшорными связями, клиенты лоббистов, получающие контракты
• владение недвижимостью — поиск зарегистрированных сделок/ипотек по имени или адресу (Нью-Йорк; для других округов направляйте пользователей в соответствующий реестр)
• история судебных разбирательств — поиск мнений федеральных и местных судов, а также досье PACER
• разрешение сущностей из нескольких источников при вариативности имён (суффиксы LLC, сокращения)
• построение цепочек доказательств с явными уровнями уверенности
• «что говорили об X» — международные новости (GDELT) + нарратив Wikipedia + Wayback Machine для восстановления неработающих URL

НЕ используйте этот навык для:

• общего веб-исследования → web_search / web_extract
• OSINT по доменам/инфраструктуре → навык domain-intel
• академической литературы → навык arxiv
• поиска профилей в соцсетях → навык sherlock (опционально)
• финансирования федеральных избирательных кампаний США — FEC намеренно НЕ включён (API ненадёжен для ad-hoc запросов по именам доноров на бесплатном уровне DEMO_KEY). Для федеральных пожертвований направляйте пользователей напрямую на https://www.fec.gov/data/.

Рабочий процесс

Агент запускает скрипты через инструмент terminal. SKILL_DIR — это каталог, содержащий данный SKILL.md.

1. Определите, какие источники применимы

Прочитайте записи в вики источников данных, чтобы спланировать расследование:

ls SKILL_DIR/references/sources/

# Федеральные финансовые / регуляторные
cat SKILL_DIR/references/sources/sec-edgar.md       # корпоративные отчёты
cat SKILL_DIR/references/sources/usaspending.md     # федеральные контракты
cat SKILL_DIR/references/sources/senate-ld.md       # лоббизм
cat SKILL_DIR/references/sources/ofac-sdn.md        # санкции
cat SKILL_DIR/references/sources/icij-offshore.md   # офшорные утечки

# Идентичность / недвижимость / суды / архивы / новости
cat SKILL_DIR/references/sources/nyc-acris.md       # записи о недвижимости в Нью-Йорке
cat SKILL_DIR/references/sources/opencorporates.md  # глобальный корпоративный реестр
cat SKILL_DIR/references/sources/courtlistener.md   # судебные записи (федеральные + местные)
cat SKILL_DIR/references/sources/wayback.md         # архивы Wayback Machine
cat SKILL_DIR/references/sources/wikipedia.md       # Wikipedia + Wikidata
cat SKILL_DIR/references/sources/gdelt.md           # глобальный мониторинг новостей

Каждая запись следует 9-секционному шаблону: сводка, доступ, схема, охват, ключи для кросс-ссылок, качество данных, получение, юридические аспекты, ссылки.

Раздел потенциал кросс-ссылок отображает ключи соединения между источниками — читайте их в первую очередь, чтобы выбрать правильную пару.

2. Получите данные

Для каждого источника есть скрипт получения на stdlib в SKILL_DIR/scripts/:

Федеральные финансовые / регуляторные

# Корпоративные отчёты SEC EDGAR
python3 SKILL_DIR/scripts/fetch_sec_edgar.py --cik 0000320193 \
    --types 10-K,10-Q --out data/edgar_filings.csv

# Федеральные контракты USAspending
python3 SKILL_DIR/scripts/fetch_usaspending.py --recipient "EXAMPLE CORP" \
    --fy 2024 --out data/contracts.csv

# Раскрытия лоббистов Сената LD-1 / LD-2
python3 SKILL_DIR/scripts/fetch_senate_ld.py --client "EXAMPLE CORP" \
    --year 2024 --out data/lobbying.csv

# Полный список санкций OFAC SDN
python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --out data/ofac_sdn.csv

# Офшорные утечки ICIJ — при первом использовании загружает ~70 МБ CSV,
# затем выполняет локальный поиск. Кэшируется на 30 дней в
# $VIBEOS_OSINT_CACHE/icij/ (по умолчанию: ~/.cache/vibeos-osint/icij/).
python3 SKILL_DIR/scripts/fetch_icij_offshore.py --entity "EXAMPLE CORP" \
    --out data/icij.csv

Идентичность / недвижимость / суды / архивы / новости

# Записи о недвижимости в Нью-Йорке (акты, ипотеки, залоги) — ACRIS через Socrata
python3 SKILL_DIR/scripts/fetch_nyc_acris.py --name "SMITH, JOHN" \
    --out data/acris.csv
python3 SKILL_DIR/scripts/fetch_nyc_acris.py --address "571 HUDSON" \
    --out data/acris_addr.csv

# OpenCorporates — корпоративные реестры 130+ юрисдикций
# (требуется бесплатный токен; установите OPENCORPORATES_API_TOKEN или передайте --token)
python3 SKILL_DIR/scripts/fetch_opencorporates.py --query "Example Corp" \
    --jurisdiction us_ny --out data/opencorporates.csv

# CourtListener — мнения федеральных и местных судов, досье PACER
python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Smith v. Example Corp" \
    --type opinions --out data/courts.csv

# Wayback Machine — исторические снимки веб-страниц
python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
    --match host --collapse digest --out data/wayback.csv

# Wikipedia + Wikidata — нарративная биография + структурированные факты
# Установите VIBEOS_OSINT_UA=your-app/1.0 (your@email) для идентификации
python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Bill Gates" \
    --out data/wp.csv

# GDELT — глобальные новости на 100+ языках, ~2015→настоящее время
python3 SKILL_DIR/scripts/fetch_gdelt.py --query '"Example Corp"' \
    --timespan 1y --out data/gdelt.csv

Все выходные данные — нормализованные CSV с заголовком. Повторный запуск скриптов идемпотентен.

Если частное лицо отсутствует в источнике (например, SEC EDGAR для человека из непубличной компании, USAspending для того, кто не является федеральным подрядчиком, Senate LDA для того, кто не является клиентом лоббистов), скрипт возвращает 0 строк с чётким предупреждением, а не молча записывает пустой CSV. EDGAR специально отмечает, когда резолвер названий компаний сопоставил подателя индивидуальной формы 3/4/5, а не корпоративного регистранта.

Примечания по ограничениям скорости находятся в записи вики каждого источника. Стандартные загрузчики вежливо делают паузу между запросами с пагинацией. API-ключи повышают лимиты запросов для источников, которые их поддерживают (SEC_USER_AGENT, SENATE_LDA_TOKEN, OPENCORPORATES_API_TOKEN, COURTLISTENER_TOKEN). Все скрипты немедленно выводят ответы 429 с сообщением о квоте вышестоящей системы, чтобы пользователь знал о необходимости замедлиться или предоставить ключ.

3. Разрешите сущности по разным источникам

Нормализуйте имена и найдите совпадения между двумя CSV-файлами:

# Сопоставление клиентов лоббистов (Senate LDA) с получателями контрактов (USAspending)
python3 SKILL_DIR/scripts/entity_resolution.py \
    --left  data/lobbying.csv   --left-name-col  client_name \
    --right data/contracts.csv  --right-name-col recipient_name \
    --out data/cross_links.csv

Три уровня сопоставления с явной степенью уверенности:

Уровень	Метод	Уверенность
exact	Нормализованные строки равны после удаления суффиксов/пунктуации	высокая
fuzzy	Равенство отсортированных токенов (совпадение по набору слов)	средняя
token_overlap	≥60% перекрытия токенов, ≥2 общих токена, токены ≥4 символов	низкая

Столбцы выходного cross_links.csv: match_type, confidence, left_name, right_name, left_normalized, right_normalized, left_row, right_row.

4. Статистическая корреляция по времени (опционально)

Проверьте, сгруппированы ли два временных ряда подозрительно близко друг к другу — например, подача лоббистских отчётов рядом с датами присуждения контрактов — с помощью теста перестановок:

python3 SKILL_DIR/scripts/timing_analysis.py \
    --donations data/lobbying.csv --donation-date-col filing_date \
        --donation-amount-col income --donation-donor-col client_name \
        --donation-recipient-col registrant_name \
    --contracts data/contracts.csv --contract-date-col award_date \
        --contract-vendor-col recipient_name \
    --cross-links data/cross_links.csv \
    --permutations 1000 \
    --out data/timing.json

Флаги столбцов скрипта намеренно обобщены — исходный инструмент был написан для пожертвований и контрактов, но он работает с любыми временными рядами (событие, получатель), соединёнными через кросс-ссылки. Нулевая гипотеза: время событий не зависит от дат контрактов. Одностороннее p-значение = доля перестановок со средним расстоянием до ближайшего контракта ≤ наблюдаемому. Минимум 3 события на пару (плательщик, поставщик) для выполнения теста.

5. Постройте JSON-файл результатов (цепочка доказательств)

python3 SKILL_DIR/scripts/build_findings.py \
    --cross-links data/cross_links.csv \
    --timing data/timing.json \
    --out data/findings.json

Каждый результат имеет id, title, severity, confidence, summary, evidence[], sources[]. Каждый элемент доказательства указывает на конкретную строку в CSV-файле источника. Пользователь (или последующий агент) может проверить каждое утверждение по его источнику.

Дисциплина уверенности и доказательств

Это ключевое правило навыка. Сообщите пользователю:

• Каждое утверждение должно быть привязано к записи. Никаких голословных заявлений.
• Уровень уверенности сопровождает утверждение. match_type=fuzzy означает «вероятно», а не «подтверждено».
• Разрешение сущностей даёт кандидатов, а НЕ выводы. Совпадение fuzzy между «ACME LLC» и «Acme Holdings Group» — это зацепка, а не факт.
• Статистическая значимость ≠ правонарушение. p < 0,05 означает, что временной паттерн маловероятен при нулевой гипотезе. Это не устанавливает коррупцию.
• Все источники данных здесь — публичные записи. Они всё ещё могут содержать неточности, устаревшую информацию или редактирования (GDPR, запечатанные записи).

Добавление нового источника данных

Используйте шаблон:

cp SKILL_DIR/templates/source-template.md \
    SKILL_DIR/references/sources/<your-source>.md

Заполните все 9 разделов. Напишите скрипт fetch_<source>.py в scripts/, который использует только stdlib и записывает нормализованный CSV. Обновите список источников в разделе «Когда использовать» выше.

Инструменты и их ограничения

• entity_resolution.py НЕ использует внешние библиотеки нечёткого поиска (нет rapidfuzz, нет jellyfish). Сопоставление по набору токенов — это верхняя граница. Если нужен Левенштейн, транслитерация или фонетическое сопоставление, установите через pip отдельно.
• timing_analysis.py использует random из Python для перестановок. Для воспроизводимости передайте --seed N.
• Скрипты fetch_*.py используют urllib.request и соблюдают Retry-After. Интенсивное массовое использование может нарушить условия использования — сначала прочитайте юридический раздел каждого источника.

Юридическое примечание

Все источники Фазы 1 являются публичными записями. Массовое получение разрешено в соответствии с их соответствующими условиями доступа (FOIA, законы о публичных записях, явная публикация ICIJ, публичные данные OFAC). Однако:

• Некоторые источники агрессивно ограничивают скорость. Уважайте их заголовки.
• Некоторые редактируют информацию о регистрантах (GDPR в WHOIS, запечатанные документы).
• Перекрёстная проверка публичных записей для идентификации частных лиц может иметь этические последствия. Навык создаёт цепочки доказательств, а не обвинения.