posturanet 0.1.0__tar.gz

posturanet-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+.posturanet/runs/
+.hypothesis/
+# Never commit Terraform state or plans: they can contain secrets.
+*.tfstate
+*.tfstate.*
+*.tfplan
+tfplan
+plan.json
+.terraform/
+.env

posturanet-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to PosturaNet. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+First public release.
+
+### Changed (license)
+- PosturaNet is licensed under the Functional Source License 1.1 with an Apache 2.0 future license (`FSL-1.1-ALv2`, see `LICENSE.md`): free to use, read and change; no competing commercial products; each release becomes Apache 2.0 two years after it ships.
+
+### Added (R1.5: PosturaNet check)
+- `posturanet contract check --source [--file x.tf]`: offline check of the Terraform source against the contracts (no plan, no AWS). Literal inline ingress only; remote modules, `dynamic` blocks and non-literal values are UNKNOWN (US-7).
+- `--github-check [--sha]`: publishes a `PosturaNet contract` check run (PASS → success, BLOCK → failure, UNKNOWN → neutral) with annotations on the broken contract line and the resource block (FR-29, US-4 for one repo). Needs `checks: write`.
+- Results now carry each broken rule's contract line and the resource's file:line; text output shows `caused by:` per design system §7.
+- GitHub Action `command: check`: runs `terraform plan -lock=false` itself (or takes `plan`), or `source-only: "true"` for an offline check; `fail-on-unknown`, `check-run`; output `check-url`. Example workflow in `integrations/github/`.
+- `posturanet hook claude-code`: Claude Code PostToolUse hook. After a `.tf` edit it runs the source check and hands a BLOCK reason back to the agent; always exits 0. Wired into the Claude plugin (`skills/posturanet/plugin.json`) and `integrations/claude-code/`.
+- MCP `check_change`: `plan_json` is now optional; without it, checks the source, optionally only `files`.
+- Cursor rule and MCP config (`integrations/cursor/`), and `integrations/README.md` ("add PosturaNet to your pipeline").
+- PRD: per-repo contract checks are in Community; the org-wide gate stays in Team (R4).
+- Terminal logo: the PosturaNet logo (cloud, P, arrow) in half-block pixels with the brand gradient, shown by bare `posturanet` and `posturanet init` (on stderr). Only at an interactive terminal: never in JSON, pipes, CI, MCP or hooks. `NO_COLOR` drops color, non-UTF-8 terminals get a text-only version, `POSTURANET_NO_BANNER=1` turns it off.
+
+### Added (R1: SG contracts)
+- Read-only AWS layer (`aws/readonly.py`): every call goes through an allowlist; anything else raises `MutatingCallBlocked`. `posturanet init` prints the IAM policy generated from the same list (NFR-2, FR-47 partial).
+- Evidence: VPC flow logs via CloudWatch Logs Insights, scoped to the security group's ENIs, chunked by 7 days, with a fail-closed 10,000-row cap. Offline `--evidence-file` JSON source. Confidence (high/medium/low/none), coverage and max gap, periodicity (daily/weekly/monthly/irregular/rare/one_off) with peak-hour detection (FR-11..FR-15).
+- Behavior contracts: draft builder with default `must_deny` (world access on sensitive and exposed ports), YAML store per design system §5 (header, key order, flow-style rules, quoted account id). Approved contracts are used as-is and never overwritten; owner/ref edits survive regeneration (FR-14).
+- Z3 synthesis of the minimal ingress rule set: replaces only open rules, keeps traffic the remaining rules already allow, supernets up to /16 internal and /24 public, quota-aware, lexicographic objective (exposure, then rule count). UNSAT and solver timeouts stop (FR-18).
+- HCL rewrite of inline `ingress {}` blocks with literal values, fmt-clean output (checked against real `terraform fmt`), CRLF preserved. Dynamic blocks, non-literal values, block comments and separate rule resources stop (FR-20).
+- Drift check from state ingress before synthesis, and from the plan's `before` during validation (FR-9).
+- Validation runner in a temp copy: guardrails, `fmt -check`, `init` + `validate`, `plan -lock=false` + `show -json`, plan scope (target only, update in place), drift, plan-matches-fix, contract invariants (Z3 for allow, exact set checks for deny, with `model_scope`), finding re-check for EC2.13/14/18/19/53/54, optional tflint/checkov. PASS / FAIL / INCOMPLETE; anything but PASS opens no PR (FR-21..FR-26).
+- PR delivery through the GitHub REST API: idempotency key + finding marker (one open PR per finding; same key → no writes, new key → update), base-branch content check, `posturanet/...` branches only, max open PRs, PR title/body/labels per design system §6, safety contract YAML (FR-27, FR-28, FR-30).
+- S3 backend: `backend "s3"` block parsing and `s3:GetObject` through the read-only client; state kept in memory only (FR-5).
+- CLI: `fix [--dry-run | --open-pr] [--evidence-file] [--window 90d]`, `contract build`, `contract check --plan` (exit 5 on BLOCK), `init`, `mcp`. Text output shows observed sources and the proposed diff.
+- MCP server (stdio, MCP SDK 2.x) with read-only `explain_finding`, `propose_fix`, `check_change` (FR-40). Claude skill `skills/posturanet/SKILL.md` (FR-41). Composite GitHub Action `action/` (FR-39 partial).
+- 129 tests, including hypothesis properties for synthesis and the Z3 allow check (zero wrongly-reported-safe), a no-mutating-AWS-calls test, a static "no boto3 outside `aws/`" test, and a real `terraform fmt` integration test.
+
+### Fixed
+- Flow-log query no longer filters on `flowDirection`, which exists only in custom log formats. On the default format it returned zero inbound flows, so every rule looked unused and could be proposed for removal. Inbound is now matched by `dstAddr` against the ENIs' own IPs, and an unparseable row stops the run instead of being dropped.
+
+### Added (testing)
+- `.github/workflows/posturanet.yml`: ruff, mypy, pytest (Python 3.11 and 3.12, real terraform for the fmt test), shellcheck on the Action entrypoint, and an offline smoke run.
+- `sandbox/`: a throwaway Terraform repo for end-to-end tests: SG open on 22, an internal client, default-format VPC flow logs with 120-day retention, a read-only role, traffic scripts and a day-by-day test plan.
+
+### Changed
+- `fix` without `--dry-run` now runs the full pipeline (`check` mode); `--open-pr` delivers. `--dry-run` never calls AWS, GitHub or `terraform plan`, and writes nothing.
+- A dry run without `--evidence-file` stops after locate, with next steps instead of "arrives in R1".
+- `StageStop` can mark a stop as unknown (`?`, e.g. no evidence) and carry its own exit code (4 for validation FAIL).
+
+### Not in R1 (tracked)
+- Athena flow-log mode and `evidence.max_scan_gb`; IPv6 synthesis; `aws_security_group_rule` / `aws_vpc_security_group_ingress_rule` resources; `verify`, check runs (FR-29), freeze windows; MCP `open_fix_pr`; `init` writing config.
+
+### Added (R0: dry-run skeleton)
+- Package skeleton (`src/posturanet`), Pydantic v2 models for findings, locations, config and run records.
+- ASFF ingest: Security Hub JSON → OCSF-aligned `Finding`, plus manual `sg-…` resource ids (FR-1, FR-3, FR-4).
+- Locator v0: local Terraform state v4 → address (modules, index keys) → `file:line` via a minimal HCL scanner → owners from CODEOWNERS (FR-5..FR-8). Remote modules, S3 backend, duplicates and missing resources stop the run.
+- `posturanet fix <target> --dry-run [--repo] [--state] [--format text|json] [--ascii]`, output per the design system. Exit codes 0 / 2 / 3.
+- Synthetic fixtures (`tests/fixtures/`) and 36 tests.
+
+### Notes
+- Drift is reported as unknown until `terraform plan` lands in R1.
+- The state fixture is named `state.fixture.json` so the repo's `*.tfstate` ignore rule stays in force.

