Обзор безопасности

HTTPC следует принципу «Secure by Default» (безопасность по умолчанию): все ключевые функции безопасности работают из коробки, без дополнительной настройки защищая от типовых поверхностей атаки. При обработке пользовательских URL, вызове внешних недоверенных сервисов или работе в сценариях с высокими требованиями безопасности (финансы, медицина, госсектор) многоуровневая защита HTTPC служит надёжной базовой линией.

Матрица функций безопасности

Следующая таблица суммирует каждую функцию безопасности, соответствующее поле Config, значение по умолчанию и связанные функции/опции для быстрого нахождения точки конфигурации.

Функция	Поле Config	Значение по умолчанию	Связанные функции / опции
Минимальная версия TLS	Security.MinTLSVersion	TLS 1.2	—
Максимальная версия TLS	Security.MaxTLSVersion	TLS 1.3	—
Пользовательская конфигурация TLS	Security.TLSConfig	nil (по умолчанию)	—
Пропуск проверки сертификата	Security.InsecureSkipVerify	false	Только для тестирования
Закрепление сертификата	Security.CertificatePinner	nil (отключено)	NewSPKIHashPinner и др.
Защита SSRF	Security.AllowPrivateIPs	false (включено)	WithAllowPrivateIPs
Точное исключение SSRF	Security.SSRFExemptCIDRs	nil	—
Валидация URL	Security.ValidateURL	true	—
Валидация заголовков	Security.ValidateHeaders	true	—
Строгая проверка Content-Length	Security.StrictContentLength	true	—
Проверка безопасности Cookie	Security.CookieSecurity	nil (без проверки)	StrictCookieSecurityConfig, WithSecureCookie
Лимит размера тела ответа	Security.MaxResponseBodySize	10MB	—
Лимит размера тела запроса	Security.MaxRequestBodySize	0 (без лимита)	Требует явной установки
Защита от декомпрессионных бомб	Security.MaxDecompressedBodySize	100MB	—
Лимит размера заголовков ответа	Connection.MaxResponseHeaderBytes	0 (умолчание Go 10MB)	—
Белый список перенаправлений	Security.RedirectWhitelist	nil (разрешить все)	—
Лимит числа перенаправлений	Defaults.MaxRedirects	10	WithMaxRedirects
Следование перенаправлениям	Defaults.FollowRedirects	true	WithFollowRedirects

TIP

При обработке пользовательских URL используйте httpc.SecureConfig() напрямую для получения наиболее строгой базовой линии безопасности: отключение перенаправлений, лимит ответа 5MB, более короткие таймауты, включённая валидация URL/заголовков.

Безопасность TLS

HTTPC по умолчанию требует TLS 1.2+, отклоняя доказанно небезопасные TLS 1.0/1.1:

cfg := httpc.DefaultConfig()
// По умолчанию TLS 1.2-1.3, ручная настройка не требуется
cfg.Security.MinTLSVersion = tls.VersionTLS12
cfg.Security.MaxTLSVersion = tls.VersionTLS13

Для принудительного TLS 1.3 (более высокие требования безопасности, поддержка клиентом и сервером) установите MinTLSVersion = tls.VersionTLS13. После установки TLSConfig значения MinTLSVersion/MaxTLSVersion игнорируются — приоритет у TLSConfig.

WARNING

InsecureSkipVerify предназначен только для тестирования. Никогда не устанавливайте true в продакшене — иначе TLS-шифрование становится бесполезным, и злоумышленник в середине может перехватывать и подменять данные. После установки HTTPC выводит предупреждение безопасности в stderr в не-тестовой среде (см. ниже «Механизм предупреждений безопасности»).

Дополнительные детали TLS (наборы шифров, закрепление сертификатов, mTLS, пользовательские CA) см. в TLS и закрепление сертификатов.

Защита от SSRF

