plugin-scanner 2.0.570__tar.gz → 2.0.572__tar.gz

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.570
+Version: 2.0.572
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

plugin_scanner-2.0.572/docs/guard/enterprise-event-taxonomy.md

@@ -0,0 +1,83 @@
+# Guard Enterprise Event Taxonomy
+
+Guard Cloud emits a normalized, redacted event shape for exports, webhook
+delivery, and SIEM forwarding. The canonical schema version is `guard.siem.v1`.
+
+## Required fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `eventVersion` | string | Always `guard.siem.v1` |
+| `eventType` | enum | See event types below |
+| `occurredAt` | ISO-8601 UTC | Event timestamp |
+| `severity` | enum | `info`, `medium`, `high`, `critical` |
+| `workspaceId` | string | Workspace scope for the event |
+| `receiptId` | string | Linked receipt or audit record id |
+| `actor.actorType` | enum | `human`, `agent`, `system` |
+| `actor.actorHash` | string | Stable hashed actor identifier |
+| `subject.artifactType` | enum | `receipt`, `approval`, `policy`, `incident`, `feed`, `package` |
+| `subject.artifactId` | string | Stable artifact identifier |
+| `subject.ecosystem` | string \| null | Package ecosystem when relevant |
+| `redaction.rawCommandIncluded` | false | Raw shell commands are never exported |
+| `redaction.rawPromptIncluded` | false | Raw prompts are never exported |
+| `redaction.secretMaterialIncluded` | false | Secrets and tokens are never exported |
+| `routing.suggestedSink` | enum | `siem`, `ticketing`, `case-management` |
+| `routing.enterpriseTrigger` | string \| null | Sales-assist trigger when applicable |
+
+## Event types
+
+| `eventType` | Typical severity | Meaning |
+| --- | --- | --- |
+| `receipt.created` | info | Guard recorded a decision receipt |
+| `approval.resolved` | medium | Human or delegated approval resolved |
+| `policy.mutation` | medium | Workspace policy changed |
+| `incident.created` | high | Guard opened an incident |
+| `feed.degraded` | medium | Supply-chain feed stale or degraded |
+| `package.blocked` | critical | Package install blocked by policy |
+
+## Confidence and severity guidance
+
+- **Severity** describes customer impact if the event is ignored.
+- **Confidence** for incident and firewall events is stored on incident and
+  evaluation records in Guard Cloud, not in raw command text.
+- Export and webhook payloads use redacted summaries only. Confidence scores
+  appear as numeric fields on incident exports, not as free-text model output.
+
+## Identity fields
+
+| ID | Scope | Notes |
+| --- | --- | --- |
+| `workspaceId` | Cloud workspace | Required on signed-in exports |
+| `actor.actorHash` | Actor | Hashed; no email or display name in SIEM payload |
+| `receiptId` | Audit trail | Join key across receipt, incident, and export manifests |
+| Agent / device ids | Runtime | Available on receipt exports and incident timelines; omitted from default SIEM samples |
+
+## Generic webhook schema versioning
+
+Webhook deliveries SHOULD include:
+
+```json
+{
+  "schemaVersion": "guard.webhook.v1",
+  "event": { "... guard.siem.v1 fields ..." },
+  "delivery": {
+    "provider": "webhook",
+    "sentAt": "2026-06-10T18:00:00.000Z",
+    "idempotencyKey": "delivery_01jz_example"
+  }
+}
+```
+
+Breaking changes increment `guard.webhook.vN`. Non-breaking field additions stay
+on the same major version.
+
+## Vendor mapping
+
+Guard ships sample mappings for common SIEM sinks in
+`hol-points-portal/src/lib/guard/siem/guard-siem-vendor-formats.ts`. These are
+schema examples for webhook forwarding; native Splunk, Elastic, Sentinel, and
+Datadog integrations remain **Planned** in the integration catalog until each
+provider has setup, delivery, retry, and test coverage.
+
+See [Enterprise export examples](./enterprise-export-examples.md) for JSON
+samples.

plugin_scanner-2.0.572/docs/guard/enterprise-export-examples.md

