licenselens 0.3.0__tar.gz

licenselens-0.3.0/.debug-journal.md

@@ -0,0 +1,47 @@
+# Debug Journal - pytest collection import
+Started: 2026-08-11T12:38:29-04:00
+Goal: Determine why the documented local baseline command fails to import `tests.fake_clients` and preserve a reliable full-suite gate.
+
+## Environment snapshot (Phase 0)
+- Runtime: Python >=3.12 project launched through `uv run`; exact interpreter query pending.
+- Entry: `uv run pytest -q`
+- Ports / sockets: none.
+- Git HEAD: `3f76fb0`; branch `main` is one commit ahead of `origin/main`; pre-existing untracked `.omo/`.
+- References read: `debugging/references/runtimes/python.md`, `debugging/references/methodology/00-setup.md`, `debugging/references/methodology/02-investigate.md`.
+
+## Hypotheses
+1. [OPEN] The `pytest` console-script launcher omits the repository root from `sys.path`, while `python -m pytest` includes it - distinguishing evidence: interpreter and `sys.path` captured under both launchers - if true, fix is: invocation contract.
+2. [OPEN] Python 3.14 resolves an installed or namespace package named `tests` instead of this repository's directory - distinguishing evidence: `sys.version`, `find_spec("tests")`, and import result on Python 3.14 versus a supported runtime - if true, fix is: package marker.
+3. [OPEN] Pytest's configured `pythonpath = ["src"]` and import mode make `tests.fake_clients` invalid because `tests/` is not a package - distinguishing evidence: successful collection after a temporary package marker or explicit root path, with launcher unchanged - if true, fix is: package marker.
+
+## Failed hypothesis round counter
+- Round 1: pending.
+- Round 2: pending.
+
+## Artifacts to revert
+- [ ] `.debug-journal.md` - remove after final verification.
+- [ ] `.git/info/exclude` local line for `.debug-journal.md` - remove after journal cleanup.
+- [ ] Existing `.venv/` and `.pytest_cache/` were touched by the baseline `uv run pytest -q`; preserve rather than deleting pre-existing user state.
+
+## Findings
+### 2026-08-11T12:35:06-04:00 - baseline full suite
+- Source: `uv run pytest -q`
+- Value: `ModuleNotFoundError: No module named 'tests'` while importing `tests/test_collectors_graph.py`.
+- Interpretation: collection fails before any test executes.
+- Refutes/Confirms: establishes the repro; hypotheses remain open.
+
+## Oracle Triple (if invoked)
+
+## Final fix
+
+### 2026-08-11T12:39:00-04:00 - interpreter and import resolution
+- Source: `uv run python -c '<runtime introspection>'`
+- Value: `3.14.6`; executable `/Users/waifumachine/licenselens/.venv/bin/python3`; `tests_spec` resolves to `/Users/waifumachine/licenselens/tests`; `fake_spec` resolves to `/Users/waifumachine/licenselens/tests/fake_clients.py`.
+- Interpretation: local namespace-package resolution works when Python is launched as a module from the repository root.
+- Refutes/Confirms: refutes H2 shadowing in the module launcher; H1/H3 remain open.
+
+### 2026-08-11T12:39:00-04:00 - module invocation control
+- Source: `uv run python -m pytest -q`
+- Value: `144 passed in 1.35s`.
+- Interpretation: production and tests are healthy under the module invocation; the failure is launcher/package-path specific.
+- Refutes/Confirms: supports H1 and H3; refutes a general suite defect.

licenselens-0.3.0/.dockerignore

@@ -0,0 +1,14 @@
+.venv
+.venv/
+__pycache__
+*.pyc
+*.egg-info
+.pytest_cache
+.ruff_cache
+reports
+dist
+build
+openspec
+docs
+examples
+tests

licenselens-0.3.0/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env for local live scans (never commit real secrets).
+# Prefer exporting these in your shell or CI secret store.
+
+AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
+AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
+
+# Required only for --auth client_secret
+AZURE_CLIENT_SECRET=
+
+# Optional: default public client is used for device-code if CLIENT_ID omitted
+# (not recommended for production assessments — register your own app).

licenselens-0.3.0/.github/ISSUE_TEMPLATE/check-request.md

@@ -0,0 +1,31 @@
+---
+name: Check request
+about: Propose a new Security License Lens check
+title: "check: "
+labels: check
+---
+
+## Capability / SKU
+
+Which Microsoft SKU or service plan unlocks this?
+
+## Expected configuration
+
+What should be true when the capability is realized?
+
+## Gap signal
+
+How do we detect default / unused / partial configuration?
+
+## Workload
+
+- [ ] Identity / Entra
+- [ ] Defender / XDR
+- [ ] Sentinel
+- [ ] Purview
+- [ ] Endpoint
+- [ ] Other
+
+## References
+
+Learn.microsoft.com or product docs links.

