sovereign-observer 0.1.0__tar.gz

sovereign_observer-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# ── Secrets — NEVER commit these ───────────────────────────────────────────
+# Losing/leaking ENCRYPTION_KEY (Fernet) makes all stored customer cloud
+# credentials undecryptable; a leaked GCP service account or Firebase key is a
+# full account compromise. Keep this list strict.
+.env
+.env.*
+!.env.example
+*.key
+secret.key
+*service_account*.json
+gcp_service_account.json
+firebase*.json
+serviceAccount*.json
+*.pem
+credentials.json
+
+# ── Databases / local state ────────────────────────────────────────────────
+*.db
+*.sqlite
+*.sqlite3
+instance/
+.runtime/
+
+# ── Terraform plan artifacts (may embed resource values) ──────────────────
+*.tfplan
+*.tfstate
+*.tfstate.*
+.terraform/
+
+# ── Python ─────────────────────────────────────────────────────────────────
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+
+# ── Node / frontend ──────────────────────────────────────────────────────────
+node_modules/
+frontend/build/
+frontend/build-check*/
+frontend/public/screenshots/
+
+# ── Misc ───────────────────────────────────────────────────────────────────
+.DS_Store
+
+.vercel
+
+# ── Outreach data (scraped contact emails + send history — never public) ───
+marketing/outreach/lead_messages_generated.csv
+marketing/outreach/send_queue.csv
+# The timestamped backups refresh_queue.py writes hold the same scraped
+# addresses as send_queue.csv itself, so they need the same rule — an ignored
+# file whose backups are committed is not ignored.
+marketing/outreach/send_queue.*.csv
+marketing/outreach/sent_log.csv
+# Agent output: proposed actions with lead names, addresses and draft bodies.
+marketing/outreach/approval_queue.json
+marketing/outreach/followup_log.csv
+
+# ── MCP server: generated engine copy ──────────────────────────────────────
+# scripts/vendor_engine.py copies the backend's IaC engine modules here at
+# build time. Committing them would put a second copy of the rule logic in git,
+# which is exactly the drift the vendoring design exists to prevent.
+integrations/mcp-server/sovereign_mcp/_vendor/
+integrations/mcp-server/dist/
+integrations/mcp-server/build/
+integrations/mcp-server/*.egg-info/

sovereign_observer-0.1.0/Makefile

@@ -0,0 +1,17 @@
+PYTHON ?= python
+
+.PHONY: vendor test wheel clean
+
+## Copy the IaC engine in from the backend. Required before building.
+vendor:
+	$(PYTHON) scripts/vendor_engine.py
+
+test: vendor
+	$(PYTHON) -m pytest tests/ -q
+
+## Vendor THEN build — a wheel built without vendoring ships no engine.
+wheel: vendor
+	$(PYTHON) -m build --wheel
+
+clean:
+	rm -rf dist build *.egg-info sovereign_mcp/_vendor

sovereign_observer-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: sovereign-observer
+Version: 0.1.0
+Summary: Scan AI-generated Terraform for security misconfigurations, in your editor, before it is committed.
+Project-URL: Homepage, https://sovereignobserver.com
+Author: Sovereign Observer
+License: Apache-2.0
+Keywords: checkov,compliance,cspm,iac,mcp,security,terraform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: checkov==3.3.11
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sovereign MCP
+
+Your AI assistant writes Terraform. This checks it before you do.
+
+An MCP server that scans Terraform for security misconfigurations **while the code is
+being generated**, not after it lands in a pull request. It runs locally, needs no
+account, and your infrastructure code never leaves your machine.
+
+```
+You:       "add an RDS instance for the orders service"
+Assistant: [writes HCL] → [scans it] → [fixes 4 findings] → shows you the result
+```
+
+---
+
+## Why this exists
+
+Provider defaults optimise for *it works*, not *it is safe*. Terraform generated from a
+model's memory is routinely unencrypted, publicly reachable, or missing deletion
+protection — and the cost of fixing that rises steeply the further it travels. In the
+editor it is one attribute. In a PR it is a review cycle. In production it is an incident.
+
+CI already catches this. CI catches it three days and one argument later.
+
+---
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add sovereign -- uvx sovereign-observer
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sovereign": {
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "sovereign": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sovereign": {
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+First run downloads the engine (~100 MB) and takes a moment. After that it is local and
+fast.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `scan_terraform` | Scan HCL — from disk or an unsaved buffer. Returns findings by severity with file and line. |
+| `explain_finding` | The full remediation for one finding: what is wrong and the exact Terraform to fix it. |
+| `apply_fixes` | Apply the mechanically-safe fixes and return patched HCL. |
+| `secure_template` | A hardened starting point for a resource type, so the insecure version never gets written. |
+| `check_compliance` | Map findings to SOC 2, ISO 27001, NIST 800-53, PCI-DSS, DORA, NIS2, NCA (Saudi), NESA (UAE). |
+| `framework_coverage` | Which articles of a regulation automated scanning can and cannot evidence. |
+| `org_requirements` | Your organization's own rules for a resource type — *before* the code is written. |
+| `org_status` | Whether org policy is in force, or built-in rules only. |
+
+You do not call these. The assistant does, on its own, because the server tells it to.
+
+---
+
+## Organization policy
+
+Everything above works with no account. Connecting an organization adds **your
+company's own rules** to the same local evaluation:
+
+```bash
+export SOVEREIGN_TOKEN=...   # Integrations → GitHub in the dashboard
+```
+
+The difference this makes is in *when* the rule applies. Without it, the assistant writes
+Terraform and then finds out it was wrong. With it:
+
+```
+You:       "add an RDS instance for the orders service"
+Assistant: → org_requirements("aws_db_instance")
+           ← "backup_retention_period must be at least 365"
+             "region must be one of: eu-west-1, eu-central-1"
+           [writes Terraform that already satisfies both]
+           → scan_terraform → clean
+```
+
+The rule is supplied to the generator, not applied to the output. That is the whole point
+— a violation that never gets written costs nothing to fix.
+
+Company rules appear in scans tagged `source: org_policy`, so a developer can always tell
+a company requirement from a built-in one. They are authored in the dashboard as YAML and
+enforced identically in the editor, in CI, and in a cloud scan.
+
+**This does not change what leaves your machine.** Rules come down; code never goes up.
+The only request this server makes is a `GET` for your org's rules —
+`tests/test_org_policy.py::test_no_terraform_is_ever_uploaded` asserts that at the
+transport, and asserts an unconnected install opens no socket at all. If the API is
+unreachable or the token is rejected, the built-in rules still run locally and the scan
+still works.
+
+---
+
+## What it does not do
+
+Worth stating plainly, because a security tool that overstates its scope is worse than no
+tool:
+
+- **It is not a compliance assessment.** `check_compliance` returns control *mappings* —
+  evidence that shortens an audit. Every framework it maps also carries governance,
+  process and training obligations no configuration scanner can observe. A clean scan is
+  not a compliant organisation.
+- **NCA control identifiers are provisional**, pending reconciliation against the
+  authority's published catalogue. Cite the subdomain names.
+- **`apply_fixes` is deliberately narrow.** It applies only single-attribute, in-place
+  changes from a hand-verified allowlist, and never overwrites a value wired to a variable
+  or expression. Everything else stays advisory, because a mechanical fix that is
+  syntactically clean can still take a running system down.
+- **It scans Terraform**, not live cloud accounts, container images, or dependencies.
+
+For live multi-cloud posture management, attack-path analysis and audit-ready reporting,
+this is the editor-side slice of [Sovereign Observer](https://sovereignobserver.com).
+
+---
+
+## Privacy
+
+The scan runs in this process, on your machine. There is no API key, no account, and no
+network call in the default path — the server works with networking disabled. Your
+Terraform is never uploaded.
+
+---
+
+## Development
+
+From a checkout of the product repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+The IaC engine is **copied in from the backend at build time** by
+`scripts/vendor_engine.py`, into a gitignored `sovereign_mcp/_vendor/`. That is
+deliberate: the repository holds exactly one copy of the rule logic, so the editor and CI
+can never disagree about whether a resource is insecure. `sovereign_mcp/engine.py` vendors
+on demand in a source checkout, so there is no build step for day-to-day work.
+
+Never edit anything under `_vendor/`. Edit the backend module and re-run the script.
+
+```bash
+python -m pytest tests/ -q
+```
+
+`tests/test_parity.py` is the one that matters — it fails if the vendored copy drifts from
+its source, or if the Checkov pin stops matching the backend's.
+
+Licensed Apache-2.0. Built on [Checkov](https://github.com/bridgecrewio/checkov)
+(Apache-2.0).

sovereign_observer-0.1.0/README.md

@@ -0,0 +1,194 @@
+# Sovereign MCP
+
+Your AI assistant writes Terraform. This checks it before you do.
+
+An MCP server that scans Terraform for security misconfigurations **while the code is
+being generated**, not after it lands in a pull request. It runs locally, needs no
+account, and your infrastructure code never leaves your machine.
+
+```
+You:       "add an RDS instance for the orders service"
+Assistant: [writes HCL] → [scans it] → [fixes 4 findings] → shows you the result
+```
+
+---
+
+## Why this exists
+
+Provider defaults optimise for *it works*, not *it is safe*. Terraform generated from a
+model's memory is routinely unencrypted, publicly reachable, or missing deletion
+protection — and the cost of fixing that rises steeply the further it travels. In the
+editor it is one attribute. In a PR it is a review cycle. In production it is an incident.
+
+CI already catches this. CI catches it three days and one argument later.
+
+---
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add sovereign -- uvx sovereign-observer
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sovereign": {
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "sovereign": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sovereign": {
+      "command": "uvx",
+      "args": ["sovereign-observer"]
+    }
+  }
+}
+```
+
+First run downloads the engine (~100 MB) and takes a moment. After that it is local and
+fast.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `scan_terraform` | Scan HCL — from disk or an unsaved buffer. Returns findings by severity with file and line. |
+| `explain_finding` | The full remediation for one finding: what is wrong and the exact Terraform to fix it. |
+| `apply_fixes` | Apply the mechanically-safe fixes and return patched HCL. |
+| `secure_template` | A hardened starting point for a resource type, so the insecure version never gets written. |
+| `check_compliance` | Map findings to SOC 2, ISO 27001, NIST 800-53, PCI-DSS, DORA, NIS2, NCA (Saudi), NESA (UAE). |
+| `framework_coverage` | Which articles of a regulation automated scanning can and cannot evidence. |
+| `org_requirements` | Your organization's own rules for a resource type — *before* the code is written. |
+| `org_status` | Whether org policy is in force, or built-in rules only. |
+
+You do not call these. The assistant does, on its own, because the server tells it to.
+
+---
+
+## Organization policy
+
+Everything above works with no account. Connecting an organization adds **your
+company's own rules** to the same local evaluation:
+
+```bash
+export SOVEREIGN_TOKEN=...   # Integrations → GitHub in the dashboard
+```
+
+The difference this makes is in *when* the rule applies. Without it, the assistant writes
+Terraform and then finds out it was wrong. With it:
+
+```
+You:       "add an RDS instance for the orders service"
+Assistant: → org_requirements("aws_db_instance")
+           ← "backup_retention_period must be at least 365"
+             "region must be one of: eu-west-1, eu-central-1"
+           [writes Terraform that already satisfies both]
+           → scan_terraform → clean
+```
+
+The rule is supplied to the generator, not applied to the output. That is the whole point
+— a violation that never gets written costs nothing to fix.
+
+Company rules appear in scans tagged `source: org_policy`, so a developer can always tell
+a company requirement from a built-in one. They are authored in the dashboard as YAML and
+enforced identically in the editor, in CI, and in a cloud scan.
+
+**This does not change what leaves your machine.** Rules come down; code never goes up.
+The only request this server makes is a `GET` for your org's rules —
+`tests/test_org_policy.py::test_no_terraform_is_ever_uploaded` asserts that at the
+transport, and asserts an unconnected install opens no socket at all. If the API is
+unreachable or the token is rejected, the built-in rules still run locally and the scan
+still works.
+
+---
+
+## What it does not do
+
+Worth stating plainly, because a security tool that overstates its scope is worse than no
+tool:
+
+- **It is not a compliance assessment.** `check_compliance` returns control *mappings* —
+  evidence that shortens an audit. Every framework it maps also carries governance,
+  process and training obligations no configuration scanner can observe. A clean scan is
+  not a compliant organisation.
+- **NCA control identifiers are provisional**, pending reconciliation against the
+  authority's published catalogue. Cite the subdomain names.
+- **`apply_fixes` is deliberately narrow.** It applies only single-attribute, in-place
+  changes from a hand-verified allowlist, and never overwrites a value wired to a variable
+  or expression. Everything else stays advisory, because a mechanical fix that is
+  syntactically clean can still take a running system down.
+- **It scans Terraform**, not live cloud accounts, container images, or dependencies.
+
+For live multi-cloud posture management, attack-path analysis and audit-ready reporting,
+this is the editor-side slice of [Sovereign Observer](https://sovereignobserver.com).
+
+---
+
+## Privacy
+
+The scan runs in this process, on your machine. There is no API key, no account, and no
+network call in the default path — the server works with networking disabled. Your
+Terraform is never uploaded.
+
+---
+
+## Development
+
+From a checkout of the product repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+The IaC engine is **copied in from the backend at build time** by
+`scripts/vendor_engine.py`, into a gitignored `sovereign_mcp/_vendor/`. That is
+deliberate: the repository holds exactly one copy of the rule logic, so the editor and CI
+can never disagree about whether a resource is insecure. `sovereign_mcp/engine.py` vendors
+on demand in a source checkout, so there is no build step for day-to-day work.
+
+Never edit anything under `_vendor/`. Edit the backend module and re-run the script.
+
+```bash
+python -m pytest tests/ -q
+```
+
+`tests/test_parity.py` is the one that matters — it fails if the vendored copy drifts from
+its source, or if the Checkov pin stops matching the backend's.
+
+Licensed Apache-2.0. Built on [Checkov](https://github.com/bridgecrewio/checkov)
+(Apache-2.0).

sovereign_observer-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sovereign-observer"
+version = "0.1.0"
+description = "Scan AI-generated Terraform for security misconfigurations, in your editor, before it is committed."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Sovereign Observer" }]
+keywords = ["mcp", "terraform", "iac", "security", "checkov", "cspm", "compliance"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.2.0",
+    # Pinned to the same version the backend runs, so an MCP scan and a CI scan
+    # evaluate identical policy. See tests/test_parity.py.
+    "checkov==3.3.11",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4"]
+
+[project.scripts]
+sovereign-observer = "sovereign_mcp.server:main"
+
+[project.urls]
+Homepage = "https://sovereignobserver.com"
+
+# `packages` picks up sovereign_mcp/_vendor as well — hatchling does not read
+# .gitignore, so the generated engine copy ships in the wheel even though it is
+# never committed. Run scripts/vendor_engine.py BEFORE building, or the wheel
+# will be missing its engine. `make wheel` does both in order.
+[tool.hatch.build.targets.wheel]
+packages = ["sovereign_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sovereign_observer-0.1.0/scripts/vendor_engine.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Copy the backend's IaC engine modules into ``sovereign_mcp/_vendor``.
+
+Why this exists
+---------------
+The MCP server must run on a developer's laptop with no Flask app and no
+network, but it must evaluate *exactly* the policy the backend evaluates. Two
+hand-maintained copies of the rule logic would be worse than shipping no MCP at
+all — a finding that appears in the editor but not in CI (or the reverse)
+destroys trust in both.
+
+So the backend stays the single source of truth in git, and this script
+mechanically copies the modules at build time. ``sovereign_mcp/_vendor`` is
+**generated and gitignored** — never edit it, and never commit it.
+
+The copied modules are pure stdlib (verified: no Flask, no SQLAlchemy, no
+``current_app``). The directory layout below mirrors the backend's
+``services/`` + ``services/scanners/`` shape on purpose, so the relative import
+``from ..remediation_service import RemediationService`` inside
+``checkov_scanner`` keeps resolving without patching a single line.
+
+Run directly (``python scripts/vendor_engine.py``) or let ``sovereign_mcp.engine``
+call it automatically on first import in a source checkout.
+"""
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+
+# relpath under the backend  ->  relpath under _vendor/
+MODULES = {
+    "backend/app/services/remediation_service.py": "remediation_service.py",
+    "backend/app/services/scanners/checkov_scanner.py": "scanners/checkov_scanner.py",
+    "backend/app/services/scanners/hcl_locator.py": "scanners/hcl_locator.py",
+    "backend/app/services/scanners/hcl_to_plan.py": "scanners/hcl_to_plan.py",
+    "backend/app/services/scanners/regulatory_overlays.py": "scanners/regulatory_overlays.py",
+    "backend/app/services/scanners/compliance_crosswalk.py": "scanners/compliance_crosswalk.py",
+    # The HCL fix-applier the GitHub Action uses. Shared so a fix applied in the
+    # editor is byte-for-byte the fix the Action would have applied in CI.
+    "integrations/github-action/scan.py": "hcl_fixer.py",
+    # Org custom-policy evaluation. These four run the same YAML rules against
+    # the same inventory shape the server does, so an org rule means the same
+    # thing in the editor as it does in a scan. They sit at the _vendor root
+    # because policy_engine imports remediation_registry by absolute name.
+    "backend/app/services/scanners/terraform_inventory.py": "scanners/terraform_inventory.py",
+    "policy_engine.py": "policy_engine.py",
+    "remediation_registry.py": "remediation_registry.py",
+    "remediation_supplement.py": "remediation_supplement.py",
+}
+
+_GENERATED_HEADER = (
+    "# ⚠ GENERATED FILE — DO NOT EDIT.\n"
+    "# Copied verbatim from {source} by scripts/vendor_engine.py.\n"
+    "# Edit the backend module instead; this copy is regenerated at build time.\n"
+)
+
+
+def find_app_root(start: Optional[Path] = None) -> Optional[Path]:
+    """Walk up from ``start`` looking for the 'main application' directory.
+
+    Returns None when running from an installed wheel, where there is no
+    backend source tree to copy from (and none is needed — the wheel already
+    carries the vendored modules).
+    """
+    here = (start or Path(__file__).resolve()).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent / "backend" / "app" / "services" / "scanners" / "checkov_scanner.py"
+        if candidate.is_file():
+            return parent
+    return None
+
+
+def vendor(app_root: Optional[Path] = None, dest: Optional[Path] = None) -> Path:
+    """Copy the engine modules into ``dest``. Returns the vendor directory."""
+    app_root = app_root or find_app_root()
+    if app_root is None:
+        raise FileNotFoundError(
+            "Could not locate the backend source tree. Run this from a checkout "
+            "of the Sovereign Observer repository."
+        )
+
+    dest = dest or (Path(__file__).resolve().parent.parent / "sovereign_mcp" / "_vendor")
+    if dest.exists():
+        shutil.rmtree(dest)
+    (dest / "scanners").mkdir(parents=True, exist_ok=True)
+
+    # Package markers so relative imports inside the copied modules resolve.
+    (dest / "__init__.py").write_text(
+        '"""Generated vendor tree — see scripts/vendor_engine.py."""\n', encoding="utf-8"
+    )
+    (dest / "scanners" / "__init__.py").write_text("", encoding="utf-8")
+
+    for src_rel, dst_rel in MODULES.items():
+        src = app_root / src_rel
+        if not src.is_file():
+            raise FileNotFoundError(f"Expected engine module missing: {src}")
+        body = src.read_text(encoding="utf-8")
+        (dest / dst_rel).write_text(
+            _GENERATED_HEADER.format(source=src_rel) + body, encoding="utf-8"
+        )
+
+    return dest
+
+
+def main() -> int:
+    dest = vendor()
+    print(f"vendored {len(MODULES)} engine modules -> {dest}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sovereign_observer-0.1.0/sovereign_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Sovereign MCP — Terraform security scanning inside your AI assistant."""
+
+__version__ = "0.1.0"

sovereign_observer-0.1.0/sovereign_mcp/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Generated vendor tree — see scripts/vendor_engine.py."""