@@ -0,0 +1,162 @@
+# Guard Enterprise Export Examples
+
+This page lists export surfaces security and GRC teams can reference during
+reviews. All examples are redacted by default.
+
+## Export surfaces
+
+| Export | API / surface | Contents |
+| --- | --- | --- |
+| Policy version | **Controls** UI + policy receipts | Active rules, owners, scopes, receipt links |
+| Firewall evaluation | **Firewall** UI + `/api/guard/supply-chain/*` | Package, version, harness, policy version, decision |
+| Receipt / evidence manifest | `/api/guard/receipts/export` | Redacted receipt summaries and filters |
+| Incident timeline | **Incidents** UI + incident export | Attack-path header, owner, evidence refs, remediation |
+| Trust score snapshot | **Intelligence** UI | Workspace risk posture summary |
+| Notification delivery record | **Settings** → Integrations | Provider health, last delivery, retry state |
+| Workspace audit events | `/api/guard/supply-chain/audit/export` | Supply-chain audit log (CSV/JSON) |
+| AI-BOM bundle | Inventory export builder | MCP, skills, packages, policies with redaction metadata |
+| Integrity manifest | Enterprise export manifest helper | SHA-256 checksums per export artifact |
+
+## Integrity manifest (example)
+
+```json
+{
+  "schemaVersion": "guard.enterprise-export.v1",
+  "generatedAt": "2026-06-10T18:00:00.000Z",
+  "workspaceId": "workspace_9d21",
+  "artifacts": [
+    {
+      "exportType": "receipt-manifest",
+      "contentSha256": "b3a8f2…",
+      "recordCount": 128,
+      "redaction": {
+        "rawSecretsIncluded": false,
+        "rawCommandsIncluded": false,
+        "rawPromptsIncluded": false
+      }
+    }
+  ]
+}
+```
+
+## Canonical SIEM event (guard.siem.v1)
+
+```json
+{
+  "eventVersion": "guard.siem.v1",
+  "eventType": "package.blocked",
+  "occurredAt": "2026-06-08T18:10:00.000Z",
+  "severity": "critical",
+  "workspaceId": "workspace_9d21",
+  "receiptId": "package_receipt_01jz",
+  "actor": { "actorType": "agent", "actorHash": "actor_agent_7f3a" },
+  "subject": {
+    "artifactType": "package",
+    "artifactId": "package:npm/acme-risky-install",
+    "ecosystem": "npm"
+  },
+  "redaction": {
+    "rawCommandIncluded": false,
+    "rawPromptIncluded": false,
+    "secretMaterialIncluded": false
+  },
+  "routing": {
+    "enterpriseTrigger": "siem_export_schema_request",
+    "suggestedSink": "siem"
+  }
+}
+```
+
+## Webhook envelope (available today)
+
+Use the **Webhook** integration in Guard Cloud to POST the canonical event to
+your HTTPS endpoint:
+
+```json
+{
+  "schemaVersion": "guard.webhook.v1",
+  "event": { "... guard.siem.v1 object ..." },
+  "delivery": {
+    "provider": "webhook",
+    "sentAt": "2026-06-10T18:00:00.000Z",
+    "idempotencyKey": "delivery_01jz_example"
+  }
+}
+```
+
+## Vendor sink examples (schema mapping)
+
+These examples show how to map `guard.siem.v1` into common SIEM shapes when
+forwarding through your webhook receiver. Native connectors remain **Planned**
+until provider setup and delivery tests ship.
+
+### Splunk HEC-style
+
+```json
+{
+  "time": 1717867800,
+  "host": "guard-cloud",
+  "source": "hol-guard",
+  "sourcetype": "guard:siem:v1",
+  "event": { "... guard.siem.v1 object ..." }
+}
+```
+
+### Elastic ECS-style
+
+```json
+{
+  "@timestamp": "2026-06-08T18:10:00.000Z",
+  "event.kind": "event",
+  "event.category": ["security"],
+  "event.type": ["info"],
+  "event.action": "package.blocked",
+  "guard.event_version": "guard.siem.v1",
+  "guard.workspace_id": "workspace_9d21",
+  "guard.receipt_id": "package_receipt_01jz",
+  "guard.redaction": {
+    "raw_command_included": false,
+    "raw_prompt_included": false,
+    "secret_material_included": false
+  }
+}
+```
+
+### Microsoft Sentinel-style
+
+```json
+{
+  "TimeGenerated": "2026-06-08T18:10:00.000Z",
+  "AlertName": "Guard package blocked",
+  "Severity": "High",
+  "ExtendedProperties": {
+    "guardEventVersion": "guard.siem.v1",
+    "guardEventType": "package.blocked",
+    "guardWorkspaceId": "workspace_9d21",
+    "guardReceiptId": "package_receipt_01jz"
+  }
+}
+```
+
+### Datadog log-style
+
+```json
+{
+  "ddsource": "hol-guard",
+  "service": "guard-cloud",
+  "message": "Guard package blocked",
+  "guard": { "... guard.siem.v1 object ..." }
+}
+```
+
+## Redaction rules (all exports)
+
+Exports MUST NOT include:
+
+- Raw shell commands or prompt bodies
+- Bearer tokens, API keys, or `.env` contents
+- Local filesystem paths under user home directories
+- Raw email addresses in SIEM samples
+
+Portal export builders attach explicit `redaction` metadata when fields are
+removed or summarized.

