API будет доступен по адресу `http://localhost:8000`.

Для локального выполнения трансформации также должны быть запущены Redis и transform worker. Одного Redis недостаточно.

Запустите Redis:```bash
docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine

Если вы видите `Job queue not available` или `Redis not available`, убедитесь, что:

- `OGI_REDIS_URL` указывает на `redis://localhost:6379/0` для локальных запусков на хосте
- бэкенд был перезапущен после запуска Redis
- отдельный процесс воркера запущен
- вы не используете hostname `redis`, доступный только в Docker, вне Docker Compose

Если вы запускаете бэкенд с PostgreSQL (`OGI_USE_SQLITE=false`), при запуске автоматически применяются миграции Alembic перед обработкой запросов. Развертывания Docker делают то же самое в точке входа контейнера бэкенда.

Запуски AI Investigator обрабатываются другим отдельным воркером:```bash
cd backend
uv run python -m ogi.agent.run_worker

Откройте http://localhost:5173. Вот и всё.

### AI Investigator

AI Investigator — это опциональный рабочий процесс на основе провайдера, который может планировать последовательности преобразований, запрашивать утверждения и обобщать ход расследования в рабочем пространстве.

- Откройте вкладку `AI Investigator` в проекте
- Настройте провайдера и модель в диалоге настроек исследователя
- Сохраните ключи API провайдера в разделе `API Keys`
- Запустите отдельный процесс `agent-worker` вместе с бэкендом

Текущая реализация поддерживает настройку провайдера для каждого пользователя и выделенный рабочий процесс, который выполняет шаги расследования независимо от основного API-сервера.

### CLI

Два поддерживаемых способа запуска CLI:

**Рекомендуемый** (активация не требуется):```bash
cd backend
uv sync
uv run ogi --help

## Docker

### Разработка```bash
cp .env.example .env
docker compose up

Используйте файл компоновки для продакшена только если у вас уже есть доступный экземпляр PostgreSQL и вы установили `OGI_DATABASE_URL` соответствующим образом:```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Для удаления определенных ограничений в локальном развертывании:```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none

### Встроенные категории преобразований

| Категория | Примеры                              |
| --------- | ------------------------------------ |
| DNS       | A, AAAA, MX, NS, CNAME записи        |
| IP & ASN  | GeoIP, обратный IP, информация об ASN|
| SSL/TLS   | Прозрачность сертификатов, SSL labs  |
| Email     | Валидация почтового сервера, проверки на утечки |
| Web       | WHOIS, информация о домене, извлечение данных с веб-страниц |
| Social    | Поиск имени пользователя, социальные профили |
| Hash      | Поиск MD5, SHA1, SHA256             |
| Location  | Геокодирование, погода, данные о ближайших ASN |

### Поддерживаемые типы сущностей

`Person` • `Username` • `Domain` • `IPAddress` • `EmailAddress` • `PhoneNumber` • `Organization` • `URL` • `SocialMedia` • `Hash` • `Document` • `Location` • `ASNumber` • `Network` • `MXRecord` • `NSRecord` • `Nameserver` • `SSLCertificate` • `Subdomain` • `HTTPHeader`

### Создание собственных преобразований

