oss-policy-kit 2.0.1__py3-none-any.whl

oss_policy_kit/__init__.py

@@ -0,0 +1,3 @@
+"""OSS Policy Kit - local evaluation of OSS security baseline controls."""
+
+__version__ = "2.0.1"

oss_policy_kit/__main__.py

@@ -0,0 +1,6 @@
+"""python -m oss_policy_kit"""
+
+from oss_policy_kit.cli.main import main
+
+if __name__ == "__main__":
+    main()

oss_policy_kit/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters for external evidence (e.g. OpenSSF Scorecard JSON)."""

oss_policy_kit/adapters/local_paths.py

@@ -0,0 +1,18 @@
+"""Safe path resolution for repository targets."""
+
+from pathlib import Path
+
+from oss_policy_kit.domain.errors import InvalidInputError
+
+
+def resolve_existing_dir(path_str: str) -> Path:
+    """Resolve user-supplied path to an absolute directory."""
+
+    candidate = Path(path_str).expanduser()
+    try:
+        resolved = candidate.resolve()
+    except OSError as exc:
+        raise InvalidInputError(f"Invalid path: {path_str} ({exc})") from exc
+    if not resolved.is_dir():
+        raise InvalidInputError(f"Not a directory or does not exist: {resolved}")
+    return resolved

oss_policy_kit/adapters/scorecard_json.py

@@ -0,0 +1,80 @@
+"""Optional ingestion of OpenSSF Scorecard JSON exports."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from oss_policy_kit.infrastructure.yaml_io import load_yaml_file
+
+
+@dataclass(slots=True)
+class ScorecardCheck:
+    """Normalized check entry."""
+
+    name: str
+    score: int | None
+    reason: str | None = None
+
+
+@dataclass(slots=True)
+class ScorecardBundle:
+    """Parsed Scorecard payload."""
+
+    checks: list[ScorecardCheck] = field(default_factory=list)
+    raw_path: str | None = None
+
+
+def _coerce_checks(blob: Any) -> list[ScorecardCheck]:
+    if blob is None:
+        return []
+    if isinstance(blob, dict) and "checks" in blob:
+        blob = blob["checks"]
+    if not isinstance(blob, list):
+        return []
+    out: list[ScorecardCheck] = []
+    for item in blob:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name", "")).strip()
+        if not name:
+            continue
+        score = item.get("score")
+        score_i = int(score) if isinstance(score, int) else None
+        reason = item.get("reason") or item.get("details")
+        reason_s = str(reason) if reason is not None else None
+        out.append(ScorecardCheck(name=name, score=score_i, reason=reason_s))
+    return out
+
+
+def load_scorecard_json(path: Path) -> ScorecardBundle:
+    """Load Scorecard JSON (common CLI export shapes)."""
+
+    text = path.read_text(encoding="utf-8")
+    data = json.loads(text)
+    checks: list[ScorecardCheck] = []
+    if isinstance(data, dict):
+        if "scorecard" in data and isinstance(data["scorecard"], dict):
+            checks = _coerce_checks(data["scorecard"].get("checks"))
+        if not checks:
+            checks = _coerce_checks(data.get("checks"))
+    return ScorecardBundle(checks=checks, raw_path=str(path.resolve()))
+
+
+def load_scorecard_auto(path: Path) -> ScorecardBundle:
+    """Load JSON or YAML scorecard-like file."""
+
+    suf = path.suffix.lower()
+    if suf in {".yaml", ".yml"}:
+        data = load_yaml_file(path)
+        checks = _coerce_checks(data if isinstance(data, dict) else None)
+        return ScorecardBundle(checks=checks, raw_path=str(path.resolve()))
+    return load_scorecard_json(path)
+
+
+def checks_as_map(bundle: ScorecardBundle | None) -> dict[str, ScorecardCheck]:
+    if bundle is None:
+        return {}
+    return {c.name.lower(): c for c in bundle.checks}

oss_policy_kit/application/__init__.py

@@ -0,0 +1 @@
+"""Application services: load, evaluate, report."""

oss_policy_kit/application/batch_evaluate.py

