plugin-scanner 3.0.0a256__tar.gz → 3.0.0a257__tar.gz

{plugin_scanner-3.0.0a256 → plugin_scanner-3.0.0a257}/.github/workflows/mdm-cloud-integration-lab.yml

@@ -10,6 +10,7 @@ on:
       - "docs/guard/mdm-cloud-integration-lab-*.md"
       - "docs/guard/schemas/mdm-cloud-*.json"
       - ".github/workflows/mdm-cloud-integration-lab.yml"
+      - "ci/test-suite-ratchet-baseline.json"
   push:
     branches: [release/3.0]
     paths:
@@ -19,6 +20,7 @@ on:
       - "docs/guard/mdm-cloud-integration-lab-*.md"
       - "docs/guard/schemas/mdm-cloud-*.json"
       - ".github/workflows/mdm-cloud-integration-lab.yml"
+      - "ci/test-suite-ratchet-baseline.json"
   workflow_dispatch:
 
 permissions:
@@ -30,8 +32,8 @@ concurrency:
 
 jobs:
   integration:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
     env:
       HOL_MDM_LAB_PROJECT: mdm-cloud-${{ github.run_id }}-${{ github.run_attempt }}
     steps:
@@ -63,31 +65,73 @@ jobs:
             uv.lock
           save-cache: false
       - run: uv sync --frozen --extra dev --python 3.12
-      - name: Run focused contract and real-HTTP tests
+      - name: Generate an ephemeral MDM lab admin token
+        shell: bash
+        run: |
+          token="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
+          echo "::add-mask::$token"
+          echo "HOL_MDM_LAB_ADMIN_TOKEN=$token" >> "$GITHUB_ENV"
+      - name: Run focused contracts, persistence, and real-HTTP restart tests
         run: |
           uv run --no-sync pytest -q \
             tests/test_guard_mdm_cloud_control.py \
+            tests/test_guard_mdm_cloud_hardening.py \
             tests/test_guard_mdm_cloud_schemas.py \
             tests/test_guard_mdm_cloud_lab_registration.py \
             tests/test_guard_mdm_cloud_lab_integration.py
-      - name: Run standalone multi-device Docker lab
+      - name: Lint and format MDM Cloud hardening surfaces
+        run: |
+          uv run --no-sync ruff check \
+            src/codex_plugin_scanner/guard/mdm/cloud_control.py \
+            scripts/mdm/cloud-lab \
+            scripts/mdm/run-cloud-integration-lab.py \
+            tests/test_guard_mdm_cloud_control.py \
+            tests/test_guard_mdm_cloud_hardening.py \
+            tests/test_guard_mdm_cloud_lab_registration.py \
+            tests/test_guard_mdm_cloud_lab_integration.py
+          uv run --no-sync ruff format --check \
+            src/codex_plugin_scanner/guard/mdm/cloud_control.py \
+            scripts/mdm/cloud-lab \
+            scripts/mdm/run-cloud-integration-lab.py \
+            tests/test_guard_mdm_cloud_control.py \
+            tests/test_guard_mdm_cloud_hardening.py \
+            tests/test_guard_mdm_cloud_lab_registration.py \
+            tests/test_guard_mdm_cloud_lab_integration.py
+      - name: Validate Compose model
+        run: |
+          docker compose \
+            --project-name "$HOL_MDM_LAB_PROJECT" \
+            --file scripts/mdm/cloud-lab/docker-compose.yml \
+            config --quiet
+      - name: Run standalone multi-device Docker lab with process restart
         run: |
           mkdir -p artifacts/mdm-cloud-lab
           uv run --no-sync python scripts/mdm/run-cloud-integration-lab.py \
             --project "$HOL_MDM_LAB_PROJECT" \
             --artifacts artifacts/mdm-cloud-lab
-      - name: Validate bounded report
+      - name: Validate report checksum and native boundary
         run: |
           uv run --no-sync python - <<'PY'
+          import hashlib
           import json
           from pathlib import Path
-          report = json.loads(Path('artifacts/mdm-cloud-lab/mdm-cloud-integration-report.json').read_text())
+          report_path = Path('artifacts/mdm-cloud-lab/mdm-cloud-integration-report.json')
+          checksum_path = Path('artifacts/mdm-cloud-lab/mdm-cloud-integration-report.json.sha256')
+          report = json.loads(report_path.read_text())
+          expected = checksum_path.read_text().split()[0]
+          assert hashlib.sha256(report_path.read_bytes()).hexdigest() == expected
           assert report['schemaVersion'] == 'hol-guard-mdm-cloud-integration-lab.v1'
           assert report['healthy'] is True