licenselens-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What changed and why -->
+
+## Type
+
+- [ ] New check
+- [ ] Catalog update
+- [ ] Collector / engine
+- [ ] Docs
+- [ ] Fix
+
+## Checklist
+
+- [ ] `ruff check src tests` passes
+- [ ] `pytest` passes
+- [ ] `licenselens scan --dry-run` still works
+- [ ] No secrets or customer tenant data included

licenselens-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src tests
+
+      - name: Ruff format check
+        run: ruff format --check src tests
+
+      - name: Pytest with coverage
+        run: pytest tests/ --cov=licenselens --cov-report=term-missing --cov-fail-under=72 -q
+
+      - name: Dry-run scan
+        # Exit 1 means gaps/partial findings (expected in demo data)
+        run: |
+          set +e
+          licenselens scan -o reports
+          code=$?
+          if [ "$code" -ne 0 ] && [ "$code" -ne 1 ]; then exit "$code"; fi
+
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+          ls -la dist/
+
+      - name: Smoke-test installed wheel
+        run: |
+          python -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/pip install dist/*.whl
+          /tmp/wheel-venv/bin/licenselens version
+          /tmp/wheel-venv/bin/licenselens checks
+          /tmp/wheel-venv/bin/licenselens diff --help
+          /tmp/wheel-venv/bin/licenselens batch --help
+          /tmp/wheel-venv/bin/licenselens discover-workspace --help
+          set +e
+          /tmp/wheel-venv/bin/licenselens scan -o /tmp/wheel-reports
+          code=$?
+          if [ "$code" -ne 0 ] && [ "$code" -ne 1 ]; then exit "$code"; fi
+          # HTML rendered means templates + catalog were packaged via licenselens/data
+          test -f /tmp/wheel-reports/security-license-lens-report.html

licenselens-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

licenselens-0.3.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Security License Lens outputs
+reports/
+reports-live/
+*.report.html
+*.report.json
+out/
+
+# Local planning / tooling (not part of the public product)
+openspec/
+.opencode/
+.omo/

licenselens-0.3.0/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+All notable changes to Security License Lens are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] — 2026-08-12
+
+### Added
+- **Scan diff (`licenselens diff`)** — compare two scan JSON artifacts by
+  `check_id`; groups new gaps, resolved, improved, worsened, unchanged, and
+  confidence changes; Markdown or JSON output
+- **Batch scans (`licenselens batch`)** — run one `tenants.yaml` across many
+  tenants; per-tenant `reports/<slug>/<timestamp>/` output plus `index.md`;
+  one failing tenant no longer aborts the batch
+- **Workspace discovery (`licenselens discover-workspace`)** — enumerate
+  subscriptions and Log Analytics workspaces, probe each for
+  `Microsoft.SecurityInsights/alertRules`, and print Sentinel-capable ARM IDs
+- **Doctor profiles (`licenselens doctor --profile`)** — `basic` (core Graph)
+  is the default; `full` also probes the Defender for Endpoint API and the
+  Sentinel workspace when `--workspace-resource-id` is provided
+- **Auto-discovery in scans** — `run_scan(..., discover_workspaces=True)`
+  selects a workspace only when exactly one Sentinel-capable workspace exists
+  (otherwise warns and refuses to guess)
+- **Structured output layout** — `output.build_report_dir` slug/timestamp
+  nesting with a `flat=True` legacy mode
+- **Demo and quickstart commands** — `licenselens demo`, `licenselens quickstart`
+- **Top-card rollup** — capability rollup (% realized), ranked moves (impact,
+  exposure, effort), EXPOSED chip for legacy auth and MFA-less GA
+- **Interactive `scan`** — in a TTY, prompts for demo vs live, auth method,
+  missing credentials, output dir, optional browser open / Sentinel / doctor;
+  non-TTY stays dry-run by default and never hangs
+- **Batch defaults** — `tenants.yaml` top-level `defaults:` merged into each
+  tenant; optional `packs` and `allow_email_proxy`
+- **HTML TAGLINE** — report now uses the product tagline in its header and footer
+- **Entitlement provenance** — every detected SKU traces back to its parent
+  SKU, so reports explain which entitlement licensed each capability; CLI
+  pack selection is validated against the catalog
+- **Doctor permission check** — required Graph permission tuples are synced
+  to collector definitions, and doctor reports any missing
+  `graphPermissions` per collector
+- **Tenant provisioning guide** — step-by-step docs for app registration,
+  permissions, and seeding a tenant for a first live assessment
+- **Credential gate** — `scripts/check_creds.py` gives a three-state verdict
+  for live validation: `CREDENTIALS_OK`, `BLOCKED` (missing `AZURE_*`
+  variables), or `CONNECTIVITY_FAILED`, never printing the client secret
+
+### Changed
+- **Default packs** are `identity` + `endpoint` (email off by default)
+- **MDO email check** no longer uses Secure Score by default. No Graph API
+  reads Safe Links / Safe Attachments / preset policy config (Exchange Online
+  PowerShell only). Opt-in: `--allow-email-proxy` (labeled, never rolls up to
+  fully working). Doctor reports email policy unreadability with a
+  portal/PowerShell one-line fix.
+- **Live SKIPPED warnings** now separate "cannot verify via Graph" (email
+  policy config) from genuinely unimplemented evaluators
+- **Reports are evidence-led** — every finding ties observed evidence to the
+  expected control and the capability it maps to, with actionable next steps
+- **CLI counts are truthful** — license priority figures reflect what was
+  actually detected, exposure rendering is consistent, and disclosure
+  markers flag degraded proxy paths
+- **Security Defaults guidance corrected** — guidance now distinguishes
+  tenants where Security Defaults is the right baseline from tenants licensed
+  for Conditional Access / Identity Protection
+- **Explicit proxy opt-outs respected** — quality policy and ranked-move
+  output honor `--allow-email-proxy` opt-outs and never present a degraded
+  path as fully working
+- **CI** now enforces `ruff format --check` and a 65% line coverage floor
+
+### Fixed
+- **Error handling hardened** — Security Defaults, Conditional Access, and
+  Access Reviews evaluators degrade to a clear per-check status instead of
+  crashing the scan on unexpected API responses
+- **Lint debt** — full Ruff lint and format cleanup across `src` and `tests`
+- **Reproducible installs** — `uv.lock` is now tracked in the repository
+- **Recurring scan instructions** — docs no longer misroute readers setting
+  up repeat assessments
+- **JSON compatibility** — `CapabilitySummary` keeps the legacy JSON shape
+  for existing consumers
+
+### Notes
+- `diff` rank ordering mirrors engine finding priority (gap < partial <
+  skipped < error < ok < not_licensed)
+- Batch entries support `auth_mode` aliases (`device`, `client_secret`,
+  `azure_cli`, `dry_run`)
+
+## [0.2.0] — 2026-08-05
+
+### Added
+- **Complete 10-check pack (Session F)**
+  - `sen-analytics-rule-coverage` — ARM SecurityInsights alert rules
+  - `sen-ueba-not-enabled` — ARM UEBA / entity analytics settings
+  - `pur-dlp-not-enforced` — Secure Score DLP/information-protection proxy
+- ARM client (`https://management.azure.com`) for Sentinel
+- CLI workspace binding: `--workspace-resource-id` or subscription/RG/name
+- Doctor probe for Sentinel workspace when workspace ID is provided
+- Dry-run demos for Sentinel + Purview; sample report updated
+
+### Notes
+- All 10 registered checks evaluate when licensed (no more `skipped` for the original pack)
+- Sentinel live scans require workspace + Microsoft Sentinel Reader (or equivalent)
+- MDO/MDI/Purview may still rely on Secure Score proxies
+
+## [0.2.0b1] — 2026-08-05
+
+### Added
+- **Defender pack (Session E)**
+  - `mdo-p2-policies-default` via Secure Score control signals (Safe Links/Attachments proxy)
+  - `mde-onboard-gap` via Defender for Endpoint API machine inventory vs licensed units
+  - `mdi-sensors-missing` via Secure Score control signals
+- Secure Score collector (`SecurityEvents.Read.All`)
+- MDE API client (`Machine.Read.All` on WindowsDefenderATP)
+- Doctor probes for Secure Score and MDE API
+
+### Notes
+- MDO/MDI use Secure Score as a proxy when direct policy/sensor APIs are unavailable
+- Sentinel and Purview checks remain registered but skipped
+
+## [0.1.0] — 2026-08-05
+
+First production-oriented release for **identity-first** Microsoft tenant assessments.
+
+### Added
+- Product branding: **Security License Lens** (`licenselens` CLI package)
+- Entitlement catalog mapping SKUs/service plans → capabilities with plain-language outcomes
+- Ten registered checks (identity, defender, sentinel, purview, endpoint)
+- **Live identity evaluators**
+  - `id-ca-priv-gaps` — Conditional Access MFA + legacy auth block
+  - `id-idprotect-off` — risk-based CA (Identity Protection outcomes)
+  - `id-pim-unused` — standing privileged roles vs PIM eligibility
+  - `id-dormant-privileged` — enabled privileged users with no recent successful sign-in
+- Live Microsoft Graph auth: device code, client secret, Azure CLI
+- Graph client with pagination and 429/5xx retries
+- Live `subscribedSkus` collection and capability resolution
+- `licenselens doctor` preflight (token, organization, SKUs, CA, role assignments)
+- Static HTML / JSON / Markdown reports with customer-facing copy first
+- Exit codes: `0` success, `1` gaps/partial, `2` auth/config/Graph error
+- Docs: app registration, permissions, architecture, comparison, contributing checks
+- Scrubbed dry-run sample report under `examples/sample-report/`
+
+### Notes
+- Defender, Sentinel, and Purview checks are registered but still return `skipped` until collectors ship (v0.2 roadmap)
+- Sign-in sampling for dormant privileged is page-capped; large tenants may see a truncation warning
+- Findings are advisory; not a Microsoft product and not a compliance certification
+
+## [0.1.0b3] — 2026-08-05
+
+- Session C: PIM + dormant privileged evaluators
+
+## [0.1.0b2] — 2026-08-05
+
+- Session B: Conditional Access + Identity Protection evaluators
+
+## [0.1.0b1] — 2026-08-05
+
+- Session A: live auth + subscribed SKUs + doctor
+
+## [0.1.0a1] — 2026-08-05
+
+- Initial scaffold: catalog, checks YAML, dry-run engine, HTML report, plain-language layer
+
+[0.3.0]: https://github.com/d4rk-pri0r/licenselens/releases/tag/v0.3.0
+[0.1.0]: https://github.com/d4rk-pri0r/licenselens/releases/tag/v0.1.0

licenselens-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Security License Lens a harassment-free experience for everyone.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Report unacceptable behavior to the maintainer via GitHub Security advisories or a private maintainer contact channel listed in SECURITY.md.
+
+Maintainers may remove, edit, or reject contributions that do not align with this Code of Conduct.
+
+## Attribution
+
+Adapted from the Contributor Covenant, version 2.1.

licenselens-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Security License Lens
+
+Thanks for helping map paid Microsoft security capabilities to real configuration.
+
+## Ways to contribute
+
+1. **New checks** (highest value) — YAML under `checks/<workload>/`
+2. **Catalog updates** — service plan / SKU mappings in `catalog/`
+3. **Collectors** — read-only Graph / Azure data sources
+4. **Docs and samples** — clearer MSP/consultant workflows
+5. **Bug fixes and tests**
+
+## Development setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check src tests
+pytest
+licenselens scan -o reports
+```
+
+## Adding a check
+
+Follow [docs/adding-a-check.md](docs/adding-a-check.md).
+
+Minimum bar for a new check PR:
+
+- Valid YAML with stable `id`
+- `required_capabilities` pointing at catalog entries
+- Clear remediation and at least one reference URL
+- Unit test or fixture when collector logic is included
+- No write/remediation API calls
+
+## Code style
+
+- Python 3.12+, type hints preferred
+- `ruff` for lint
+- Do not commit secrets, tenant IDs from real customers, or unredacted reports
+
+## Public docs and releases
+
+This repo is a standalone product. Keep GitHub-facing material presentation-neutral:
+
+- Do **not** mention conference talks, CFPs, slide decks, “talk-ready” milestones, or event names in README, CHANGELOG, docs, CLI help, release notes, or commit messages meant for GitHub.
+- Describe features in product terms (quick start, default packs, demo command).
+- Local planning tools (OpenSpec changes, editor agent config) stay out of the repo — see `.gitignore`.
+
+## Pull requests
+
+- One logical change per PR
+- Link related issues
+- Include dry-run output snippet when behavior changes
+
+## Code of conduct
+
+Be respectful. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

licenselens-0.3.0/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+LABEL org.opencontainers.image.source="https://github.com/d4rk-pri0r/licenselens"
+LABEL org.opencontainers.image.description="Security License Lens — detect Microsoft security configuration debt: capabilities you pay for but leave unused."
+LABEL org.opencontainers.image.licenses="MIT"
+
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE* ./
+COPY src ./src
+COPY checks ./checks
+COPY catalog ./catalog
+COPY templates ./templates
+
+RUN pip install --upgrade pip && pip install .
+
+# Reports land in /reports; mount a host directory there for dry-run or live scans.
+RUN mkdir /reports
+WORKDIR /reports
+
+ENTRYPOINT ["licenselens"]
+CMD ["demo", "-o", "/reports"]

licenselens-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 d4rk-pri0r
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.