Ms Office Security Python

Microsoft Office Security — Python

Companion skill to ms-office-python (parent). For other areas see: ms-office-excel-python, ms-office-word-python, ms-office-powerpoint-python, ms-office-graph-python, ms-office-enterprise-sso-python.

This skill is the family's hardening surface. It ships THREE artifacts (Q1-A1 LOCKED):

1. Markdown human-readable checklist — for code review walkthroughs and design docs (references/checklist.md).
2. YAML rule manifest — machine-readable, the source of truth for what the validator detects (ms_office_security_check/rules.yaml).
3. Runnable Python validator — python3 -m ms_office_security_check <project_root> [flags], mirroring dep-currency-check's shape.

ALL VALIDATOR OUTPUT IS ADVISORY ONLY — NOT A SECURITY GATE. The validator surfaces findings to inform code review; it does not replace bandit, pip-audit, gitleaks, or semgrep, all of which run alongside it in a healthy CI pipeline. See §3 (Defer-to-X table) for the explicit boundary list.

1. Overview

The validator is narrowly scoped to Office / MSAL / Graph / Entra patterns — the things that bandit, semgrep, gitleaks, and pip-audit don't catch. It does NOT replace those tools; it complements them. Generic Python security issues, generic secret scanning, dependency CVE detection, and SBOM emission all belong elsewhere.

The validator runs entirely offline. No network calls, no live tenant validation, no token introspection. Output is JSON canonical (msosec.v1), with Markdown and SARIF as renderings.

2. The 17 v1 rules (narrowed from validator design doc's 32)

Per master design doc §8, bob ships exactly 17 rules in v1 (range 15-19 acceptable). The narrowing applies the following category-level rules: KEEP all Office-specific Auth (6 rules), KEEP Office-specific Transport (1), KEEP all Graph Scopes (3), DROP generic Secrets (defer to gitleaks / dep-currency-check), KEEP all Deprecated APIs (5), DROP Supply chain (defer to dep-currency-check / pip-audit), ADD Office documents (2).

The manifest is at ms_office_security_check/rules.yaml. Summary table — each rule has a stable ID (forever), severity, detection mechanism, and references back to the design.

Arithmetic: 6 Auth (A001, A002, A003, A004, A009, A010, A013 — that's 7) + 1 Transport (B001) + 3 Graph scopes (C001, C002, C003) + 5 Deprecated (E001, E002 suppressed, E003, E004, E005 — 4 active emitting) + 2 Office docs (OFFICE001, OFFICE002) = 7 + 1 + 3 + 4 + 2 = 17 rules (E002 listed but always suppressed when A001 fires — counted as 1, design §8 dedup note).

Rule-overlap check (WP-8 acceptance criterion): every retained rule covers an Office-specific or MSAL/Graph/Entra-specific pattern that bandit (B501 verify=False generic, B105 hardcoded password), semgrep (Python ruleset), gitleaks (generic secret regex), pip-audit (CVE), or dep-currency-check (currency + CVE) does not catch. The retained set is intentionally narrow.

3. Defer-to-X (what this validator does NOT do)

4. CLI

python3 -m ms_office_security_check <project_root> [flags]

Module name: ms_office_security_check (underscores). Skill directory: ms-office-security-python/. The Python package layout mirrors dep-currency-check/dep_currency_check/.

Flags (mirror dep-currency-check shape)

Exit codes (mirror dep-currency-check)

Suppression

# msosec: ignore MSOSEC-A009 at end-of-line OR on the previous line. # msosec: ignore MSOSEC-A009, MSOSEC-A010 for multiple. # msosec: ignore file at top of file suppresses ALL rules in that file. Project-level allowlist via [tool.ms-office-security.ignore] in pyproject.toml or ms-office-security.yaml.

5. Output schema (msosec.v1)

JSON canonical:

{
  "schema_version": "msosec.v1",
  "validator_version": "1.0.0",
  "generated_at": "2026-05-22T10:00:00Z",
  "project_root": "/path/to/project",
  "config_source": "ms-office-security.yaml",
  "files_scanned": 142,
  "rules_loaded": 17,
  "rules_run": 17,
  "rules_skipped": [],
  "summary": {"critical": 2, "high": 5, "medium": 3, "info": 1, "suppressed": 4},
  "findings": [
    {
      "rule_id": "MSOSEC-A009",
      "severity": "critical",
      "category": "auth",
      "file": "src/integrations/sso.py",
      "line": 42,
      "col": 12,
      "code_excerpt": "jwt.decode(token, key, options={\"verify_signature\": False})",
      "message": "JWT signature verification disabled.",
      "fix_hint": "Remove options={\"verify_signature\": False}. Pass algorithms=[\"RS256\"] and use PyJWKClient.",
      "references": [
        "skill://ms-office-enterprise-sso-python#jwt-validation",
        "https://pyjwt.readthedocs.io/en/stable/usage.html"
      ],
      "confidence": "high",
      "detection": "ast",
      "advisory_only": true
    }
  ],
  "suppressions": [],
  "advisories": []
}

Advisory-only banner — the advisory_only: true field appears on every finding. Markdown rendering opens with:

Advisory only — not a security gate. This report surfaces Office-specific patterns for code review. Generic security findings belong to bandit / semgrep / gitleaks / pip-audit / dep-currency-check.

6. Integration points

NOT integrated in v1 (deferred): G_MSOSEC gate in _meta/gates.py, scope_delta source, alf skill-level wiring.

7. Consolidated security checklist (Markdown human-readable summary)

The full Markdown checklist lives at references/checklist.md. Cross-references to per-skill HARD-RULEs and hardening bullets across the family. Summary of categories:

• Authentication — broker enforcement, ROPC removal, hardcoded secret detection, encrypted token cache, JWT validation.
• Authorization (Graph scopes) — least-privilege scope selection, Application Access Policy for application permissions, RSC for Teams apps.
• Transport — TLS verification on Graph calls, CA bundle integrity, OAuth XOAUTH2 for SMTP.
• Deprecated APIs — adal, exchangelib (Exchange Online), pymsteams, requests-kerberos, pywin32 COM automation in server contexts.
• Office documents — XXE defence via defusedxml, formula-injection sanitization (Excel), macro-strip handling for .docm/.xlsm/.pptm, password-protected workbook decryption.
• Logging & audit — never log raw tokens / refresh tokens / webhook URLs; redactor wrappers on debug-level HTTP logging; audit-log every privileged Graph operation.
• National clouds — authority URL + Graph endpoint matrix verified per resource; sovereign-cloud feature parity check.
• Operational — token cache hardening (msal-extensions), webhook subscription validation, throttling backoff caps, certificate rotation policy.

8. Anti-Patterns

9. Update Triggers (per Codex M-1 — alf will scan these)

• Microsoft deprecation announcements affecting: EWS, Office 365 Connectors API, ADAL, basic auth for SMTP / IMAP / POP, any msgraph-sdk major version, azure-identity major version, broker DLL distribution model.
• Major version bumps of: any of the libraries the rule manifest references.
• New Office-specific CVE class (e.g., a new XXE in lxml / openpyxl).
• dep-currency-check ↔ this validator boundary changes (e.g., dep-currency-check grows secret scanning — in which case revisit whether the deferred Category D should remain dropped).
• Annual review on: 2027-05-22.

See Also