-          assert report['stepCount'] >= 25
+          assert report['stepCount'] >= 50
           assert report['nativeCertification']['outcome'] == 'not-evaluated'
           assert all(step['passed'] is True for step in report['steps'])
           PY
+      - name: Trivy scan MDM lab image and configuration
+        run: |
+          docker run --rm -v "$PWD:/workdir" \
+            aquasec/trivy@sha256:85e87be1a96459c38a4eea47dc64eb2d342bb14cd4b4cef96adcf6ff03378b7c \
+            fs --scanners misconfig,secret --severity HIGH,CRITICAL \
+            --exit-code 1 --quiet /workdir/scripts/mdm/cloud-lab
       - name: Collect bounded Compose logs on failure
         if: failure()
         run: |
@@ -95,15 +139,15 @@ jobs:
           docker compose \
             --project-name "$HOL_MDM_LAB_PROJECT" \
             --file scripts/mdm/cloud-lab/docker-compose.yml \
-            logs --no-color --tail 400 > artifacts/mdm-cloud-lab/compose.log 2>&1 || true
+            logs --no-color --tail 1000 > artifacts/mdm-cloud-lab/workflow-compose.log 2>&1 || true
       - name: Upload MDM Cloud lab evidence
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: mdm-cloud-integration-${{ github.run_id }}-${{ github.run_attempt }}
           path: artifacts/mdm-cloud-lab
-          if-no-files-found: warn
-          retention-days: 14
+          if-no-files-found: error
+          retention-days: 30
       - name: Tear down lab
         if: always()
         run: |

{plugin_scanner-3.0.0a256 → plugin_scanner-3.0.0a257}/.gitignore

@@ -33,6 +33,7 @@ dashboard/.vite/
 dashboard/dist/
 dashboard/.artifacts/
 .artifacts/
+artifacts/mdm-cloud-lab/
 output/playwright/
 .guard-*/
 .guard-ui-review/

{plugin_scanner-3.0.0a256 → plugin_scanner-3.0.0a257}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 3.0.0a256
+Version: 3.0.0a257
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Security, https://hol.org/guard/security

plugin_scanner-3.0.0a257/ci/test-suite-ratchet-baseline.json

@@ -0,0 +1,5 @@
+{
+  "maximum_collected_cases": 15635,
+  "maximum_test_source_lines": 337010,
+  "schema_version": 1
+}

{plugin_scanner-3.0.0a256 → plugin_scanner-3.0.0a257}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "3.0.0a256"
+version = "3.0.0a257"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-3.0.0a256 → plugin_scanner-3.0.0a257}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "3.0.0a256"
+version = "3.0.0a257"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

plugin_scanner-3.0.0a256/release-metadata/plugin-scanner-v3.0.0a256.toolchain.cdx.json → plugin_scanner-3.0.0a257/release-metadata/plugin-scanner-v3.0.0a257.toolchain.cdx.json

@@ -27,7 +27,7 @@
     "component": {
       "name": "hol-guard-release-toolchain",
       "type": "application",
-      "version": "3.0.0a256"
+      "version": "3.0.0a257"
     }
   },
   "specVersion": "1.6",

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/Dockerfile