SSRF (Server-Side Request Forgery, подделка серверных запросов) — атака, при которой злоумышленник побуждает сервер отправлять запросы во внутреннюю сеть, что позволяет похищать учётные данные метаданных облачных instances, сканировать порты intranet, обращаться к внутренним административным интерфейсам. HTTPC включает защиту SSRF по умолчанию, блокируя соединения с приватными/зарезервированными диапазонами IP.

cfg := httpc.DefaultConfig()
// AllowPrivateIPs = false (по умолчанию) → блокировка 127.0.0.1, 10.x, 192.168.x, 169.254.x и др.

// Точное исключение определённых CIDR (например, VPN, внутренние сервисы VPC)
cfg.Security.SSRFExemptCIDRs = []string{
    "10.0.0.0/8",    // Внутренний VPC
    "100.64.0.0/10", // Tailscale VPN
}

// Пресет с самой сильной защитой SSRF
client, _ := httpc.New(httpc.SecureConfig())

Блокируемые диапазоны IP

Диапазон	CIDR	Описание
IPv4 loopback	127.0.0.0/8	localhost
Класс A приватные	10.0.0.0/8	Внутренняя сеть
Класс B приватные	172.16.0.0/12	Внутренняя сеть
Класс C приватные	192.168.0.0/16	Внутренняя сеть
Link-local	169.254.0.0/16	Автоконфигурация (включая метаданные AWS/Azure)
CGNAT	100.64.0.0/10	Carrier-grade NAT (включая метаданные Alibaba Cloud)
Класс E зарезервированные	240.0.0.0/4	Зарезервированные адреса
«Эта сеть»	0.0.0.0/8	Идентификатор данной сети
TEST-NET	192.0.2.0/24 и др.	Для документации
IPv6 loopback	::1/128	localhost
IPv6 уникальные локальные	fc00::/7	Внутренняя сеть
IPv6 link-local	fe80::/10	Автоконфигурация

Выше приведены основные диапазоны. Полный список (включая IPv4-mapped IPv6, NAT64 64:ff9b::/96, префикс документации IPv6 2001:db8::/32 и др.) см. в исходном коде isPrivateOrReservedIP. HTTPC также блокирует традиционные IP-литералы в десятичном/шестнадцатеричном/восьмеричном формате (например, 2130706433, 0x7f000001) для предотвращения обхода. Подробнее см. Защита от SSRF.

Валидация заголовков

ValidateHeaders (включено по умолчанию) автоматически предотвращает CRLF-инъекции и контрабанду заголовков запроса — отклоняет значения заголовков с возвратом каретки/переводом строки, нулевыми байтами и другими управляющими символами:

// Следующие заголовки будут отклонены
httpc.WithHeader("X-Custom", "value\r\nInjected: header") // CRLF-инъекция
httpc.WithHeader("X-Bad", "value\x00null")                // Управляющие символы

Валидация использует O(1) поиск по таблице — накладные расходы минимальны, PerformanceConfig() также сохраняет эту проверку.

Безопасность Cookie

HTTPC предоставляет трёхуровневый контроль безопасности Cookie: уровень конфигурации (глобально), уровень сессии (SessionManager), уровень запроса (WithSecureCookie).

CookieSecurityConfig

CookieSecurityConfig определяет обязательные атрибуты безопасности Cookie, защищая от CSRF, XSS, перехвата сессии:

Поле	Описание	Default	Strict
RequireSecure	Только HTTPS-передача	false	true
RequireHttpOnly	Запрет доступа из JS	false	true
RequireSameSite	Атрибут SameSite	"" (без ограничений)	"Strict"
AllowSameSiteNone	Разрешить SameSite=None	true	false
RequireSecureForSameSiteNone	None требует Secure	true	true

Валидация уровня конфигурации (глобальная)

cfg := httpc.DefaultConfig()
// Строгий режим: требуется Secure + HttpOnly + SameSite=Strict
cfg.Security.CookieSecurity = httpc.StrictCookieSecurityConfig()

// Или пользовательская настройка
cfg.Security.CookieSecurity = &httpc.CookieSecurityConfig{
    RequireSecure:   true,
    RequireHttpOnly: true,
    RequireSameSite: "Lax",
}

