versionsec 0.7.1__py3-none-any.whl

forgeguard/__init__.py

@@ -0,0 +1,78 @@
+"""Compatibility shim: ForgeGuard was renamed to VersionSec in 0.7.0.
+
+``import forgeguard`` and ``import forgeguard.cli`` keep working and resolve to the
+canonical ``versionsec`` implementation. There is no second implementation here: every
+name is an alias of the canonical module object, so the two import paths cannot drift.
+
+Canonical from 0.7.0 onward::
+
+    python -m pip install versionsec
+    import versionsec
+
+The legacy path stays quiet on purpose - it emits no warning to stdout or stderr, so
+existing automation does not break. See MIGRATION.md.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+import versionsec as _versionsec
+
+__version__ = _versionsec.__version__
+__all__ = list(getattr(_versionsec, "__all__", []))
+
+_SUBMODULES = (
+    "advisories",
+    "advisories.evaluator",
+    "advisories.models",
+    "assessment",
+    "checks",
+    "cli",
+    "client",
+    "config_review",
+    "engine",
+    "exporters",
+    "exporters.json",
+    "exporters.markdown",
+    "exporters.sarif",
+    "models",
+    "output",
+    "policy",
+    "providers",
+    "providers.base",
+    "providers.forgejo",
+    "providers.gitea",
+    "providers.registry",
+    "report",
+    "runner_review",
+    "safety",
+    "scoring",
+    "urls",
+    "version",
+)
+
+# Register each canonical submodule under the legacy name as well, so that the
+# statement form ``import forgeguard.cli`` resolves without a second implementation.
+for _name in _SUBMODULES:
+    try:
+        _module = importlib.import_module(f"versionsec.{_name}")
+    except ModuleNotFoundError:  # pragma: no cover - defensive
+        continue
+    sys.modules[f"{__name__}.{_name}"] = _module
+    if "." not in _name:
+        globals()[_name] = _module
+del _name, _module
+
+
+def __getattr__(name: str):
+    """Any remaining attribute resolves against the canonical package."""
+    try:
+        return getattr(_versionsec, name)
+    except AttributeError as exc:
+        raise AttributeError(name) from exc
+
+
+def __dir__():
+    return sorted(set(dir(_versionsec)) | {n for n in _SUBMODULES if "." not in n})

versionsec/__init__.py

@@ -0,0 +1,9 @@
+"""VersionSec by Gexiro.
+
+Read-only security posture and supply-chain visibility for self-hosted Gitea.
+Scope is limited to one own or explicitly authorized instance.
+"""
+
+from .version import __version__
+
+__all__ = ["__version__"]

versionsec/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

versionsec/advisories/__init__.py

@@ -0,0 +1 @@
+"""Version-only advisory evaluation; never performs network access."""

versionsec/advisories/catalog/forgejo.json

@@ -0,0 +1,38 @@
+{
+  "version": "2026-09-11.1",
+  "verified_at": "2026-09-11",
+  "records": [
+    {
+      "id": "FG-FJ-TEMPLATE-20260910",
+      "product": "forgejo",
+      "title": "Template initialization security update version posture",
+      "sources": [
+        "https://codeberg.org/forgejo/forgejo/src/branch/forgejo/release-notes-published/15.0.8.md",
+        "https://codeberg.org/forgejo/forgejo/src/branch/forgejo/release-notes-published/16.0.4.md"
+      ],
+      "source_sha256": [
+        "d0ca357d547734c72b2956ba5fd36784ce3a37f1c2fb3c1c28cf870ff25dd7d4",
+        "5769d9d511c035f29e0c345718f4a2cc1f9567f9f93895005e038cafd2c4b99a"
+      ],
+      "verified_at": "2026-09-11",
+      "retrieval_url": "https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/release-notes-published/15.0.8.md ; https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/release-notes-published/16.0.4.md",
+      "selected_record_id": "forgejo-release-notes-15.0.8+16.0.4",
+      "selected_record_location": "Two exact release-note documents; bytes frozen and re-verified unchanged on 2026-09-11. Establishes fixed releases only; no affected introduction boundary is asserted.",
+      "affected": [],
+      "fixed": [
+        {
+          "lower": "15.0.8",
+          "upper": "15.0.8"
+        },
+        {
+          "lower": "16.0.4",
+          "upper": "16.0.4"
+        }
+      ],
+      "severity": "critical",
+      "severity_source": "https://codeberg.org/forgejo/forgejo/src/branch/forgejo/release-notes-published/16.0.4.md",
+      "limitations": "Release notes prove fixes in these exact releases. They do not establish an introduction boundary; all other versions remain undetermined. No CVE ID is assigned by this catalog.",
+      "applicability": "Unmodified upstream release; no feature activation or exploitability claim."
+    }
+  ]
+}

versionsec/advisories/catalog/gitea.json

@@ -0,0 +1,68 @@
+{
+  "version": "2026-09-11.1",
+  "verified_at": "2026-09-11",
+  "records": [
+    {
+      "id": "FG-CVE-27771",
+      "product": "gitea",
+      "title": "CVE-2026-27771 version posture",
+      "sources": [
+        "https://github.com/go-gitea/gitea/security/advisories/GHSA-8qw8-rq86-9pc2"
+      ],
+      "source_sha256": [
+        "09a541436af61a369d038203d01c9bd1bb4c903b1bc6ab19f7694da62f4f52f5"
+      ],
+      "verified_at": "2026-09-11",
+      "retrieval_url": "https://api.github.com/repos/go-gitea/gitea/security-advisories/GHSA-8qw8-rq86-9pc2",
+      "selected_record_id": "GHSA-8qw8-rq86-9pc2",
+      "selected_record_location": "Single advisory record endpoint; frozen exact bytes, not a collection listing.",
+      "affected": [
+        {
+          "lower": "0.0.0",
+          "upper": "1.26.1"
+        }
+      ],
+      "fixed": [
+        {
+          "lower": "1.26.2",
+          "upper": "1.27.3"
+        }
+      ],
+      "severity": "high",
+      "severity_source": "https://github.com/go-gitea/gitea/security/advisories/GHSA-8qw8-rq86-9pc2",
+      "limitations": "No custom vendor backports or future releases inferred.",
+      "applicability": "Unmodified upstream version; version posture only."
+    },
+    {
+      "id": "FG-CVE-78433",
+      "product": "gitea",
+      "title": "CVE-2026-78433 version posture",
+      "sources": [
+        "https://github.com/go-gitea/gitea/security/advisories/GHSA-frpv-2xgv-wxpq"
+      ],
+      "source_sha256": [
+        "c8e6cec99c7f6fc41a4b18b6cb0cff9e2c86561dec7952d63176a52aee7a5110"
+      ],
+      "verified_at": "2026-09-11",
+      "retrieval_url": "https://api.github.com/repos/go-gitea/gitea/security-advisories/GHSA-frpv-2xgv-wxpq",
+      "selected_record_id": "GHSA-frpv-2xgv-wxpq",
+      "selected_record_location": "Single advisory record endpoint for this GHSA, not the security-advisories collection listing whose bytes and hash differ and drift.",
+      "affected": [
+        {
+          "lower": "1.26.0",
+          "upper": "1.27.2"
+        }
+      ],
+      "fixed": [
+        {
+          "lower": "1.27.3",
+          "upper": "1.27.3"
+        }
+      ],
+      "severity": "medium",
+      "severity_source": "https://github.com/go-gitea/gitea/security/advisories/GHSA-frpv-2xgv-wxpq",
+      "limitations": "No custom vendor backports or future releases inferred.",
+      "applicability": "Unmodified upstream version; version posture only."
+    }
+  ]
+}

versionsec/advisories/evaluator.py

@@ -0,0 +1,83 @@
+import hashlib
+import json
+from importlib.resources import files
+
+from ..assessment import EvidenceFinding, Identity
+from ..models import EvidenceState, Severity, Status
+from ..providers.base import release_version
+from .models import Advisory
+
+
+def catalog(product: str) -> tuple[list[Advisory], dict]:
+    if product not in {"gitea", "forgejo"}:
+        return [], {"version": "2026-09-10.1", "coverage": "unknown product"}
+    data = (
+        files("versionsec")
+        .joinpath("advisories", "catalog", product + ".json")
+        .read_bytes()
+    )
+    payload = json.loads(data)
+    records = [Advisory.model_validate(x) for x in payload["records"]]
+    if any(r.product != product for r in records) or len(
+        {r.id for r in records}
+    ) != len(records):
+        raise ValueError("Invalid provider catalog")
+    return records, {
+        "version": payload["version"],
+        "verified_at": payload["verified_at"],
+        "sha256": hashlib.sha256(data).hexdigest(),
+        "coverage": "Curated records only; absence is not evidence of safety.",
+    }
+
+
+def evaluate(record: Advisory, identity: Identity) -> EvidenceFinding:
+    version = release_version(identity.normalized_version)
+    outcome = "undetermined"
+    reason = "Product/version conflict, unsupported syntax, or version outside catalog evidence."
+    if (
+        identity.declared_product == record.product
+        and not identity.product_conflict
+        and not identity.version_conflict
+        and version is not None
+        and not record.conditions
+    ):
+        if any(x.contains(version) for x in record.affected):
+            outcome = "affected"
+        elif any(x.contains(version) for x in record.fixed):
+            outcome = "fixed"
+        if outcome != "undetermined":
+            reason = (
+                "Version is within the catalog's explicit " + outcome + " interval."
+            )
+    return EvidenceFinding(
+        id=record.id,
+        title=record.title,
+        scope="version",
+        source="catalog:" + record.product,
+        observed={
+            "version": identity.normalized_version,
+            "record_version": record.record_version,
+            "outcome": outcome,
+        },
+        evidence={"outcome": outcome},
+        expected="Version within the explicit fixed range for this advisory.",
+        status=Status.FAIL
+        if outcome == "affected"
+        else Status.PASS
+        if outcome == "fixed"
+        else Status.INFO,
+        severity=Severity(record.severity) if outcome == "affected" else Severity.info,
+        evidence_state=EvidenceState.INDETERMINATE
+        if outcome == "undetermined"
+        else EvidenceState.ASSESSED,
+        applicability="undetermined" if outcome == "undetermined" else "applicable",
+        reason=reason,
+        rationale=reason
+        + " Version assessment does not prove exploitability. "
+        + record.limitations,
+        remediation="Review the upstream advisory and upgrade within a supported line."
+        if outcome != "fixed"
+        else "",
+        references=sorted(record.sources),
+        penalty_group="version-advisories",
+    )

versionsec/advisories/models.py

@@ -0,0 +1,53 @@
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..providers.base import release_version
+
+
+class Interval(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    lower: str
+    upper: str
+
+    @model_validator(mode="after")
+    def validate_bounds(self):
+        low, high = release_version(self.lower), release_version(self.upper)
+        if low is None or high is None or low > high:
+            raise ValueError("Invalid inclusive advisory interval")
+        return self
+
+    def contains(self, version: tuple[int, int, int]) -> bool:
+        return release_version(self.lower) <= version <= release_version(self.upper)
+
+
+class Advisory(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str
+    product: Literal["gitea", "forgejo"]
+    record_version: int = 1
+    title: str
+    sources: list[str]
+    source_sha256: list[str]
+    verified_at: str
+    affected: list[Interval]
+    fixed: list[Interval]
+    severity: Literal["critical", "high", "medium", "low", "info"]
+    severity_source: str
+    limitations: str
+    applicability: str
+    retrieval_url: str = ""
+    selected_record_id: str = ""
+    selected_record_location: str = ""
+    conditions: dict[str, bool] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def disjoint_ranges(self):
+        for a in self.affected:
+            for b in self.fixed:
+                if not (
+                    release_version(a.upper) < release_version(b.lower)
+                    or release_version(b.upper) < release_version(a.lower)
+                ):
+                    raise ValueError("Overlapping affected/fixed intervals")
+        return self

versionsec/assessment.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .models import Finding, ScanResult
+
+Intent = Literal["public", "private", "unspecified"]
+Profile = Literal["minimal", "standard", "extended"]
+
+
+class EvidenceFinding(Finding):
+    check_version: str = "1"
+    scope: Literal["http", "version", "operator-snapshot"]
+    source: str
+    observed: dict = Field(default_factory=dict)
+    expected: str
+    applicability: Literal[
+        "applicable", "undetermined", "not_applicable", "skipped_by_profile"
+    ]
+    reason: str
+    penalty_group: str
+
+
+class Identity(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    declared_product: str | None
+    declared_version_marker: str | None = None
+    observed_product_marker: str | None
+    product_source: str
+    declared_version: str | None
+    observed_version: str | None
+    normalized_version: str | None
+    product_conflict: bool
+    version_conflict: bool
+    support: Literal["qualified", "unsupported", "unknown"]
+    provider_revision: str | None
+
+
+class Assessment(ScanResult):
+    schema_id: Literal["forgeguard.assessment.v1"] = "forgeguard.assessment.v1"
+    profile: str
+    profile_version: Literal["1"] = "1"
+    policy: Intent
+    policy_version: Literal["1"] = "1"
+    scoring_version: Literal["2"] = "2"
+    identity: Identity
+    catalog: dict
+    findings: list[EvidenceFinding]
+    skipped_checks: list[str]
+    request_count: int
+    limitations: list[str]
+    run: dict[str, str] = Field(default_factory=dict)
+
+    def normalized(self) -> dict:
+        result = self.model_dump(mode="json")
+        result["run"] = {
+            k: v
+            for k, v in result["run"].items()
+            if k not in {"timestamp", "reviewed_at"}
+        }
+        if not result["run"]:
+            result.pop("run")
+        result.pop("scan_id")
+        return result