stackgen-sdk 0.4.0rc4__tar.gz → 0.4.0rc5__tar.gz

{stackgen_sdk-0.4.0rc4 → stackgen_sdk-0.4.0rc5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.4.0rc4
+Version: 0.4.0rc5
 Summary: StackGen SDK — Aiden, SRE, and Vault from one client
 Project-URL: Homepage, https://appcd-dev.github.io/stackgen-sdk/
 Project-URL: Documentation, https://appcd-dev.github.io/stackgen-sdk/

{stackgen_sdk-0.4.0rc4 → stackgen_sdk-0.4.0rc5}/src/stackgen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0rc4'
-__version_tuple__ = version_tuple = (0, 4, 0, 'rc4')
+__version__ = version = '0.4.0rc5'
+__version_tuple__ = version_tuple = (0, 4, 0, 'rc5')
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.4.0rc4 → stackgen_sdk-0.4.0rc5}/src/stackgen/aiden/__init__.py

@@ -1,6 +1,7 @@
 """Aiden (platform) namespace — webhooks, sessions, artifacts, Ask Guild, workflows."""
 
 from stackgen.aiden.ask import AskArtifactResult
+from stackgen.aiden.audit import AuditExportResult
 from stackgen.aiden.namespace import AidenNamespace
 from stackgen.aiden.resources import PolicyConflictRule
 from stackgen.aiden.run_status import ExecutionStatus, RunPhase, RunStatus
@@ -21,6 +22,7 @@ __all__ = [
     "AgentDefinition",
     "AidenNamespace",
     "AskArtifactResult",
+    "AuditExportResult",
     "ExecutionStatus",
     "PolicyConflictRule",
     "PublishWorkflowResult",

stackgen_sdk-0.4.0rc5/src/stackgen/aiden/audit.py

@@ -0,0 +1,69 @@
+"""Page through audit events and export them to a local NDJSON file."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterator
+
+from stackgen.aiden.resources import AidenResources
+from stackgen.config import StackgenConfig
+
+
+@dataclass
+class AuditExportResult:
+    output_path: Path
+    count: int
+
+
+class AuditExportJourney:
+    def __init__(self, config: StackgenConfig) -> None:
+        self._resources = AidenResources(config)
+
+    def iter_events(self, **params: Any) -> Iterator[dict[str, Any]]:
+        """Yield every audit event, paging past the server's per-page cap.
+
+        Accepts the same filters as ``list_audit_events`` (``event_type``,
+        ``actor_login``, ``tool_name``, ``from``/``to``, ``format="ocsf"``,
+        …). Pass ``max_events`` to stop after that many rows.
+        """
+        max_events = params.pop("max_events", None)
+        if max_events is not None:
+            max_events = int(max_events)
+            if max_events < 0:
+                raise ValueError("max_events must be >= 0")
+
+        query = dict(params)
+        yielded = 0
+        while True:
+            page = self._resources.list_audit_events_page(**query)
+            items = page.get("items")
+            if not isinstance(items, list):
+                items = []
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                yield item
+                yielded += 1
+                if max_events is not None and yielded >= max_events:
+                    return
+
+            if not page.get("has_more"):
+                return
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+            query["cursor"] = cursor
+
+    def export(self, output_path: str, **params: Any) -> AuditExportResult:
+        """Page through every matching event and write NDJSON to ``output_path``."""
+        dest = Path(output_path).expanduser().resolve()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        count = 0
+        with dest.open("w", encoding="utf-8") as handle:
+            for event in self.iter_events(**params):
+                handle.write(json.dumps(event, default=str))
+                handle.write("\n")
+                count += 1
+        return AuditExportResult(output_path=dest, count=count)

{stackgen_sdk-0.4.0rc4 → stackgen_sdk-0.4.0rc5}/src/stackgen/aiden/namespace.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
+from stackgen.aiden.audit import AuditExportJourney, AuditExportResult
 from stackgen.aiden.models import ModelRegistry
 from stackgen.aiden.resources import AidenResources, PolicyConflictRule
 from stackgen.aiden.run_status import RunStatus, build_run_status, require_run_ids
@@ -29,6 +30,7 @@ class AidenNamespace:
         self._webhook_ops = WebhookOps(config)
         self._resources = AidenResources(config)
         self._subscribe = ExecutionSubscribe(config)
+        self._audit = AuditExportJourney(config)
         self.models = ModelRegistry(config)
 
     def run_webhook_and_download_report(
@@ -384,8 +386,29 @@ class AidenNamespace:
         return self._resources.when_policies_disagree(agent_name, rule)
 
     def list_audit_events(self, **params: Any) -> list[dict[str, Any]]:
+        """First page of GET /audit/events only.
+
+        Prefer :meth:`iter_audit_events` or :meth:`export_audit_events` when you
+        need every matching row past the server page cap.
+        """
         return self._resources.list_audit_events(**params)
 
+    def iter_audit_events(self, **params: Any) -> Iterator[dict[str, Any]]:
+        """Yield every matching audit event, paging past the server page cap.
+
+        Same filters as :meth:`list_audit_events` (``event_type``, ``from`` /
+        ``to``, ``format="ocsf"``, …). Pass ``max_events`` to stop early.
+        """
+        return self._audit.iter_events(**params)
+
+    def export_audit_events(self, output_path: str, **params: Any) -> AuditExportResult:
+        """Page through matching audit events and write NDJSON to ``output_path``.
+
+        Use ``format="ocsf"`` when handing the file to a SIEM or external
+        auditor. Same filters as :meth:`iter_audit_events`.
+        """
+        return self._audit.export(output_path, **params)
+
     def get_audit_event(self, event_id: str) -> dict[str, Any]:
         return self._resources.get_audit_event(event_id)
 

{stackgen_sdk-0.4.0rc4 → stackgen_sdk-0.4.0rc5}/src/stackgen/aiden/resources.py

@@ -274,8 +274,18 @@ class AidenResources:
         return {"combining_algorithm": wire, "rule": rule}
 
     def list_audit_events(self, **params: Any) -> list[dict[str, Any]]:
+        """First page of GET /audit/events only.
+
+        Prefer :meth:`~stackgen.aiden.namespace.AidenNamespace.iter_audit_events`
+        or :meth:`~stackgen.aiden.namespace.AidenNamespace.export_audit_events`
+        when you need every matching row past the server page cap.
+        """
         return _http.as_list(self._get("/audit/events", params))
 
+    def list_audit_events_page(self, **params: Any) -> dict[str, Any]:
+        """One cursor page of GET /audit/events (items/next_cursor/has_more)."""
+        return _as_object(self._get("/audit/events", params), "listAuditEvents")
+
     def get_audit_event(self, event_id: str) -> dict[str, Any]:
         return _as_object(self._get(f"/audit/events/{event_id}"), "getAuditEvent")