업데이트로 돌아가기
New releaseAug 31, 2026

proxy v0.7.0

패키지 레지스트리용 경량 캐싱 프록시.

공유

git-pkgs proxy

패키지 레지스트리를 위한 캐싱 프록시입니다. 아티팩트를 로컬에 캐싱하여 패키지 다운로드 속도를 높이고, 대역폭 사용량을 줄이며 안정성을 향상시킵니다.

버전 쿨다운

대부분의 공급망 공격은 속도에 의존합니다. 악성 버전이 게시되면 아무도 알아차리기 전에 몇 분 안에 자동화된 파이프라인에 의해 소비됩니다. 쿨다운 기능은 새로 게시된 버전에 격리 기간을 추가합니다. 활성화하면 프록시는 구성 가능한 임계값을 초과할 때까지 메타데이터 응답에서 해당 버전을 제거합니다.

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

3일 쿨다운은 lodash가 4.18.0 버전을 게시하면, 3일이 지날 때까지 빌드가 4.17.21을 계속 사용한다는 의미입니다. 만약 새 릴리스가 손상된 것으로 밝혀지더라도, 당신은 전혀 노출되지 않습니다.

해석 순서: 패키지 오버라이드, 그다음 생태계 오버라이드, 그다음 전역 기본값. 이를 통해 보수적인 기본값을 설정하고 더 빠른 업데이트가 필요한 패키지에 대해 예외를 지정할 수 있습니다. 전체 구성 참조는 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]

프록시는 아티팩트 바이트를 스캐너에 업로드하지 않습니다. 각 스캐너는 패키지 메타데이터와 단기 서명 URL을 받아 알림을 받으며, 스캐너는 프록시 자체 스토리지에서 바이트를 직접 가져옵니다. 스캐너는 동시에 실행되며, block 모드 스캐너가 허용되지 않음 판정을 가장 먼저 보고하면 즉시 승리하고 나머지는 취소됩니다. 전체 구성 참조와 스캐너 HTTP 계약은 docs/configuration.md를 참조하세요.

지원되는 레지스트리

레지스트리언어/플랫폼쿨다운완료
npmJavaScript예✓
CargoRust예✓
RubyGemsRuby예✓
Go proxyGo✓
HexElixir예*✓
pub.devDart예✓
PyPIPython예✓
MavenJava✓
Gradle Build CacheJava/Kotlin✓
NuGet.NET예✓
ComposerPHP예✓
ConanC/C++✓
CondaPython/R예✓
CRANR✓
JuliaJulia✓
SwiftSwift✓
ContainerDocker/OCI✓
HomebrewmacOS/Linux✓
DebianDebian/Ubuntu✓
RPMRHEL/Fedora✓
AlpineAlpine Linux✓
ArchArch Linux✗
ChefChef✗
GenericAny✓
HelmKubernetes✓
VagrantVagrant✗

쿨다운은 메타데이터에 게시 타임스탬프가 있어야 합니다. 쿨다운 열에 "예"가 없는 레지스트리는 타임스탬프를 노출하지 않거나 아직 연결되지 않은 것입니다.

* Hex 쿨다운은 프록시가 protobuf 페이로드를 재인코딩하므로 레지스트리 서명 검증을 비활성화해야 합니다(HEX_NO_VERIFY_REPO_ORIGIN=1).

설치

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

기본 차트는 /data 아래에서 SQLite와 파일시스템 아티팩트 스토리지를 사용하여 10 GiB 영구 볼륨으로 백업된 레플리카 하나를 배포합니다. 인그레스, 외부 데이터베이스 및 오브젝트 스토리지 구성 옵션은 deploy/charts/proxy/values.yaml을 참조하세요.

빠른 시작

# 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)

이 저장소는 주석이 달린 핸들러로부터 OpenAPI 스펙을 생성하기 위해 swaggo를 사용합니다.

스펙 생성:

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는 프록시를 통해 작동합니다. audit 및 signing-key 엔드포인트는 구성된 업스트림 레지스트리로 전달되며, 업스트림 인증이 적용됩니다. 따라서 권고 사항은 프록시 자체의 취약점 데이터가 아닌 업스트림의 데이터베이스에서 가져오며, cooldown에 의해 보류된 버전은 보고서에서 제외되지 않습니다.