plugin_scanner-2.0.572/docs/guard/enterprise-packet.md

@@ -0,0 +1,118 @@
+# HOL Guard Enterprise Packet
+
+This packet explains what Guard controls, where customers see those controls in
+the product, and which exports security and GRC teams can request without
+engineering narration.
+
+Guard Cloud is optional. Local Guard continues to enforce policy, write
+receipts, and operate without sign-in. Cloud adds synced memory, team RBAC,
+integrations, exports, and admin workflows on top of the same local runtime.
+
+Related docs:
+
+- [Local Guard vs Guard Cloud](./local-vs-cloud.md)
+- [Harness support matrix](./harness-support.md)
+- [Enterprise event taxonomy](./enterprise-event-taxonomy.md)
+- [Enterprise export examples](./enterprise-export-examples.md)
+
+## Control maps
+
+Each map lists the control, the enforcement layer, and where the customer can
+review it in Guard Cloud or local runtime output.
+
+### AI agent risk
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| Harness discovery and attach | Detects configured harnesses and records runtime sessions | Syncs session health and stale coverage | **Agents**, **Home** |
+| Tool-call interception | Evaluates shell, MCP, skill, and file actions before side effects | Stores searchable receipts and decision history | **Evidence**, **Inbox** |
+| Approval paths | Native harness approval, local approval center, terminal resolution | Delegated approvals and team routing | **Inbox**, **Controls** |
+| Agent identity and tokens | Local daemon identity and scoped tokens | Workspace-scoped agent registry and RBAC | **Agents**, **Team** |
+| Trust and drift signals | Local policy and inventory diff detection | Trust score, incidents, intelligence findings | **Intelligence**, **Incidents** |
+
+### MCP and skill risk
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| MCP server inventory | Parses descriptors, commands, transports, and dependencies | Syncs inventory snapshots over time | **Agents**, **Evidence** |
+| Skill inventory | Parses `SKILL.md`, install intent, and declared tools | Syncs skill drift and review history | **Agents**, **Evidence** |
+| Descriptor and schema drift | Detects hash changes and material risk deltas | Requires reapproval when drift is high-risk | **Inbox**, **Controls** |
+| Tool poisoning and shadowing checks | Local evaluators flag hidden instructions and collisions | Incident routing for high-confidence drift | **Incidents**, **Intelligence** |
+| Package intent inside skills | Blocks risky install instructions before execution | Receipts and firewall linkage | **Firewall**, **Evidence** |
+
+### Supply-chain risk
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| Package manager shims | Intercepts npm, pnpm, pip, and other supported managers | Firewall UI and synced evaluations | **Firewall** |
+| Feed freshness and source health | Local feed checks and stale warnings | Feed health indicators in Cloud | **Firewall**, **Controls** |
+| Policy evaluation | Local block, warn, monitor, and exception paths | Shared policy memory and simulator | **Controls**, **Firewall** |
+| Audit export | Local receipts include package intent metadata | Workspace audit export API | **Firewall**, API export |
+
+### Local enforcement
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| Launch interception | Blocks or warns before risky commands run | Mirrors decisions after sync | Local daemon, **Evidence** |
+| Policy version pinning | Local policy files and presets | Team policy packs and workspace scope | **Controls** |
+| Receipts and explain output | Signed local receipts with redacted summaries | Searchable history and exports | **Evidence** |
+| Cloud outage independence | Enforcement continues without Cloud sign-in | Sync catches up when Cloud returns | **Home**, **Protect** |
+
+### Evidence and export
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| Receipt manifest export | Redacted local summaries | `/api/guard/receipts/export` | **Evidence** export |
+| AI-BOM export | Inventory redaction in export builder | Workspace-scoped AI-BOM bundle | **Evidence**, API |
+| Action explanation fields | Shared explanation contract in receipts | Inspector and export surfaces | **Evidence**, **Incidents** |
+| Integrity manifest | Local export checksum metadata | Enterprise manifest helper in portal | Export bundle header |
+| SIEM forwarding | Not required for local protection | Generic **Webhook** integration (available) | **Settings** → Integrations |
+
+### Notification and incident response
+
+| Control | Local Guard | Guard Cloud | Customer view |
+| --- | --- | --- | --- |
+| High-severity routing | Local alerts and approval center | Slack, email, PagerDuty, Jira, GitHub, webhook | **Settings**, **Incidents** |
+| Incident timeline | Local receipt linkage | Attack-path header, owner, remediation checklist | **Incidents** |
+| External work linkage | N/A locally | Jira, GitHub, PagerDuty, Slack refs on incidents | **Incidents** |
+| Delivery records | Local notification attempts when configured | Integration health and retry status | **Settings** → Integrations |
+
+Catalog-only observability providers (Datadog, Splunk, Sentinel) are labeled
+**Planned** in Guard Cloud. Customers can still forward the canonical
+`guard.siem.v1` payload through the available **Webhook** integration today.
+
+## Workspace controls
+
+| Control | Where enforced | Customer view |
+| --- | --- | --- |
+| Personal vs team workspace scope | Cloud auth and workspace queries | **Settings**, workspace switcher |
+| Viewer / member / admin / owner RBAC | API route guards | **Team**, **Settings** |
+| Service principal ownership | Token and principal registry | **Agents** |
+| Billing entitlements | Plan config and checkout | **Billing** |
+| Audit read/export permissions | Supply-chain and evidence routes | API + **Evidence** |
+
+## Buyer FAQ
+
+**Does Guard require Cloud sign-in for local protection?**  
+No. Local interception, policy, receipts, and approval paths work without Cloud.
+
+**What does a paid Cloud plan add?**  
+Synced history, searchable activity, team RBAC, integrations, exports, longer
+retention, and admin workflows.
+
+**Where do we see a blocked package install?**  
+**Firewall** for evaluation details, **Evidence** for receipts, **Incidents**
+when severity warrants routing, and export APIs for GRC archives.
+
+**Can we send events to Splunk or Datadog today?**  
+Use the available **Webhook** integration with the canonical event schema in
+[Enterprise event taxonomy](./enterprise-event-taxonomy.md). Native Splunk,
+Datadog, and Sentinel connectors remain catalog **Planned** until setup,
+delivery, retry, and tests ship for each provider.
+
+## Source references
+
+- Guard architecture: [architecture.md](./architecture.md)
+- Incident response: [incident-response.md](./incident-response.md)
+- Remediation patterns: [remediation.md](./remediation.md)
+- Cloud API inventory: `hol-points-portal/docs/guard-cloud-api-inventory.generated.md`

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/docs/guard/get-started.md