@@ -0,0 +1,34 @@
+FROM ghcr.io/astral-sh/uv:0.9.26-python3.12-bookworm-slim@sha256:add251a8fbfa14ff5e115adf93cb113c7b58c57bc84f0992164f5b6631b3451f
+
+ARG HOL_MDM_LAB_UID=10001
+ARG HOL_MDM_LAB_GID=10001
+
+WORKDIR /hol-guard
+
+COPY pyproject.toml uv.lock README.md ./
+COPY docs ./docs
+COPY contracts ./contracts
+COPY src ./src
+COPY scripts/mdm ./scripts/mdm
+
+RUN test -f contracts/guard-cloud-review/v2/contract.json \
+    && test -f contracts/guard-cloud-review/v2/fixtures.json \
+    && uv sync --frozen \
+    && groupadd --gid "${HOL_MDM_LAB_GID}" hol-mdm \
+    && useradd --uid "${HOL_MDM_LAB_UID}" --gid "${HOL_MDM_LAB_GID}" \
+        --home-dir /nonexistent --no-create-home --shell /usr/sbin/nologin hol-mdm \
+    && mkdir -p /state /artifacts /etc/hol-guard \
+    && chown -R "${HOL_MDM_LAB_UID}:${HOL_MDM_LAB_GID}" /state /artifacts /etc/hol-guard \
+    && chmod 0700 /state /artifacts /etc/hol-guard
+
+RUN mkdir -p /state /artifacts /etc/hol-guard \
+    && chmod 1777 /state /artifacts
+
+ENV PATH="/hol-guard/.venv/bin:${PATH}" \
+    PYTHONPATH="/hol-guard/src" \
+    PYTHONDONTWRITEBYTECODE="1" \
+    PYTHONUNBUFFERED="1"
+
+USER 10001:10001
+
+ENTRYPOINT ["python"]

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/README.md

@@ -0,0 +1,64 @@
+# HOL Guard multi-device MDM Cloud integration lab
+
+This directory contains the provider-neutral integration lab for HOL Guard 3.0 MDM control. It runs a persistent reference Cloud service, a deterministic fault proxy, four independently keyed HOL Guard device runtimes across two workspaces, and a fleet orchestrator over real HTTP.
+
+## Run
+
+From the repository root:
+
+```bash
+python scripts/mdm/run-cloud-integration-lab.py
+```
+
+The runner builds the current worktree, starts the control plane and devices, executes the initial security matrix, restarts Cloud and every device, executes persistence checks, validates the report, writes a SHA-256 checksum, captures bounded logs, and tears down the entire Compose project.
+
+Useful modes:
+
+```bash
+python scripts/mdm/run-cloud-integration-lab.py --dry-run
+python scripts/mdm/run-cloud-integration-lab.py --keep
+python scripts/mdm/run-cloud-integration-lab.py \
+  --artifacts artifacts/mdm-cloud-lab
+```
+
+## Services
+
+- `volume-init`: grants the fixed unprivileged lab identity access only to named state and evidence volumes.
+- `cloud`: signed desired state, one-time enrollment, assignments, historical acknowledgements, health, remediation, audit, and SQLite durability.
+- `proxy`: partitions, throttling, forced status responses, request drops, lost success responses, corruption, truncation, malformed JSON, stale replay, and ETag removal.
+- `device-a`, `device-b`, `device-c`: independent machines in the alpha workspace.
+- `device-d`: an independent machine in a second workspace for tenant isolation.
+- `orchestrator`: enrollment, baseline, canary, skipped revisions, rollback, crash recovery, replay, partition, corruption, idempotency, fixed remediation, evidence verification, restart, and privacy assertions.
+
+All runtime services use UID and GID `10001`, read-only root filesystems, dropped capabilities, no-new-privileges, internal-only networking, bounded memory and CPU, and separate persistent volumes. The project exposes no host ports and does not mount the Docker socket.
+
+## Fast tests without Docker
+
+```bash
+PYTHONPATH=src:scripts/mdm/cloud-lab pytest -q \
+  tests/test_guard_mdm_cloud_control.py \
+  tests/test_guard_mdm_cloud_hardening.py \
+  tests/test_guard_mdm_cloud_schemas.py \
+  tests/test_guard_mdm_cloud_lab_integration.py \
+  tests/test_guard_mdm_cloud_lab_registration.py
+```
+
+The real-HTTP test starts the same Cloud, proxy, and four device implementations in one Python process. It stops and recreates all servers against the same state directories before the restart phase. The Docker gate additionally proves container isolation, named-volume permissions, unprivileged execution, and evidence export.
+
+## Security invariants
+
+- Enrollment is one-time and bound to workspace, device, installation generation, and a unique P-256 key.
+- Every runtime request binds method, path, body digest, timestamp, device identity, and a persistent monotonic sequence.
+- Desired state is RSA-PSS signed and binds identity, revision, policy hash, predecessor hash, validity, and rollback metadata.
+- A newer revision is visible even when its policy bytes match an earlier revision.
+- Devices retain the last known good policy whenever Cloud, transport, signature, JSON, ETag, or policy validation fails.
+- Historical acknowledgements remain valid after a newer assignment is published.
+- Outboxes remove an item only after delivery or a proven exact duplicate. Ambiguous `409`, `429`, `503`, and lost-response outcomes remain retryable.
+- Remediation is limited to a fixed typed action set. Arbitrary commands, scripts, shells, URLs, credentials, and open parameter bags are rejected.
+- Local execution success remains `awaiting_evidence` until a later healthy report proves recovery.
+- Audit details are redacted and linked by a tamper-evident hash chain.
+- Workspace-scoped state cannot reveal or control another tenant.
+
+## Certification boundary
+
+The lab proves the HOL Guard-owned provider-neutral control and evidence path. It does not certify Apple APNs, Automated Device Enrollment, supervision, notarization, Windows OMA-DM/CSP, SYSTEM execution, Authenticode, WDAC, or any commercial provider. Those gates remain explicitly `not-evaluated` until executed on the actual platform or provider.

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/cloud_service.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Reference stateful Cloud service for the HOL Guard MDM integration lab."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from lab_common import CloudServer, ContractError, Store
+
+
+def _load_seeds() -> list[dict[str, str]]:
+    raw = os.environ.get("HOL_MDM_LAB_DEVICE_SEEDS", "[]")
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise ContractError("enrollment_seed_json_invalid") from error
+    if not isinstance(value, list) or len(value) > 64:
+        raise ContractError("enrollment_seed_json_invalid")
+    seeds: list[dict[str, str]] = []
+    for item in value:
+        if not isinstance(item, dict) or set(item) != {
+            "workspaceId",
+            "deviceId",
+            "installationGeneration",
+            "token",
+        }:
+            raise ContractError("enrollment_seed_json_invalid")
+        if not all(isinstance(item[key], str) for key in item):
+            raise ContractError("enrollment_seed_json_invalid")
+        seeds.append({key: item[key] for key in item})
+    return seeds
+
+
+def _required_admin_token() -> str:
+    token = os.environ.get("HOL_MDM_LAB_ADMIN_TOKEN", "").strip()
+    if not token:
+        raise RuntimeError("HOL_MDM_LAB_ADMIN_TOKEN is required")
+    return token
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8090)
+    parser.add_argument("--database", type=Path, default=Path("/state/cloud.sqlite3"))
+    parser.add_argument("--signing-key", type=Path, default=Path("/state/cloud-key.pem"))
+    args = parser.parse_args()
+    server = CloudServer(
+        (args.host, args.port),
+        Store(args.database, args.signing_key, _load_seeds()),
+        _required_admin_token(),
+    )
+    try:
+        server.serve_forever(poll_interval=0.25)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/device_agent.py