Валидация уровня сессии

sm, _ := httpc.NewSessionManagerDefault()
// Влияет на все последующие вызовы SetCookie, независимо от порядка добавления
sm.SetCookieSecurity(httpc.StrictCookieSecurityConfig())

Валидация уровня запроса

security := &httpc.CookieSecurityConfig{
    RequireSecure:   true,
    RequireHttpOnly: true,
}
// Внимание: WithSecureCookie должен идти после WithCookie, проверяет только Cookie, добавленные к этому моменту
result, err := client.Get("https://api.example.com",
    httpc.WithCookie(sessionCookie),
    httpc.WithSecureCookie(security),
)

WARNING

WithSecureCookie — это «последующая проверка» на уровне запроса: она валидирует только те Cookie, которые существуют на момент её применения. Обязательно помещайте её после всех опций WithCookie. Для глобальной валидации, не зависящей от порядка добавления, используйте CookieSecurity уровня конфигурации или SetCookieSecurity уровня сессии.

Защита от декомпрессионных бомб

Злоумышленник может использовать ответы gzip/deflate с высоким коэффициентом сжатия для исчерпания памяти (например, 10MB сжатых данных распаковываются в несколько GB). MaxDecompressedBodySize (по умолчанию 100MB) ограничивает фактический размер после распаковки, предотвращая декомпрессионные бомбы на корню.

cfg := httpc.DefaultConfig()
cfg.Security.MaxDecompressedBodySize = 50 * 1024 * 1024 // Лимит распаковки 50MB

Приоритеты

Конфигурация	Действующий лимит
Только MaxResponseBodySize	Применяется он (строже)
Только MaxDecompressedBodySize	Лимит на размер после распаковки
Оба установлены	Действует меньший (более строгий)

TIP

MaxResponseBodySize ограничивает переданные байты до распаковки, MaxDecompressedBodySize — фактические байты после распаковки. Вместе они обеспечивают двухслойную защиту.

Лимит размера тела запроса

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

cfg := httpc.DefaultConfig()
cfg.Security.MaxRequestBodySize = 5 * 1024 * 1024 // Лимит загрузки 5MB

WARNING

В отличие от MaxResponseBodySize (по умолчанию 10MB), MaxRequestBodySize по умолчанию равен 0 (без лимита) и не имеет автоматического резервного значения. При обработке пользовательских загрузок или проксировании запросов обязательно устанавливайте лимит явно.

Безопасность перенаправлений

Перенаправления — частый носитель SSRF и открытых перенаправлений. HTTPC предоставляет многоуровневый контроль:

// Сценарии, чувствительные к безопасности: полностью отключить перенаправления
cfg := httpc.SecureConfig() // FollowRedirects = false

// Или ограничить целевые домены перенаправлений (поддерживает подстановочные знаки *.example.com)
cfg := httpc.DefaultConfig()
cfg.Security.RedirectWhitelist = []string{
    "api.example.com",
    "auth.example.com",
    "*.cdn.example.com",
}

RedirectWhitelist поддерживает точное сопоставление и подстановочные знаки: *.example.com сопоставляется со строгими поддоменами типа api.example.com, но не с голым доменом example.com (оба нужно указать отдельно). Перенаправления на домены не из белого списка блокируются. Цели перенаправлений также проходят SSRF IP-валидацию.

Лимит размера заголовков ответа

MaxResponseHeaderBytes ограничивает размер заголовков ответа сервера, предотвращая сценарии, когда вредоносный сервер отправляет огромные заголовки для исчерпания памяти:

cfg := httpc.DefaultConfig()
cfg.Connection.MaxResponseHeaderBytes = 1 * 1024 * 1024 // Лимит заголовков ответа 1MB

По умолчанию 0 означает использование значения стандартной библиотеки Go (10MB). В высокобезопасных сценариях рекомендуется сократить до 1MB.

Механизм предупреждений безопасности