posturanet-0.1.0/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Mihir Ajmera
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+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.

posturanet-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: posturanet
+Version: 0.1.0
+Summary: Evidence-backed remediation agent for AWS + Terraform. Fixes cloud security issues without breaking prod.
+Project-URL: Homepage, https://www.posturanet.com
+Project-URL: Source, https://github.com/Mihirajmera/posturanet
+Project-URL: Issues, https://github.com/Mihirajmera/posturanet/issues
+Project-URL: Changelog, https://github.com/Mihirajmera/posturanet/blob/main/CHANGELOG.md
+Author: PosturaNet
+License-Expression: FSL-1.1-ALv2
+License-File: LICENSE.md
+Keywords: aws,cloud-security,mcp,remediation,security-groups,terraform,z3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Requires-Dist: z3-solver>=4.12
+Provides-Extra: dev
+Requires-Dist: boto3-stubs[ec2,logs,s3]>=1.34; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# PosturaNet
+
+**Fixes cloud security issues without breaking prod.**
+
+PosturaNet is a source-available remediation agent for AWS + Terraform. It takes a security finding, locates the owning Terraform and team, learns what actually uses the resource from flow logs and CloudTrail, records that as a *behavior contract*, and opens a pull request with the smallest fix that keeps every observed behavior working. It runs in your CI with a read-only role and never changes production.
+
+It also checks every security group change, written by a person or an AI agent, against those contracts before it merges: a `PosturaNet contract` check on PRs, a step in any CI, and a hook for Claude Code and Cursor. See [integrations/](integrations/README.md).
+
+> Status: early access (0.1.0). Security group ingress only.
+
+## Install
+```bash
+pip install posturanet            # add [mcp] for the MCP server: pip install "posturanet[mcp]"
+posturanet init                   # prints the read-only IAM policy PosturaNet needs
+```
+Python 3.11+. The GitHub Action is `Mihirajmera/posturanet/action@v0.1.0`; see [integrations/](integrations/README.md).
+
+## Try it (offline, no AWS)
+From a clone of this repo:
+```bash
+pip install -e ".[dev]"
+posturanet fix tests/fixtures/findings/sg_ssh_open.json --dry-run \
+  --repo tests/fixtures/tf/basic --evidence-file tests/fixtures/flows/bastion_90d.json
+```
+This reads a synthetic finding, finds the Terraform block and its owner, builds a behavior contract from 89 days of synthetic flow logs, computes the smallest rule set with Z3, and prints the diff. Nothing is written.
+
+With a read-only role: drop `--dry-run` to read flow logs and run `terraform plan`, then add `--open-pr`. Before changing security group ingress, run `posturanet contract check --plan plan.json`, or `--source` for an offline check of the edited HCL (exit 5 means BLOCK).
+
+## Project docs
+| Doc | Purpose |
+|---|---|
+| [docs/01_PRD.md](docs/01_PRD.md) | Product requirements: what we build, with FR/NFR IDs |
+| [docs/02_ARCHITECTURE_AND_DATA.md](docs/02_ARCHITECTURE_AND_DATA.md) | Architecture, data models, schemas, queries |
+| [AGENTS.md](AGENTS.md) | Rules for AI coding agents, and for PosturaNet's own runtime agent |
+| [docs/04_DESIGN_SYSTEM.md](docs/04_DESIGN_SYSTEM.md) | CLI, PR, check-run and brand design system |
+
+## License
+[Functional Source License 1.1, Apache 2.0 future license](LICENSE.md) (`FSL-1.1-ALv2`).
+
+- **You can** use PosturaNet for free in your own company, read the code, change it and run it in your CI, including for clients if you provide services.
+- **You can't** offer it, or a product built from it, as a competing commercial product or service.
+- **After two years** each release becomes Apache 2.0, with no restrictions.
+
+"PosturaNet" is a trademark: forks must use another name. Paid features ship separately in `posturanet-pro`.

