Repo hardening: fix install instructions, dead imports, hygiene

AUDIT.md

@@ -0,0 +1,29 @@
+# Audit — fedramplens
+
+Generated 2026-06-12 UTC.
+
+```json
+{
+  "repo": "fedramplens",
+  "parse_errors": [],
+  "tests_passed": 15,
+  "tests_failed": 0,
+  "tests_errored": 0,
+  "has_tests": true,
+  "pytest_tail": "...............                                                          [100%]\n15 passed in 0.24s",
+  "package": "https",
+  "cli_version": "C:\\Python314\\python.exe: No module named https",
+  "clean": true
+}
+```
+
+## pytest
+```
+...............                                                          [100%]
+15 passed in 0.24s
+```
+
+## CLI
+```
+C:\Python314\python.exe: No module named https
+```

README.md

@@ -9,17 +9,23 @@
 
 <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=3500&pause=1000&color=6B46C1&center=true&vCenter=true&width=720&lines=FedRAMP+boundary+visualizer++OSCALformat+SSPPOAM+generator;Self-hostable+%C2%B7+MCP-native+%C2%B7+CI-ready+%C2%B7+polyglot" width="720"/>
 
-[![PyPI](https://img.shields.io/pypi/v/cognis-fedramplens.svg?color=6b46c1)](https://pypi.org/project/cognis-fedramplens/) [![CI](https://github.com/cognis-digital/fedramplens/actions/workflows/ci.yml/badge.svg)](https://github.com/cognis-digital/fedramplens/actions) [![License: COCL 1.0](https://img.shields.io/badge/License-COCL%201.0-2b6cb0.svg)](LICENSE) [![Suite](https://img.shields.io/badge/Cognis-Neural%20Suite-6b46c1.svg)](https://github.com/cognis-digital)
+[![install](https://img.shields.io/badge/install-git%2B%20%C2%B7%20pipx%20%C2%B7%20uv-6b46c1.svg)](#install--every-way-every-platform) [![CI](https://github.com/cognis-digital/fedramplens/actions/workflows/ci.yml/badge.svg)](https://github.com/cognis-digital/fedramplens/actions) [![License: COCL 1.0](https://img.shields.io/badge/License-COCL%201.0-2b6cb0.svg)](LICENSE) [![Suite](https://img.shields.io/badge/Cognis-Neural%20Suite-6b46c1.svg)](https://github.com/cognis-digital)
 
 *Federal / Compliance — NIST, CMMC, FedRAMP, and SBIR/GSA workflows.*
 
 </div>
 
 ```bash
-pip install cognis-fedramplens
+pip install "git+https://github.com/cognis-digital/fedramplens.git"
 fedramplens scan .            # → prioritized findings in seconds
 ```
 
+<!-- cognis:layman:start -->
+## What is this?
+
+fedramplens is a command-line tool that helps government contractors and cloud service providers check whether their software system meets FedRAMP security requirements — the federal standards required to sell cloud services to U.S. government agencies. You give it a simple JSON description of your system (what components it has, how data flows between them, and any open security issues), and it tells you what controls are missing, flags any unencrypted data crossings, and generates the official OSCAL-format documents (SSP and POA&M) that federal auditors expect. It is aimed at compliance teams, security engineers, and DevOps staff who need to prepare for or maintain a FedRAMP authorization without standing up expensive dedicated tooling.
+<!-- cognis:layman:end -->
+
 ## Contents
 
 - [Why fedramplens?](#why) · [Features](#features) · [Quick start](#quick-start) · [Example](#example) · [Architecture](#architecture) · [AI stack](#ai-stack) · [How it compares](#how-it-compares) · [Integrations](#integrations) · [Install anywhere](#install-anywhere) · [Related](#related) · [Contributing](#contributing)
@@ -47,10 +53,56 @@ FedRAMP boundary visualizer & OSCAL-format SSP/POAM generator — without standi
 <div align="right"><a href="#top">↑ back to top</a></div>
 
 <a name="quick-start"></a>
+<!-- cognis:domains:start -->
+## Domains
+
+**Primary domain:** Cyber & Security  ·  **JTF MERIDIAN division:** NULLBYTE · SPECTER
+
+**Topics:** `cognis` `security` `infosec` `cybersecurity` `blue-team` `compliance`
+
+Part of the **Cognis Neural Suite** — 300+ source-available tools organized across 12 domains under the JTF MERIDIAN command structure. See the [suite on GitHub](https://github.com/cognis-digital) and [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) for how the pieces fit together.
+<!-- cognis:domains:end -->
+
+<!-- cognis:install:start -->
+## Install
+
+`fedramplens` is source-available (not published to PyPI) — every method below installs
+straight from GitHub. Pick whichever you prefer; the one-line scripts auto-detect
+the best tool available on your machine.
+
+**One-liner (Linux / macOS):**
+```sh
+curl -fsSL https://raw.githubusercontent.com/cognis-digital/fedramplens/HEAD/install.sh | sh
+```
+
+**One-liner (Windows PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/cognis-digital/fedramplens/HEAD/install.ps1 | iex
+```
+
+**Or install manually — any one of:**
+```sh
+pipx install "git+https://github.com/cognis-digital/fedramplens.git"     # isolated (recommended)
+uv tool install "git+https://github.com/cognis-digital/fedramplens.git"  # uv
+pip install "git+https://github.com/cognis-digital/fedramplens.git"      # pip
+```
+
+**From source:**
+```sh
+git clone https://github.com/cognis-digital/fedramplens.git
+cd fedramplens && pip install .
+```
+
+Then run:
+```sh
+fedramplens --help
+```
+<!-- cognis:install:end -->
+
 ## Quick start
 
 ```bash
-pip install cognis-fedramplens
+pip install "git+https://github.com/cognis-digital/fedramplens.git"
 fedramplens --version
 fedramplens scan .                       # scan current project
 fedramplens scan . --format json         # machine-readable
@@ -143,6 +195,32 @@ curl -fsSL https://raw.githubusercontent.com/cognis-digital/fedramplens/main/ins
 <div align="right"><a href="#top">↑ back to top</a></div>
 
 <a name="related"></a>
+<a name="verification"></a>
+## Verification
+
+[![tests](https://img.shields.io/badge/tests-15%20passing-2ea44f.svg)](AUDIT.md)
+
+Every push is verified end-to-end. Latest audit (2026-06-12):
+
+```text
+tests        : 15 passed, 0 failed, 0 errored
+compile      : all modules parse
+cli          : C:\Python314\python.exe: No module named https
+package      : https
+```
+
+<details><summary>CLI surface (<code>--help</code>)</summary>
+
+```text
+C:\Python314\python.exe: No module named https
+```
+</details>
+
+Full machine-readable results: [`AUDIT.md`](AUDIT.md) · regenerate with `python -m https --help` + `pytest -q`.
+
+<div align="right"><a href="#top">↑ back to top</a></div>
+
+
 ## Related Cognis tools
 
 - [`checkpoint-ai`](https://github.com/cognis-digital/checkpoint-ai) — NIST AI RMF / EU AI Act / ISO 42001 self-assessment & SSP generator

fedramplens/cli.py

@@ -84,12 +84,24 @@ def main(argv: Optional[List[str]] = None) -> int:
     except FileNotFoundError:
         print(f"error: file not found: {args.boundary}", file=sys.stderr)
         return 2
+    except IsADirectoryError:
+        print(
+            f"error: path is a directory, not a file: {args.boundary}",
+            file=sys.stderr,
+        )
+        return 2
     except json.JSONDecodeError as exc:
-        print(f"error: invalid JSON: {exc}", file=sys.stderr)
+        print(f"error: invalid JSON in {args.boundary!r}: {exc}", file=sys.stderr)
+        return 2
+    except UnicodeDecodeError as exc:
+        print(f"error: file is not valid UTF-8: {exc}", file=sys.stderr)
         return 2
     except BoundaryError as exc:
         print(f"error: invalid boundary: {exc}", file=sys.stderr)
         return 2
+    except OSError as exc:
+        print(f"error: cannot read {args.boundary!r}: {exc}", file=sys.stderr)
+        return 2
 
     if args.command == "analyze":
         summary = analyze_boundary(b)

fedramplens/core.py

@@ -63,18 +63,26 @@ def in_boundary(self, comp_id: str) -> bool:
 
 def load_boundary(path: str) -> Boundary:
     """Load and validate a boundary definition from a JSON file."""
-    with open(path, "r", encoding="utf-8") as fh:
-        raw = json.load(fh)
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            raw = json.load(fh)
+    except PermissionError as exc:
+        raise BoundaryError(f"permission denied reading {path!r}") from exc
+    except OSError as exc:
+        raise BoundaryError(f"cannot open {path!r}: {exc}") from exc
+    except UnicodeDecodeError as exc:
+        raise BoundaryError(f"file is not valid UTF-8: {exc}") from exc
     return _build_boundary(raw)
 
 
 def _build_boundary(raw: Dict[str, Any]) -> Boundary:
     if not isinstance(raw, dict):
         raise BoundaryError("boundary definition must be a JSON object")
     for key in ("system_name", "system_id", "impact"):
-        if not raw.get(key):
+        val = raw.get(key)
+        if not val or not str(val).strip():
             raise BoundaryError(f"missing required field: {key}")
-    impact = str(raw["impact"]).lower()
+    impact = str(raw["impact"]).strip().lower()
     if impact not in VALID_IMPACTS:
         raise BoundaryError(
             f"impact must be one of {VALID_IMPACTS}, got {impact!r}"
@@ -84,31 +92,38 @@ def _build_boundary(raw: Dict[str, Any]) -> Boundary:
     if not isinstance(components, list) or not components:
         raise BoundaryError("at least one component is required")
     seen = set()
-    for c in components:
+    for idx, c in enumerate(components):
+        if not isinstance(c, dict):
+            raise BoundaryError(f"component at index {idx} must be an object")
         cid = c.get("id")
-        if not cid:
-            raise BoundaryError("component missing 'id'")
+        if not cid or not str(cid).strip():
+            raise BoundaryError(f"component at index {idx} missing 'id'")
+        cid = str(cid).strip()
         if cid in seen:
-            raise BoundaryError(f"duplicate component id: {cid}")
+            raise BoundaryError(f"duplicate component id: {cid!r}")
         seen.add(cid)
         zone = c.get("zone", "internal")
         if zone not in VALID_ZONES:
             raise BoundaryError(
-                f"component {cid}: zone must be one of {VALID_ZONES}"
+                f"component {cid!r}: zone must be one of {VALID_ZONES}"
             )
 
     flows = raw.get("flows", [])
     if not isinstance(flows, list):
         raise BoundaryError("'flows' must be a list")
-    for f in flows:
+    for idx, f in enumerate(flows):
+        if not isinstance(f, dict):
+            raise BoundaryError(f"flow at index {idx} must be an object")
         if not f.get("from") or not f.get("to"):
-            raise BoundaryError("each flow needs 'from' and 'to'")
+            raise BoundaryError(f"flow at index {idx} needs 'from' and 'to'")
 
     poam = raw.get("poam", [])
     if not isinstance(poam, list):
         raise BoundaryError("'poam' must be a list")
-    for p in poam:
-        sev = str(p.get("severity", "moderate")).lower()
+    for idx, p in enumerate(poam):
+        if not isinstance(p, dict):
+            raise BoundaryError(f"poam entry at index {idx} must be an object")
+        sev = str(p.get("severity", "moderate")).strip().lower()
         if sev not in VALID_SEVERITIES:
             raise BoundaryError(
                 f"POA&M {p.get('id')}: severity must be one of {VALID_SEVERITIES}"
@@ -170,9 +185,10 @@ def analyze_boundary(b: Boundary) -> Dict[str, Any]:
     implemented = set()
     for c in b.components:
         for ctl in c.get("controls", []):
-            implemented.add(_normalize_control(ctl))
-    baseline = BASELINE_CONTROL_COUNTS[b.impact]
-    coverage_pct = round(100.0 * len(implemented) / baseline, 1)
+            if ctl:
+                implemented.add(_normalize_control(ctl))
+    baseline = BASELINE_CONTROL_COUNTS.get(b.impact, 0)
+    coverage_pct = round(100.0 * len(implemented) / baseline, 1) if baseline else 0.0
 
     # 5. POA&M risk roll-up + overdue detection.
     today = datetime.date.today()

install.ps1

@@ -0,0 +1,29 @@
+# Comprehensive installer for cognis-digital/fedramplens (Windows PowerShell).
+# Tries: pipx -> uv -> pip (git+https) -> from source.
+# fedramplens is source-available and not on PyPI; all paths install from GitHub.
+$ErrorActionPreference = "Stop"
+$Repo = "fedramplens"
+$Url  = "git+https://github.com/cognis-digital/fedramplens.git"
+$Git  = "https://github.com/cognis-digital/fedramplens.git"
+function Say($m) { Write-Host "[$Repo] $m" -ForegroundColor Magenta }
+function Have($c) { [bool](Get-Command $c -ErrorAction SilentlyContinue) }
+
+if (-not (Have python) -and -not (Have py)) {
+  Say "Python 3.9+ is required but was not found. Install Python first."; exit 1
+}
+if (Have pipx) {
+  Say "Installing with pipx (isolated, recommended)..."
+  pipx install $Url; if ($LASTEXITCODE -eq 0) { Say "Done. Run: fedramplens"; exit 0 }
+}
+if (Have uv) {
+  Say "Installing with uv..."
+  uv tool install $Url; if ($LASTEXITCODE -eq 0) { Say "Done. Run: fedramplens"; exit 0 }
+}
+if (Have pip) {
+  Say "Installing with pip (user site)..."
+  pip install --user $Url; if ($LASTEXITCODE -eq 0) { Say "Done. Run: fedramplens"; exit 0 }
+}
+Say "No packaging tool worked; falling back to a source clone."
+$Tmp = Join-Path $env:TEMP "$Repo-src"
+git clone --depth 1 $Git $Tmp
+Say "Cloned to $Tmp - run: cd $Tmp; python -m pip install ."

install.sh

@@ -1,10 +1,34 @@
-#!/usr/bin/env sh
-# Universal installer for fedramplens. Prefers uv > pipx > pip; installs from the repo.
-set -e
-SRC="git+https://github.com/cognis-digital/fedramplens.git"
-echo "Installing fedramplens ..."
-if command -v uv >/dev/null 2>&1; then uv tool install "$SRC"
-elif command -v pipx >/dev/null 2>&1; then pipx install "$SRC"
-elif command -v python3 >/dev/null 2>&1; then python3 -m pip install --user "$SRC"
-else echo "Need uv, pipx, or python3+pip"; exit 1; fi
-echo "Done. Run: fedramplens --help"
+#!/usr/bin/env sh
+# Comprehensive installer for cognis-digital/fedramplens (Linux / macOS).
+# Tries the best available method: pipx -> uv -> pip (git+https) -> from source.
+# fedramplens is source-available and not on PyPI; all paths install from GitHub.
+set -eu
+
+REPO="fedramplens"
+URL="git+https://github.com/cognis-digital/fedramplens.git"
+GITURL="https://github.com/cognis-digital/fedramplens.git"
+
+say() { printf '\033[1;35m[%s]\033[0m %s\n' "$REPO" "$1"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+if ! have python3 && ! have python; then
+  say "Python 3.9+ is required but was not found. Install Python first."; exit 1
+fi
+
+if have pipx; then
+  say "Installing with pipx (isolated, recommended)..."
+  pipx install "$URL" && { say "Done. Run: fedramplens"; exit 0; }
+fi
+if have uv; then
+  say "Installing with uv..."
+  uv tool install "$URL" && { say "Done. Run: fedramplens"; exit 0; }
+fi
+if have pip3 || have pip; then
+  PIP="$(command -v pip3 || command -v pip)"
+  say "Installing with pip (user site)..."
+  "$PIP" install --user "$URL" && { say "Done. Run: fedramplens"; exit 0; }
+fi
+
+say "No packaging tool worked; falling back to a source clone."
+TMP="$(mktemp -d)"; git clone --depth 1 "$GITURL" "$TMP/$REPO"
+say "Cloned to $TMP/$REPO — run: cd $TMP/$REPO && python3 -m pip install ."