Python CLI-инструмент для быстрого анализа IOC (IP-адреса, домены, CVE) с использованием 6 бесплатных API Threat Intel. Вывод: цветной Excel, JSON, CSV. Использует: VT, Shodan, AbuseIPDB.
Исследуйте IP-адреса, домены, хеши и CVE через 6 бесплатных API-сервисов киберразведки — не переключаясь между вкладками браузера.
Быстрый старт · Использование · Архитектура · API-ключи · Скриншоты · Участие в разработке
🚀 С гордостью представлен в официальном репозитории Awesome OSINT.
ThreatLens — это единый инструмент командной строки, который объединяет поиск данных киберразведки по наиболее авторитетным бесплатным OSINT-источникам. Вместо того чтобы вставлять IP-адрес на пять разных сайтов, ThreatLens опрашивает их все параллельно, нормализует результаты и выдаёт чёткий вердикт — прямо в терминале или в аккуратном цветном отчёте Excel/JSON/CSV.
Создан для аналитиков SOC, специалистов по реагированию на инциденты, охотников за угрозами и всех, кому нужно быстрое и надёжное обогащение IOC без выхода из командной оболочки.
|
Почему ThreatLens
|
Не предназначен для
|
| Возможность | Подробности |
|---|---|
| 🎯 Типы IOC | IP, домен, URL, хеш файла (MD5 / SHA1 / SHA256), CVE |
| 🔌 Интегрированные API | AbuseIPDB, VirusTotal, AlienVault OTX, Shodan, URLScan.io, NVD |
| 📄 Разбор логов | Автоматически извлекает все типы IOC из любого лога или текстового файла |
| 📊 Отчёты | Excel (с цветовой кодировкой), JSON, CSV |
| 💾 Локальный кеш | Кеш SQLite с настраиваемым TTL — пропускает повторные запросы по известным IOC |
| 🛡️ Безопасность | Блокировка редиректов, белый список хостов, маскировка API-ключей в логах, нейтрализация формул в электронных таблицах |
| 🔒 Lockfile | requirements.lock с хешами SHA-256 для воспроизводимых установок |
| 💻 Опыт работы с CLI | Прогресс-бары Rich, цветные таблицы и чистый итоговый вердикт |
| 🧩 Архитектура | Модульные обогатители, типизированные модели, строгое разделение ответственности |
| ✅ Протестировано | 60 модульных и интеграционных тестов с pytest; CI через GitHub Actions |
| ⚡ Отказоустойчивость | Один сбойный API никогда не блокирует остальные — ошибки изолируются и логируются |
# 1. Clone & install
git clone https://github.com/AbdaullahAG/threatlens.git
cd threatlens
pip install -r requirements.txt
# 2. Configure your API keys
cp config/keys.env.example config/keys.env
# → edit config/keys.env and fill in your keys
# 3. Run your first scan
python main.py -i 45.33.32.156
💡 NVD (поиск CVE) работает из коробки без API-ключа. Все остальные API предлагают бесплатный тариф, регистрация в котором занимает менее 2 минут — см. API-ключи ниже.
pip install --require-hashes -r requirements.lock
| Базовый поиск по одному IOC |
| Комбинируйте разные типы IOC в одном запуске |
| Массовое исследование прямо из сырых логов |
| Машиночитаемый вывод для конвейеров |
| Ограничение обогащения выбранными источниками |
| Excel + JSON + CSV за один запуск |
| Обогащение CVE через NIST NVD (бесплатно, без ключа) |
| Полное логирование запросов/ответов для диагностики |
| Флаг | Описание |
|---|---|
-i, --ip | IP-адрес(а) для исследования |
-d, --domain | Домен(ы) для исследования |
-s, --hash | Хеш(и) файла — MD5 / SHA1 / SHA256 |
-c, --cve | Идентификатор(ы) CVE, например CVE-2021-44228 |
--file | Путь к лог- или текстовому файлу для автоматического извлечения IOC |
--apis | Ограничить обогащение определённым набором API |
--format | Формат вывода: excel (по умолчанию) | json | csv | all |
--output | Каталог для сохранения отчётов (по умолчанию: ./output) |
--no-report | Выводить результаты только в терминал, не сохранять файл |
--cache-path | Путь к SQLite для локального кеша (по умолчанию: .threatlens/investigations.db) |
--cache-ttl | Время жизни кеша в секундах (по умолчанию: 3600) |
--no-cache | Полностью обойти локальный кеш |
--max-requests | Ограничение на внешние вызовы API за запуск (по умолчанию: 250) |
--max-iocs | Максимум уникальных IOC за запуск (по умолчанию: 1000) |
--allow-private-iocs | Разрешить приватные/loopback IP-адреса (по умолчанию отключено) |
--delay | Задержка между вызовами API для настройки ограничения частоты |
-v, --verbose | Включить отладочное логирование |
threat_intel_tool/
├── main.py # CLI entry point & argument parser
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Dev/CI tooling (ruff, bandit, pip-audit, pip-tools)
├── requirements.lock # Pinned lockfile with SHA-256 hashes
├── pytest.ini # pytest configuration (marks, etc.)
├── config/
│ └── keys.env # API keys (copy from keys.env.example)
├── output/ # Generated reports land here
├── src/
│ ├── engine.py # Main orchestrator (collect → enrich → report)
│ ├── models.py # IOC & EnrichmentResult dataclasses
│ ├── storage.py # SQLite cache & investigation history
│ ├── parsers/
│ │ └── ioc_parser.py # Regex-based IOC extractor with validation
│ ├── enrichers/
│ │ ├── base.py # Abstract base — safe HTTP client (redirect-block, budget, retry)
│ │ ├── registry.py # Enricher dispatcher
│ │ ├── abuseipdb.py # AbuseIPDB (IP)
│ │ ├── virustotal.py # VirusTotal (IP / Domain / URL / Hash)
│ │ ├── otx.py # AlienVault OTX (IP / Domain / URL / Hash)
│ │ ├── shodan.py # Shodan (IP)
│ │ ├── urlscan.py # URLScan.io (URL / Domain)
│ │ └── nvd.py # NVD / NIST (CVE — no key required)
│ ├── reporters/
│ │ ├── excel_reporter.py # Color-coded Excel reports
│ │ ├── other_reporters.py # JSON & CSV output
│ │ └── terminal_display.py # Rich terminal tables
│ └── utils/
│ ├── config.py # API key loader & runtime config
│ ├── logger.py # Rich logging setup
│ ├── banner.py # ASCII banner
│ ├── quota.py # Per-run request budget (thread-safe)
│ └── security.py # IOC validation, formula neutralisation, secret redaction
└── tests/
├── conftest.py # pytest fixtures & --run-e2e flag
├── test_core.py # IOC parser, verdict logic, cache round-trip (34 tests)
├── test_enrichers.py # BaseEnricher HTTP edge-cases — mock only (9 tests)
├── test_reporters.py # Excel/CSV formula protection + SQLite integration (17 tests)
└── test_cli_e2e.py # Full CLI run against real NVD API (opt-in, --run-e2e)
Принципы проектирования
src/enrichers/, наследующий BaseEnricher. Изменения в других местах не требуются.BaseEnricher.get() обеспечивает работу только по HTTPS, белый список хостов, блокировку редиректов, обработку 429/Retry-After и ограничение бюджета запросов в одном месте.config/keys.env с откатом к системным переменным окружения.--delay) удерживает вас в пределах бесплатных тарифов каждого API.result.errors; один сбойный API никогда не обрушит весь скан.=, +, -, @).| Провайдер | Регистрация | Бесплатный тариф |
|---|---|---|
| AbuseIPDB | Бесплатно | 1 000 проверок/день |
| VirusTotal | Бесплатно | 4 запроса/мин · 500 запросов/день |
| AlienVault OTX | Бесплатно | Без ограничений (публичный фид) |
| Shodan | Бесплатно | Ограниченное число запросов |
| URLScan.io | Бесплатно | 5 000 запросов/день (поиск бесплатен) |
| NVD / NIST | Опционально | Ключ не требуется |
# Run all unit and integration tests (no network required)
pytest tests/ -v --ignore=tests/test_cli_e2e.py
# With coverage report
pytest tests/ -v --ignore=tests/test_cli_e2e.py --cov=src --cov-report=term-missing
# Run the end-to-end CLI test (makes a real NVD request)
pytest tests/test_cli_e2e.py --run-e2e -v
| Файл тестов | Покрытие |
|---|---|
test_core.py | Парсер IOC (все типы + граничные случаи), логика вердикта, круговой тест кеша SQLite |
test_enrichers.py | BaseEnricher.get() — блокировка редиректов, исчерпание бюджета, 429+Retry-After, маскировка API-ключей в логах, не-JSON ответ, некорректный JSON, белый список хостов, блокировка схемы HTTP |
test_reporters.py | Нейтрализация инъекции формул в Excel и CSV (7 вариантов префиксов), сквозная передача чисел, истечение TTL SQLite, upsert, запись исследования |
test_cli_e2e.py | Полный запуск подпроцесса: python main.py -c CVE-2021-44228 --apis nvd --format json → код выхода 0, корректный JSON, правильный вердикт |
| Мера | Реализация |
|---|---|
| Только HTTPS | BaseEnricher.get() отклоняет любой URL, не начинающийся с https://, до выполнения запроса |
| Белый список хостов | Каждый обогатитель объявляет allowed_hosts; запросы к неизвестным хостам молча отбрасываются |
| Блокировка редиректов | Все запросы используют allow_redirects=False |
| 429 / Retry-After | Одна автоматическая повторная попытка с соблюдением заголовка Retry-After (не более 15 с) |
| Бюджет запросов | --max-requests жёстко ограничивает общее число вызовов API за запуск |
| Маскировка API-ключей | В исключениях и строках логов сырые значения ключей заменяются на [REDACTED] |
| Инъекция формул | Все значения ячеек Excel и CSV очищаются с помощью spreadsheet_value() |
| Валидация IOC | Каждый IOC, переданный через CLI, проверяется и нормализуется перед обогащением |
| Защита от приватных IP | Приватные/loopback адреса отклоняются по умолчанию (--allow-private-iocs для переопределения) |
| Аудит зависимостей | pip-audit запускается в CI; requirements.lock фиксирует все хеши для воспроизводимых установок |
Терминал:
╭──────────────────────────── IOC Collection ─────────────────────────────╮
│ Found 4 IOCs to investigate │
│ CVE: 1 Domain: 1 Hash: 1 IP: 1 │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Active APIs: abuseipdb, virustotal, otx, shodan, urlscan, nvd
🌐 IP Address Results
┌─────────────────┬──────────────┬──────────┬─────────┬────────────────────┐
│ IP Address │ Verdict │ Abuse % │ Country │ ISP / Org │
├─────────────────┼──────────────┼──────────┼─────────┼────────────────────┤
│ 45.33.32.156 │ Suspicious │ 42 │ US │ Linode │
└─────────────────┴──────────────┴──────────┴─────────┴────────────────────┘
⚠️ CVE Results
┌──────────────────┬──────────┬──────┬──────────────┐
│ CVE ID │ Severity │ CVSS │ Published │
├──────────────────┼──────────┼──────┼──────────────┤
│ CVE-2021-44228 │ Critical │ 10.0 │ 2021-12-10 │
└──────────────────┴──────────┴──────┴──────────────┘
Отчёт Excel: Многостраничная книга с цветовой кодировкой вердиктов (🔴 вредоносный · 🟡 подозрительный · 🟢 чистый), сохраняется в output/ThreatLens_Report_<timestamp>.xlsx
Есть идея? Откройте issue — вклад и предложения приветствуются.
Вклад приветствуется и ценится!
git checkout -b feature/my-featurepytest tests/ -v --ignore=tests/test_cli_e2e.py проходит и ruff check . не выдаёт ошибокНовые обогатители, исправления ошибок, улучшения документации и покрытие тестами — всё это отличные первые вклады — см. Архитектура, чтобы понять, как устроены обогатители.
Этот проект распространяется под лицензией PolyForm Noncommercial License 1.0.0.
Вы можете свободно использовать, изучать, изменять и распространять этот код в личных, образовательных или исследовательских целях. Коммерческое использование не разрешено без предварительного письменного разрешения автора ([email protected]).
Этот инструмент предназначен только для образовательных целей и авторизованного тестирования безопасности. Пользователь несёт исключительную ответственность за соблюдение условий обслуживания интегрированных API и всех применимых законов. Автор не несёт никакой ответственности и не отвечает за любое неправомерное использование, незаконную деятельность или ущерб, причинённый этой программой.
Если ThreatLens сэкономил вам время, поставьте ему ⭐ — это поможет другим узнать о проекте.