posturanet-0.1.0/README.md

@@ -0,0 +1,44 @@
+# PosturaNet
+
+**Fixes cloud security issues without breaking prod.**
+
+PosturaNet is a source-available remediation agent for AWS + Terraform. It takes a security finding, locates the owning Terraform and team, learns what actually uses the resource from flow logs and CloudTrail, records that as a *behavior contract*, and opens a pull request with the smallest fix that keeps every observed behavior working. It runs in your CI with a read-only role and never changes production.
+
+It also checks every security group change, written by a person or an AI agent, against those contracts before it merges: a `PosturaNet contract` check on PRs, a step in any CI, and a hook for Claude Code and Cursor. See [integrations/](integrations/README.md).
+
+> Status: early access (0.1.0). Security group ingress only.
+
+## Install
+```bash
+pip install posturanet            # add [mcp] for the MCP server: pip install "posturanet[mcp]"
+posturanet init                   # prints the read-only IAM policy PosturaNet needs
+```
+Python 3.11+. The GitHub Action is `Mihirajmera/posturanet/action@v0.1.0`; see [integrations/](integrations/README.md).
+
+## Try it (offline, no AWS)
+From a clone of this repo:
+```bash
+pip install -e ".[dev]"
+posturanet fix tests/fixtures/findings/sg_ssh_open.json --dry-run \
+  --repo tests/fixtures/tf/basic --evidence-file tests/fixtures/flows/bastion_90d.json
+```
+This reads a synthetic finding, finds the Terraform block and its owner, builds a behavior contract from 89 days of synthetic flow logs, computes the smallest rule set with Z3, and prints the diff. Nothing is written.
+
+With a read-only role: drop `--dry-run` to read flow logs and run `terraform plan`, then add `--open-pr`. Before changing security group ingress, run `posturanet contract check --plan plan.json`, or `--source` for an offline check of the edited HCL (exit 5 means BLOCK).
+
+## Project docs
+| Doc | Purpose |
+|---|---|
+| [docs/01_PRD.md](docs/01_PRD.md) | Product requirements: what we build, with FR/NFR IDs |
+| [docs/02_ARCHITECTURE_AND_DATA.md](docs/02_ARCHITECTURE_AND_DATA.md) | Architecture, data models, schemas, queries |
+| [AGENTS.md](AGENTS.md) | Rules for AI coding agents, and for PosturaNet's own runtime agent |
+| [docs/04_DESIGN_SYSTEM.md](docs/04_DESIGN_SYSTEM.md) | CLI, PR, check-run and brand design system |
+
+## License
+[Functional Source License 1.1, Apache 2.0 future license](LICENSE.md) (`FSL-1.1-ALv2`).
+
+- **You can** use PosturaNet for free in your own company, read the code, change it and run it in your CI, including for clients if you provide services.
+- **You can't** offer it, or a product built from it, as a competing commercial product or service.
+- **After two years** each release becomes Apache 2.0, with no restrictions.
+
+"PosturaNet" is a trademark: forks must use another name. Paid features ship separately in `posturanet-pro`.