@@ -0,0 +1,372 @@
+"""Evaluate multiple repository roots against one or more profiles (monorepo / batch)."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+from collections import Counter, defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, cast
+
+import oss_policy_kit
+from oss_policy_kit.adapters.local_paths import resolve_existing_dir
+from oss_policy_kit.application.cli_output import FailOnPolicy, fail_on_violated
+from oss_policy_kit.application.engine import evaluate_repository
+from oss_policy_kit.application.loader import load_catalog, load_profile_by_id, merge_kit_root
+from oss_policy_kit.application.reporting import compute_priority_insights, report_to_dict, write_markdown_report
+from oss_policy_kit.domain.errors import InvalidInputError
+
+REPO_SIGNALS: tuple[str, ...] = (
+    ".git",
+    "README.md",
+    "README.rst",
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.py",
+    "Dockerfile",
+    "go.mod",
+    "pom.xml",
+    "Cargo.toml",
+    "build.gradle",
+    "buildspec.yml",
+    "azure-pipelines.yml",
+)
+REPO_GLOB_SIGNALS: tuple[str, ...] = ("*.csproj", "*.sln")
+
+
+def is_likely_repository(path: Path) -> tuple[bool, str]:
+    """Return ``(True, signal_found)`` when *path* looks like a repository root."""
+
+    for signal in REPO_SIGNALS:
+        if (path / signal).exists():
+            return True, signal
+    for pattern in REPO_GLOB_SIGNALS:
+        if list(path.glob(pattern)):
+            return True, pattern
+    return False, ""
+
+
+def _batch_failure_counts(fails_by_target: dict[str, int]) -> list[int]:
+    return list(fails_by_target.values())
+
+
+def _failure_distribution_bucketing(fail_counts: list[int]) -> dict[str, int]:
+    buckets = {"0": 0, "1-5": 0, "6-10": 0, "11+": 0}
+    for n in fail_counts:
+        if n == 0:
+            buckets["0"] += 1
+        elif n <= 5:
+            buckets["1-5"] += 1
+        elif n <= 10:
+            buckets["6-10"] += 1
+        else:
+            buckets["11+"] += 1
+    return buckets
+
+
+def _gate_violated_for_batch(policy: FailOnPolicy, summaries: list[dict[str, int]]) -> bool:
+    if policy == "none":
+        return False
+    return any(fail_on_violated(policy, s) for s in summaries)
+
+
+@dataclass(slots=True)
+class BatchRunRow:
+    """One target × profile evaluation summary."""
+
+    target_name: str
+    target_path: str
+    profile_id: str
+    summary_by_status: dict[str, int]
+    report_path_json: str
+    report_path_md: str
+
+
+@dataclass(slots=True)
+class BatchResult:
+    """Paths to consolidated batch artifacts plus CI gate outcome."""
+
+    batch_json: Path
+    batch_md: Path
+    gate_violated: bool
+
+
+def discover_batch_targets(
+    target_root: Path,
+    *,
+    include: str | None,
+    exclude: str | None,
+) -> list[Path]:
+    """Return immediate child directories of *target_root* suitable as repo roots."""
+
+    out: list[Path] = []
+    for child in sorted(target_root.iterdir(), key=lambda p: p.name.lower()):
+        if not child.is_dir():
+            continue
+        if child.name.startswith("."):
+            continue
+        if include and not fnmatch.fnmatch(child.name, include):
+            continue
+        if exclude and fnmatch.fnmatch(child.name, exclude):
+            continue
+        out.append(child)
+    return out
+
+
+def run_batch_evaluation(
+    *,
+    target_root: Path,
+    profile_ids: list[str],
+    output_dir: Path,
+    kit_root: Path | None,
+    include: str | None,
+    exclude: str | None,
+    fail_on: str = "none",
+    skip_non_repos: bool = False,
+    progress_callback: Callable[[str, int, int], None] | None = None,
+) -> BatchResult:
+    """Evaluate each discovered child of *target_root* against every *profile_id*.
+
+    Writes per-run ``evaluation-report.{json,md}`` under
+    ``output_dir / <sanitized_target_name> / <profile_id> /`` plus consolidated
+    ``evaluation-batch.json`` and ``evaluation-batch.md`` at *output_dir*.
+    """
+
+    policy = cast(FailOnPolicy, fail_on.lower())
+    root = merge_kit_root(kit_root)
+    catalog = load_catalog(root / "controls" / "catalog.yaml")
+    targets = discover_batch_targets(target_root, include=include, exclude=exclude)
+    if not targets:
+        raise InvalidInputError(f"No subdirectories to evaluate under {target_root}")
+
+    skipped_dirs: list[dict[str, str]] = []
+    eval_queue: list[tuple[Path, bool]] = []
+    for child in targets:
+        likely, _sig = is_likely_repository(child)
+        if skip_non_repos and not likely:
+            skipped_dirs.append(
+                {
+                    "name": child.name,
+                    "path": str(child.resolve()),
+                    "reason": "No repository root signals (README, manifest, Dockerfile, lockfile path, etc.).",
+                }
+            )
+            continue
+        eval_queue.append((child, likely))
+
+    if not eval_queue:
+        raise InvalidInputError(
+            "No repositories to evaluate after filtering. Remove --skip-non-repos or add include/exclude patterns."
+        )
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    rows: list[BatchRunRow] = []
+    consolidated_reports: list[dict[str, Any]] = []
+    summaries_for_gate: list[dict[str, int]] = []
+    total_runs = len(eval_queue) * len(profile_ids)
+    run_index = 0
+
+    for target, likely_repo in eval_queue:
+        repo = resolve_existing_dir(str(target))
+        safe_name = target.name.replace("/", "_").replace("\\", "_")
+        for pid in profile_ids:
+            run_index += 1
+            if progress_callback is not None:
+                progress_callback(target.name, run_index, total_runs)
+            profile = load_profile_by_id(root, pid)
+            report = evaluate_repository(
+                repo_root=repo,
+                profile=profile,
+                catalog=catalog,
+                waiver_outcome=None,
+                scorecard=None,
+            )
+            dest = output_dir / safe_name / pid
+            dest.mkdir(parents=True, exist_ok=True)
+            json_path = dest / "evaluation-report.json"
+            md_path = dest / "evaluation-report.md"
+            json_path.write_text(
+                json.dumps(report_to_dict(report), indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+            write_markdown_report(report, md_path)
+            rows.append(
+                BatchRunRow(
+                    target_name=target.name,
+                    target_path=str(repo.resolve()),
+                    profile_id=pid,
+                    summary_by_status=dict(report.summary_by_status),
+                    report_path_json=str(json_path.resolve()),
+                    report_path_md=str(md_path.resolve()),
+                )
+            )
+            summaries_for_gate.append(dict(report.summary_by_status))
+            run_payload: dict[str, Any] = {
+                "target_name": target.name,
+                "target_path": str(repo.resolve()),
+                "profile_id": pid,
+                "summary_by_status": report.summary_by_status,
+                "action_insights": compute_priority_insights(report),
+                "reports": {"json": str(json_path.resolve()), "markdown": str(md_path.resolve())},
+            }
+            if not skip_non_repos and not likely_repo:
+                run_payload["likely_not_a_repository"] = True
+            consolidated_reports.append(run_payload)
+
+    generated_at = datetime.now(UTC).replace(microsecond=0).isoformat()
+    gate_violated = _gate_violated_for_batch(policy, summaries_for_gate)
+
+    totals: dict[str, int] = defaultdict(int)
+    for row in rows:
+        for k, v in row.summary_by_status.items():
+            totals[k] += v
+
+    fails_by_target: dict[str, int] = defaultdict(int)
+    for row in rows:
+        fails_by_target[row.target_name] += row.summary_by_status.get("fail", 0)
+
+    fc_values = _batch_failure_counts(fails_by_target)
+    all_tied = len(fails_by_target) >= 2 and len(set(fc_values)) == 1
+    common_fail_count: int | None = fc_values[0] if all_tied else None
+
+    comparison_lines: list[str] = []
+    if fails_by_target:
+        if all_tied:
+            comparison_lines.append(
+                f"All **{len(fails_by_target)}** repositories share the same failure count "
+                f"({common_fail_count}) — no clear best or worst performer."
+            )
+        else:
+            max_f = max(fails_by_target.values())
+            min_f = min(fails_by_target.values())
+            worst_targets = sorted(n for n, c in fails_by_target.items() if c == max_f)
+            best_targets = sorted(n for n, c in fails_by_target.items() if c == min_f)
+            comparison_lines.append(
+                f"- **Most failures (tie-break: lexicographic name)**: {', '.join(f'`{n}`' for n in worst_targets)}"
+            )
+            comparison_lines.append(f"- **Fewest failures**: {', '.join(f'`{n}`' for n in best_targets)}")
+
+    dist = _failure_distribution_bucketing(fc_values)
+
+    gap_hits: Counter[str] = Counter()
+    for cr in consolidated_reports:
+        ac = cr.get("action_insights") or {}
+        for ids in (ac.get("failing_controls_by_category") or {}).values():
+            for cid in ids:
+                gap_hits[str(cid)] += 1
+
+    batch_payload: dict[str, Any] = {
+        "schema_version": "https://github.com/lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit/reports/batch/0.1",
+        "generated_at": generated_at,
+        "kit_version": oss_policy_kit.__version__,
+        "target_root": str(target_root.resolve()),
+        "profile_ids": profile_ids,
+        "gate_violated": gate_violated,
+        "fail_on": policy,
+        "all_tied": all_tied,
+        "common_fail_count": common_fail_count,
+        "failure_distribution": dist,
+        "runs": consolidated_reports,
+    }
+    if skipped_dirs:
+        batch_payload["skipped_directories"] = skipped_dirs
+
+    batch_json = output_dir / "evaluation-batch.json"
+    batch_json.write_text(json.dumps(batch_payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    md_lines = [
+        "# OSS Policy Kit - batch evaluation",
+        "",
+        f"- **Generated (UTC)**: `{generated_at}`",
+        f"- **Kit version**: `{oss_policy_kit.__version__}`",
+        f"- **Target root**: `{target_root.resolve()}`",
+        f"- **Profiles**: {', '.join(f'`{p}`' for p in profile_ids)}",
+        (
+            f"- **Targets evaluated**: {len(eval_queue)} child folder(s) x {len(profile_ids)} "
+            f"profile(s) = {len(rows)} run(s)"
+        ),
+        "",
+        "## Consolidated status totals (all runs)",
+        "",
+    ]
+    for status in sorted(totals.keys()):
+        md_lines.append(f"- `{status}`: **{totals[status]}**")
+    md_lines.append("")
+
+    label = policy
+    gate_state = "**VIOLATED**" if gate_violated else "**PASSED**"
+    md_lines.append(f"- **CI gate (`--fail-on: {label}`)**: {gate_state}")
+    md_lines.append("")
+
+    md_lines.append("## Failure distribution (per target, total `fail` across profiles)")
+    md_lines.append("")
+    md_lines.append("| Fail count range | Repositories |")
+    md_lines.append("| --- | ---: |")
+    md_lines.append(f"| 0 | {dist['0']} |")
+    md_lines.append(f"| 1-5 | {dist['1-5']} |")
+    md_lines.append(f"| 6-10 | {dist['6-10']} |")
+    md_lines.append(f"| 11+ | {dist['11+']} |")
+    md_lines.append("")
+
+    if comparison_lines:
+        md_lines.append("## Quick comparison (by total `fail` counts across profiles)")
+        md_lines.append("")
+        for ln in comparison_lines:
+            if ln.startswith("All **"):
+                md_lines.append(f"- {ln}")
+            else:
+                md_lines.append(ln)
+        md_lines.append("")
+
+    if skipped_dirs:
+        md_lines.append("## Skipped directories")
+        md_lines.append("")
+        for s in skipped_dirs:
+            md_lines.append(f"- `{s['name']}` — {s['reason']}")
+        md_lines.append("")
+
+    md_lines.extend(
+        [
+            "## Matrix (per target folder)",
+            "",
+            "| Target | Profile | fail | manual-review | pass | other |",
+            "| --- | --- | ---: | ---: | ---: | --- |",
+        ]
+    )
+    for row in rows:
+        summary = row.summary_by_status
+        fails = summary.get("fail", 0)
+        mrr = summary.get("manual-review-required", 0)
+        passes = summary.get("pass", 0)
+        other = sum(v for k, v in summary.items() if k not in {"fail", "manual-review-required", "pass"})
+        md_lines.append(f"| `{row.target_name}` | `{row.profile_id}` | {fails} | {mrr} | {passes} | {other} |")
+    md_lines.append("")
+    if gap_hits:
+        md_lines.append("## Repeated failing controls (across runs)")
+        md_lines.append("")
+        md_lines.append("| Control id | Runs (count) |")
+        md_lines.append("| --- | ---: |")
+        for cid, n in gap_hits.most_common(15):
+            md_lines.append(f"| `{cid}` | {n} |")
+        md_lines.append("")
+    md_lines.append("## Report artifacts (paths relative to batch output directory)")
+    md_lines.append("")
+    out_abs = output_dir.resolve()
+    for row in rows:
+        jp = Path(row.report_path_json).resolve()
+        mp = Path(row.report_path_md).resolve()
+        try:
+            rel_json = jp.relative_to(out_abs)
+            rel_md = mp.relative_to(out_abs)
+            j_show, m_show = rel_json.as_posix(), rel_md.as_posix()
+        except ValueError:
+            j_show, m_show = str(jp), str(mp)
+        md_lines.append(f"- `{row.target_name}` x `{row.profile_id}` -> `{j_show}` , `{m_show}`")
+    batch_md = output_dir / "evaluation-batch.md"
+    batch_md.write_text("\n".join(md_lines), encoding="utf-8")
+
+    return BatchResult(batch_json=batch_json, batch_md=batch_md, gate_violated=gate_violated)

oss_policy_kit/application/cli_output.py

@@ -0,0 +1,160 @@
+"""CLI stdout helpers for automation-friendly summaries."""
+
+from __future__ import annotations
+
+import json
+import sys
+import textwrap
+from typing import Literal
+
+from oss_policy_kit.application.reporting import compute_priority_insights
+from oss_policy_kit.cli.terminal_ui import max_gap_line_chars, terminal_width
+from oss_policy_kit.domain.models import ControlResult, ControlStatus, ExecutionReport
+
+OutputFormat = Literal["human", "json"]
+FailOnPolicy = Literal["none", "fail", "degraded"]
+STATUS_ORDER: tuple[str, ...] = (
+    "pass",
+    "fail",
+    "manual-review-required",
+    "self-attested",
+    "not-evaluated",
+    "waived",
+    "not-observable",
+    "not-applicable",
+)
+
+
+def _ordered_summary(summary_by_status: dict[str, int]) -> dict[str, int]:
+    """Return status counts in a stable, policy-oriented order."""
+
+    ordered: dict[str, int] = {}
+    for status in STATUS_ORDER:
+        if status in summary_by_status:
+            ordered[status] = summary_by_status[status]
+    # Preserve forward compatibility for any future status keys.
+    for status, count in summary_by_status.items():
+        if status not in ordered:
+            ordered[status] = count
+    return ordered
+
+
+def _human_primary_gap_line(result: ControlResult, *, max_len: int) -> str:
+    """Build a short, failure-oriented gap line (avoid catalog titles that read like successes)."""
+
+    reason = (result.reason or "").strip().replace("\n", " ")
+    if reason:
+        if len(reason) > max_len:
+            return reason[: max_len - 1].rstrip() + "..."
+        return reason
+    return f"{result.control_id}: action required (see report for details)."
+
+
+def fail_on_violated(policy: FailOnPolicy, summary_by_status: dict[str, int]) -> bool:
+    """Return True when the run should exit with code 1 for policy reasons."""
+
+    if policy == "none":
+        return False
+    fails = summary_by_status.get("fail", 0)
+    if policy == "fail":
+        return fails > 0
+    if policy == "degraded":
+        manual = summary_by_status.get("manual-review-required", 0)
+        return fails > 0 or manual > 0
+    raise ValueError(f"Unknown fail-on policy: {policy!r}")
+
+
+def print_stdout_summary(report: ExecutionReport, *, output_format: OutputFormat) -> None:
+    """Emit a compact machine- or human-readable summary line to stdout (for piping)."""
+
+    if output_format == "json":
+        ordered_summary = _ordered_summary(report.summary_by_status)
+        payload = {
+            "schema_version": report.schema_version,
+            "kit_version": report.kit_version,
+            "profile_id": report.profile_id,
+            "target_path": report.target_path,
+            "summary_by_status": ordered_summary,
+            "controls_total": sum(ordered_summary.values()),
+            "operational_warnings_count": len(report.operational_warnings),
+        }
+        if report.scorecard_supplemental is not None:
+            payload["scorecard_supplemental"] = report.scorecard_supplemental
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+        return
+    ordered_summary = _ordered_summary(report.summary_by_status)
+    tw = max(20, terminal_width(sys.stdout))
+    gap_max = max_gap_line_chars(stream=sys.stdout)
+    lines: list[str] = []
+    lines.append(f"Profile: {report.profile_id}")
+    lines.append(f"Target: {report.target_path}")
+    status_bits = [f"{k}={v}" for k, v in ordered_summary.items() if v]
+    lines.append("Outcome: " + (", ".join(status_bits) if status_bits else "(no counts)"))
+    total_c = sum(ordered_summary.values())
+    warn_c = len(report.operational_warnings)
+    lines.append(f"Controls: {total_c} | Operational warnings: {warn_c}")
+
+    fails = [r for r in report.results if r.status == ControlStatus.FAIL]
+    mrr = [r for r in report.results if r.status == ControlStatus.MANUAL_REVIEW_REQUIRED]
+    gap_lines: list[str] = []
+    seen: set[str] = set()
+    for r in fails + mrr:
+        line = _human_primary_gap_line(r, max_len=gap_max)
+        if line in seen:
+            continue
+        gap_lines.append(line)
+        seen.add(line)
+        if len(gap_lines) >= 3:
+            break
+    if not gap_lines:
+        insights = compute_priority_insights(report)
+        for row in insights["top_structural_causes"][:3]:
+            bucket = str(row["bucket"])
+            if bucket not in seen:
+                gap_lines.append(f"{bucket} ({row['count']} control(s))")
+                seen.add(bucket)
+            if len(gap_lines) >= 3:
+                break
+    lines.append("")
+    lines.append("Top gaps:")
+    bullet_w = max(12, tw - 4)
+    for g in gap_lines[:3]:
+        wrapped = textwrap.wrap(
+            g,
+            width=bullet_w,
+            break_long_words=True,
+            break_on_hyphens=False,
+        )
+        if not wrapped:
+            continue
+        lines.append(f"  - {wrapped[0]}")
+        lines.extend(f"    {ln}" for ln in wrapped[1:])
+
+    insights = compute_priority_insights(report)
+    next_step = (
+        insights["recommended_actions"][0]
+        if insights["recommended_actions"]
+        else "Revise o relatório Markdown/JSON para priorizar correções."
+    )
+    lines.append("")
+    lines.append("Suggested next step:")
+    step_w = max(12, tw - 2)
+    lines.extend(textwrap.wrap(next_step, width=step_w, break_long_words=True, break_on_hyphens=False))
+
+    if report.external_waiver_path:
+        lines.append("")
+        note = (
+            "Waiver note: an external file was loaded via --waivers; "
+            "this does not change GOV-WAIV-014 (versioned waivers in the repository)."
+        )
+        lines.extend(textwrap.wrap(note, width=tw, break_long_words=True, break_on_hyphens=False))
+        path_prefix = "  Path: "
+        path_rest = report.external_waiver_path
+        if len(path_prefix) + len(path_rest) <= tw:
+            lines.append(path_prefix + path_rest)
+        else:
+            lines.append(path_prefix.rstrip())
+            path_w = max(12, tw - 4)
+            lines.extend(f"    {pl}" for pl in textwrap.wrap(path_rest, width=path_w, break_long_words=True))
+
+    sys.stdout.write("\n".join(lines) + "\n")