From a41a45175dbf56015ba825a88e5bad44174edb92 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 3 Jul 2026 16:37:51 +0000 Subject: [PATCH 1/2] docs: group Terraform drift tutorials under a subsection --- config/navigation.json | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/config/navigation.json b/config/navigation.json index 1bcf9e9..86bd7e7 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -113,8 +113,13 @@ { "group": "Security", "pages": [ - "tutorials/detecting_unexpected_statefile_changes", - "tutorials/detecting_non_terraform_changes", + { + "group": "Detecting Terraform drift", + "pages": [ + "tutorials/detecting_unexpected_statefile_changes", + "tutorials/detecting_non_terraform_changes" + ] + }, "tutorials/rotating_api_keys" ] }, From 166fc1cf9c21f0e7b498706e84032620c7616889 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 3 Jul 2026 16:42:27 +0000 Subject: [PATCH 2/2] docs: remove superseded unauthorized_iac_changes tutorial --- tutorials/unauthorized_iac_changes.md | 158 -------------------------- 1 file changed, 158 deletions(-) delete mode 100644 tutorials/unauthorized_iac_changes.md diff --git a/tutorials/unauthorized_iac_changes.md b/tutorials/unauthorized_iac_changes.md deleted file mode 100644 index 691f5d8..0000000 --- a/tutorials/unauthorized_iac_changes.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Detecting unauthorized Terraform changes" -description: "Learn how to use Kosli to detect unauthorized Terraform infrastructure changes — changes made outside your approved CI process." ---- - -By the end of this tutorial, you will have set up Kosli to track authorized Terraform changes and detect when an unauthorized change slips through. - - -This tutorial focuses on detecting changes made by bypassing the approved Terraform process (e.g. a developer running `terraform apply` directly from their machine). Detecting infrastructure drift is a separate concern covered by [Terraform drift detection](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift). - - -## Prerequisites - -* [Install Terraform](https://developer.hashicorp.com/terraform/install). -* [Install Snyk CLI](https://docs.snyk.io/snyk-cli/getting-started-with-the-snyk-cli#install-the-snyk-cli-and-authenticate-your-machine) (optional — needed for the security scan step). -* [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/authenticating_to_kosli). - -## Setup - -```shell -export KOSLI_ORG= -export KOSLI_API_TOKEN= -``` - -Clone the tutorial repository: - -```shell -git clone https://github.com/kosli-dev/iac-changes-tutorial.git -cd iac-changes-tutorial -``` - -## Create a Kosli flow - -Create a Kosli flow to represent the approved process for Terraform changes. Using --use-empty-template keeps things simple for this tutorial: - -```shell -kosli create flow tf-tutorial --use-empty-template -``` - -## Make and track an authorized change - - -In production, an authorized change goes through CI. In this tutorial, you run those commands locally to simulate the process. - - -Begin a trail to represent a single authorized change: - -```shell -kosli begin trail authorized-1 --flow=tf-tutorial -``` - -Optionally, scan your Terraform config for security issues and attest the SARIF output to Kosli: - -```shell -snyk iac test main.tf --sarif-file-output=sarif.json -kosli attest snyk --name=security --flow=tf-tutorial --trail=authorized-1 --scan-results=sarif.json -``` - -Create a Terraform plan, save it to a file, and attest it to Kosli: - -```shell -terraform init -terraform plan -out=tf.plan -kosli attest generic --name=tf-plan --flow=tf-tutorial --trail=authorized-1 --attachments=tf.plan -``` - -Apply the plan and attest the resulting state file as an artifact. Kosli calculates a fingerprint from the state file contents — this fingerprint is how it later detects unauthorized changes: - - -This tutorial uses a local state file for simplicity. In production, the state file is typically stored in cloud storage (e.g. AWS S3) and you would download it after the authorized change. Note that `--build-url` and `--commit-url` are set to placeholder URLs here — in CI these are set automatically. - - -```shell -terraform apply -auto-approve tf.plan -kosli attest artifact terraform.tfstate --name=state-file --artifact-type=file --flow=tf-tutorial --trail=authorized-1 \ - --build-url=https://example.com --commit-url=https://example.com --commit=HEAD -``` - -## Monitor the state file - -To detect unauthorized changes, Kosli monitors the state file for changes by tracking it in an environment. Create a `server` environment: - -```shell -kosli create env terraform-state --type=server -``` - -Report the current state file to the environment: - - -In production, configure environment reporting to run periodically or on state file changes. See [reporting AWS environments](/tutorials/report_aws_envs) if you use S3 as your Terraform backend. - - -```shell -kosli snapshot path terraform-state --name=tf-state --path=terraform.tfstate -``` - -Check the latest snapshot: - -```shell -kosli get snapshot terraform-state -``` - -You should see: - -```plaintext -COMMIT ARTIFACT FLOW COMPLIANCE RUNNING_SINCE REPLICAS -d881b2f Name: tf-state tf-tutorial COMPLIANT 28 minutes ago 1 - Fingerprint: a57667a7b921b91d438631afa1a1fe35300b4da909a19d2b61196580f30f1d0c -``` - -The `FLOW` column shows `tf-tutorial` — Kosli has provenance for this change. In the Kosli UI under **Environments > terraform-state**, the artifact shows as compliant. - -Environment shows an authorized change - -## Introduce an unauthorized change - -Simulate an unauthorized change by modifying line 6 of `main.tf` — change `random_pet_result` to `random_pet_name` — then apply directly without going through the approved process: - -```shell -terraform apply --auto-approve -``` - -Report the updated state file to Kosli: - - -In production this step is not needed — environment reporting runs automatically on change or on a schedule. - - -```shell -kosli snapshot path terraform-state --name=tf-state --path=terraform.tfstate -``` - -Check the snapshot again: - -```shell -kosli get snapshot terraform-state -``` - -You should see: - -```plaintext -COMMIT ARTIFACT FLOW COMPLIANCE RUNNING_SINCE REPLICAS -N/A Name: tf-state N/A NON-COMPLIANT 8 minutes ago 1 - Fingerprint: edd93dcde27718ed493222ceb218275655555f3f3bfefa95628c599e678ac325 -``` - -The `FLOW` is now `N/A` — Kosli has no provenance for this state file fingerprint. It was not attested through any known flow, which means the change was unauthorized. The environment page reflects this: - -Environment shows an unauthorized change - -## What you've accomplished - -You have used Kosli to track authorized Terraform changes and detect an unauthorized one. By fingerprinting the Terraform state file and comparing it against attested artifacts, Kosli can tell whether a running infrastructure state came from an approved process or not. - -From here you can: -* Set up alerts and automated responses when unauthorized changes are detected using [Kosli Actions](/integrations/kosli_actions) -* See how to report S3-backed state files automatically in the [Report AWS environments](/tutorials/report_aws_envs) tutorial