posturanet-0.1.0/integrations/README.md

@@ -0,0 +1,75 @@
+# Add PosturaNet to your pipeline
+
+PosturaNet's contract check runs where you already work. It answers one question about a
+security group change, whoever wrote it, a person or an AI agent: **does this still allow every
+source that really uses the group, and does it keep denied networks closed?**
+
+It needs a behavior contract for the group (`posturanet contract build <sg-id>`, then merge the
+PR that adds `posturanet/contracts/<address>.yaml`). Groups without a contract are not checked.
+
+| Result | Meaning | Exit code | Check run |
+|---|---|---|---|
+| `PASS` | every contract holds | 0 | `success` |
+| `BLOCK` | a `must_allow` source would be cut off, a `must_deny` network opened, or the group deleted | 5 | `failure` |
+| `UNKNOWN` | PosturaNet can't judge it (computed values, `dynamic` blocks, remote modules) | 3 | `neutral` |
+
+UNKNOWN is never shown as green. Z3 checks cover ingress CIDR, port and protocol only; security
+group references, prefix lists and egress are outside the model.
+
+## Two ways to check
+
+| | `--plan` | `--source` |
+|---|---|---|
+| Input | `terraform show -json` output | the `.tf` files in the checkout |
+| Needs | terraform, read-only AWS credentials | nothing (offline, under a second) |
+| Judges | everything the plan knows | literal inline `ingress` blocks; anything else is UNKNOWN |
+| Use for | the PR check | editor and AI agent hooks, quick local checks |
+
+```bash
+terraform plan -lock=false -out tfplan && terraform show -json tfplan > plan.json
+posturanet contract check --plan plan.json
+posturanet contract check --source --file modules/bastion/main.tf
+```
+
+## 1. GitHub pull requests
+Copy [`github/posturanet-check.yml`](github/posturanet-check.yml) to `.github/workflows/`.
+Every PR touching `*.tf` or a contract gets a **PosturaNet contract** check run. On BLOCK the
+check fails and annotates the exact contract line and the resource block:
+
+```text
+✗ module.bastion.aws_security_group.this
+  breaks must_allow: 203.0.113.7/32 → 22/tcp (partner-sftp)
+  caused by: planned ingress in modules/bastion/main.tf:12
+  → keep the rule, or update the contract in the same PR with owner approval
+```
+
+The job needs `checks: write`. Make it a required status check in branch protection to stop a
+merge on BLOCK. Set `fail-on-unknown: "false"` if UNKNOWN should not fail the job.
+
+## 2. Any other CI
+After your existing `terraform plan` step:
+```bash
+terraform show -json tfplan > plan.json
+posturanet contract check --plan plan.json        # exit 5 fails the build on BLOCK
+```
+To publish a GitHub check run from another CI, add `--github-check --sha <commit>` and set
+`GITHUB_TOKEN` (with `checks: write`) and `GITHUB_REPOSITORY`.
+
+## 3. Claude Code
+Install the plugin in [`../skills/posturanet`](../skills/posturanet) (skill, MCP server and hook),
+or copy [`claude-code/settings.json`](claude-code/settings.json) into `.claude/settings.json` and
+[`claude-code/.mcp.json`](claude-code/.mcp.json) into the repo root.
+
+After every edit to a `.tf` file, the hook runs `posturanet hook claude-code`. On BLOCK, Claude
+gets the reason and fixes its own change before going on. On UNKNOWN it is told to check with a
+plan. The hook only reads the file path from the event and never writes anything.
+
+## 4. Cursor and other MCP agents
+Copy [`cursor/mcp.json`](cursor/mcp.json) to `.cursor/mcp.json` and
+[`cursor/posturanet.mdc`](cursor/posturanet.mdc) to `.cursor/rules/`. The rule tells the agent to
+call `check_change` with the edited files and stop on BLOCK. Any MCP client works the same way:
+run `posturanet mcp` and call `check_change`.
+
+## What PosturaNet never does here
+No AWS writes (the role is read-only), no `terraform apply`, no merge, no state lock
+(`-lock=false`). Nothing leaves your runner except the check run sent to your own GitHub.

