statewatch 0.1.0__tar.gz

statewatch-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git push *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git fetch *)",
+      "Bash(git ls-tree *)",
+      "Bash(echo \"graph module on dev?  $\\(git ls-tree -r --name-only origin/dev)",
+      "Bash(awk 'length>100{print FILENAME\":\"FNR\" \\(\"length\"\\)\"}' tests/test_classifier.py tests/test_impact.py tests/test_resources.py)",
+      "Bash(gh pr *)",
+      "Bash(git stash *)",
+      "Bash(echo \"PR #4: $\\(gh pr view 4 --json state,mergeCommit -q '.state + \" merge=\" + \\(.mergeCommit.oid // \"not-merged\"\\)' \\)\")"
+    ]
+  }
+}

statewatch-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Generated graph renders
+graph.png
+*.dot.png
+
+# Local-only build-in-public posting log (never committed)
+docs/social/x-posts.md

statewatch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to statewatch
+
+statewatch is GCP-only in v0.1 by design. The two highest-value contributions are **new
+cloud adapters** (AWS, Azure) and **new GCP resource types** — both have explicit
+extension seams so you don't have to touch the engine.
+
+## Dev setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q          # 40+ tests, all green
+ruff check .
+mypy src/statewatch
+```
+
+Offline run (no GCP project needed): `statewatch scan --tfstate
+tests/fixtures/firewall_subnet_drift.tfstate.json --project demo-project --stub`.
+
+## Adding a cloud adapter (AWS / Azure)
+
+The boundary is `src/statewatch/adapters/base.py` — a `CloudAdapter` `Protocol`. An
+adapter's only job is **auth + return live state as normalized `Resource` objects**. It
+does not diff, classify, or know about Terraform.
+
+Implement four things (see the protocol docstring for the full contract):
+
+1. `name` — `"aws"` / `"azure"`.
+2. `authenticate()` — establish credentials via the provider's standard mechanism and make
+   one cheap call to validate them. Raise `AdapterAuthError` on failure.
+3. `supported_resource_types()` — the Terraform type names you can fetch
+   (e.g. `{"aws_instance", "aws_security_group"}`).
+4. `fetch_resources(types, *, scope)` — query the provider inventory API
+   (AWS Config / Azure Resource Graph) and map each native object into a `Resource`,
+   deriving a `resource_id` that matches what Terraform-side normalization produces, and
+   filling `parent_refs` from obvious attribute references.
+
+Nothing else in the codebase needs to change — the differ, graph, classifier and impact
+analyzer are provider-agnostic.
+
+## Adding a GCP resource type
+
+One module per type under `src/statewatch/resources/` (see `compute_instance.py`,
+`firewall.py`, `subnetwork.py`, `gke_cluster.py` for the pattern):
+
+1. Create `resources/<type>.py` with `RESOURCE_TYPE`, `normalize_from_tfstate(...)`, and
+   `normalize_from_cai(...)`. Build `resource_id` from the shared id helpers in
+   `normalizer.py` so it unifies with other resources' `parent_refs` (this is what makes
+   the graph connect — see KNOWN_ISSUES history for why it matters).
+2. Register it in `resources/__init__.py` (`_TF`, `_CAI`, `_CAI_ASSET_TO_TYPE`) and add
+   the CAI asset type to `adapters/gcp.py`.
+3. Whitelist only *comparable* attributes; never copy server-generated noise
+   (`*_fingerprint`, `self_link`, ids, timestamps).
+4. Add severity rules in `classifier.py` if the type has security-relevant changes.
+5. Add a realistic fixture and tests. **Fixtures are the README of the test suite** —
+   real-shaped `.tfstate`, not toy examples.
+
+## Conventions
+
+- Edge direction is `A → B` = "A depends on B"; impact flows against it (predecessors).
+- Don't overclaim: severity is a heuristic proxy for propagation, stated as such in
+  output and docs. Keep it that way.
+- Deferred work goes in `KNOWN_ISSUES.md` with *why* and *when*, never silently.
+- ruff + mypy clean; tests green; honest commit messages (phase/scope-enabling edits to
+  shared modules committed separately).
+
+## Out of scope (v0.1)
+
+Auto-remediation, multi-cloud in one run, a web dashboard, a SaaS, and replacing
+`terraform plan`. See "What this is NOT trying to be" in `spec.md`.

statewatch-0.1.0/Dockerfile

@@ -0,0 +1,11 @@
+# Container image for the statewatch GitHub Action.
+FROM python:3.12-slim
+
+WORKDIR /opt/statewatch
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
+COPY action/entrypoint.py /action/entrypoint.py
+
+ENTRYPOINT ["python", "/action/entrypoint.py"]

statewatch-0.1.0/KNOWN_ISSUES.md

@@ -0,0 +1,68 @@
+# Known issues / deferred work
+
+Tracked, deliberately-deferred items. Each says *why* it was deferred and *when* it must
+be addressed. A deferred fix that isn't written down is a forgotten bug.
+
+## Resolved
+
+### 1. Subnet ref dropped the region for bare-name inputs — RESOLVED in Phase 3
+Resolved at Phase 3 entry as planned. `normalizer.subnetwork_ref_from_attr` now produces
+a region-qualified canonical id for full-URL, path, **and** bare-name forms; for bare
+names the region is derived from the instance's own zone (a GCP instance's subnet is
+always in its region). `resources/subnetwork.py` builds its `resource_id` from the same
+shared `subnetwork_id`, so an instance's inferred subnet ref and the subnet resource node
+unify into one node. Regression locked by
+`tests/test_resources.py::test_known_issue_1_subnet_ref_unifies_across_input_forms`.
+Original report retained below for history.
+
+<details><summary>Original deferral (Phase 2)</summary>
+
+### 1. `_normalize_subnetwork_ref` drops the region for bare-name inputs
+- **Where:** `src/statewatch/normalizer.py` — `_normalize_subnetwork_ref`.
+- **What:** When a compute instance's `subnetwork` attribute is a *full URL* or a
+  `projects/.../regions/.../subnetworks/...` path, the inferred `parent_ref` id keeps the
+  region segment (`projects/<p>/regions/<r>/subnetworks/<n>`). When it's a *bare name*,
+  the fallback emits `projects/<p>/subnetworks/<n>` — **no region**.
+- **Why it matters:** Phase 3 makes `google_compute_subnetwork` a first-class normalized
+  resource. Its node `resource_id` will be the regional form. If Phase 1's bare-name
+  fallback id doesn't match that form, an inferred edge and the real subnet node will *not
+  unify* — the graph will show a duplicate/dangling external node instead of connecting
+  the instance to its actual subnet. This is exactly the "Phase 3 fights the graph"
+  failure mode flagged during Phase 2 design.
+- **Why deferred:** Fixing it in Phase 2 means churning Phase 1 normalization mid-phase
+  with no Phase 2 consumer that needs it (the fixtures use full URLs, which are already
+  correct). Approved for deferral during Phase 2 architectural review.
+- **Fix at Phase 3 entry:** make the subnetwork (and, symmetrically, network/SA) id
+  derivation produce the *same* canonical id the Phase 3 subnetwork normalizer will assign
+  — region-qualified — and add a normalizer test asserting an instance's inferred subnet
+  ref equals the subnet resource's `resource_id` for bare-name, path, and URL inputs.
+
+</details>
+
+### 2. `scan` degraded instead of failing when GCP auth was unavailable — RESOLVED in Phase 4
+`adapters/gcp.py` now makes a real `AssetServiceClient.list_assets` call by default.
+`scan` no longer degrades: a missing-credentials situation is a hard `typer.Exit(2)`
+(`cli._produce_report`). Offline demo/CI is an explicit, separate path — `--stub` or
+`STATEWATCH_STUB_GCP=1` — never a silent fallback. Original carry-forward retained below.
+
+<details><summary>Original follow-up (Phases 1–3)</summary>
+
+`scan` printed a warning and continued against stubbed CAI when ADC was absent, because
+the live-state fetch was stubbed and degrading kept it demonstrable offline. The fix was
+gated on a real `list_assets` call landing, which it did in Phase 4.
+
+</details>
+
+## Carried to v0.2 (none)
+
+Nothing is being silently carried. v0.2 (drift attribution) is a separate, scoped release
+per `spec.md`; it is not a deferred bug.
+
+## Heuristics stated honestly (not bugs, but tracked)
+
+- **Severity as a propagation proxy.** Impact labelling treats severity ≥ MEDIUM as
+  "propagates." This is a deliberate heuristic, not dataflow analysis, and is stated as
+  such in terminal output, JSON, and the README. A future enhancement could model
+  per-attribute propagation; v0.1 intentionally does not.
+- **Firewall applicability inference** matches on network + target tags/SAs, not a
+  packet-level evaluation. Documented in `graph/inferred.py`.

statewatch-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

statewatch-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: statewatch
+Version: 0.1.0
+Summary: Dependency-aware infrastructure drift detector for GCP
+Project-URL: Homepage, https://github.com/pyjeebz/statewatch
+Project-URL: Repository, https://github.com/pyjeebz/statewatch
+Author: pyjeebz
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: drift,gcp,infrastructure,sre,terraform
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: google-auth>=2.0
+Requires-Dist: google-cloud-asset>=3.20
+Requires-Dist: google-cloud-storage>=2.10
+Requires-Dist: networkx>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: schedule>=1.2
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# statewatch
+
+**Your infrastructure drifted. statewatch tells you what breaks.**
+
+A dependency-aware drift detector for GCP. It compares live Cloud Asset Inventory state
+against your Terraform state, builds a resource dependency graph (including dependencies
+Terraform itself doesn't track), and reports, per drift, **how bad it is** and **what
+else is affected**.
+
+Detection is commodity — every tool tells you a field changed. The hard question on call
+at 2 AM is *"what does this break?"* That's what statewatch answers.
+
+![statewatch scan showing a CRITICAL firewall drift and a MEDIUM subnet drift, each with its DIRECT blast radius](docs/img/scan-showcase.svg)
+
+## Install
+
+```bash
+pip install statewatch
+```
+
+Python 3.11+. Apache-2.0.
+
+## Quickstart
+
+```bash
+# 1. Point it at your Terraform state and GCP project (needs roles/cloudasset.viewer)
+statewatch scan --tfstate ./terraform.tfstate --project my-gcp-project
+
+# 2. See the dependency graph it builds (text | json | dot)
+statewatch graph --tfstate ./terraform.tfstate --project my-gcp-project --format dot | dot -Tpng > graph.png
+
+# 3. Generate a starter config
+statewatch init --tfstate ./terraform.tfstate --project my-gcp-project
+```
+
+No GCP project handy? Add `--stub` to any `scan` for an offline demo against bundled
+sample state. State can also live in GCS: `--tfstate gs://my-bucket/env/prod.tfstate`.
+
+## What statewatch does
+
+- **Severity × impact, not just "drift detected."** Every finding carries a severity
+  (CRITICAL / MEDIUM / LOW) *and* a blast radius — the resources that depend on the
+  drifted one, labelled **DIRECT** (one hop), **INDIRECT** (two hops), or **WATCH**
+  (further, or low-propagation drift). `CRITICAL firewall drift — 2 DIRECT` is a
+  different alert than `drift detected`.
+- **A real dependency graph.** Built automatically from Terraform `depends_on`, from
+  manual edges in `statewatch.yaml`, and — the defensible part — **inferred from resource
+  attributes**: a subnet referenced in an instance's `subnetwork` field, or a firewall
+  that applies to an instance by tag, is a real dependency even when `depends_on` never
+  mentions it. Terraform doesn't track those. statewatch does.
+- **Exit codes for CI.** `0` clean · `1` low/medium drift · `2` critical, or any drift
+  with a significant blast radius. Wire it into a pipeline and the build fails when it
+  should.
+
+Resource types in v0.1: `google_compute_instance`, `google_compute_firewall`,
+`google_compute_subnetwork`, `google_container_cluster`.
+
+## Who this is for
+
+statewatch is for **SRE on-call, incident response, and large-scale Terraform setups** —
+the engineer staring at drift in infrastructure they didn't write, who needs to triage
+fast, and any setup where implicit dependencies live in attribute fields that Terraform's
+own dependency tree doesn't capture.
+
+**It is not for everyone, and that's deliberate.** If you wrote the Terraform and you're
+the one running `plan`, you know what depends on what — `terraform plan` is enough and you
+don't need this. statewatch earns its keep when the person seeing the drift *isn't* the
+person who wrote the code, or when there are too many simultaneous drift events to triage
+by hand. Underclaiming who it's for is the point.
+
+One honesty note: statewatch uses **severity as a heuristic proxy for whether drift
+propagates** to dependents. It is not dataflow analysis and doesn't claim to be — the
+terminal output and JSON say so too.
+
+## Why statewatch and not …
+
+| | what it tells you | what it doesn't |
+|---|---|---|
+| `terraform plan` | exactly what *your* config would change | nothing about live drift you didn't cause; only what's in the dependency tree |
+| Terraform Cloud drift detection | a resource drifted | what *else* is affected; implicit attribute-level dependencies |
+| driftctl | unmanaged / drifted resources, broadly | severity, and the downstream blast radius |
+| **statewatch** | what drifted, how bad, **and what depends on it** | it's GCP-only, detection-only (no auto-fix), and intentionally narrow in audience |
+
+statewatch is a *complement* to `terraform plan`, not a replacement.
+
+## How it works
+
+```
+GCP live state            Terraform state
+(Cloud Asset Inventory)   (local file or gs://)
+        └──────────┬──────────┘
+                   ▼
+        normalize → structural diff
+                   ▼
+      severity classifier   dependency graph
+                   └─────────┬────────┘
+                             ▼
+            impact analyzer (walk predecessors)
+                             ▼
+        severity × impact report  (terminal · JSON · Slack · GitHub PR)
+```
+
+Impact flows *against* dependency edges: when B drifts, the affected resources are B's
+transitive predecessors (everything that depends on B).
+
+## Running in CI
+
+A GitHub Action ships in this repo (`action.yml`): it runs a scan, upserts a single
+findings comment on the PR, and fails the check when statewatch exits `2`.
+
+```yaml
+- uses: google-github-actions/auth@v2
+  with: { workload_identity_provider: ..., service_account: ... }
+- uses: pyjeebz/statewatch@v0.1.0
+  with:
+    tfstate: gs://my-bucket/env/prod.tfstate
+    project: my-gcp-project
+```
+
+Slack notifications and `--watch` (continuous, notify-only-on-new-drift) are configured
+via `statewatch.yaml` — run `statewatch init` to scaffold one.
+
+## Future
+
+statewatch is the intelligence layer — *what changed and what it breaks*. **v0.2** adds
+drift attribution: *who* changed it and *when*, by correlating GCP Audit Logs. AWS and
+Azure adapters are open for community contribution behind a stable adapter interface; the
+runtime layer is a separate, later effort.
+
+## Roadmap
+
+- **v0.2** — drift attribution (Audit Logs: actor, method, timestamp). Opt-in.
+- AWS adapter (Config + CloudTrail) and Azure adapter (Resource Graph + Activity Log) —
+  community contributions welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+- Tracked, deliberately-deferred items live in [KNOWN_ISSUES.md](KNOWN_ISSUES.md).
+
+## Contributing
+
+The adapter and per-resource-type seams are designed for external contribution —
+[CONTRIBUTING.md](CONTRIBUTING.md) explains the `CloudAdapter` interface and how to add a
+resource type without touching the engine.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).