@@ -11,6 +11,9 @@ protection. See
 [Local Guard vs Guard Cloud](./local-vs-cloud.md) for the full subscription
 boundary.
 
+For security reviews, sales conversations, and GRC packets, see the
+[Enterprise packet](./enterprise-packet.md).
+
 ## The everyday flow
 
 1. Start the guided first-run setup:

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/pyproject.toml

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

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.570"
+version = "2.0.572"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/src/codex_plugin_scanner/guard/aibom_detection.py

@@ -33,18 +33,31 @@ INVENTORY_ITEM_KINDS: tuple[str, ...] = (
     "network_endpoint",
 )
 
-_MAX_FILE_BYTES = 1024 * 1024
+_READ_CHUNK_BYTES = 65536
 _CURSOR_RULE_PATTERNS = ("*.mdc", "*.md")
 _CODEX_SKILL_ROOTS = (".agents/skills",)
 
 
-def file_content_hash(path: Path, *, max_bytes: int = _MAX_FILE_BYTES) -> str | None:
+def file_content_hash(path: Path, *, max_bytes: int | None = None) -> str | None:
+    """Return a SHA-256 digest of the full file bytes used for approval drift detection.
+
+    When ``max_bytes`` is set, only that prefix is hashed. Production callers must
+    leave ``max_bytes`` unset so tail edits cannot bypass change detection.
+    """
     try:
+        digest = hashlib.sha256()
         with path.open("rb") as handle:
