git-pkgs proxy

Кэширующий прокси для реестров пакетов. Ускоряет загрузку пакетов за счёт локального кэширования артефактов, снижая потребление трафика и повышая надёжность.

Version Cooldown

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

cooldown:
  default: "3d"              # hide versions published less than 3 days ago
  ecosystems:
    npm: "7d"                # npm gets a longer window
    cargo: "0"               # disable for cargo
  packages:
    "pkg:npm/lodash": "0"    # exempt trusted packages

Трёхдневный период ожидания означает, что когда lodash публикует версию 4.18.0, ваши сборки продолжают использовать 4.17.21, пока не пройдёт 3 дня. Если новый релиз окажется скомпрометированным, вы никогда не подвергались риску.

Порядок разрешения: переопределение пакета, затем переопределение экосистемы, затем глобальное значение по умолчанию. Это позволяет задать консервативное значение по умолчанию и сделать исключения для пакетов, где нужны более быстрые обновления. Полный справочник по конфигурации см. в docs/configuration.md.

Сканирование артефактов

Период ожидания учитывает только временную метку публикации версии — он никогда не проверяет сами байты. Сканирование артефактов закрывает этот пробел: когда оно включено, каждый артефакт помещается в хранилище и сканируется одной или несколькими внешними службами (trivy, ClamAV, Wiz или любой другой, поддерживающей небольшой контракт HTTP/JSON), прежде чем он будет зафиксирован в кэше и отдан клиентам.

scanning:
  enabled: true
  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
  scanners:
    - name: clamav
      url: http://clamav-adapter:8080/scan
      mode: block             # a block verdict deletes the artifact and returns 403
    - name: trivy
      url: http://trivy-adapter:8081/scan
      mode: monitor            # findings are logged, never gate caching
      ecosystems: [npm, pypi]

Прокси никогда не загружает байты артефактов в сканер. Каждый сканер получает уведомление с метаданными пакета и кратковременной подписанной ссылкой; сканер сам забирает байты из собственного хранилища прокси. Сканеры работают параллельно, и первый сканер в режиме block, сообщивший вердикт «не разрешено», немедленно побеждает, отменяя остальные. Полный справочник по конфигурации и HTTP-контракт сканера см. в docs/configuration.md.

Поддерживаемые реестры

Реестр	Язык/Платформа	Cooldown	Завершено
npm	JavaScript	Да	✓
Cargo	Rust	Да	✓
RubyGems	Ruby	Да	✓
Go proxy	Go		✓
Hex	Elixir	Да*	✓
pub.dev	Dart	Да	✓
PyPI	Python	Да	✓
Maven	Java		✓
Gradle Build Cache	Java/Kotlin		✓
NuGet	.NET	Да	✓
Composer	PHP	Да	✓
Conan	C/C++		✓
Conda	Python/R	Да	✓
CRAN	R		✓
Julia	Julia		✓
Swift	Swift		✓
Container	Docker/OCI		✓
Homebrew	macOS/Linux		✓
Debian	Debian/Ubuntu		✓
RPM	RHEL/Fedora		✓
Alpine	Alpine Linux		✓
Arch	Arch Linux		✗
Chef	Chef		✗
Generic	Any		✓
Helm	Kubernetes		✓
Vagrant	Vagrant		✗

Cooldown требует наличия временных меток публикации в метаданных. Реестры без «Да» в столбце cooldown либо не предоставляют временные метки, либо ещё не подключены.

* Cooldown для Hex требует отключения проверки подписи реестра (HEX_NO_VERIFY_REPO_ORIGIN=1), поскольку прокси перекодирует protobuf-полезную нагрузку.

Установка

brew install git-pkgs/git-pkgs/proxy

Или скачайте бинарный файл со страницы релизов.

Helm

Установите чарт из GHCR, указав публичный URL, который клиенты менеджеров пакетов будут использовать для доступа к прокси:

helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
  --set config.data.base_url=https://proxy.example.com

Стандартный chart разворачивает одну реплику с постоянным томом на 10 GiB, используя SQLite и файловое хранилище артефактов в /data. См. deploy/charts/proxy/values.yaml для параметров конфигурации ingress, внешней базы данных и объектного хранилища.

Быстрый старт

# Build from source
go build -o proxy ./cmd/proxy

# Run with defaults (listens on :8080)
./proxy

# Run with custom settings
./proxy -listen :3000 -base-url https://proxy.example.com

Прокси теперь запущен. Настройте ваши менеджеры пакетов для его использования.

OpenAPI (Swagger)

В этом репозитории используется swaggo для генерации спецификации OpenAPI из аннотированных обработчиков.

Сгенерируйте спецификацию:

go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

Сгенерированные файлы записываются в docs/swagger/.

Когда прокси запущен, получите актуальную спецификацию по адресу:

• http://localhost:8080/openapi.json

Или замените http://localhost:8080 на ваш настроенный базовый URL. Эта ссылка также отображается на панели управления.

Настройка менеджеров пакетов

npm

Создайте или отредактируйте ~/.npmrc:

registry=http://localhost:8080/npm/

Или задайте для каждого проекта в .npmrc:

registry=http://localhost:8080/npm/

Или используйте переменную окружения:

npm_config_registry=http://localhost:8080/npm/ npm install

npm audit, pnpm audit, yarn npm audit и npm audit signatures работают через прокси: конечные точки аудита и ключей подписи передаются в настроенный вышестоящий реестр с применением аутентификации вышестоящего реестра. Таким образом, рекомендации поступают из базы данных вышестоящего реестра, а не из собственных данных прокси об уязвимостях, и версии, задержанные cooldown, не исключаются из отчёта.

Cargo

Создайте или отредактируйте ~/.cargo/config.toml:

[source.crates-io]
replace-with = "proxy"

[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

Или задайте для каждого проекта в .cargo/config.toml в корне вашего проекта.

RubyGems / Bundler

Задайте источник gem в вашем Gemfile:

source "http://localhost:8080/gem"

Или настройте глобально:

gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

Go-модули

Задайте переменную окружения GOPROXY:

export GOPROXY=http://localhost:8080/go,direct

Или в профиле вашей оболочки для постоянного применения.

Homebrew

Направьте JSON API и домен артефактов Homebrew на прокси:

export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080

Домен артефактов проксирует манифесты и blob-объекты bottle по пути /v2/homebrew/core/. Маршрутизация GHCR ограничена этим репозиторием. Исходные архивы, загрузки приложений cask, артефакты пользовательских tap-репозиториев и устаревшие flat-file зеркала bottle используют обычные резервные URL Homebrew. Оставьте резервный режим включённым, не задавая переменную HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK.

Включите cache_metadata или задайте PROXY_CACHE_METADATA=true, чтобы сохранять ответы JSON API Homebrew для офлайн-резерва. Blob-объекты bottle и их OCI-манифесты кэшируются и без этой настройки.