pydoctor-cli 2.0.0__tar.gz → 2.0.1__tar.gz

{pydoctor_cli-2.0.0/pydoctor_cli.egg-info → pydoctor_cli-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.0.0
+Version: 2.0.1
 Summary: Premium Python environment diagnostic CLI — your project's personal physician.
 Author-email: Favour Bamgboye <demiladebamgboye@gmail.com>
 Maintainer-email: Favour Bamgboye <demiladebamgboye@gmail.com>
@@ -323,6 +323,10 @@ pydoctor fix
 
 ## Release History
 
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/README.md

@@ -74,6 +74,10 @@ pydoctor fix
 
 ## Release History
 
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/pydoctor/__init__.py

@@ -9,6 +9,6 @@ Author: Favour Bamgboye
 License: MIT
 """
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 __author__ = "Favour Bamgboye"
 __description__ = "Python environment diagnostic CLI — your project's doctor."

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/pydoctor/cli/main.py

@@ -82,7 +82,7 @@ _HELP_EPILOG = """
 [section]🏥  COMMUNITY & SUPPORT[/]
 
   [label]Docs:[/][pkg] https://pydoctor.vercel.app/docs[/]
-  [label]Version:[/][info] v2.0.0 (Premium Kernel Edition)[/]
+  [label]Version:[/][info] v2.0.1 (Premium Kernel Edition)[/]
 
 [kernel]Healthy code leads to healthy deployments. Keep your environment sterile.[/]
 """

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/pydoctor/scanners/vulnerability_scanner.py

@@ -50,9 +50,19 @@ def scan(ctx: ProjectContext) -> list[Issue]:
     client = OSVClient(cache=cache)
 
     # Query OSV for all installed packages
-    records = client.query_packages(ctx.installed_packages)
+    records = _dedupe_records(client.query_packages(ctx.installed_packages))
+    failed = list(getattr(client, "failed_packages", []) or [])
+
+    issues: list[Issue] = []
+
+    if failed:
+        # Fail closed: a security scan that could not reach the vulnerability
+        # database must never report the project as healthy.
+        issues.append(_incomplete_scan_issue(failed, len(ctx.installed_packages)))
 
     if not records:
+        if failed:
+            return issues
         return [
             Issue(
                 category=CATEGORY,
@@ -67,8 +77,6 @@ def scan(ctx: ProjectContext) -> list[Issue]:
             )
         ]
 
-    issues: list[Issue] = []
-
     # Add environment context info
     issues.append(
         Issue(
@@ -90,6 +98,66 @@ def scan(ctx: ProjectContext) -> list[Issue]:
     return issues
 
 
+_SEVERITY_RANK = {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1, "UNKNOWN": 0}
+
+
+def _dedupe_records(records: list[VulnerabilityRecord]) -> list[VulnerabilityRecord]:
+    """
+    Collapse records that describe the same advisory.
+
+    OSV often returns one advisory under several databases (for example a
+    GHSA entry and a PYSEC entry that list each other as aliases). Without
+    this step each copy is reported and penalised separately, so a single
+    vulnerability can cost the health score twice. Records for the same
+    package and version are merged when their IDs or aliases overlap; the
+    highest severity among the duplicates is kept.
+    """
+    kept: list[VulnerabilityRecord] = []
+    kept_ids: list[set[str]] = []
+    for rec in records:
+        ids = {rec.vuln_id, *rec.aliases}
+        for idx, existing in enumerate(kept):
+            if (
+                existing.package == rec.package
+                and existing.version == rec.version
+                and kept_ids[idx] & ids
+            ):
+                kept_ids[idx] |= ids
+                if _SEVERITY_RANK.get(rec.severity.upper(), 0) > _SEVERITY_RANK.get(
+                    existing.severity.upper(), 0
+                ):
+                    existing.severity = rec.severity
+                existing.aliases = sorted(kept_ids[idx] - {existing.vuln_id})
+                break
+        else:
+            kept.append(rec)
+            kept_ids.append(ids)
+    return kept
+
+
+def _incomplete_scan_issue(failed: list[str], total: int) -> Issue:
+    """Build the ERROR issue reported when OSV lookups did not complete."""
+    preview = ", ".join(sorted(failed)[:5])
+    if len(failed) > 5:
+        preview += f", and {len(failed) - 5} more"
+    return Issue(
+        category=CATEGORY,
+        code="SEC_SCAN_INCOMPLETE",
+        severity=Severity.ERROR,
+        title=f"Security scan incomplete: {len(failed)} of {total} packages not checked",
+        description=(
+            "pydoctor could not reach the OSV vulnerability database "
+            f"(https://api.osv.dev) for: {preview}. These packages were not "
+            "checked, so the absence of findings is not evidence that they are safe."
+        ),
+        recommendation=(
+            "Check network or proxy access to api.osv.dev, or raise "
+            "PYDOCTOR_REQUEST_TIMEOUT, then run `pydoctor scan-security` again."
+        ),
+        extra={"unchecked_packages": sorted(failed)},
+    )
+
+
 def _record_to_issue(rec: VulnerabilityRecord) -> Issue:
     """
     Convert a VulnerabilityRecord into a structured Issue.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/pydoctor/security/osv_client.py

@@ -99,6 +99,11 @@ class OSVClient:
         self._cache = cache or CacheManager()
         self._timeout = timeout
         self._session = requests.Session()
+        # Packages whose OSV lookup could not be completed (network error,
+        # timeout, or a non-2xx response after all retries). Callers must
+        # check this: an empty result list does NOT mean "no vulnerabilities"
+        # when this list is non-empty.
+        self.failed_packages: list[str] = []
         self._session.headers.update(
             {
                 "Content-Type": "application/json",
@@ -123,8 +128,10 @@ class OSVClient:
         Returns
         -------
         list[VulnerabilityRecord]
-            All vulnerabilities found.  Empty list if none / network error.
+            All vulnerabilities found. Packages that could not be checked
+            are recorded in ``self.failed_packages``.
         """
+        self.failed_packages = []
         if not packages:
             return []
 
@@ -196,7 +203,10 @@ class OSVClient:
                 break
             except (requests.RequestException, ValueError):
                 if attempt == retries - 1:
-                    # Final attempt failed — return whatever we got from cache
+                    # Final attempt failed. Record the packages we could not
+                    # check so the scanner can report an incomplete scan
+                    # instead of a clean bill of health.
+                    self.failed_packages.extend(name for name, _ in to_fetch)
                     return records
                 # Simple exponential backoff: 1s, 2s, 4s...
                 time.sleep(2**attempt)

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1/pydoctor_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.0.0
+Version: 2.0.1
 Summary: Premium Python environment diagnostic CLI — your project's personal physician.
 Author-email: Favour Bamgboye <demiladebamgboye@gmail.com>
 Maintainer-email: Favour Bamgboye <demiladebamgboye@gmail.com>
@@ -323,6 +323,10 @@ pydoctor fix
 
 ## Release History
 
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name        = "pydoctor-cli"
-version     = "2.0.0"
+version     = "2.0.1"
 description = "Premium Python environment diagnostic CLI — your project's personal physician."
 readme      = "README.md"
 license     = { file = "LICENSE" }

{pydoctor_cli-2.0.0 → pydoctor_cli-2.0.1}/tests/test_vulnerability_scanner.py

@@ -80,3 +80,78 @@ def test_vulns_detected_and_mapped(basic_ctx, monkeypatch):
     assert critical_issue.package == "requests"
     assert critical_issue.code == "SEC_VULNERABILITY"
     assert warning_issue.package == "flask"
+
+
+def test_unreachable_osv_fails_closed(basic_ctx, monkeypatch):
+    """When OSV cannot be reached, report an ERROR instead of 'no vulnerabilities'."""
+
+    class FakeClient:
+        def __init__(self, **kwargs):
+            self.failed_packages = []
+
+        def query_packages(self, pkgs):
+            self.failed_packages = list(pkgs)
+            return []
+
+    monkeypatch.setattr("pydoctor.scanners.vulnerability_scanner.OSVClient", FakeClient)
+
+    issues = vulnerability_scanner.scan(basic_ctx)
+    codes = [i.code for i in issues]
+    assert "SEC_SCAN_INCOMPLETE" in codes
+    assert "SEC_NO_VULNS" not in codes
+    incomplete = next(i for i in issues if i.code == "SEC_SCAN_INCOMPLETE")
+    assert incomplete.severity == Severity.ERROR
+
+
+def test_osv_client_records_failed_packages(monkeypatch, tmp_path):
+    """OSVClient records unchecked packages when every retry fails."""
+    import requests
+
+    from pydoctor.cache.cache_manager import CacheManager
+    from pydoctor.security import osv_client as osv_module
+
+    monkeypatch.setattr(osv_module.time, "sleep", lambda _s: None)
+    client = osv_module.OSVClient(cache=CacheManager(cache_file=tmp_path / "c.json"))
+
+    def boom(*args, **kwargs):
+        raise requests.ConnectionError("offline")
+
+    monkeypatch.setattr(client._session, "post", boom)
+    records = client.query_packages({"requests": "2.31.0"})
+    assert records == []
+    assert client.failed_packages == ["requests"]
+
+
+def test_aliased_advisories_reported_once(basic_ctx, monkeypatch):
+    """A GHSA and a PYSEC record that alias each other count as one vulnerability."""
+
+    class FakeClient:
+        def __init__(self, **kwargs):
+            self.failed_packages = []
+
+        def query_packages(self, pkgs):
+            return [
+                VulnerabilityRecord(
+                    vuln_id="GHSA-6q48-6c7w-9gw2",
+                    package="certifi",
+                    version="2026.7.22",
+                    summary="certifi bundles emSign roots with compromised keys",
+                    severity="HIGH",
+                    aliases=["PYSEC-2026-4320"],
+                ),
+                VulnerabilityRecord(
+                    vuln_id="PYSEC-2026-4320",
+                    package="certifi",
+                    version="2026.7.22",
+                    summary="certifi bundles emSign roots with compromised keys",
+                    severity="CRITICAL",
+                    aliases=["GHSA-6q48-6c7w-9gw2"],
+                ),
+            ]
+
+    monkeypatch.setattr("pydoctor.scanners.vulnerability_scanner.OSVClient", FakeClient)
+
+    issues = vulnerability_scanner.scan(basic_ctx)
+    vulns = [i for i in issues if i.code == "SEC_VULNERABILITY"]
+    assert len(vulns) == 1
+    assert vulns[0].severity == Severity.CRITICAL