@@ -0,0 +1,10 @@
+from device_base import DeviceBase
+from device_outbox import DeviceOutboxMixin
+from device_policy import DevicePolicyMixin
+from device_remediation import DeviceRemediationMixin
+
+
+class Device(DeviceRemediationMixin, DevicePolicyMixin, DeviceOutboxMixin, DeviceBase):
+    """Complete independently keyed HOL Guard MDM endpoint."""
+
+    pass

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/device_base.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+from device_support import response_error_code
+from lab_common import atomic, decode_json_object, http_request, json_bytes
+
+from codex_plugin_scanner.guard.mdm.cloud_control import (
+    ENROLL_SCHEMA,
+    ContractError,
+    iso,
+    public_pem,
+    sign_proof,
+    utcnow,
+)
+
+
+class DeviceBase:
+    """Persistent identity, endpoint state, enrollment, and request proof."""
+
+    def __init__(
+        self,
+        state: Path,
+        cloud: str,
+        workspace: str,
+        device: str,
+        generation: str,
+        token: str,
+        policy_path: Path,
+    ) -> None:
+        self.state = state
+        self.cloud = cloud.rstrip("/")
+        self.workspace = workspace
+        self.device = device
+        self.generation = generation
+        self.token = token
+        self.policy_path = policy_path
+        state.mkdir(parents=True, exist_ok=True)
+        self.lock = threading.RLock()
+        self.faults: dict[str, object] = {
+            "crashAfterWrite": False,
+            "replayNext": False,
+            "workspaceOverride": None,
+            "holdOutbox": False,
+            "clockOffsetSeconds": 0,
+        }
+        self.key = self._load_or_create_key()
+        self.meta = self._load_json(
+            "meta",
+            {
+                "requestSequence": 0,
+                "healthSequence": 0,
+                "revision": None,
+                "policyHash": None,
+                "etag": None,
+                "enrolled": False,
+                "lastSyncError": None,
+                "completedJobs": {},
+            },
+        )
+        self.outbox = self._load_json(
+            "outbox",
+            {"acks": [], "health": [], "results": [], "deadLetters": []},
+        )
+        self.proofs: dict[tuple[str, str, bytes], dict[str, str]] = {}
+        self._validate_state_shape()
+
+    @property
+    def w(self) -> str:
+        return self.workspace
+
+    @property
+    def d(self) -> str:
+        return self.device
+
+    @property
+    def g(self) -> str:
+        return self.generation
+
+    @property
+    def out(self) -> dict[str, Any]:
+        return self.outbox
+
+    def _now(self):
+        offset = self.faults.get("clockOffsetSeconds", 0)
+        seconds = offset if isinstance(offset, int) and not isinstance(offset, bool) else 0
+        return utcnow() + timedelta(seconds=seconds)
+
+    def _file(self, name: str) -> Path:
+        return self.state / f"{name}.json"
+
+    def _load_json(self, name: str, default: dict[str, object]) -> dict[str, Any]:
+        path = self._file(name)
+        if path.is_symlink():
+            raise ContractError(f"device_{name}_symlink")
+        if not path.exists():
+            return json.loads(json.dumps(default))
+        try:
+            value = decode_json_object(path.read_bytes())
+        except (OSError, ContractError) as error:
+            raise ContractError(f"device_{name}_invalid") from error
+        return value
+
+    def _save(self, name: str, value: object) -> None:
+        atomic(self._file(name), json_bytes(value))
+
+    def _validate_state_shape(self) -> None:
+        for key in ("requestSequence", "healthSequence"):
+            value = self.meta.get(key)
+            if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+                raise ContractError("device_meta_invalid")
+        for key in ("acks", "health", "results", "deadLetters"):
+            if not isinstance(self.outbox.get(key), list):
+                raise ContractError("device_outbox_invalid")
+        if not isinstance(self.meta.get("completedJobs"), dict):
+            raise ContractError("device_meta_invalid")
+
+    def _load_or_create_key(self) -> ec.EllipticCurvePrivateKey:
+        path = self.state / "device-key.pem"
+        if path.is_symlink():
+            raise ContractError("device_key_symlink")
+        if path.exists():
+            key = serialization.load_pem_private_key(path.read_bytes(), password=None)
+            if not isinstance(key, ec.EllipticCurvePrivateKey) or not isinstance(key.curve, ec.SECP256R1):
+                raise ContractError("device_key_invalid")
+            return key
+        key = ec.generate_private_key(ec.SECP256R1())
+        atomic(
+            path,
+            key.private_bytes(
+                serialization.Encoding.PEM,
+                serialization.PrivateFormat.PKCS8,
+                serialization.NoEncryption(),
+            ),
+        )
+        return key
+
+    def enroll(self) -> None:
+        if self.meta["enrolled"]:
+            return
+        public_key = public_pem(self.key.public_key())
+        payload = {
+            "schemaVersion": ENROLL_SCHEMA,
+            "workspaceId": self.workspace,
+            "deviceId": self.device,
+            "installationGeneration": self.generation,
+            "keyId": hashlib.sha256(public_key.encode("utf-8")).hexdigest()[:32],
+            "publicKeyPem": public_key,
+            "token": self.token,
+        }
+        status, _, data = http_request("POST", self.cloud + "/runtime/v1/enroll", payload)
+        if status != 201 or not isinstance(data, dict):
+            raise RuntimeError(f"enrollment_failed:{status}:{response_error_code(data)}")
+        cloud_public_key = data.get("cloudPublicKeyPem")
+        if not isinstance(cloud_public_key, str):
+            raise RuntimeError("enrollment_missing_cloud_key")
+        parsed = serialization.load_pem_public_key(cloud_public_key.encode("utf-8"))
+        if not isinstance(parsed, rsa.RSAPublicKey):
+            raise RuntimeError("enrollment_cloud_key_invalid")
+        atomic(self.state / "cloud-key.pem", cloud_public_key.encode("utf-8"))
+        self.meta["enrolled"] = True
+        self._save("meta", self.meta)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: object | None = None,
+        extra: dict[str, str] | None = None,
+    ) -> tuple[int, dict[str, str], object | None]:
+        body = b"" if payload is None else json_bytes(payload)
+        workspace_override = self.faults.get("workspaceOverride")
+        workspace = workspace_override if isinstance(workspace_override, str) and workspace_override else self.workspace
+        proof_key = (method, path, body)
+        if self.faults.get("replayNext") is True and proof_key in self.proofs:
+            headers = dict(self.proofs[proof_key])
+            self.faults["replayNext"] = False
+        else:
+            self.meta["requestSequence"] += 1
+            self._save("meta", self.meta)
+            sequence = self.meta["requestSequence"]
+            observed_at = iso(self._now())
+            headers = {
+                "x-hol-workspace-id": workspace,
+                "x-hol-device-id": self.device,
+                "x-hol-installation-generation": self.generation,
+                "x-hol-request-sequence": str(sequence),
+                "x-hol-request-time": observed_at,
+                "x-hol-request-signature": sign_proof(
+                    self.key,
+                    method,
+                    path,
+                    body,
+                    sequence,
+                    observed_at,
+                ),
+            }
+            self.proofs[proof_key] = dict(headers)
+        headers.update(extra or {})
+        return http_request(method, self.cloud + path, payload, headers)