HTTPC выводит предупреждения в stderr для высокорисковых конфигураций в не-тестовой среде, напоминая разработчикам о необходимости исправлений. Два типа конфигураций вызывают предупреждения:

Конфигурация	Условие срабатывания	Содержание предупреждения
InsecureSkipVerify = true	Обнаружено в httpc.New(), не-тестовая среда	Проверка TLS-сертификатов отключена
TestingConfig()	Проверяется при вызове, не-тестовая среда	Отключены проверка TLS, защита SSRF, валидация URL/заголовков

Предупреждения через sync.Once срабатывают максимум один раз каждого типа на процесс, избегая переполнения логов. Определение тестовой среды: исполняемый файл с суффиксом .test / .test.exe или установлены переменные окружения GO_TEST / GOTEST=1.

Перенаправление или подавление предупреждений

// Перенаправление в пользовательский writer (например, структурированный лог)
httpc.SetSecurityWarnOutput(os.Stdout)

// Полное подавление (не рекомендуется — предупреждения являются ограждением безопасности, не должны замалчиваться)
httpc.SetSecurityWarnOutput(io.Discard)

WARNING

SetSecurityWarnOutput(io.Discard) тихо подавляет предупреждения безопасности. Используйте только после полного аудита конфигурации (например, подтверждение, что TestingConfig используется только для тестовых бинарников), никогда не применяйте в продакшен-развёртываниях для маскировки предупреждений.

Безопасность загрузки файлов

Путь файла Download проходит пять уровней защиты через prepareFilePath, предотвращая path traversal и атаки перезаписи файлов:

1. Блокировка UNC-путей: отклоняет сетевые пути вида \\server\share
2. Фильтрация управляющих символов: отклоняет пути с управляющими символами (< 0x20, 0x7F, 0x00)
3. Защита системных путей: отказ в записи в /etc, /bin, C:\Windows и другие системные каталоги (включая разрешение символических ссылок родительских каталогов)
4. Обнаружение path traversal: после filepath.Clean блокирует выход ../ за пределы рабочего каталога
5. Защита от символических ссылок: отклоняет пути, ведущие к символическим ссылкам, рекурсивно проверяет родительские каталоги от атак TOCTOU

После завершения загрузки можно проверить целостность файла через поле Checksum (SHA-256); при ошибке проверки скачанный файл автоматически удаляется.

Промежуточное ПО аудита

AuditMiddleware генерирует структурированные события аудита для каждого цикла запрос/ответ, подходит для сценариев со строгими требованиями соответствия (финансы, медицина, госсектор). URL автоматически маскируется (учётные данные удаляются), конфиденциальные заголовки запроса (Authorization, Cookie и др.) по умолчанию скрываются.

auditMiddleware := httpc.AuditMiddleware(&httpc.AuditConfig{
    OnAudit: func(event httpc.AuditEvent) {
        // event.URL уже маскирован; SourceIP/UserID извлекаются из context
        log.Printf("[AUDIT] %s %s -> %d (%v)",
            event.Method, event.URL, event.StatusCode, event.Duration)
    },
    Format:         "json",   // text или json
    IncludeHeaders: true,     // Записывать заголовки запроса/ответа (конфиденциальные маскируются)
    MaskHeaders:    []string{"Authorization", "Cookie", "Set-Cookie"},
    SanitizeError:  true,     // Очистка конфиденциальной информации в ошибках
})

cfg := httpc.DefaultConfig()
cfg.Middleware.Middlewares = []httpc.MiddlewareFunc{auditMiddleware}

SourceIP и UserID внедряются через ключи context: httpc.SourceIPKey, httpc.UserIDKey. Полные поля аудита, параметры конфигурации и практики продакшена см. в Контрольный список для продакшена.

Что дальше

• Защита от SSRF — детальный разбор защиты SSRF, исключения CIDR и защита метаданных облака
• TLS и закрепление сертификатов — конфигурация TLS, закрепление сертификатов и mTLS
• Контрольный список для продакшена — предзапусковые проверочные позиции по категориям и методы валидации