tfscout 0.1.0__tar.gz

tfscout-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e '.[dev]'
+      - run: ruff check . && ruff format --check .
+      - run: pytest -q
+
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - id: review
+        uses: ./
+        with:
+          mode: review
+          plan: tests/fixtures/plan_review.json
+          provider: none
+          comment: "false"
+      - id: drift
+        uses: ./
+        with:
+          mode: drift
+          plan: tests/fixtures/plan_drift.json
+          provider: none
+          comment: "false"
+      - name: Check outputs
+        run: |
+          test "${{ steps.review.outputs.max-severity }}" = critical
+          test "${{ steps.drift.outputs.drift-detected }}" = true
+          test -s "${{ steps.review.outputs.report-file }}"

tfscout-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+# Runs when a GitHub release is published. Uses PyPI trusted publishing (OIDC), so no API token is stored.
+# One-time setup on https://pypi.org/manage/account/publishing/ ("Add a new pending publisher"):
+#   PyPI project name: tfscout · Owner: mikonoid · Repository: tfscout
+#   Workflow: publish.yml · Environment: pypi
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Check that the tag matches the package version
+        run: |
+          version=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('src/tfscout/__init__.py').read())[1])")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "::error::release tag v$tag does not match __version__ $version"
+            exit 1
+          fi
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.3

tfscout-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.terraform/
+*.tfplan
+*.tfstate*

