feat: add downloadBaseURL and checksum inputs (closes #206)

Author: benjaminbob21

.github/workflows/integration-tests.yml

@@ -54,3 +54,32 @@ jobs:
 
          - name: Validate kubectl setup old version
            run: python test/validate-kubectl.py 'v1.15.1'
+
+         - name: Fetch known SHA256 for v1.30.0 linux/amd64
+           id: sha
+           run: |
+              value=$(curl -fsSL https://dl.k8s.io/release/v1.30.0/bin/linux/amd64/kubectl.sha256)
+              echo "value=$value" >> "$GITHUB_OUTPUT"
+
+         - name: Setup kubectl with valid checksum
+           uses: ./
+           with:
+              version: 'v1.30.0'
+              checksum: ${{ steps.sha.outputs.value }}
+
+         - name: Validate kubectl setup with checksum
+           run: python test/validate-kubectl.py 'v1.30.0'
+
+         - name: Setup kubectl with bad checksum (expect failure)
+           id: badsum
+           continue-on-error: true
+           uses: ./
+           with:
+              version: 'v1.29.0'
+              checksum: 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef'
+
+         - name: Assert bad-checksum step failed
+           if: steps.badsum.outcome != 'failure'
+           run: |
+              echo "Expected bad-checksum step to fail, but outcome was: ${{ steps.badsum.outcome }}"
+              exit 1

action.yml

@@ -5,6 +5,14 @@ inputs:
       description: 'Version of kubectl'
       required: true
       default: 'latest'
+   downloadBaseURL:
+      description: 'Base URL to download kubectl from (https only). Use for private mirrors.'
+      required: false
+      default: 'https://dl.k8s.io'
+   checksum:
+      description: 'Expected SHA256 of the kubectl binary. Recommended when overriding downloadBaseURL.'
+      required: false
+      default: ''
 outputs:
    kubectl-path:
       description: 'Path to the cached kubectl binary'

package-lock.json

@@ -23,6 +23,7 @@
    "dependencies": {
       "@actions/core": "^3.0.1",
       "@actions/exec": "^3.0.0",
+      "@actions/http-client": "^4.0.0",
       "@actions/tool-cache": "^4.0.0"
    },
    "devDependencies": {

package.json

@@ -1,8 +1,143 @@
 import * as os from 'os'
-import * as util from 'util'
 import * as fs from 'fs'
+import * as path from 'path'
+import * as crypto from 'crypto'
 import * as core from '@actions/core'
 import * as toolCache from '@actions/tool-cache'
+import {HttpClient} from '@actions/http-client'
+
+export const DEFAULT_KUBECTL_BASE_URL = 'https://dl.k8s.io'
+
+export function normalizeBaseURL(input: string): string {
+   const u = new URL(input)
+   return `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, '')}`
+}
+
+export function isDefaultBaseURL(input: string): boolean {
+   try {
+      return (
+         normalizeBaseURL(input) === normalizeBaseURL(DEFAULT_KUBECTL_BASE_URL)
+      )
+   } catch {
+      return false
+   }
+}
+
+const SECURE_DOWNLOAD_MAX_BYTES = 256 * 1024 * 1024
+
+export async function secureDownload(downloadURL: string): Promise<string> {
+   const client = new HttpClient('setup-kubectl', [], {
+      allowRedirects: false
+   })
+   const response = await client.get(downloadURL)
+   const status = response.message.statusCode
+
+   if (status && status >= 300 && status < 400) {
+      const location = response.message.headers['location']
+      response.message.resume()
+      throw new Error(
+         `Refusing redirect from custom downloadBaseURL (status ${status} -> ${location}).`
+      )
+   }
+   if (status === 404) {
+      response.message.resume()
+      throw new toolCache.HTTPError(404)
+   }
+   if (status !== 200) {
+      response.message.resume()
+      throw new Error(`Download failed with status ${status}`)
+   }
+
+   const contentLengthHeader = response.message.headers['content-length']
+   const contentLength = Array.isArray(contentLengthHeader)
+      ? contentLengthHeader[0]
+      : contentLengthHeader
+   if (contentLength) {
+      const declared = Number.parseInt(contentLength, 10)
+      if (Number.isFinite(declared) && declared > SECURE_DOWNLOAD_MAX_BYTES) {
+         response.message.resume()
+         throw new Error(
+            `Refusing download: Content-Length ${declared} exceeds cap ${SECURE_DOWNLOAD_MAX_BYTES} bytes.`
+         )
+      }
+   }
+
+   const chunks: Buffer[] = []
+   let received = 0
+   for await (const chunk of response.message as AsyncIterable<Buffer>) {
+      received += chunk.length
+      if (received > SECURE_DOWNLOAD_MAX_BYTES) {
+         response.message.destroy()
+         throw new Error(
+            `Refusing download: response body exceeded cap ${SECURE_DOWNLOAD_MAX_BYTES} bytes.`
+         )
+      }
+      chunks.push(chunk)
+   }
+
+   const tmpDir = process.env['RUNNER_TEMP'] || os.tmpdir()
+   const tmpFile = path.join(tmpDir, `kubectl-${crypto.randomUUID()}`)
+   fs.writeFileSync(tmpFile, Buffer.concat(chunks))
+   return tmpFile
+}
+
+export function validateBaseURL(input: string): URL {
+   let url: URL
+   try {
+      url = new URL(input)
+   } catch {
+      throw new Error(`Invalid downloadBaseURL: "${input}" is not a valid URL.`)
+   }
+
+   if (url.protocol !== 'https:') {
+      throw new Error(
+         `downloadBaseURL must use https://, got "${url.protocol}" in "${input}".`
+      )
+   }
+
+   if (url.username || url.password) {
+      throw new Error(
+         'downloadBaseURL must not contain userinfo (user:pass@host).'
+      )
+   }
+
+   const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '')
+   const isLoopback =
+      host === 'localhost' || host === '127.0.0.1' || host === '::1'
+   const isLinkLocal = host.startsWith('169.254.')
+   const isPrivateV4 =
+      /^10\./.test(host) ||
+      /^192\.168\./.test(host) ||
+      /^172\.(1[6-9]|2\d|3[0-1])\./.test(host)
+   // Gate IPv6 ranges on ':' so DNS labels like "fcd.example.com" aren't matched.
+   const isIPv6Literal = host.includes(':')
+   const isUniqueLocalV6 = isIPv6Literal && /^f[cd]/.test(host)
+   const isLinkLocalV6 = isIPv6Literal && /^fe[89ab]/.test(host)
+   const isUnspecified = host === '0.0.0.0' || host === '::'
+   if (
+      isLoopback ||
+      isLinkLocal ||
+      isPrivateV4 ||
+      isUniqueLocalV6 ||
+      isLinkLocalV6 ||
+      isUnspecified
+   ) {
+      throw new Error(
+         `downloadBaseURL host "${host}" is loopback/link-local/private and is blocked by default.`
+      )
+   }
+
+   return url
+}
+
+export function validateVersion(version: string): void {
+   if (!/^v?\d+\.\d+\.\d+$/.test(version)) {
+      throw new Error(
+         `Invalid kubectl version: "${version}". Expected a value like "v1.30.0".`
+      )
+   }
+}
+
 export function getKubectlArch(): string {
    const arch = os.arch()
    if (arch === 'x64') {
@@ -11,28 +146,51 @@ export function getKubectlArch(): string {
    return arch
 }
 
-export function getkubectlDownloadURL(version: string, arch: string): string {
+export function getkubectlDownloadURL(
+   version: string,
+   arch: string,
+   baseURL: string = DEFAULT_KUBECTL_BASE_URL
+): string {
+   validateVersion(version)
+   const url = validateBaseURL(baseURL)
+
+   let osDir: string
+   let file: string
    switch (os.type()) {
       case 'Linux':
-         return `https://dl.k8s.io/release/${version}/bin/linux/${arch}/kubectl`
-
+         osDir = 'linux'
+         file = 'kubectl'
+         break
       case 'Darwin':
-         return `https://dl.k8s.io/release/${version}/bin/darwin/${arch}/kubectl`
-
+         osDir = 'darwin'
+         file = 'kubectl'
+         break
       case 'Windows_NT':
       default:
-         return `https://dl.k8s.io/release/${version}/bin/windows/${arch}/kubectl.exe`
+         osDir = 'windows'
+         file = 'kubectl.exe'
+         break
    }
+
+   const basePath = url.pathname.replace(/\/+$/, '')
+   url.pathname = `${basePath}/release/${version}/bin/${osDir}/${arch}/${file}`
+   return url.toString()
 }
 
 export async function getLatestPatchVersion(
    major: string,
-   minor: string
+   minor: string,
+   baseURL: string = DEFAULT_KUBECTL_BASE_URL
 ): Promise<string> {
    const version = `${major}.${minor}`
-   const sourceURL = `https://dl.k8s.io/release/stable-${version}.txt`
+   const url = validateBaseURL(baseURL)
+   const basePath = url.pathname.replace(/\/+$/, '')
+   url.pathname = `${basePath}/release/stable-${version}.txt`
+   const sourceURL = url.toString()
    try {
-      const downloadPath = await toolCache.downloadTool(sourceURL)
+      const downloadPath = isDefaultBaseURL(baseURL)
+         ? await toolCache.downloadTool(sourceURL)
+         : await secureDownload(sourceURL)
       const latestPatch = fs
          .readFileSync(downloadPath, 'utf8')
          .toString()