posturanet-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "posturanet"
+version = "0.1.0"
+description = "Evidence-backed remediation agent for AWS + Terraform. Fixes cloud security issues without breaking prod."
+readme = "README.md"
+license = "FSL-1.1-ALv2"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.11"
+authors = [{ name = "PosturaNet" }]
+keywords = ["aws", "terraform", "security-groups", "remediation", "cloud-security", "mcp", "z3"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.6,<3",
+  "typer>=0.12",
+  "rich>=13.7",
+  "ruamel.yaml>=0.18",
+  "z3-solver>=4.12",
+  "boto3>=1.34",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://www.posturanet.com"
+Source = "https://github.com/Mihirajmera/posturanet"
+Issues = "https://github.com/Mihirajmera/posturanet/issues"
+Changelog = "https://github.com/Mihirajmera/posturanet/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+mcp = ["mcp>=2.0,<3"]
+dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.10", "hypothesis>=6.100", "boto3-stubs[ec2,logs,s3]>=1.34"]
+
+[project.scripts]
+posturanet = "posturanet.cli.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/posturanet"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/posturanet", "tests", "README.md", "CHANGELOG.md", "LICENSE.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# CLI output snapshots must match real line lengths.
+"tests/**" = ["E501"]  # long synthetic fixture data
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["z3", "z3.*"]
+ignore_missing_imports = true

posturanet-0.1.0/sandbox/README.md

@@ -0,0 +1,63 @@
+# PosturaNet sandbox
+
+A small, deliberately open AWS setup for testing PosturaNet end to end: one security group with SSH open to `0.0.0.0/0`, real traffic from known sources, and VPC flow logs. This folder is meant to become its own throwaway GitHub repo, which is the repo PosturaNet opens PRs against.
+
+**Use a separate sandbox AWS account.** This opens port 22 to the internet on purpose. There's no key pair, so nobody can log in, but internet scanners will connect. That noise is part of the test.
+
+## What it creates
+| Resource | Why |
+|---|---|
+| VPC `10.42.0.0/16`, public subnet, internet gateway | Isolated network |
+| `module.bastion`: SG with `22/tcp` from `0.0.0.0/0`, t3.micro with no key pair | The finding to fix |
+| `aws_instance.client` (t3.nano, optional) | A steady internal source: connects to the bastion every 30 min |
+| VPC flow logs (default format) → CloudWatch Logs, 120-day retention | The evidence |
+| IAM role `posturanet-sandbox-readonly` | What PosturaNet and `terraform plan` run as |
+
+**Cost:** roughly $5–15 a month, mostly the two instances (often $0 on the free tier). Flow-log ingestion and Logs Insights queries for this traffic volume cost cents. `terraform destroy` removes everything.
+
+## Setup (day 0)
+1. Copy this folder into a new private GitHub repo, e.g. `posturanet-sandbox`. In `.github/CODEOWNERS` and `.posturanet.yml`, put your GitHub handle.
+2. Apply with **your own admin credentials** (PosturaNet never applies):
+   ```bash
+   terraform init
+   terraform apply -var trusted_principal_arn=arn:aws:iam::<ACCOUNT_ID>:user/<you>
+   ```
+   Note the outputs: `security_group_id`, `bastion_public_ip`, `posturanet_role_arn`.
+3. Add a profile that assumes the read-only role, in `~/.aws/config`:
+   ```ini
+   [profile posturanet-sandbox]
+   role_arn = <posturanet_role_arn output>
+   source_profile = default
+   region = us-east-1
+   ```
+   Run every PosturaNet command with `AWS_PROFILE=posturanet-sandbox`, so PosturaNet's calls **and** `terraform plan` both use the read-only role. (`aws.role_arn` in `.posturanet.yml` only applies to PosturaNet's own calls, not to the plan.)
+4. Start traffic from your laptop (an external daily source):
+   - Windows: `schtasks /Create /SC HOURLY /TN PosturaNetTraffic /TR "powershell -NoProfile -File C:\path\to\traffic\traffic.ps1 -Ip <bastion_public_ip>"`
+   - macOS/Linux: `0 9-18 * * * /path/to/traffic/traffic.sh <bastion_public_ip>` in `crontab -e`
+5. Optional: copy `traffic/github-actions-traffic.yml.example` to `.github/workflows/traffic.yml` for irregular public sources.
+6. Commit and push, including `.terraform.lock.hcl`. Never commit `terraform.tfstate`; it's git-ignored.
+
+## Test plan
+| When | Run | Expect |
+|---|---|---|
+| Day 0 | `posturanet fix <sg-id> --dry-run` | Stops after locate (no evidence in a dry run). Owner from CODEOWNERS. |
+| Day 1+ | `posturanet fix <sg-id>` | `evidence` stops: confidence low (under 14 days). Check the sources it lists match your laptop IP and `10.42.1.x`. |
+| Day 1+ | `posturanet contract build <sg-id>` | Draft contract in `posturanet/contracts/`. Read it. |
+| Day 14+ | `posturanet fix <sg-id>` | Real `terraform plan`, all required checks PASS, `VALIDATED`, risk medium. |
+| Day 14+ | `GITHUB_TOKEN=… posturanet fix <sg-id> --open-pr` | A PR in the sandbox repo. Re-run: "PR already open", no duplicate. |
+| After merge | `terraform apply`, keep traffic running | Your laptop and the client still connect; the scanners stop. |
+| Any time | Edit ingress to drop your IP, `terraform plan -out p && terraform show -json p > plan.json`, `posturanet contract check --plan plan.json` | Exit 5, BLOCK, names your IP. |
+| Day 60+ | `posturanet fix <sg-id>` | Confidence high, risk low (if no needs-review sources). |
+
+Use `--format json` and keep the output of every run; those records are the test log.
+
+## What to watch for
+- **Scanners.** Port 22 open to the internet collects many one-off public sources. R1 keeps `needs_review` sources in the fix (the safe direction) and labels the PR. Watch how many appear, and whether the rule quota stops the fix. This is the first real-world question the sandbox answers.
+- **Plan permissions.** If `terraform plan` fails with AccessDenied under the read-only role, note the action; that's the input for a narrower customer policy.
+- **Anything that stops.** STOPPED is a valid answer, but record the reason: each one is either correct fail-closed behavior or a bug.
+
+## Clean up
+```bash
+terraform destroy -var trusted_principal_arn=<same as apply>
+```
+and remove the scheduled task or cron entry.

