Metadata-Version: 2.5
Name: licenselens
Version: 0.3.0
Summary: Security License Lens — detect Microsoft security configuration debt: capabilities you pay for but leave unused.
Project-URL: Homepage, https://github.com/d4rk-pri0r/licenselens
Project-URL: Repository, https://github.com/d4rk-pri0r/licenselens
Project-URL: Issues, https://github.com/d4rk-pri0r/licenselens/issues
Author: d4rk-pri0r
License-Expression: MIT
License-File: LICENSE
Keywords: defender,entra,graph,license,microsoft,purview,security,sentinel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: azure-identity>=1.19.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.4
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.12.5
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Security License Lens

**The security you already own (and ignore).**

CLI: `licenselens` · Requires Python 3.12+

Security License Lens finds **Microsoft security configuration debt**: high-value capabilities in E5, Entra ID P2, Defender, and related SKUs that stay at default or unused. It starts from **owned entitlements**, maps them to expected controls, and reports gaps as *you pay for X → expected Y → observed Z*.

> Sample report (dry-run): [examples/sample-report/](examples/sample-report/)

## Quick start

```bash
# One-command offline demo → HTML report
pipx install licenselens   # or: pip install -e ".[dev]"
licenselens demo

# Interactive scan: prompts for anything missing (TTY)
licenselens scan

# Or jump straight to a live tenant walkthrough
licenselens quickstart
```

In a terminal, `licenselens scan` asks demo vs live tenant, sign-in method, and
other missing options. Flags and `AZURE_*` env vars always win when set.
Non-interactive environments default to dry-run (or exit with a clear error on
`--live` without credentials).

Default priority packs are **identity + endpoint**. They shape the headline rollup and top actions; enabled checks still evaluate unless `--workload` filters them. Email policy config is not readable via Graph (PowerShell-only); use `--allow-email-proxy` only if you explicitly want a labeled Secure Score degraded path.

### Live / MSP

```bash
licenselens doctor --live --auth client_secret
licenselens scan --live --auth client_secret -o reports
licenselens batch tenants.yaml -o reports
```

## Why Security License Lens?

| Tool | Optimizes for |
|------|----------------|
| [ScubaGear](https://github.com/cisagov/ScubaGear) | CISA baseline compliance |
| [Maester](https://github.com/maester365/maester) | Continuous config tests (Pester) |
| [Monkey365](https://github.com/silverhack/monkey365) | Broad CSPM / CIS-style assessment |
| Microsoft Secure Score | Score + recommendations (not SKU-gated) |
| License waste scripts | Seat assignment efficiency |
| **Security License Lens** | **Owned SKUs → expected high-value controls → unused/default gaps** |

### Diff, discovery, and batch

```bash
# Compare two scan JSON artifacts by check_id
licenselens diff reports/before.json reports/after.json -o reports/diff.md

# Discover Sentinel-capable workspaces (prints ARM resource IDs)
licenselens discover-workspace --auth client_secret

# Multi-tenant scans from tenants.yaml (per-tenant reports + index.md)
licenselens batch tenants.yaml -o reports
```

## Full check pack (v0.3.0)

| Check ID | Workload | Live evaluation |
|----------|----------|-----------------|
| `id-ca-priv-gaps` | Identity | Conditional Access MFA + legacy auth |
| `id-idprotect-off` | Identity | Risk-based CA |
| `id-pim-unused` | Identity | Standing roles vs PIM eligibility |
| `id-dormant-privileged` | Identity | Unused privileged users |
| `id-security-defaults-on` | Identity | Security defaults ON despite CA licenses |
| `id-access-reviews-unused` | Identity | Access Reviews licensed but never configured |
| `mdo-p2-policies-default` | Defender | Off default packs; opt-in `--allow-email-proxy` only |
| `mde-onboard-gap` | Endpoint | MDE API vs licensed units |
| `mdi-sensors-missing` | Defender | Secure Score proxy |
| `sen-analytics-rule-coverage` | Sentinel | ARM analytics rules (workspace required) |
| `sen-ueba-not-enabled` | Sentinel | ARM UEBA/entity analytics settings |
| `pur-dlp-not-enforced` | Purview | Secure Score DLP proxy |

Unlicensed capabilities report `not_licensed` instead of false gaps.

### Known limitations

See [docs/limitations.md](docs/limitations.md) for the full list. Short version:

- **Email pack off by default** — no Graph API for MDO policy config (PowerShell-only); `--allow-email-proxy` is opt-in and labeled
- MDI / Purview may still use **Secure Score proxies** (starter packs)
- Sentinel needs a **workspace ARM ID** + Azure RBAC
- Sign-in / MDE inventories may **truncate** on huge tenants
- Findings are **advisory**, not a compliance certification
- **No product telemetry** by default

## Architecture

```
SKUs / service plans → capability catalog → eligible checks
        → collectors (Graph / MDE / ARM) → findings → HTML / JSON / Markdown
```

## Permissions

See [docs/permissions.md](docs/permissions.md) and [docs/app-registration.md](docs/app-registration.md).

### Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success (no gap/partial findings) |
| 1 | Completed with gap or partial findings |
| 2 | Auth / configuration / API error |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/adding-a-check.md](docs/adding-a-check.md).

## Security

[SECURITY.md](SECURITY.md) — read-only, no telemetry by default.

## License

[MIT](LICENSE)

## Disclaimer

Security License Lens is an independent open-source project and is **not** affiliated with, endorsed by, or sponsored by Microsoft Corporation. Findings are advisory. “Microsoft”, “Entra”, “Defender”, “Sentinel”, and “Purview” are trademarks of their respective owners.