-            payload = handle.read(max_bytes)
+            if max_bytes is None:
+                while True:
+                    chunk = handle.read(_READ_CHUNK_BYTES)
+                    if not chunk:
+                        break
+                    digest.update(chunk)
+            else:
+                digest.update(handle.read(max_bytes))
+        return digest.hexdigest()
     except OSError:
         return None
-    return fingerprint_text(payload.decode("utf-8", errors="replace"))
 
 
 def directory_content_hash(root: Path, *, home_dir: Path) -> str:

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.570"
+__version__ = "2.0.572"

{plugin_scanner-2.0.570 → plugin_scanner-2.0.572}/tests/test_guard_aibom_detection.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from codex_plugin_scanner.guard.adapters.base import HarnessContext
+from codex_plugin_scanner.guard.adapters.cursor import CursorHarnessAdapter
+from codex_plugin_scanner.guard.adapters.hermes import HermesHarnessAdapter
+from codex_plugin_scanner.guard.adapters.openclaw import OpenClawHarnessAdapter
 from codex_plugin_scanner.guard.aibom_detection import (
     INVENTORY_ITEM_KINDS,
     discover_shared_workspace_aibom_artifacts,
@@ -10,10 +14,7 @@ from codex_plugin_scanner.guard.aibom_detection import (
     file_content_hash,
     instruction_role_for_path,
 )
-from codex_plugin_scanner.guard.adapters.base import HarnessContext
-from codex_plugin_scanner.guard.adapters.cursor import CursorHarnessAdapter
-from codex_plugin_scanner.guard.adapters.hermes import HermesHarnessAdapter
-from codex_plugin_scanner.guard.adapters.openclaw import OpenClawHarnessAdapter
+from codex_plugin_scanner.guard.consumer.service import artifact_hash, diff_artifact
 from codex_plugin_scanner.guard.inventory_contract import inventory_snapshot_from_detection
 from codex_plugin_scanner.guard.models import HarnessDetection
 
@@ -102,6 +103,61 @@ def test_discover_codex_skills_and_marketplace_plugins(tmp_path: Path) -> None:
     assert "plugin" in artifact_types
 
 
+def test_content_hash_detects_tail_changes_beyond_one_mebibyte(tmp_path: Path) -> None:
+    prefix = b"A" * (1024 * 1024)
+    path = tmp_path / "AGENTS.md"
+    path.write_bytes(prefix + b"tail-version-one\n")
+    first = file_content_hash(path)
+    path.write_bytes(prefix + b"tail-version-two\n")
+    second = file_content_hash(path)
+
+    assert first is not None
+    assert second is not None
+    assert first != second
+
+
+def test_diff_artifact_detects_tail_only_instruction_change(tmp_path: Path) -> None:
+    workspace = tmp_path / "repo"
+    workspace.mkdir()
+    agents_md = workspace / "AGENTS.md"
+    prefix = b"policy-" * (1024 * 1024 // len(b"policy-") + 1)
+    prefix = prefix[: 1024 * 1024]
+    agents_md.write_bytes(prefix + b"approved-tail\n")
+
+    artifacts_v1 = discover_shared_workspace_aibom_artifacts(
+        "codex",
+        home_dir=tmp_path,
+        workspace_dir=workspace,
+    )
+    artifact_v1 = next(
+        (artifact for artifact in artifacts_v1 if artifact.artifact_type == "instruction"),
+        None,
+    )
+    assert artifact_v1 is not None, "Expected an instruction artifact in v1 discovery"
+    previous = {
+        **artifact_v1.to_dict(),
+        "artifact_hash": artifact_hash(artifact_v1),
+        "env_keys": [],
+    }
+
+    agents_md.write_bytes(prefix + b"malicious-tail\n")
+    artifacts_v2 = discover_shared_workspace_aibom_artifacts(
+        "codex",
+        home_dir=tmp_path,
+        workspace_dir=workspace,
+    )
+    artifact_v2 = next(
+        (artifact for artifact in artifacts_v2 if artifact.artifact_type == "instruction"),
+        None,
+    )
+    assert artifact_v2 is not None, "Expected an instruction artifact in v2 discovery"
+
+    diff = diff_artifact(previous, artifact_v2)
+
+    assert diff["changed"] is True
+    assert diff["previous_hash"] != diff["current_hash"]
+
+
 def test_content_hash_changes_when_instruction_file_changes(tmp_path: Path) -> None:
     path = tmp_path / "AGENTS.md"
     path.write_text("version one\n", encoding="utf-8")