Хотите создать свои? Смотрите [руководство по участию](https://github.com/opengraphintel/ogi-transforms/blob/main/CONTRIBUTING.md).

Если вашему преобразованию требуются внешние учетные данные для сервисов, укажите их в `api_keys_required`. Не храните секреты в настройках преобразования. OGI управляет ими в разделе `API Keys`, а плагины, использующие секреты, считаются привилегированным кодом.

Если ваше преобразование предоставляет настраиваемые ограничения, такие как `max_results` или `max_content_chars`, по возможности отдавайте предпочтение стандартным названиям параметров, а не уникальным именам. OGI может централизованно переопределять максимальные значения с помощью `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`, что помогает облачным развертываниям соблюдать лимиты, в то время как локальные пользователи могут их удалить.

Каждый плагин — это директория с манифестом `plugin.yaml`:```yaml
name: my-transform
version: "1.0.0"
display_name: My Transform
description: What it does
author: Your Name
license: MIT
category: dns
input_types: [Domain]
output_types: [IPAddress]
permissions:
  network: true
  filesystem: false
  subprocess: false

### Конфигурация

OGI использует [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) с поддержкой файлов `.env`. Переменные времени выполнения/бэкенда имеют префикс `OGI_`.

Настройки в виде списка принимают:

- JSON-массивы, например `["plugins","../plugins"]`
- строки, разделённые запятыми, например `plugins,../plugins`

<details>
<summary><strong>Основные переменные окружения</strong></summary>

| Переменная                                    | Описание                                                                                                      | Значение по умолчанию                              |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `OGI_APP_NAME`                                | Имя приложения                                                                                                | `OGI`                                              |
| `OGI_HOST`                                    | Хост привязки бэкенда                                                                                         | `0.0.0.0`                                          |
| `OGI_PORT`                                    | Порт бэкенда                                                                                                  | `8000`                                             |
| `OGI_CORS_ORIGINS`                            | Разрешённые источники фронтенда                                                                               | `http://localhost:5173,http://localhost:3000`       |
| `OGI_USE_SQLITE`                              | Использовать SQLite вместо PostgreSQL                                                                         | `true`                                             |
| `OGI_DB_PATH`                                 | Путь к файлу базы данных SQLite                                                                               | `ogi.db`                                           |
| `OGI_DATABASE_URL`                            | Строка подключения PostgreSQL                                                                                 | `postgresql://postgres:postgres@localhost:5432/ogi` |
| `OGI_REDIS_URL`                               | Строка подключения Redis для RQ/задач                                                                         | `redis://localhost:6379/0`                          |
| `OGI_RQ_QUEUE_NAME`                           | Имя очереди для задач преобразования                                                                          | `transforms`                                       |
| `OGI_TRANSFORM_TIMEOUT`                       | Тайм-аут задачи преобразования в секундах                                                                     | `300`                                              |
| `OGI_AGENT_WORKER_POLL_INTERVAL_SEC`          | Интервал опроса для рабочего AI-исследователя                                                                 | `2.0`                                              |
| `OGI_AGENT_CLAIM_TIMEOUT_SEC`                 | Тайм-аут устаревшей блокировки шага AI-исследователя для восстановления                                        | `120`                                              |
| `OGI_AUTO_RUN_MIGRATIONS`                     | Автоматический запуск Alembic при локальном запуске приложения без SQLite                                      | `true`                                             |
| `OGI_RUN_DB_MIGRATIONS`                       | Запуск миграций БД в точке входа контейнера                                                                    | `false`                                            |
| `OGI_DB_MIGRATION_RETRIES`                    | Количество повторных попыток миграции в точке входа                                                           | `30`                                               |
| `OGI_DB_MIGRATION_DELAY_SECONDS`              | Задержка между повторными попытками миграции в точке входа                                                    | `2`                                                |
| `OGI_PLUGIN_DIRS`                             | Каталоги поиска плагинов                                                                                      | `plugins,../plugins`                               |
| `OGI_DEPLOYMENT_MODE`                         | Режим развёртывания (`self-hosted` или `cloud`)                                                               | `self-hosted`                                      |
| `OGI_CLOUD_BILLING_ENABLED`                   | Включить биллинг для Supporter (только облачная версия) и принудительное ограничение интервалов преобразований | `false`                                            |
| `OGI_FREE_TRANSFORM_COOLDOWN_SECONDS`         | Задержка между запусками преобразований для бесплатных облачных пользователей                                 | `1800`                                             |
| `OGI_PAID_TRANSFORM_COOLDOWN_SECONDS`         | Задержка между запусками преобразований для платных облачных пользователей                                    | `0`                                                |
| `OGI_STRIPE_SECRET_KEY`                       | Секретный ключ сервера Stripe для сессий Checkout и портала                                                   | не задано                                          |
| `OGI_STRIPE_WEBHOOK_SECRET`                   | Подпись вебхука Stripe                                                                                        | не задано                                          |
| `OGI_STRIPE_SUPPORTER_PRICE_ID`               | Идентификатор повторяющейся цены Stripe для плана Supporter                                                    | не задано                                          |
| `OGI_STRIPE_SUPPORTER_AMOUNT_CENTS`           | Отображаемая сумма для плана Supporter                                                                        | `300`                                              |
| `OGI_STRIPE_SUPPORTER_CURRENCY`               | Отображаемая валюта для плана Supporter                                                                       | `usd`                                              |
| `OGI_BILLING_SUCCESS_URL`                     | Необязательный URL перенаправления при успешном Checkout Stripe                                                | берётся из запроса                                |
| `OGI_BILLING_CANCEL_URL`                      | Необязательный URL перенаправления при отмене Checkout Stripe                                                  | берётся из запроса                                |
| `OGI_BILLING_PORTAL_RETURN_URL`               | Необязательный URL возврата с портала биллинга Stripe                                                          | берётся из запроса                                |
| `OGI_REGISTRY_REPO`                           | Репозиторий GitHub реестра преобразований                                                                     | `opengraphintel/ogi-transforms`                    |
| `OGI_REGISTRY_CACHE_TTL`                      | Время жизни кэша реестра в секундах                                                                           | `3600`                                             |
| `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`         | Необязательная глобальная карта максимальных переопределений для настроек преобразования                      | пусто                                              |
| `OGI_GITHUB_TOKEN`                            | Необязательный токен GitHub для обхода лимитов скорости реестра/API                                            | не задано                                          |
| `OGI_SUPABASE_URL`                            | URL проекта Supabase                                                                                          | не задано                                          |
| `OGI_SUPABASE_ANON_KEY`                       | Анонимный/публичный ключ Supabase                                                                             | не задано                                          |
| `OGI_SUPABASE_SERVICE_ROLE_KEY`               | Ключ служебной роли Supabase                                                                                  | не задано                                          |
| `OGI_SUPABASE_JWT_SECRET`                     | JWT-секрет Supabase                                                                                           | не задано                                          |
| `OGI_SUPABASE_REDIRECT_URL`                   | URL перенаправления, используемый потоками аутентификации фронтенда                                           | не задано                                          |
| `OGI_ADMIN_EMAILS`                            | Администраторы для управления реестром/плагинами                                                               | не задано                                          |
| `OGI_TELEMETRY_ENABLED`                       | Включить или отключить телеметрию на уровне установки                                                          | `true`                                             |
| `OGI_TELEMETRY_LEVEL`                         | Уровень телеметрии (`basic` или `full`)                                                                       | `full`                                             |
| `OGI_API_KEY_ENCRYPTION_KEY`                  | Ключ Fernet для шифрованного хранения ключей API                                                              | не задано (настоятельно рекомендуется)              |
| `OGI_API_KEY_INJECTION_ALLOW_COMMUNITY_PLUGINS` | Разрешить получение сохранённых ключей API плагинам сообщества                                                | `true`                                             |
| `OGI_API_KEY_INJECTION_TRUSTED_TIERS_ONLY`    | Ограничить вставку сохранённых ключей только доверенными уровнями                                             | `false`                                            |
| `OGI_API_KEY_INJECTION_ALLOWED_TIERS`         | Уровни, разрешённые при включённом режиме только доверенных                                                   | `official,verified`                                 |
| `OGI_API_KEY_SERVICE_ALLOWLIST`               | Необязательный список разрешённых сервисов для вставки сохранённых ключей                                     | пусто                                              |
| `OGI_API_KEY_SERVICE_BLOCKLIST`               | Необязательный список заблокированных сервисов для вставки сохранённых ключей                                 | пусто                                              |
| `OGI_LLM_PROVIDER`                            | Провайдер AI-исследователя по умолчанию (запасной вариант)                                                    | `openai`                                           |
| `OGI_LLM_MODEL`                               | Модель AI-исследователя по умолчанию (запасной вариант)                                                       | `gpt-4.1-mini`                                     |
| `OGI_EXPOSE_ERROR_DETAILS`                    | Включать внутренние детали в ответы 500                                                                      | `false`                                            |
| `OGI_SANDBOX_ENABLED`                         | Включить режим выполнения в песочнице                                                                         | `false`                                            |
| `OGI_SANDBOX_TIMEOUT`                         | Тайм-аут песочницы в секундах                                                                                 | `30`                                               |
| `OGI_SANDBOX_MEMORY_MB`                       | Ограничение памяти песочницы в МБ                                                                             | `256`                                              |
| `OGI_SANDBOX_ALLOWED_TIERS`                   | Разрешённые уровни в облачном режиме песочницы                                                                | `official,verified`                                 |
| `OGI_BOOT_REQUIREMENTS_ENABLE`                | Включить установку зависимостей плагинов при загрузке                                                         | `true`                                             |
| `OGI_BOOT_REQUIREMENTS_FILE`                  | Путь к файлу требований при загрузке                                                                          | `/app/plugins/requirements.txt`                    |
| `OGI_BOOT_LOCK_FILE`                          | Путь к файлу блокировки при загрузке                                                                          | `/app/plugins/ogi-lock.json`                       |
| `OGI_BOOT_REQUIREMENTS_STRICT`                | Завершать запуск, если отсутствуют зависимости плагинов                                                       | `false`                                            |
| `OGI_BOOT_REQUIREMENTS_CACHE_DIR`             | Временный/кэш-каталог для генерации требований при загрузке                                                   | `/tmp/ogi-boot`                                    |
| `OGI_FRONTEND_PORT`                           | Локальное сопоставление порта фронтенда Docker                                                                | `3000`                                             |
| `OGI_IMAGE_TAG`                               | Тег образа для production-развёртываний docker-compose/Coolify                                                | `latest`                                           |
| `OGI_BACKEND_IMAGE`                           | Необязательное переопределение образа бэкенда                                                                 | `ghcr.io/khashashin/ogi-backend`                   |
| `OGI_WORKER_IMAGE`                            | Необязательное переопределение образа рабочего. По умолчанию совпадает с образом бэкенда.                     | `ghcr.io/khashashin/ogi-backend`                   |
| `OGI_FRONTEND_IMAGE`                          | Необязательное переопределение образа фронтенда                                                               | `ghcr.io/khashashin/ogi-frontend`                  |
| `OGI_CLI_BEARER_TOKEN`                        | Необязательный токен Bearer для CLI для бэкендов с аутентификацией                                             | не задано                                          |

Полный список см. в [`.env.example`](https://github.com/khashashin/ogi/blob/HEAD/.env.example).

</details>

## Разработка

### Запуск тестов```bash
# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest

# Frontend
cd frontend
pnpm test

### CI Pipeline

The [CI workflow](https://github.com/khashashin/ogi/blob/HEAD/.github/workflows/ci.yml) runs on every pull request:

- **Backend:** ruff lint, mypy type check, pytest
- **Frontend:** vitest, eslint, vite build

## Contributing

PRs welcome! If you find a bug or have an idea, [open an issue](https://github.com/khashashin/ogi/issues).

For new transforms, contribute to [ogi-transforms](https://github.com/opengraphintel/ogi-transforms).

### Getting Started

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## Legal & Responsible Use

OGI is a general-purpose OSINT and graph analysis tool. **You are solely responsible for how you use it.** See [LEGAL.md](https://github.com/khashashin/ogi/blob/HEAD/LEGAL.md) for the full legal notice.

- **Comply with third-party Terms of Service.** Transforms that query external services (DNS, WHOIS, web scraping, username lookups, etc.) must be used in accordance with the ToS of those services. Automated or bulk querying of sites that prohibit it may violate their terms.
- **Respect data protection law.** If you are in the EU or processing data about EU residents, GDPR applies to you as the data controller. Collecting, storing, or processing personal data (names, email addresses, IP addresses, etc.) requires a lawful basis. OGI itself does not store data beyond your local instance — you are responsible for what you collect and retain.
- **Use for lawful purposes only.** OGI is intended for legitimate security research, investigations, threat intelligence, and educational use. Do not use it to harass individuals, conduct unauthorized access, or violate applicable law.
- **File format compatibility.** OGI supports import of the MTGX graph exchange format. This is provided purely for data interoperability and does not imply any affiliation with or endorsement by the makers of tools that use this format.

> **Disclaimer:** OGI is provided "as is" without warranty of any kind. The authors are not liable for any misuse or damages arising from use of this software.

## License

This project is licensed under the [GNU Affero General Public License v3.0](https://github.com/khashashin/ogi/blob/HEAD/LICENSE).

---

<div align="center">

**[Report Bug](https://github.com/khashashin/ogi/issues) &bull; [Request Feature](https://github.com/khashashin/ogi/issues) &bull; [Discussions](https://github.com/opengraphintel/ogi-transforms/discussions)**

Made with 💜 by the OGI community

</div>