diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 03b78a1..cc7f3ba 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,10 +1,14 @@ # Test the action the way a customer uses it: `uses: ./`, on the runners we # claim to support, against the real marketplace. # -# The whole test runs on `dry-run: true`, so it needs NO Linro install, NO +# The whole test runs on `dry-run: true` against a stand-in install +# (testdata/stub-install.py on loopback), so it needs NO Linro install, NO real # token, and no secrets at all. That is deliberate — a test that needs a # credential is a test that stops running the moment the credential lapses, -# and this one has to keep working on forks and on Dependabot branches. +# and this one has to keep working on forks and on Dependabot branches. The +# stand-in serves the install's download route (bearer token, X-Linro-Sha256) +# and takes the tarball from the public marketplace; once the marketplace +# requires a key for /artifacts, it needs one too. # # What it does NOT cover, and cannot without an install: that a submission is # accepted and comes back as a check run. That path is exercised continuously @@ -99,10 +103,16 @@ jobs: steps: - uses: actions/checkout@v7 - - name: Simulate a fixture plan (no install, no token) + - name: Start a stand-in install + id: stub + run: echo "url=$(testdata/start-stub.sh stub ok)" >> "$GITHUB_OUTPUT" + + - name: Simulate a fixture plan (no install, no real token) id: sim uses: ./ with: + server: ${{ steps.stub.outputs.url }} + token: ci-token plan: testdata/plan.json account: "000000000000" region: eu-central-1 @@ -118,6 +128,14 @@ jobs: test -n "$RESOLVED" || { echo "::error::version output is empty"; exit 1; } echo "ran linro-simulator ${RESOLVED}" + - name: The CLI came from the install, with the token + run: | + # The download route and the bearer are the v2 contract with the + # install; the stand-in logs what it was asked for. + cat "${RUNNER_TEMP}/stub.log" + grep -q '^/api/simulator/download/[^/]*/[a-z0-9]*-[a-z0-9]*\.tar\.gz auth=ok$' "${RUNNER_TEMP}/stub.log" || + { echo "::error::the action did not download from the install with its token"; exit 1; } + # The multi-source contract, which is the part most likely to rot: several # sources become ONE simulation, plan and preview COMBINE, and a blank line # is not a path. @@ -130,9 +148,15 @@ jobs: steps: - uses: actions/checkout@v7 + - name: Start a stand-in install + id: stub + run: echo "url=$(testdata/start-stub.sh stub ok)" >> "$GITHUB_OUTPUT" + - name: Terraform AND Pulumi, one simulation uses: ./ with: + server: ${{ steps.stub.outputs.url }} + token: ci-token plan: | testdata/plan.json @@ -147,6 +171,8 @@ jobs: - name: OpenTofu is a label on the source, not a different format uses: ./ with: + server: ${{ steps.stub.outputs.url }} + token: ci-token plan: testdata/plan.json opentofu: "true" account: "000000000000" @@ -211,12 +237,29 @@ jobs: steps: - uses: actions/checkout@v7 + - name: Start stand-in installs + id: stub + run: | + { + echo "url=$(testdata/start-stub.sh stub ok)" + echo "bad-sha=$(testdata/start-stub.sh stub-bad-sha bad-sha)" + echo "no-sha=$(testdata/start-stub.sh stub-no-sha no-sha)" + } >> "$GITHUB_OUTPUT" + + # Each case must fail AND for its own reason (testdata/expect-refusal.sh + # reads the reason the action recorded), so a stub failure cannot pass + # for the check a case is about. `if: always()` runs every check. - name: No sources at all is refused id: nothing continue-on-error: true uses: ./ with: + server: ${{ steps.stub.outputs.url }} + token: ci-token dry-run: "true" + - name: "Check: no sources" + if: always() + run: testdata/expect-refusal.sh "no sources" "${{ steps.nothing.outcome }}" "nothing to simulate" - name: A real submission without a token is refused id: no-token @@ -225,6 +268,170 @@ jobs: with: plan: testdata/plan.json server: https://example.invalid + token: "" + - name: "Check: missing token" + if: always() + run: testdata/expect-refusal.sh "missing token" "${{ steps.no-token.outcome }}" "the token input is required" + + - name: A dry run without a token is refused + id: dry-no-token + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.url }} + token: "" + dry-run: "true" + - name: "Check: dry run without a token" + if: always() + run: testdata/expect-refusal.sh "dry run without a token" "${{ steps.dry-no-token.outcome }}" "the token input is required" + + - name: A dry run without a server is refused + id: dry-no-server + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "" + token: ci-token + dry-run: "true" + - name: "Check: dry run without a server" + if: always() + run: testdata/expect-refusal.sh "dry run without a server" "${{ steps.dry-no-server.outcome }}" "the server input is required" + + - name: A server with user info is refused + id: userinfo + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "https://user@acme.example" + token: ci-token + dry-run: "true" + - name: "Check: user info" + if: always() + run: testdata/expect-refusal.sh "user info" "${{ steps.userinfo.outcome }}" "must not carry user info" + + - name: A loopback prefix with user info is refused + id: userinfo-loopback + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "http://127.0.0.1:80@evil.example" + token: ci-token + dry-run: "true" + - name: "Check: loopback user info" + if: always() + run: testdata/expect-refusal.sh "loopback user info" "${{ steps.userinfo-loopback.outcome }}" "must not carry user info" + + - name: A host that only starts with localhost is not loopback + id: localhost-suffix + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "http://localhost.evil.com" + token: ci-token + dry-run: "true" + - name: "Check: localhost suffix" + if: always() + run: testdata/expect-refusal.sh "localhost suffix" "${{ steps.localhost-suffix.outcome }}" "plain http only for a loopback install" + + - name: A host that only starts with 127.0.0.1 is not loopback + id: ip-suffix + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "http://127.0.0.1.nip.io" + token: ci-token + dry-run: "true" + - name: "Check: 127.0.0.1 suffix" + if: always() + run: testdata/expect-refusal.sh "127.0.0.1 suffix" "${{ steps.ip-suffix.outcome }}" "plain http only for a loopback install" + + - name: An IPv6 loopback with user info is refused + id: ipv6-userinfo + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: "http://[::1]@evil.example" + token: ci-token + dry-run: "true" + - name: "Check: [::1] user info" + if: always() + run: testdata/expect-refusal.sh "[::1] user info" "${{ steps.ipv6-userinfo.outcome }}" "must not carry user info" + + # Not a refusal: with every proxy variable pointing at a closed port, the + # loopback stand-in is still reached, so the request (and its token) + # did not go through the proxy. + - name: A loopback install is reached past a proxy + uses: ./ + # One spelling each: workflow env names are case-insensitive. curl + # reads http_proxy only in lower case, and ALL_PROXY in either. + env: + http_proxy: http://127.0.0.1:9 + HTTPS_PROXY: http://127.0.0.1:9 + ALL_PROXY: http://127.0.0.1:9 + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.url }} + token: ci-token + dry-run: "true" + + - name: A token the install refuses is refused + id: wrong-token + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.url }} + token: not-the-token + dry-run: "true" + - name: "Check: refused token" + if: always() + run: testdata/expect-refusal.sh "refused token" "${{ steps.wrong-token.outcome }}" "refused the token (HTTP 401)" + + - name: Plain http to an install that is not on loopback is refused + id: plain-http + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: http://example.invalid + token: ci-token + dry-run: "true" + - name: "Check: plain http" + if: always() + run: testdata/expect-refusal.sh "plain http" "${{ steps.plain-http.outcome }}" "server must be an https:// URL" + + - name: A download that does not match X-Linro-Sha256 is refused + id: bad-sha + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.bad-sha }} + token: ci-token + dry-run: "true" + - name: "Check: sha256 mismatch" + if: always() + run: testdata/expect-refusal.sh "sha256 mismatch" "${{ steps.bad-sha.outcome }}" "does not match the sha256 the install stated" + + - name: A download without X-Linro-Sha256 is refused + id: no-sha + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.no-sha }} + token: ci-token + dry-run: "true" + - name: "Check: no sha256 header" + if: always() + run: testdata/expect-refusal.sh "no sha256 header" "${{ steps.no-sha.outcome }}" "sent no X-Linro-Sha256 header" - name: A boolean that is neither true nor false is refused id: bad-bool @@ -232,10 +439,13 @@ jobs: uses: ./ with: plan: testdata/plan.json - # The whole point: `yes` must not quietly read as false and turn the - # gate off. This is the one wrong answer that looks like it worked. + server: ${{ steps.stub.outputs.url }} + token: ci-token strict: "yes" dry-run: "true" + - name: "Check: bad boolean" + if: always() + run: testdata/expect-refusal.sh "bad boolean" "${{ steps.bad-bool.outcome }}" "the strict input must be true or false" - name: A version the marketplace does not serve is refused id: bad-version @@ -243,25 +453,24 @@ jobs: uses: ./ with: plan: testdata/plan.json + server: ${{ steps.stub.outputs.url }} + token: ci-token version: v99.99.99 dry-run: "true" + - name: "Check: unknown version" + if: always() + run: testdata/expect-refusal.sh "unknown version" "${{ steps.bad-version.outcome }}" "has no linro-simulator v99.99.99" - - name: Assert each refusal actually failed - run: | - # continue-on-error records the outcome instead of ending the job, so - # a step that WRONGLY succeeded is only caught by checking here. Without - # this, "the action refuses bad input" would be an untested claim. - fail=0 - for pair in "no sources:${{ steps.nothing.outcome }}" \ - "missing token:${{ steps.no-token.outcome }}" \ - "bad boolean:${{ steps.bad-bool.outcome }}" \ - "unknown version:${{ steps.bad-version.outcome }}"; do - name="${pair%%:*}"; outcome="${pair##*:}" - if [ "$outcome" != "failure" ]; then - echo "::error::${name} should have failed the step, got '${outcome}'" - fail=1 - else - echo "ok: ${name} → ${outcome}" - fi - done - exit "$fail" + - name: A version that is not a version is refused before any request + id: malformed-version + continue-on-error: true + uses: ./ + with: + plan: testdata/plan.json + server: ${{ steps.stub.outputs.url }} + token: ci-token + version: "1.0/../../x" + dry-run: "true" + - name: "Check: malformed version" + if: always() + run: testdata/expect-refusal.sh "malformed version" "${{ steps.malformed-version.outcome }}" "is not a version" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..88274bb --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,36 @@ +# Changelog + +## v2.0.0 (unreleased) + +The CLI is downloaded from your Linro install, not anonymously from the +marketplace (ENG-1730). The marketplace is going to require a key for +downloads, and a customer's CI has no marketplace key; it has a Linro PAT. + +- The action downloads `linro-simulator` from + `/api/simulator/download//-.tar.gz` with `token` + as `Authorization: Bearer`. The install fetches it from the marketplace with + its own key and checks the marketplace's sha256; the action checks the file + again against the install's `X-Linro-Sha256` header. +- **Breaking:** `server` and `token` are required on every run, dry runs + included. +- **Breaking:** the `marketplace-url` input is removed. +- `server` must be `https://`, or plain `http://` to exactly `127.0.0.1`, + `localhost` or `[::1]` (optional port), so the token never crosses the + network in clear. User info, a query or a fragment in `server` is refused. + A loopback install is never reached through a proxy; https follows the + runner's proxy settings. +- A refused token (401), a token without `SCOPE_SIMULATIONS` (403), an + unknown version (404) and an unreachable install are reported separately. +- `version` is checked before any request (a semver or an alias such as + `latest`), and the whole download, retries included, has one 10-minute + wall-clock deadline. +- `ca-cert` also applies to the CLI download, where it replaces the system + roots. + +Needs an install that serves the simulator download. `@v1` keeps downloading +anonymously from the marketplace until the marketplace requires a key for +downloads. + +## v1.1.1 and earlier + +See the [releases](https://github.com/linro-io/simulation-github-action/releases). diff --git a/README.md b/README.md index eab0c41..630e877 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ jobs: terraform plan -out=tfplan terraform show -json tfplan > plan.json - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: plan: plan.json server: ${{ vars.LINRO_SERVER }} # https://acme.linro.app @@ -63,8 +63,9 @@ that is the gate. If you would rather block the job itself, set ## Inputs -Everything is optional except a source (`plan` and/or `preview`) and — for a -real submission — `server` and `token`. +Everything is optional except a source (`plan` and/or `preview`), `server` +and `token`. Both are required on every run, a dry run included: the action +downloads the CLI from your install with your token. Every flag `linro-simulator simulate` accepts is a first-class input. `extra-args` is for flags newer than your pinned action, not the normal way to reach anything @@ -83,9 +84,9 @@ below. | Input | Default | What it does | |---|---|---| -| `server` | | Your install, e.g. `https://acme.linro.app`. | -| `token` | | Linro PAT with `SCOPE_SIMULATIONS`. Always from a secret. | -| `ca-cert` | | PEM bundle for an install behind an internal CA. | +| `server` | | **Required.** Your install, e.g. `https://acme.linro.app`. The CLI is downloaded from it. `https://` only, or plain `http://` to a loopback install. | +| `token` | | **Required.** Linro PAT with `SCOPE_SIMULATIONS` (or `SCOPE_API`). Always from a secret. It authorizes the CLI download and the submission. | +| `ca-cert` | | PEM bundle for an install behind an internal CA. The CLI keeps the system roots and adds this bundle. The CLI download (curl `--cacert`) uses this bundle **instead of** the system roots, since it goes to the install alone, so the bundle must hold the CA that signed your install's certificate. | | `insecure` | `false` | Plaintext transport. The CLI allows this only for a **loopback** server — useful on a self-hosted runner beside an install, useless on a hosted one. | **Scope.** How the resources are identified against your inventory. @@ -107,7 +108,7 @@ below. | `label` | `linro-simulate` | Names the check run. Give each simulation in a workflow its own. | | `integration` | `github-ci` | `github-ci` → check run. `cli` → poll and print (use on push/schedule). | | `strict` | `false` | Fail if any resource could not be simulated. | -| `dry-run` | `false` | Print the payload instead of submitting. No server or token needed. | +| `dry-run` | `false` | Print the payload instead of submitting. Still needs `server` and `token`, to download the CLI. | | `poll-timeout` | | How long to wait for a result on `integration: cli`. | | `allow-provider-mismatch` | `false` | Proceed past a Pulumi provider major skew. Attributes may be dropped, so a pass means less. | | `gateway-oidc-audience` | | Override the OIDC audience. Leave unset — the install is asked for its own, so it cannot drift. | @@ -121,7 +122,6 @@ below. | Input | Default | What it does | |---|---|---| | `version` | `v0.2.1` | CLI version to run, or `latest`. | -| `marketplace-url` | `https://marketplace.linro.io` | Where the CLI is downloaded from. | Outputs: `version` (the CLI version that ran) and `binary-path`. @@ -176,7 +176,7 @@ describes a world that does not exist. Read the value off the connector — do not retype what you think you configured: ```yaml - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: plan: infra/plan.json server: ${{ vars.LINRO_SERVER }} @@ -197,7 +197,7 @@ simulation with one verdict, so a change spanning both tools gets a single answer instead of one per tool: ```yaml - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: plan: | infra/plan.json @@ -227,7 +227,7 @@ checking anything more. env: PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_PASSPHRASE }} - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: preview: infra/preview.json server: ${{ vars.LINRO_SERVER }} @@ -243,7 +243,7 @@ dialects: Terraform (`google`, `google-beta`), Pulumi `gcp` and Pulumi `google-native`. The action's default `version` predates this, so set it. ```yaml - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: version: v0.6.27 plan: plan.json @@ -279,40 +279,73 @@ dialects: Terraform (`google`, `google-beta`), Pulumi `gcp` and Pulumi which a check would read as compliant. The refusal says so; upgrade the install. This applies to every provider, not only GCP. -## Trying it without an install +## Seeing what a simulation would send ```yaml - - uses: linro-io/simulation-github-action@v1 + - uses: linro-io/simulation-github-action@v2 with: plan: plan.json + server: ${{ vars.LINRO_SERVER }} + token: ${{ secrets.LINRO_TOKEN }} account: "123456789012" region: eu-central-1 dry-run: "true" ``` -Prints exactly what would be submitted. No server, no token, no account of any -kind — useful for seeing what a simulation actually sends before wiring -credentials. +Prints exactly what would be submitted, and submits nothing. It still needs +`server` and `token`: the CLI is downloaded from your install. ## Runners Linux and macOS, `x64` and `arm64`. There is no Windows build of the CLI, and the action says so rather than failing obscurely. -The CLI is downloaded from the Linro marketplace — the same place your install -gets it — so a version is only available here once it has been published to -your marketplace. If you pin a `version` the marketplace does not serve, the -action fails naming the version and the platform. A network failure says so -separately: the two need opposite fixes. +The CLI is downloaded from your install, at +`/api/simulator/download//-.tar.gz`, with your token +as `Authorization: Bearer`. The install fetches it from the Linro marketplace +with its own key, so a version is only available once the marketplace serves +it, and checks it against the sha256 the marketplace states. The action checks +the file again against the install's `X-Linro-Sha256` header before running +it. If you pin a `version` the marketplace does not serve, the action fails +naming the version and the platform. A refused token (401), a token without +`SCOPE_SIMULATIONS` (403) and a network failure each say so separately: they +need different fixes. + +The download to an `https://` install follows the runner's proxy settings +(`https_proxy`, `ALL_PROXY`, `no_proxy`), as it did before. A loopback +`http://` install is never reached through a proxy, so the token cannot leave +the runner in clear. `server` must be a bare base URL: user info (`user@`), a +query or a fragment is refused, and plain `http://` is accepted only for +exactly `127.0.0.1`, `localhost` or `[::1]`, with an optional port. The whole +download, retries included, has one 10-minute deadline. ## Versioning -Pin the action to a major (`@v1`) for automatic fixes, or to an exact release +Pin the action to a major (`@v2`) for automatic fixes, or to an exact release for full reproducibility. The `version` input pins the **CLI**, independently. Both are pinned by default; `version: latest` tracks your marketplace, which is convenient and means a green run stops being evidence about any particular build. +## Upgrading from v1 + +v2 downloads the CLI from your install instead of anonymously from the +marketplace, because the marketplace is going to require a key for downloads. +Two things change, which is why it is a new major: + +- `server` and `token` are required on every run, **dry runs included**. A v1 + dry run that set neither must now set both. +- The `marketplace-url` input is gone. Remove it from your workflow: an input + the action does not declare is ignored with a warning. + +Your install must serve the simulator download (an older one answers 404). The +token you already use for submissions works, as long as it carries +`SCOPE_SIMULATIONS` or `SCOPE_API`. + +`@v1` keeps downloading anonymously from the marketplace until the marketplace +requires a key for downloads; it gets no further changes. See +[CHANGELOG.md](CHANGELOG.md). + ## What this action is not It does not create, modify or destroy any infrastructure, and it needs no cloud diff --git a/action.yml b/action.yml index 495eb9c..1c4f1e9 100644 --- a/action.yml +++ b/action.yml @@ -9,10 +9,13 @@ # The previous incarnation of this action was a Docker image with the # binary baked in, and it silently went two majors stale. # -# The CLI is downloaded from the Linro marketplace, which is also where a -# customer's own installs get it. That is deliberate: the marketplace only -# serves a version once it has been ingested and promoted, so this action can -# never run a build that no install could actually offer. +# The CLI is downloaded from your Linro install (`server`), with your PAT +# (`token`). The install fetches it from the Linro marketplace with its own +# key and checks it against the sha256 the marketplace states, so the +# marketplace only serves a version once it has been ingested and promoted, +# and this action can never run a build that no install could actually offer. +# That is also why `server` and `token` are required on every run, a dry run +# included: without them there is nowhere to download the CLI from. # # Every flag `linro-simulator simulate` accepts is a first-class input here. # `extra-args` exists for flags added to the CLI after an action release, not @@ -59,20 +62,20 @@ inputs: # ---- where to send it ---------------------------------------------------- server: description: >- - Your Linro install, e.g. https://acme.linro.app. Required unless - `dry-run` is true. - required: false - default: "" + Your Linro install, e.g. https://acme.linro.app. Required, a dry run + included: the CLI is downloaded from it. + required: true token: description: >- A Linro Personal Access Token with the SCOPE_SIMULATIONS scope. Pass it - from a secret — never inline. Required unless `dry-run` is true. - required: false - default: "" + from a secret — never inline. Required, a dry run included: it + authorizes the CLI download as well as the submission. + required: true ca-cert: description: >- Path to a PEM bundle to trust in addition to the system roots, for an - install behind an internal CA. + install behind an internal CA. The CLI download trusts this bundle only, + since it goes to the install alone. required: false default: "" insecure: @@ -165,8 +168,9 @@ inputs: default: "false" dry-run: description: >- - Assemble the payload and print it instead of submitting. Needs no server - and no token — useful for seeing exactly what a simulation would send. + Assemble the payload and print it instead of submitting — useful for + seeing exactly what a simulation would send. It still needs `server` and + `token`, to download the CLI. required: false default: "false" poll-timeout: @@ -215,7 +219,7 @@ inputs: version: description: >- linro-simulator version to run, e.g. v0.2.1, or `latest` to track the - newest version your marketplace serves. Pinning is recommended: `latest` + newest version the marketplace serves your install. Pinning is recommended: `latest` makes a green run stop being evidence about any particular version. The default is only ever raised to a version PRODUCTION serves. A default @@ -223,12 +227,6 @@ inputs: first run, which is the worst possible first impression. required: false default: "v0.2.1" - marketplace-url: - description: >- - Marketplace to download the CLI from. Override only if your Linro - deployment serves its own. - required: false - default: "https://marketplace.linro.io" outputs: version: @@ -244,22 +242,36 @@ runs: - name: Install linro-simulator id: install shell: bash + # The ca-cert path resolves from here, as it does for the CLI. + working-directory: ${{ inputs.working-directory }} env: INPUT_VERSION: ${{ inputs.version }} - INPUT_MARKETPLACE_URL: ${{ inputs.marketplace-url }} - # The ref this action runs at (e.g. v1), named to the marketplace - # in X-Linro-Client (ENG-1686); empty when run from a local path. + INPUT_SERVER: ${{ inputs.server }} + INPUT_CA_CERT: ${{ inputs.ca-cert }} + # Through env:, never argv: curl reads it from a config on stdin. + LINRO_SIMULATION_TOKEN: ${{ inputs.token }} + # The ref this action runs at (e.g. v2), sent in X-Linro-Client + # (ENG-1686); empty when run from a local path. ACTION_REF: ${{ github.action_ref }} run: | set -euo pipefail + # Every refusal goes through error(): an ::error:: annotation, and a + # line in $RUNNER_TEMP/linro-simulation-error, which this repository's + # CI reads to check that each refusal fails for its own reason. + error() { + echo "::error::$*" + printf '%s\n' "$*" >> "${RUNNER_TEMP}/linro-simulation-error" + } + rm -f "${RUNNER_TEMP}/linro-simulation-error" + # RUNNER_OS/RUNNER_ARCH are the only portable identity the runner # gives us; map them onto the marketplace's platform names. case "$RUNNER_OS" in Linux) os=linux ;; macOS) os=darwin ;; *) - echo "::error::linro-simulator has no ${RUNNER_OS} build. This action runs on Linux and macOS runners." + error "linro-simulator has no ${RUNNER_OS} build. This action runs on Linux and macOS runners." exit 1 ;; esac @@ -267,54 +279,170 @@ runs: X64) arch=amd64 ;; ARM64) arch=arm64 ;; *) - echo "::error::unsupported runner architecture ${RUNNER_ARCH} (expected X64 or ARM64)." + error "unsupported runner architecture ${RUNNER_ARCH} (expected X64 or ARM64)." + exit 1 + ;; + esac + + # Required on every run, a dry run included: the install serves the + # CLI, and the token authorizes the download. + if [ -z "$INPUT_SERVER" ]; then + error 'the server input is required: the CLI is downloaded from your Linro install (a dry run needs it too).' + exit 1 + fi + if [ -z "${LINRO_SIMULATION_TOKEN}" ]; then + error 'the token input is required: pass a Linro PAT with SCOPE_SIMULATIONS from a secret (a dry run needs it too, to download the CLI).' + exit 1 + fi + server="${INPUT_SERVER%/}" + # The token must not cross the network in clear, nor reach a host + # other than the install. The whole authority is checked, not a + # prefix: http://127.0.0.1:80@evil.example is a request to evil.example. + case "$server" in + https://*) scheme=https; rest="${server#https://}" ;; + http://*) scheme=http; rest="${server#http://}" ;; + *) + error "server must be an https:// URL (plain http only for a loopback install), got '${INPUT_SERVER}'." + exit 1 + ;; + esac + authority="${rest%%/*}" + if [[ "$server" == *[[:space:]\\?#]* ]]; then + error "server must be a plain base URL with no query, fragment, backslash or space, got '${INPUT_SERVER}'." + exit 1 + fi + if [[ "$authority" == *@* ]]; then + error "server must not carry user info (an @ before the host), got '${INPUT_SERVER}'." + exit 1 + fi + loopback_re='^(127\.0\.0\.1|localhost|\[::1\])(:[0-9]{1,5})?$' + host_re='^([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)*[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(:[0-9]{1,5})?$' + loopback=false + if [[ "$authority" =~ $loopback_re ]]; then loopback=true; fi + if [ "$scheme" = http ] && ! $loopback; then + error "server must be an https:// URL (plain http only for a loopback install), got '${INPUT_SERVER}'." + exit 1 + fi + if [ "$scheme" = https ] && ! $loopback && ! [[ "$authority" =~ $host_re ]]; then + error "server must name a host and an optional port, got '${INPUT_SERVER}'." + exit 1 + fi + # The token is a header value; a newline or quote would break the + # curl config it is passed through. + case "$LINRO_SIMULATION_TOKEN" in + *[[:space:]\"\\]*) + error 'the token contains whitespace or a quote; check the secret it comes from.' exit 1 ;; esac # The catalog stores a bare semver; the release tag people quote carries - # a leading v. Accept either. `latest` is an alias resolved server-side, - # and has no v to strip. + # a leading v. Accept either. `latest` is an alias the marketplace + # resolves, and has no v to strip. version="${INPUT_VERSION#v}" - url="${INPUT_MARKETPLACE_URL}/artifacts/simulators/linro-simulator/${version}/${os}-${arch}.tar.gz" + # The install accepts exactly this shape (a semver or an alias such as + # latest); anything else would only come back as a confusing 404. + version_re='^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$' + if ! [[ "$version" =~ $version_re ]]; then + error "the version input '${INPUT_VERSION}' is not a version: expected e.g. v0.2.1, 0.2.1 or latest." + exit 1 + fi + url="${server}/api/simulator/download/${version}/${os}-${arch}.tar.gz" dir="${RUNNER_TEMP}/linro-simulator" mkdir -p "$dir" + tarball="${dir}/linro-simulator.tar.gz" + headers="${dir}/headers.txt" + + # ${tls[@]+...}: an empty array is "unbound" to bash 3.2 (macOS) under set -u. + tls=() + if [ -n "$INPUT_CA_CERT" ]; then tls=(--cacert "$INPUT_CA_CERT"); fi - # Separate "cannot reach the marketplace" from "that version is not in - # it". They need opposite fixes, and reporting the first as the second - # sends people to chase a release that is already published. - set +e - http=$(curl -sSL --retry 3 --retry-connrefused --max-time 300 \ - -H "X-Linro-Client: simulation-github-action/${ACTION_REF:-dev}" \ - -o "${dir}/linro-simulator.tar.gz" -w '%{http_code}' "$url") - rc=$? - set -e + # A loopback install is never reached through a proxy: curl would + # otherwise send the plain-http request, token included, to one set in + # http_proxy or ALL_PROXY. https follows the runner's proxy settings. + proxy=() + if $loopback; then proxy=(--noproxy '*'); fi + + # One wall-clock deadline of 10 minutes for the whole download, + # retries included: each attempt gets whatever time is left. Retries + # are for transient failures only (refused or dropped connections, a + # timed-out attempt, 408/429/5xx), as curl's own --retry would. + # Separate "cannot reach the install" from "it refused": they need + # opposite fixes. The token goes in a curl config read from stdin, so + # it never appears in argv (`ps` on the runner). + deadline=$(( $(date +%s) + 600 )) + attempt=0 + while :; do + attempt=$((attempt + 1)) + left=$(( deadline - $(date +%s) )) + if [ "$left" -le 0 ]; then rc=28; break; fi + set +e + http=$(printf 'header = "Authorization: Bearer %s"\n' "$LINRO_SIMULATION_TOKEN" | + curl -sS --max-time "$left" -K - ${tls[@]+"${tls[@]}"} ${proxy[@]+"${proxy[@]}"} \ + -H "X-Linro-Client: simulation-github-action/${ACTION_REF:-dev}" \ + -D "$headers" -o "$tarball" -w '%{http_code}' "$url") + rc=$? + set -e + transient=false + case "$rc" in + 7|28|52|55|56) transient=true ;; + 0) case "$http" in 408|429|500|502|503|504) transient=true ;; esac ;; + esac + if ! $transient || [ "$attempt" -ge 4 ]; then break; fi + pause=$(( attempt * 2 )) + if [ $(( deadline - $(date +%s) )) -le "$pause" ]; then break; fi + sleep "$pause" + done if [ "$rc" -ne 0 ]; then - echo "::error::could not reach ${INPUT_MARKETPLACE_URL} (curl exit ${rc}). This is a network failure, not a missing version." + error "could not reach ${server} (curl exit ${rc}). This is a network or TLS failure, not a missing version." exit 1 fi case "$http" in 200) ;; - 410) - # A retraction is not a typo. Saying "check the version exists" - # here sends someone to confirm a version that does exist and was - # deliberately withdrawn — usually for a defect worth knowing about. - echo "::error::linro-simulator ${INPUT_VERSION} has been RETRACTED and is no longer served. Pin a different version." + 401) + error "${server} refused the token (HTTP 401): it is missing, expired or revoked. Mint a PAT with SCOPE_SIMULATIONS in Linro." + exit 1 + ;; + 403) + error "${server} refused the token (HTTP 403): it does not carry SCOPE_SIMULATIONS. Mint a PAT with that scope." + exit 1 + ;; + 404) + error "${server} has no linro-simulator ${INPUT_VERSION} for ${os}-${arch} (HTTP 404)." + echo "Check the version exists in the marketplace catalog and has not been retracted. An install too old to serve the simulator answers 404 too." exit 1 ;; *) - echo "::error::${INPUT_MARKETPLACE_URL} answered HTTP ${http} for linro-simulator ${INPUT_VERSION} (${os}-${arch})." - echo "Check the version exists in your marketplace catalog, and that the platform is one it publishes." + error "${server} answered HTTP ${http} for linro-simulator ${INPUT_VERSION} (${os}-${arch})." + echo "A 502 or 503 means the install could not reach the marketplace or check the token; retry, or ask your Linro administrator." exit 1 ;; esac + # A second check of the install's own: it already refuses a tarball + # that does not match the marketplace's sha256 by cutting the transfer + # short. This catches anything that changed the bytes after it. + want=$(tr -d '\r' < "$headers" | awk 'tolower($1) == "x-linro-sha256:" { v = tolower($2) } END { print v }') + if [ -z "$want" ]; then + error "${server} sent no X-Linro-Sha256 header, so the download cannot be verified." + exit 1 + fi + if command -v sha256sum >/dev/null 2>&1; then + have=$(sha256sum "$tarball" | cut -d' ' -f1) + else + have=$(shasum -a 256 "$tarball" | cut -d' ' -f1) + fi + if [ "$have" != "$want" ]; then + error "the downloaded CLI does not match the sha256 the install stated (${have} != ${want}). Not running it." + exit 1 + fi + # The release tarball wraps everything in one directory named after the # build (linro-simulator-vX.Y.Z-os-arch/), carrying the binary, its # LICENCE and its third-party notices. - tar -xzf "${dir}/linro-simulator.tar.gz" -C "$dir" --strip-components=1 + tar -xzf "$tarball" -C "$dir" --strip-components=1 chmod +x "${dir}/linro-simulator" echo "$dir" >> "$GITHUB_PATH" @@ -357,6 +485,14 @@ runs: run: | set -euo pipefail + # Every refusal goes through error(): an ::error:: annotation, and a + # line in $RUNNER_TEMP/linro-simulation-error, which this repository's + # CI reads to check that each refusal fails for its own reason. + error() { + echo "::error::$*" + printf '%s\n' "$*" >> "${RUNNER_TEMP}/linro-simulation-error" + } + args=() # Actions inputs are ALWAYS strings, so a boolean is whatever the caller @@ -370,7 +506,7 @@ runs: false|False|FALSE) return 1 ;; "") return 1 ;; *) - echo "::error::the ${1} input must be true or false, got '${2}'" + error "the ${1} input must be true or false, got '${2}'" exit 1 ;; esac @@ -398,7 +534,7 @@ runs: # Single-quoted: inside a double-quoted string a backtick starts # command substitution, so "set `plan`" would try to RUN plan. if [ ${#args[@]} -eq 0 ]; then - echo '::error::nothing to simulate — set the plan input, the preview input, or both.' + error 'nothing to simulate — set the plan input, the preview input, or both.' exit 1 fi @@ -410,15 +546,14 @@ runs: if want dry-run "$INPUT_DRY_RUN"; then args+=(--dry-run) else - # Only enforced for a real submission: a dry run needs neither, and - # demanding them would make the cheapest way to try this action the - # one that asks for a token first. + # The install step already refused a run without either; kept so + # this step stands on its own. if [ -z "$INPUT_SERVER" ]; then - echo '::error::the server input is required (or set dry-run: true).' + error 'the server input is required.' exit 1 fi if [ -z "${LINRO_SIMULATION_TOKEN}" ]; then - echo '::error::the token input is required (or set dry-run: true). Pass a Linro PAT with SCOPE_SIMULATIONS from a secret.' + error 'the token input is required. Pass a Linro PAT with SCOPE_SIMULATIONS from a secret.' exit 1 fi args+=(--server "$INPUT_SERVER" --integration "$INPUT_INTEGRATION") diff --git a/docs/product/how-to/add-the-github-action.agent.md b/docs/product/how-to/add-the-github-action.agent.md index 9f656e1..4f8bea7 100644 --- a/docs/product/how-to/add-the-github-action.agent.md +++ b/docs/product/how-to/add-the-github-action.agent.md @@ -2,7 +2,7 @@ Preconditions reviewed pinned Action ref and compatible published CLI version, existing workflow-produced plan/preview, active SIMULATIONS/API PAT in secret, correct server/scope and configured real GitHub check path. {{page:service/concepts/simulations}} provides result interpretation. -Inputs plan/preview are newline-separated repeatable paths, combine into one payload/verdict. opentofu labels plans; native selects native preview dialect. version is CLI independently of Action ref, current old defaultv0.2.1 must not be assumed capable of new bindings. Current binary floor/installed plugin compatibility must be checked. Linux/macOS AMD64/ARM64 supported; no Windows build. marketplace-url controls artifact source, pin reviewed availability. +Inputs plan/preview are newline-separated repeatable paths, combine into one payload/verdict. opentofu labels plans; native selects native preview dialect. version is CLI independently of Action ref, current old defaultv0.2.1 must not be assumed capable of new bindings. Current binary floor/installed plugin compatibility must be checked. Linux/macOS AMD64/ARM64 supported; no Windows build. Action v2 downloads the CLI from server with token (Bearer, SCOPE_SIMULATIONS or SCOPE_API), verified against X-Linro-Sha256; server and token are required even for dry-run; marketplace-url was removed in v2 (v1 downloads anonymously from the marketplace until /artifacts requires a key). The install must serve /api/simulator/download. Default integration github-ci, strictfalse, labellinro-simulate. PR job contents:read,id-token:write when gateway audience discovery requires minting. CLI asks GetSimulatorMeta for actual audience; empty means direct App path, nonempty minted OIDC. Never copy staging audience to prod or override casually. Throwaway local credentials only support cli-mode smoke, not real PR checks. Explicit integration cli polls but CLI COMPLETED can still return0 with violations: neither mode's step exit proves compliant. Require BOTH submitting Actions job and separate configured simulation check: strict local-skip failure occurs after supported subset upload, so green subset check can coexist with failed job. Inspect Result/coverage; build an explicit result-aware policy gate if using cli mode. diff --git a/docs/product/how-to/add-the-github-action.md b/docs/product/how-to/add-the-github-action.md index 5ed81ab..ceb095c 100644 --- a/docs/product/how-to/add-the-github-action.md +++ b/docs/product/how-to/add-the-github-action.md @@ -14,7 +14,7 @@ Run a reviewed Terraform plan or Pulumi preview through Linro from a pull reques ## Prepare the workflow -Have the repository owner choose a reviewed Action revision and compatible published simulator version. Configure the Linro server variable and a simulation-scoped token in repository secrets. Do not paste a token into the workflow. +Have the repository owner choose a reviewed Action revision and compatible published simulator version. Configure the Linro server variable and a simulation-scoped token in repository secrets. Do not paste a token into the workflow. From Action v2 the CLI is downloaded from your Linro server with that token, so both are required on every run, dry runs included. ```yaml name: Linro simulation diff --git a/testdata/expect-refusal.sh b/testdata/expect-refusal.sh new file mode 100755 index 0000000..0b19f02 --- /dev/null +++ b/testdata/expect-refusal.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +# expect-refusal.sh +# +# A refusal must fail the step AND for its own reason: the action records +# each ::error:: in $RUNNER_TEMP/linro-simulation-error, so a stub 502 cannot +# stand in for the sha256 check. The file is removed so the next case starts +# clean. +set -euo pipefail +name=$1 outcome=$2 want=$3 +file="${RUNNER_TEMP}/linro-simulation-error" +got=$(cat "$file" 2>/dev/null || true) +rm -f "$file" +if [ "$outcome" != "failure" ]; then + echo "::error::${name} should have failed the step, got '${outcome}'" + exit 1 +fi +if ! printf '%s' "$got" | grep -qF -- "$want"; then + echo "::error::${name} failed for another reason. Want '${want}', got: ${got:-}" + exit 1 +fi +echo "ok: ${name} → ${got}" diff --git a/testdata/start-stub.sh b/testdata/start-stub.sh new file mode 100755 index 0000000..341ebee --- /dev/null +++ b/testdata/start-stub.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Start testdata/stub-install.py in the background and print its URL. +# start-stub.sh (token: ci-token; log: $RUNNER_TEMP/.log) +set -euo pipefail +name=$1 mode=$2 +port_file="${RUNNER_TEMP}/${name}.port" +rm -f "$port_file" +STUB_TOKEN=ci-token STUB_MODE="$mode" nohup python3 "$(dirname "$0")/stub-install.py" \ + "$port_file" "${RUNNER_TEMP}/${name}.log" > "${RUNNER_TEMP}/${name}.out" 2>&1 & +for _ in $(seq 100); do + if [ -s "$port_file" ]; then + echo "http://127.0.0.1:$(cat "$port_file")" + exit 0 + fi + sleep 0.1 +done +cat "${RUNNER_TEMP}/${name}.out" >&2 +echo "the stub did not start" >&2 +exit 1 diff --git a/testdata/stub-install.py b/testdata/stub-install.py new file mode 100755 index 0000000..afcffb9 --- /dev/null +++ b/testdata/stub-install.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python3 +"""A stand-in for a Linro install's simulator download, for CI. + +It serves GET /api/simulator/download/{version}/{os}-{arch}.tar.gz the way an +install does (Authorization: Bearer , X-Linro-Sha256), so the action's +download is tested with no install and no secret. The tarball itself comes +from the public marketplace, anonymously; once the marketplace requires a key +for /artifacts this needs one too. + + stub-install.py + +Environment: STUB_TOKEN (the token to accept), STUB_MODE (ok | bad-sha | +no-sha), STUB_SOURCE (marketplace base URL). +""" +import hashlib +import http.server +import os +import re +import sys +import urllib.error +import urllib.request + +TOKEN = os.environ["STUB_TOKEN"] +MODE = os.environ.get("STUB_MODE", "ok") +SOURCE = os.environ.get("STUB_SOURCE", "https://marketplace.linro.io").rstrip("/") +PATH = re.compile(r"^/api/simulator/download/([A-Za-z0-9][A-Za-z0-9._+-]{0,63})/([a-z0-9]+-[a-z0-9]+)\.tar\.gz$") +port_file, log_file = sys.argv[1], sys.argv[2] + + +class Handler(http.server.BaseHTTPRequestHandler): + def do_GET(self): + auth = self.headers.get("Authorization", "") + with open(log_file, "a") as log: + log.write(f"{self.path} auth={'ok' if auth == 'Bearer ' + TOKEN else 'bad'}\n") + m = PATH.match(self.path) + if not m: + return self.send_error(404) + if auth != "Bearer " + TOKEN: + return self.send_error(401) + version, platform = m.groups() + req = urllib.request.Request( + f"{SOURCE}/artifacts/simulators/linro-simulator/{version}/{platform}.tar.gz", + # A User-Agent of its own: the default Python-urllib one is refused. + headers={"X-Linro-Client": "simulation-github-action/ci-stub", "User-Agent": "linro-ci-stub/1"}, + ) + try: + body = urllib.request.urlopen(req, timeout=120).read() + except urllib.error.HTTPError as e: + return self.send_error(404 if e.code in (404, 410) else 502) + except OSError: + return self.send_error(502) + sha = hashlib.sha256(body).hexdigest() + self.send_response(200) + self.send_header("Content-Type", "application/gzip") + self.send_header("Content-Length", str(len(body))) + if MODE == "bad-sha": + self.send_header("X-Linro-Sha256", "0" * 64) + elif MODE != "no-sha": + self.send_header("X-Linro-Sha256", sha) + self.end_headers() + self.wfile.write(body) + + def log_message(self, *args): + pass + + +server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler) +with open(port_file, "w") as f: + f.write(str(server.server_address[1])) +server.serve_forever()