posturanet-0.1.0/src/posturanet/__init__.py

@@ -0,0 +1,3 @@
+"""PosturaNet: evidence-backed remediation agent for AWS + Terraform."""
+
+__version__ = "0.1.0"

posturanet-0.1.0/src/posturanet/__main__.py

@@ -0,0 +1,3 @@
+from posturanet.cli.app import main
+
+main()

posturanet-0.1.0/src/posturanet/aws/__init__.py

@@ -0,0 +1,3 @@
+from posturanet.aws.readonly import ALLOWLIST, MutatingCallBlocked, ReadOnlyClient, iam_policy
+
+__all__ = ["ALLOWLIST", "MutatingCallBlocked", "ReadOnlyClient", "iam_policy"]

posturanet-0.1.0/src/posturanet/aws/readonly.py

@@ -0,0 +1,96 @@
+"""Read-only AWS access (NFR-2, architecture doc 7.3).
+
+Every AWS call in PosturaNet goes through `ReadOnlyClient`. Operations not on the allowlist
+raise `MutatingCallBlocked` before anything reaches the network. The generated IAM policy
+(`iam_policy()`) is built from the same list so the two can't drift apart.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from typing import Any
+
+from posturanet.errors import PosturaNetError
+
+ALLOWLIST: tuple[str, ...] = (
+    "ec2:Describe*",
+    "logs:StartQuery",
+    "logs:GetQueryResults",
+    "logs:DescribeLogGroups",
+    "athena:StartQueryExecution",
+    "athena:GetQueryExecution",
+    "athena:GetQueryResults",
+    "s3:GetObject",
+    "s3:ListBucket",
+    "iam:Get*",
+    "iam:List*",
+    "iam:GenerateServiceLastAccessedDetails",
+    "iam:SimulatePrincipalPolicy",
+    "securityhub:GetFindings",
+    "access-analyzer:Get*",
+    "access-analyzer:List*",
+    "sts:GetCallerIdentity",
+    "sts:AssumeRole",
+)
+
+# boto3 service names that differ from IAM action prefixes.
+_IAM_PREFIX = {"accessanalyzer": "access-analyzer"}
+
+
+class MutatingCallBlocked(PosturaNetError):
+    """An AWS operation outside the read-only allowlist was attempted."""
+
+    exit_code = 10
+
+
+def iam_action(service: str, method: str) -> str:
+    """`("ec2", "describe_network_interfaces")` -> `"ec2:DescribeNetworkInterfaces"`."""
+    prefix = _IAM_PREFIX.get(service, service)
+    op = "".join(part.capitalize() for part in method.split("_"))
+    return f"{prefix}:{op}"
+
+
+def is_allowed(action: str) -> bool:
+    return any(fnmatch.fnmatchcase(action, pattern) for pattern in ALLOWLIST)
+
+
+_PAGINATOR = re.compile(r"^(get_paginator|can_paginate|get_waiter)$")
+
+
+class ReadOnlyClient:
+    """Wraps a boto3 client; only allowlisted operations are reachable."""
+
+    def __init__(self, client: Any, service: str) -> None:
+        self._client = client
+        self._service = service
+
+    @property
+    def service(self) -> str:
+        return self._service
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_") or _PAGINATOR.match(name):
+            # Paginators and waiters would bypass the per-call check.
+            raise MutatingCallBlocked(f"{self._service}.{name} is not available in PosturaNet")
+        action = iam_action(self._service, name)
+        if not is_allowed(action):
+            raise MutatingCallBlocked(
+                f"{action} is not on the read-only allowlist; PosturaNet never writes to AWS"
+            )
+        return getattr(self._client, name)
+
+
+def iam_policy() -> dict[str, Any]:
+    """IAM policy document a customer attaches to PosturaNet's role."""
+    return {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "PosturaNetReadOnly",
+                "Effect": "Allow",
+                "Action": sorted(ALLOWLIST),
+                "Resource": "*",
+            }
+        ],
+    }