tfscout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mikonoid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tfscout-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: tfscout
+Version: 0.1.0
+Summary: AI-assisted Terraform plan review and drift detection
+Project-URL: Homepage, https://github.com/mikonoid/tfscout
+Project-URL: Issues, https://github.com/mikonoid/tfscout/issues
+Author: mikonoid
+License-Expression: MIT
+License-File: LICENSE
+Keywords: devsecops,drift,github-action,iac,llm,opentofu,terraform
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tfscout
+
+**AI-assisted plan review and drift detection for Terraform / OpenTofu.**
+Runs entirely in your CI: no SaaS, no server, and your plans never leave the runner unredacted.
+**tfscout never touches your cloud.** It only reads the plan file your pipeline already produces.
+
+🧪 **[Live demo](https://github.com/mikonoid/tfscout-demo)**: see real PR comments and drift issues, no AWS account needed.
+
+📘 **[Setup guide](https://github.com/mikonoid/tfscout/blob/main/docs/setup.md)**: what you need, AWS OIDC in 10 minutes, Jenkins/GitLab, troubleshooting.
+
+- 🔎 **`review`** reads `terraform plan` in a pull request and posts a single, auto-updated comment with what
+  changes, and what can break: data loss, open security groups, IAM wildcards, disabled encryption, forced
+  replacements, plus anything the AI notices.
+- 🧭 **`drift`** reads `terraform plan -refresh-only` on a schedule, classifies every drifted resource as
+  `noise`, `manual-change` or `risky`, explains it and suggests how to codify or revert it. Results go to one
+  GitHub issue per root module, which is updated when drift changes and closed when it is resolved.
+
+```
+plan ──► redact secrets ──► deterministic rules ──► LLM (optional) ──► PR comment / issue / JSON
+```
+
+Deterministic rules are the baseline you can trust. The LLM adds a plain-English summary and extra findings,
+and can escalate but **never downgrade** a risky item. With `provider: none` tfscout works without any AI.
+
+## Example PR comment
+
+> ### 🔎 tfscout plan review — `prod`
+> ➕ create **2** · ✏️ update **2** · ♻️ replace **1**
+>
+> - Recreates `orders-db` in another AZ
+> - Grants CI full admin
+>
+> | | Severity | Resource | Finding |
+> |---|---|---|---|
+> | 🔴 | critical | `aws_db_instance.main` | Stateful resource will be REPLACED |
+> | 🔴 | critical | `aws_iam_policy.ci` | IAM policy allows Action "*" |
+> | 🔴 | critical | `aws_security_group.web` | Ingress opened to the internet (22/tcp) |
+> | 🟠 | high | `aws_db_instance.main` | Encryption disabled (`storage_encrypted`) |
+> | 🟠 | high | `aws_db_instance.main` | AZ move forces DB recreation 🤖 |
+
+## Quick start (GitHub Action)
+
+Already running `terraform plan` in GitHub Actions? Add one step. No new cloud credentials are needed.
+Otherwise see the [setup guide](https://github.com/mikonoid/tfscout/blob/main/docs/setup.md).
+
+### Pull request review
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write   # for cloud OIDC
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: hashicorp/setup-terraform@v4
+    with: { terraform_wrapper: false }
+  # ... configure cloud credentials ...
+  - run: terraform init -input=false && terraform plan -input=false -lock=false -out=tfplan
+    working-directory: envs/prod
+  - uses: mikonoid/tfscout@v0
+    with:
+      mode: review
+      working-directory: envs/prod
+      plan: tfplan
+      provider: gemini
+      api-key: ${{ secrets.GEMINI_API_KEY }}
+      fail-on: critical   # optional merge gate
+```
+
+### Scheduled drift detection
+
+```yaml
+on:
+  schedule: [{ cron: "0 6 * * 1-5" }]
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+steps:
+  # ... checkout, setup-terraform, credentials, init ...
+  - run: terraform plan -refresh-only -input=false -lock=false -out=drift.tfplan
+    working-directory: envs/prod
+  - uses: mikonoid/tfscout@v0
+    with:
+      mode: drift
+      working-directory: envs/prod
+      plan: drift.tfplan
+      provider: gemini
+      api-key: ${{ secrets.GEMINI_API_KEY }}
+```
+
+Full workflows with a matrix over several directories: [examples/review.yml](https://github.com/mikonoid/tfscout/blob/main/examples/review.yml),
+[examples/drift.yml](https://github.com/mikonoid/tfscout/blob/main/examples/drift.yml).
+One-time AWS OIDC role for CI without stored keys: [examples/aws-oidc](https://github.com/mikonoid/tfscout/blob/main/examples/aws-oidc/main.tf).
+
+### Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `mode` | — | `review` or `drift` |
+| `plan` | — | Binary plan (`-out`) or `terraform show -json` output, relative to `working-directory` |
+| `working-directory` | `.` | Root module directory |
+| `name` | working-directory | Label used in titles; keeps comments/issues per module separate |
+| `provider` | `none` | `none`, `gemini`, `groq`, `openrouter`, `openai`, `ollama`, `custom` |
+| `model` / `base-url` | preset | Override model (comma-separated = fallback chain on 503/429/timeout/404) / endpoint |
+| `timeout` | `90` | Seconds to wait for the LLM per attempt |
+| `reasoning-effort` | preset | `minimal`/`low`/`medium`/`high` for thinking models (gemini: `low`) |
+| `api-key` | — | LLM API key (use a secret) |
+| `comment` | `true` | Post PR comment (review) or sync the drift issue (drift) |
+| `fail-on` | `none` | review: fail when a finding is at least this severity |
+| `fail-on-drift` | `false` | drift: fail when actionable drift exists |
+| `terraform-bin` | `terraform` | Use `tofu` for OpenTofu |
+
+Outputs: `max-severity`, `findings-count`, `drift-detected`, `fingerprint`, `report-file`.
+The report is also added to the job summary.
+
+## LLM providers
+
+tfscout speaks the OpenAI-compatible `/chat/completions` API, so you can use any of these:
+
+| Provider | Cost | Key |
+|---|---|---|
+| `gemini` (fallback chain `gemini-flash-lite-latest` → `gemini-3.5-flash` → `gemini-flash-latest`) | free tier | [AI Studio](https://aistudio.google.com/apikey) → `GEMINI_API_KEY` |
+| `groq` | free tier | `GROQ_API_KEY` |
+| `openrouter` | free models available | `OPENROUTER_API_KEY` |
+| `openai` | paid | `OPENAI_API_KEY` |
+| `ollama` | free, local/self-hosted runner | none |
+| `custom` | — | any OpenAI-compatible endpoint (Azure AI Foundry, vLLM, LM Studio…) |
+
+## Security & privacy
+
+- `terraform show -json` prints sensitive values **in clear text**. Before anything is sent to an LLM, tfscout
+  applies Terraform's own `*_sensitive` masks and also redacts values by key name (`password`, `token`,
+  `private_key`…) and by pattern (AWS keys, PEM keys, GitHub/Slack/OpenAI tokens, JWTs, DB URLs with
+  credentials).
+- Only redacted attribute diffs are sent, never the full state.
+- `provider: none` sends nothing anywhere.
+- Use read-only cloud credentials for planning. tfscout never runs `apply`.
+
+## CLI
+
+```bash
+pip install git+https://github.com/mikonoid/tfscout   # PyPI package coming soon
+
+terraform plan -out=tfplan
+tfscout review tfplan                                  # rules only
+GEMINI_API_KEY=... tfscout review tfplan --provider gemini
+tfscout review plan.json --format json --fail-on high  # exit 3 on high/critical
+
+terraform plan -refresh-only -out=drift.tfplan
+tfscout drift drift.tfplan --provider ollama --exit-code   # exit 2 on actionable drift
+```
+
+Works with GitLab CI, Jenkins and locally too. Requires Python ≥ 3.10 and has no third-party dependencies.
+
+## Roadmap
+
+- [ ] CloudTrail attribution for drift ("who changed it and when")
+- [ ] Cost delta via Infracost
+- [ ] Auto-generated PR that codifies a manual change
+- [ ] Custom org rules (`.tfscout.yml`: required tags, allowed regions, naming)
+- [ ] GCP/Azure rule coverage
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q && .venv/bin/ruff check . && .venv/bin/ruff format --check .
+```
+
+## License
+
+MIT

tfscout-0.1.0/README.md

@@ -0,0 +1,175 @@
+# tfscout
+
+**AI-assisted plan review and drift detection for Terraform / OpenTofu.**
+Runs entirely in your CI: no SaaS, no server, and your plans never leave the runner unredacted.
+**tfscout never touches your cloud.** It only reads the plan file your pipeline already produces.
+
+🧪 **[Live demo](https://github.com/mikonoid/tfscout-demo)**: see real PR comments and drift issues, no AWS account needed.
+
+📘 **[Setup guide](https://github.com/mikonoid/tfscout/blob/main/docs/setup.md)**: what you need, AWS OIDC in 10 minutes, Jenkins/GitLab, troubleshooting.
+
+- 🔎 **`review`** reads `terraform plan` in a pull request and posts a single, auto-updated comment with what
+  changes, and what can break: data loss, open security groups, IAM wildcards, disabled encryption, forced
+  replacements, plus anything the AI notices.
+- 🧭 **`drift`** reads `terraform plan -refresh-only` on a schedule, classifies every drifted resource as
+  `noise`, `manual-change` or `risky`, explains it and suggests how to codify or revert it. Results go to one
+  GitHub issue per root module, which is updated when drift changes and closed when it is resolved.
+
+```
+plan ──► redact secrets ──► deterministic rules ──► LLM (optional) ──► PR comment / issue / JSON
+```
+
+Deterministic rules are the baseline you can trust. The LLM adds a plain-English summary and extra findings,
+and can escalate but **never downgrade** a risky item. With `provider: none` tfscout works without any AI.
+
+## Example PR comment
+
+> ### 🔎 tfscout plan review — `prod`
+> ➕ create **2** · ✏️ update **2** · ♻️ replace **1**
+>
+> - Recreates `orders-db` in another AZ
+> - Grants CI full admin
+>
+> | | Severity | Resource | Finding |
+> |---|---|---|---|
+> | 🔴 | critical | `aws_db_instance.main` | Stateful resource will be REPLACED |
+> | 🔴 | critical | `aws_iam_policy.ci` | IAM policy allows Action "*" |
+> | 🔴 | critical | `aws_security_group.web` | Ingress opened to the internet (22/tcp) |
+> | 🟠 | high | `aws_db_instance.main` | Encryption disabled (`storage_encrypted`) |
+> | 🟠 | high | `aws_db_instance.main` | AZ move forces DB recreation 🤖 |
+
+## Quick start (GitHub Action)
+
+Already running `terraform plan` in GitHub Actions? Add one step. No new cloud credentials are needed.
+Otherwise see the [setup guide](https://github.com/mikonoid/tfscout/blob/main/docs/setup.md).
+
+### Pull request review
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write   # for cloud OIDC
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: hashicorp/setup-terraform@v4
+    with: { terraform_wrapper: false }
+  # ... configure cloud credentials ...
+  - run: terraform init -input=false && terraform plan -input=false -lock=false -out=tfplan
+    working-directory: envs/prod
+  - uses: mikonoid/tfscout@v0
+    with:
+      mode: review
+      working-directory: envs/prod
+      plan: tfplan
+      provider: gemini
+      api-key: ${{ secrets.GEMINI_API_KEY }}
+      fail-on: critical   # optional merge gate
+```
+
+### Scheduled drift detection
+
+```yaml
+on:
+  schedule: [{ cron: "0 6 * * 1-5" }]
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+steps:
+  # ... checkout, setup-terraform, credentials, init ...
+  - run: terraform plan -refresh-only -input=false -lock=false -out=drift.tfplan
+    working-directory: envs/prod
+  - uses: mikonoid/tfscout@v0
+    with:
+      mode: drift
+      working-directory: envs/prod
+      plan: drift.tfplan
+      provider: gemini
+      api-key: ${{ secrets.GEMINI_API_KEY }}
+```
+
+Full workflows with a matrix over several directories: [examples/review.yml](https://github.com/mikonoid/tfscout/blob/main/examples/review.yml),
+[examples/drift.yml](https://github.com/mikonoid/tfscout/blob/main/examples/drift.yml).
+One-time AWS OIDC role for CI without stored keys: [examples/aws-oidc](https://github.com/mikonoid/tfscout/blob/main/examples/aws-oidc/main.tf).
+
+### Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `mode` | — | `review` or `drift` |
+| `plan` | — | Binary plan (`-out`) or `terraform show -json` output, relative to `working-directory` |
+| `working-directory` | `.` | Root module directory |
+| `name` | working-directory | Label used in titles; keeps comments/issues per module separate |
+| `provider` | `none` | `none`, `gemini`, `groq`, `openrouter`, `openai`, `ollama`, `custom` |
+| `model` / `base-url` | preset | Override model (comma-separated = fallback chain on 503/429/timeout/404) / endpoint |
+| `timeout` | `90` | Seconds to wait for the LLM per attempt |
+| `reasoning-effort` | preset | `minimal`/`low`/`medium`/`high` for thinking models (gemini: `low`) |
+| `api-key` | — | LLM API key (use a secret) |
+| `comment` | `true` | Post PR comment (review) or sync the drift issue (drift) |
+| `fail-on` | `none` | review: fail when a finding is at least this severity |
+| `fail-on-drift` | `false` | drift: fail when actionable drift exists |
+| `terraform-bin` | `terraform` | Use `tofu` for OpenTofu |
+
+Outputs: `max-severity`, `findings-count`, `drift-detected`, `fingerprint`, `report-file`.
+The report is also added to the job summary.
+
+## LLM providers
+
+tfscout speaks the OpenAI-compatible `/chat/completions` API, so you can use any of these:
+
+| Provider | Cost | Key |
+|---|---|---|
+| `gemini` (fallback chain `gemini-flash-lite-latest` → `gemini-3.5-flash` → `gemini-flash-latest`) | free tier | [AI Studio](https://aistudio.google.com/apikey) → `GEMINI_API_KEY` |
+| `groq` | free tier | `GROQ_API_KEY` |
+| `openrouter` | free models available | `OPENROUTER_API_KEY` |
+| `openai` | paid | `OPENAI_API_KEY` |
+| `ollama` | free, local/self-hosted runner | none |
+| `custom` | — | any OpenAI-compatible endpoint (Azure AI Foundry, vLLM, LM Studio…) |
+
+## Security & privacy
+
+- `terraform show -json` prints sensitive values **in clear text**. Before anything is sent to an LLM, tfscout
+  applies Terraform's own `*_sensitive` masks and also redacts values by key name (`password`, `token`,
+  `private_key`…) and by pattern (AWS keys, PEM keys, GitHub/Slack/OpenAI tokens, JWTs, DB URLs with
+  credentials).
+- Only redacted attribute diffs are sent, never the full state.
+- `provider: none` sends nothing anywhere.
+- Use read-only cloud credentials for planning. tfscout never runs `apply`.
+
+## CLI
+
+```bash
+pip install git+https://github.com/mikonoid/tfscout   # PyPI package coming soon
+
+terraform plan -out=tfplan
+tfscout review tfplan                                  # rules only
+GEMINI_API_KEY=... tfscout review tfplan --provider gemini
+tfscout review plan.json --format json --fail-on high  # exit 3 on high/critical
+
+terraform plan -refresh-only -out=drift.tfplan
+tfscout drift drift.tfplan --provider ollama --exit-code   # exit 2 on actionable drift
+```
+
+Works with GitLab CI, Jenkins and locally too. Requires Python ≥ 3.10 and has no third-party dependencies.
+
+## Roadmap
+
+- [ ] CloudTrail attribution for drift ("who changed it and when")
+- [ ] Cost delta via Infracost
+- [ ] Auto-generated PR that codifies a manual change
+- [ ] Custom org rules (`.tfscout.yml`: required tags, allowed regions, naming)
+- [ ] GCP/Azure rule coverage
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q && .venv/bin/ruff check . && .venv/bin/ruff format --check .
+```
+
+## License
+
+MIT

tfscout-0.1.0/action.yml

@@ -0,0 +1,115 @@
+name: tfscout
+description: AI-assisted Terraform/OpenTofu plan review and drift detection. Explains risks in PR comments and drift in issues.
+author: mikonoid
+branding:
+  icon: search
+  color: purple
+
+inputs:
+  mode:
+    description: "`review` (comment on a PR with plan risks) or `drift` (analyse a `plan -refresh-only` and sync an issue)"
+    required: true
+  plan:
+    description: Path to the plan file (binary `-out` file or `terraform show -json` output), relative to working-directory
+    required: true
+  working-directory:
+    description: Terraform root module directory (needed to read binary plans)
+    default: "."
+  name:
+    description: Label for this root module, used in comment/issue titles and to keep them separate (defaults to working-directory)
+    default: ""
+  provider:
+    description: "LLM provider: none (rules only), gemini (free tier), groq, openrouter, openai, ollama, custom"
+    default: none
+  model:
+    description: Override the model name
+    default: ""
+  base-url:
+    description: Override the OpenAI-compatible endpoint (required for provider `custom`)
+    default: ""
+  api-key:
+    description: API key for the LLM provider (pass it from a secret)
+    default: ""
+  timeout:
+    description: Seconds to wait for the LLM per attempt
+    default: "90"
+  reasoning-effort:
+    description: "reasoning_effort for thinking models: minimal|low|medium|high (gemini default: low)"
+    default: ""
+  github-token:
+    description: Token used for PR comments and drift issues
+    default: ${{ github.token }}
+  comment:
+    description: "review: create/update a PR comment. drift: create/update/close a drift issue"
+    default: "true"
+  fail-on:
+    description: "review: fail the step when a finding has at least this severity (none|info|low|medium|high|critical)"
+    default: none
+  fail-on-drift:
+    description: "drift: fail the step when actionable drift is found"
+    default: "false"
+  terraform-bin:
+    description: terraform or tofu binary used to read binary plans
+    default: terraform
+
+outputs:
+  max-severity:
+    description: "review: highest finding severity (or `none`)"
+    value: ${{ steps.run.outputs.max-severity }}
+  findings-count:
+    description: Number of findings (review) or actionable drift items (drift)
+    value: ${{ steps.run.outputs.findings-count }}
+  drift-detected:
+    description: "drift: `true` when actionable drift was found"
+    value: ${{ steps.run.outputs.drift-detected }}
+  fingerprint:
+    description: "drift: stable id of the current drift"
+    value: ${{ steps.run.outputs.fingerprint }}
+  report-file:
+    description: Path to the rendered Markdown report
+    value: ${{ steps.run.outputs.report-file }}
+
+runs:
+  using: composite
+  steps:
+    - id: run
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        PYTHONPATH: ${{ github.action_path }}/src
+        IN_MODE: ${{ inputs.mode }}
+        IN_PLAN: ${{ inputs.plan }}
+        IN_NAME: ${{ inputs.name || inputs.working-directory }}
+        IN_PROVIDER: ${{ inputs.provider }}
+        IN_MODEL: ${{ inputs.model }}
+        IN_BASE_URL: ${{ inputs.base-url }}
+        IN_COMMENT: ${{ inputs.comment }}
+        IN_FAIL_ON: ${{ inputs.fail-on }}
+        IN_FAIL_ON_DRIFT: ${{ inputs.fail-on-drift }}
+        IN_TF_BIN: ${{ inputs.terraform-bin }}
+        TFSCOUT_API_KEY: ${{ inputs.api-key }}
+        TFSCOUT_TIMEOUT: ${{ inputs.timeout }}
+        TFSCOUT_REASONING_EFFORT: ${{ inputs.reasoning-effort }}
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+      run: |
+        set -euo pipefail
+        if ! python3 -c 'import sys; sys.exit(sys.version_info < (3, 10))' 2>/dev/null; then
+          echo "::error::tfscout needs python3 >= 3.10 on the runner (add actions/setup-python)"
+          exit 1
+        fi
+        case "$IN_MODE" in review|drift) ;; *) echo "::error::mode must be 'review' or 'drift'"; exit 1 ;; esac
+
+        report="$RUNNER_TEMP/tfscout-${IN_MODE}-$(printf '%s' "$IN_NAME" | tr -c 'A-Za-z0-9._-' '_').md"
+        args=("$IN_MODE" "$IN_PLAN" --name "$IN_NAME" --provider "$IN_PROVIDER" --terraform-bin "$IN_TF_BIN" --output "$report")
+        [[ -n "$IN_MODEL" ]] && args+=(--model "$IN_MODEL")
+        [[ -n "$IN_BASE_URL" ]] && args+=(--base-url "$IN_BASE_URL")
+        if [[ "$IN_MODE" == review ]]; then
+          [[ "$IN_COMMENT" == true ]] && args+=(--github-comment)
+          args+=(--fail-on "$IN_FAIL_ON")
+        else
+          [[ "$IN_COMMENT" == true ]] && args+=(--github-issue)
+          [[ "$IN_FAIL_ON_DRIFT" == true ]] && args+=(--exit-code)
+        fi
+
+        echo "report-file=$report" >> "$GITHUB_OUTPUT"
+        python3 -m tfscout "${args[@]}"