plugin_scanner-3.0.0a257/scripts/mdm/cloud-lab/device_outbox.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import hashlib
+
+from device_support import (
+    MAX_DEAD_LETTERS,
+    MAX_OUTBOX_ITEMS,
+    PERMANENT_STATUSES,
+    PROVEN_DUPLICATE_CODES,
+    TRANSIENT_STATUSES,
+    response_error_code,
+)
+from lab_common import json_bytes
+
+from codex_plugin_scanner.guard.mdm.cloud_control import ContractError, iso
+
+
+class DeviceOutboxMixin:
+    """Durable FIFO evidence delivery and bounded dead-letter handling."""
+
+    def _queue(self, channel: str, payload: dict[str, object]) -> None:
+        queue = self.outbox[channel]
+        if not isinstance(queue, list):
+            raise ContractError("device_outbox_invalid")
+        if len(queue) >= MAX_OUTBOX_ITEMS:
+            raise ContractError("device_outbox_full")
+        queue.append(payload)
+        self._save("outbox", self.outbox)
+
+    def _dead_letter(
+        self,
+        channel: str,
+        payload: object,
+        status: int,
+        error_code: str,
+    ) -> None:
+        dead_letters = self.outbox["deadLetters"]
+        if not isinstance(dead_letters, list):
+            raise ContractError("device_outbox_invalid")
+        dead_letters.append(
+            {
+                "channel": channel,
+                "status": status,
+                "error": error_code,
+                "payloadHash": hashlib.sha256(json_bytes(payload)).hexdigest(),
+                "observedAt": iso(self._now()),
+            }
+        )
+        del dead_letters[:-MAX_DEAD_LETTERS]
+
+    def flush(self) -> None:
+        if self.faults.get("holdOutbox") is True:
+            return
+        channels = (
+            ("acks", "/runtime/v1/acknowledgements"),
+            ("health", "/runtime/v1/health"),
+            ("results", "/runtime/v1/remediation-results"),
+        )
+        for channel, path in channels:
+            queue = self.outbox[channel]
+            if not isinstance(queue, list):
+                raise ContractError("device_outbox_invalid")
+            remaining: list[object] = []
+            blocked = False
+            for item in queue:
+                if blocked:
+                    remaining.append(item)
+                    continue
+                status, _, response = self.request("POST", path, item)
+                error_code = response_error_code(response)
+                if status in {200, 202, 204}:
+                    continue
+                if status == 409 and error_code in PROVEN_DUPLICATE_CODES:
+                    continue
+                if status in PERMANENT_STATUSES:
+                    self._dead_letter(channel, item, status, error_code)
+                    continue
+                remaining.append(item)
+                blocked = True
+                if status not in TRANSIENT_STATUSES and status not in {401, 403, 409}:
+                    self.meta["lastSyncError"] = error_code
+            self.outbox[channel] = remaining
+        self._save("outbox", self.outbox)
+        self._save("meta", self.meta)