Cargo

~/.cargo/config.toml을 생성하거나 편집하세요:

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

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

또는 프로젝트 루트의 .cargo/config.toml에서 프로젝트별로 설정하세요.

RubyGems / Bundler

Gemfile에서 gem 소스를 설정하세요:

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

Homebrew의 JSON API와 아티팩트 도메인을 프록시로 지정하세요:

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

아티팩트 도메인은 /v2/homebrew/core/ 아래의 매니페스트와 bottle blob을 프록시합니다. GHCR 라우팅은 해당 리포지터리로 제한됩니다. 소스 아카이브, cask 애플리케이션 다운로드, 사용자 정의 tap 아티팩트, 레거시 플랫 파일 bottle 미러는 Homebrew의 일반 폴백 URL을 사용합니다. HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK을 설정하지 않은 상태로 두어 폴백을 활성화하세요.

오프라인 폴백을 위해 Homebrew JSON API 응답을 보존하려면 cache_metadata를 활성화하거나 PROXY_CACHE_METADATA=true를 설정하세요. Bottle blob과 해당 OCI 매니페스트는 이 설정 없이도 캐시됩니다.

업스트림은 기본적으로 JSON API의 경우 https://formulae.brew.sh/api, 아티팩트의 경우 https://ghcr.io로 설정됩니다. 이 프록시를 다른 프록시에 연결하려면 해당 프록시의 Homebrew 엔드포인트를 업스트림으로 구성하세요:

upstream:
  homebrew_api: "https://upstream-proxy.example.com/homebrew"
  homebrew_artifact: "https://upstream-proxy.example.com"

해당 환경 변수는 PROXY_UPSTREAM_HOMEBREW_API와 PROXY_UPSTREAM_HOMEBREW_ARTIFACT입니다.

Hex (Elixir)

~/.hex/hex.config에서 구성합니다:

{default_url, <<"http://localhost:8080/hex">>}.

또는 환경 변수를 설정하세요:

export HEX_MIRROR=http://localhost:8080/hex

pub.dev (Dart/Flutter)

PUB_HOSTED_URL 환경 변수를 설정하세요:

export PUB_HOSTED_URL=http://localhost:8080/pub

PyPI (pip)

프록시를 사용하도록 pip를 구성하세요:

pip install --index-url http://localhost:8080/pypi/simple/ package_name

또는 ~/.pip/pip.conf에 설정:

[global]
index-url = http://localhost:8080/pypi/simple/

Maven

~/.m2/settings.xml에 추가하세요:

<settings>
  <mirrors>
    <mirror>
      <id>proxy</id>
      <mirrorOf>central</mirrorOf>
      <url>http://localhost:8080/maven/</url>
    </mirror>
  </mirrors>
</settings>

/maven/ 엔드포인트는 Maven Central을 기본 업스트림으로 사용하며, 기본 업스트림이 not found를 반환할 경우 Gradle 플러그인 마커 메타데이터 및 관련 아티팩트에 대해 Gradle Plugin Portal로 폴백합니다.

동일한 프록시 엔드포인트를 통한 Gradle 플러그인 해석:

pluginManagement {
  repositories {
    maven(url = "http://localhost:8080/maven/")
  }
}

Gradle HTTP 빌드 캐시

settings.gradle(.kts)에서 구성:

buildCache {
  local {
    enabled = false
  }
  remote<HttpBuildCache> {
    url = uri("http://localhost:8080/gradle/")
    push = true
  }
}

NuGet

nuget.config에서 구성:

<configuration>
  <packageSources>
    <clear />
    <add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
  </packageSources>
</configuration>

또는 CLI를 사용하세요:

dotnet nuget add source http://localhost:8080/nuget/v3/index.json -n proxy

Composer (PHP)

composer.json에서 구성합니다:

{
    "repositories": [
        {
            "type": "composer",
            "url": "http://localhost:8080/composer"
        }
    ]
}

전역으로 설정하거나:

composer config -g repositories.proxy composer http://localhost:8080/composer

Conan (C/C++)

프록시를 원격으로 추가합니다:

더 읽기

카테고리

Vulnerability AnalysisCloud SecurityDevSecOpsSupply Chain SecurityAPI Security