# Настройка Google Safe Browsing API

## Описание

Google Safe Browsing API позволяет проверять ссылки на наличие угроз безопасности:
- Вредоносное ПО (MALWARE)
- Социальная инженерия (SOCIAL_ENGINEERING)
- Нежелательное ПО (UNWANTED_SOFTWARE)
- Потенциально вредоносные приложения (POTENTIALLY_HARMFUL_APPLICATION)

## Шаг 1: Получение API ключа

### 1.1 Перейдите в Google Cloud Console
```
https://console.cloud.google.com/
```

### 1.2 Создайте новый проект или выберите существующий
- Нажмите на селектор проекта в верхней панели
- Выберите "Новый проект" или существующий
- Дайте проекту понятное имя (например, "Skleroznik Safe Browsing")

### 1.3 Включите Safe Browsing API
- В меню слева выберите "APIs & Services" → "Library"
- Найдите "Safe Browsing API"
- Нажмите "Enable"

### 1.4 Создайте учетные данные
- В меню слева выберите "APIs & Services" → "Credentials"
- Нажмите "Create Credentials" → "API Key"
- Скопируйте созданный API ключ

### 1.5 Ограничьте API ключ (рекомендуется)
- Нажмите на созданный API ключ
- В разделе "Application restrictions" выберите "HTTP referrers"
- Добавьте домены вашего приложения
- В разделе "API restrictions" выберите "Restrict key"
- Выберите только "Safe Browsing API"

## Шаг 2: Настройка переменных окружения

Добавьте в файл `.env`:

```env
# Google Safe Browsing API Configuration
GOOGLE_SAFE_BROWSING_API_KEY=your_api_key_here
GOOGLE_SAFE_BROWSING_CLIENT_ID=skleroznik-api
GOOGLE_SAFE_BROWSING_CLIENT_VERSION=1.0.0

# Link Validation Settings
GOOGLE_SAFE_BROWSING_ENABLED=true
LINK_VALIDATION_GOOGLE_TIMEOUT=5
LINK_VALIDATION_GOOGLE_FALLBACK=true
LINK_VALIDATION_GOOGLE_ERROR_FALLBACK=true
LINK_VALIDATION_STRICT_SECURITY=false
```

## Шаг 3: Проверка настройки

### 3.1 Тест API ключа
```bash
# Проверьте, что API ключ работает
curl -X POST "https://safebrowsing.googleapis.com/v4/threatMatches:find?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "clientId": "skleroznik-api",
      "clientVersion": "1.0.0"
    },
    "threatInfo": {
      "threatTypes": ["MALWARE"],
      "platformTypes": ["ANY_PLATFORM"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [{"url": "http://testsafebrowsing.appspot.com/s/malware.html"}]
    }
  }'
```

**Ожидаемый ответ для тестового URL:**
```json
{
  "matches": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threatEntryType": "URL",
      "threat": {
        "url": "http://testsafebrowsing.appspot.com/s/malware.html"
      },
      "cacheDuration": "300s"
    }
  ]
}
```

### 3.2 Проверка в приложении
```bash
# Проверьте логи после отправки ссылки
tail -f storage/logs/laravel.log | grep "Google Safe Browsing"
```

## Шаг 4: Мониторинг и диагностика

### 4.1 Проверка статуса API
```bash
# Проверьте квоты API
curl "https://safebrowsing.googleapis.com/v4/threatLists?key=YOUR_API_KEY"
```

### 4.2 Логирование
Система автоматически логирует:
- Успешные проверки
- Ошибки API
- Таймауты
- Обнаруженные угрозы

### 4.3 Метрики
Отслеживайте в Google Cloud Console:
- Количество запросов к API
- Ошибки и таймауты
- Использование квоты

## Шаг 5: Fallback стратегии

### 5.1 Текущие настройки fallback
```php
'fallback' => [
    'on_google_timeout' => true,      // Пропускать при таймауте
    'on_google_error' => true,        // Пропускать при ошибке API
    'on_any_security_failure' => false, // Не пропускать при обнаружении угроз
],
```

### 5.2 Альтернативные проверки
При недоступности Google Safe Browsing система использует:
- Локальные правила безопасности
- Проверку доменов (whitelist/blacklist)
- Базовую валидацию URL

## Шаг 6: Безопасность

### 6.1 Ограничение доступа к API ключу
- Не коммитьте API ключ в Git
- Используйте переменные окружения
- Ограничьте API ключ по доменам и API

### 6.2 Мониторинг использования
- Отслеживайте количество запросов
- Настройте алерты при превышении лимитов
- Регулярно проверяйте логи безопасности

## Шаг 7: Troubleshooting

### 7.1 Частые проблемы

**Ошибка "API key not valid"**
- Проверьте правильность API ключа
- Убедитесь, что Safe Browsing API включен
- Проверьте ограничения API ключа

**Ошибка "Quota exceeded"**
- Проверьте квоты в Google Cloud Console
- Увеличьте лимиты при необходимости
- Оптимизируйте количество запросов

**Таймауты**
- Увеличьте `LINK_VALIDATION_GOOGLE_TIMEOUT`
- Проверьте сетевую доступность
- Используйте fallback режим

### 7.2 Полезные команды
```bash
# Проверка конфигурации
php artisan config:show links.validation

# Тест валидации ссылки
php artisan tinker
>>> app(\App\Services\LinkValidationService::class)->isSafe('https://example.com')
```

## Стоимость

Google Safe Browsing API предоставляется **бесплатно** с лимитами:
- 10,000 запросов в день
- 100 запросов в минуту

Этого достаточно для большинства приложений. При превышении лимитов свяжитесь с Google для увеличения квот.

## Альтернативы

Если Google Safe Browsing недоступен, рассмотрите:
- **PhishTank API** - проверка фишинговых сайтов
- **URLVoid** - проверка репутации доменов
- **VirusTotal** - проверка файлов и URL
- **Локальные правила** - настройка whitelist/blacklist доменов

## Поддержка

- [Google Safe Browsing API Documentation](https://developers.google.com/safe-browsing)
- [Google Cloud Console](https://console.cloud.google.com/)
- [API Quotas and Pricing](https://developers.google.com/safe-browsing/v4/usage-limits)