shieldcortex 0.1.0__tar.gz → 0.2.0__tar.gz

shieldcortex-0.2.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 0.2.0 — 2026-08-11
+
+SDK lockstep release: the Python SDK now covers the full customer surface
+documented in the SDK lockstep contract, in lockstep with the TypeScript SDK.
+
+### Added
+
+- **Verification** — `submit_verification()`, `list_verifications()`,
+  `get_verification()`, `get_verification_stats()`, `delete_verification()`
+- **Skills** — `ingest_skill_scans()`, `list_skill_scans()`
+- **Threats** — `report_threat()` (OpenClaw realtime compat shim)
+- **Incidents** — `replay_incidents()`
+- **Recall** — `explain_recall()`
+- **Sync** — `get_sync_health()`, `push_memories()`, `list_synced_memories()`,
+  `push_memory_graph()`. Note: `list_synced_memories()` omits the
+  `include_deleted` param unless truthy — the server Boolean-coerces any
+  present value (even `"false"`) as enabling it. Every other boolean query
+  param was audited for the same coercion trap; none affected.
+- **Licence** — `get_license()`, `regenerate_license()`
+- **Audit** — `ingest_audit_events()`, `get_iron_dome_stats()`,
+  `get_iron_dome_events()`, and the export-manifest surface
+  (`list_audit_exports()`, `get_audit_export_manifest()`,
+  `verify_audit_export()`, `list_audit_export_verifications()`)
+- Cross-SDK endpoint parity manifest and drift guard
+  (`tests/endpoint_manifest.py`, kept in lockstep with the TS SDK's
+  `tests/endpoint-manifest.ts`), including a sync/async surface parity test
+- Shared request builders (`_payloads.py`) so the sync and async clients
+  construct identical wire payloads and cannot drift
+
+### Changed
+
+- **BREAKING:** `export_audit_logs()` (both clients) now returns
+  `AuditExportResult` — the raw file body in `.content` plus the parsed
+  `X-ShieldCortex-Export-*` integrity headers in `.headers` — instead of a
+  bare `str`. Previously the integrity headers were discarded, so exports
+  structurally could not be verified. An absent `sha256`/`signature` header
+  is `None` (never `""`): the export is unverifiable. Migration:
+  `client.export_audit_logs(...)` → `client.export_audit_logs(...).content`.
+
+### Deprecated
+
+- `create_checkout_session()` / `create_portal_session()` now emit
+  `DeprecationWarning`: self-serve plans were retired 2026-07 (Free +
+  Enterprise model); the endpoints remain for grandfathered licence holders.
+
+## 0.1.1 — 2026-03-12
+
+- Added Iron Dome patterns/policies client support; fixed the default-policy
+  verb (PUT).
+
+## 0.1.0 — 2026-02-15
+
+- Initial release: scanning, audit, quarantine, keys, teams, invites,
+  billing, devices, alerts, webhooks, firewall rules; sync + async clients;
+  CrewAI and LangChain integrations; Python 3.9+ compatibility fixes.

{shieldcortex-0.1.0 → shieldcortex-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: shieldcortex
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python SDK for the ShieldCortex API — AI memory security scanning
 Project-URL: Homepage, https://shieldcortex.ai
 Project-URL: Documentation, https://shieldcortex.ai/docs
@@ -45,7 +45,25 @@ Description-Content-Type: text/markdown
 
 Official Python SDK for the [ShieldCortex](https://shieldcortex.ai) API — AI memory security scanning.
 
-ShieldCortex is a 6-layer defence pipeline that protects AI agent memory from prompt injection, credential leaks, encoding attacks, and more.
+## How It Works
+
+AI agents store memories (user inputs, tool outputs, conversation history) to improve over time. But those memories are an attack surface — prompt injection, credential leaks, and encoding attacks can all be smuggled into memory stores.
+
+ShieldCortex scans content **before** it reaches your agent's memory through a 6-layer defence pipeline:
+
+```
+Agent receives content
+        │
+        ▼
+  ShieldCortex scan ──→ BLOCK   → reject, log threat
+        │
+        ▼
+      ALLOW ──→ safe to store in memory
+```
+
+The SDK sends content to the ShieldCortex cloud API and returns a verdict: **ALLOW**, **BLOCK**, or **QUARANTINE** — along with trust scores, threat indicators, and sensitivity classification.
+
+**Get an API key** at [shieldcortex.ai](https://shieldcortex.ai) (free tier: 500 scans/month).
 
 ## Installation
 
@@ -67,14 +85,15 @@ from shieldcortex import ShieldCortex
 
 client = ShieldCortex(api_key="sc_live_...")
 
-# Scan user input before storing in memory
-result = client.scan("user input here")
+# Scan content before storing in your agent's memory
+result = client.scan("user input to remember")
 
-if not result.allowed:
+if result.allowed:
+    save_to_memory(result)  # safe — store it
+else:
     print(f"Blocked: {result.firewall.reason}")
     print(f"Threats: {result.firewall.threat_indicators}")
-else:
-    print(f"Safe (trust: {result.trust.score})")
+    # don't store — content failed security checks
 ```
 
 ## Async Support
@@ -88,6 +107,8 @@ async with AsyncShieldCortex(api_key="sc_live_...") as client:
 
 ## Batch Scanning
 
+Scan up to 100 items in a single request — useful for bulk-importing memory entries:
+
 ```python
 from shieldcortex import BatchItem
 
@@ -98,25 +119,9 @@ result = client.scan_batch([
 print(f"Scanned: {result.total_scanned}, Threats: {result.threats}")
 ```
 
-## Audit Logs
-
-```python
-from shieldcortex import AuditQuery
-
-# Query with filters
-logs = client.get_audit_logs(AuditQuery(level="BLOCK", limit=10))
-
-# Auto-paginate through all entries
-for entry in client.iter_audit_logs():
-    print(entry.id, entry.firewall_result)
-
-# Export as CSV
-csv = client.export_audit_logs(format="csv")
-```
-
 ## CrewAI Integration
 
-Scan all memory writes before they reach your store:
+Add a security gate between your CrewAI agent and its memory store. The guard scans all content before it's saved — blocking prompt injection and credential leaks:
 
 ```python
 from shieldcortex import ShieldCortex
@@ -134,7 +139,7 @@ except MemoryBlockedError as e:
 
 ## LangChain Integration
 
-Scan LLM inputs and outputs automatically:
+Automatically scan all LLM inputs and outputs as they flow through your chain — no changes to your existing code:
 
 ```python
 from shieldcortex import AsyncShieldCortex
@@ -143,10 +148,30 @@ from shieldcortex.integrations.langchain import ShieldCortexCallbackHandler
 client = AsyncShieldCortex(api_key="sc_live_...")
 handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
 
-# Pass to any LangChain component
+# Scans inputs on chain start, outputs on LLM end, and tool I/O
 llm = ChatOpenAI(callbacks=[handler])
 ```
 
+## Audit Logs
+
+Every scan is logged. Query your history, export for compliance, or auto-paginate through all entries:
+
+```python
+from shieldcortex import AuditQuery
+
+# Query with filters
+logs = client.get_audit_logs(AuditQuery(level="BLOCK", limit=10))
+
+# Auto-paginate through all entries
+for entry in client.iter_audit_logs():
+    print(entry.id, entry.firewall_result)
+
+# Export as CSV — returns the raw body plus integrity headers
+export = client.export_audit_logs(format="csv")
+print(export.content)
+print(export.headers.sha256)  # None ⇒ export unverifiable
+```
+
 ## Error Handling
 
 ```python
@@ -162,23 +187,60 @@ except ValidationError:
     print("Invalid request")
 ```
 
-## Full API Coverage
+## API Coverage
 
-The SDK covers all ShieldCortex API endpoints:
+The SDK covers the full customer surface documented in the SDK lockstep contract:
 
 | Category | Methods |
 |----------|---------|
 | **Scanning** | `scan()`, `scan_batch()`, `scan_skill()` |
-| **Audit** | `get_audit_logs()`, `get_audit_entry()`, `get_audit_stats()`, `get_audit_trends()`, `export_audit_logs()`, `iter_audit_logs()` |
+| **Audit** | `get_audit_logs()`, `get_audit_entry()`, `get_audit_stats()`, `get_audit_trends()`, `export_audit_logs()`, `iter_audit_logs()`, `ingest_audit_events()`, `get_iron_dome_stats()`, `get_iron_dome_events()` |
+| **Audit Export Manifests** | `list_audit_exports()`, `get_audit_export_manifest()`, `verify_audit_export()`, `list_audit_export_verifications()` |
 | **Quarantine** | `get_quarantine()`, `get_quarantine_item()`, `review_quarantine_item()` |
 | **API Keys** | `create_api_key()`, `list_api_keys()`, `revoke_api_key()` |
 | **Teams** | `get_team()`, `update_team()`, `get_team_members()`, `get_usage()` |
 | **Invites** | `create_invite()`, `list_invites()`, `delete_invite()`, `resend_invite()` |
-| **Billing** | `create_checkout_session()`, `create_portal_session()` |
+| **Billing** (deprecated) | `create_checkout_session()`, `create_portal_session()` — self-serve plans retired 2026-07; retained for grandfathered licence holders |
 | **Devices** | `get_devices()`, `register_device()`, `update_device()`, `device_heartbeat()` |
 | **Alerts** | `get_alerts()`, `create_alert()`, `update_alert()`, `delete_alert()` |
 | **Webhooks** | `get_webhooks()`, `create_webhook()`, `update_webhook()`, `delete_webhook()`, `test_webhook()`, `get_webhook_deliveries()` |
 | **Firewall Rules** | `get_firewall_rules()`, `get_active_firewall_rules()`, `create_firewall_rule()`, `update_firewall_rule()`, `delete_firewall_rule()` |
+| **Iron Dome** | `get_injection_patterns()`, `get_injection_patterns_sync()`, `create_injection_pattern()`, `update_injection_pattern()`, `test_injection_pattern()`, `delete_injection_pattern()`, `get_iron_dome_policies()`, `get_iron_dome_policy_sync()`, `create_iron_dome_policy()`, `update_iron_dome_policy()`, `set_default_iron_dome_policy()`, `delete_iron_dome_policy()` |
+| **Verification** | `submit_verification()`, `list_verifications()`, `get_verification()`, `get_verification_stats()`, `delete_verification()` |
+| **Skills** | `ingest_skill_scans()`, `list_skill_scans()` |
+| **Threats** | `report_threat()` |
+| **Incidents** | `replay_incidents()` |
+| **Recall** | `explain_recall()` |
+| **Sync** | `get_sync_health()`, `push_memories()`, `list_synced_memories()`, `push_memory_graph()` |
+| **Licence** | `get_license()`, `regenerate_license()` |
+
+### Deferred endpoints
+
+The audit **verification-export download chain** (`GET .../verifications/export`,
+`GET .../verification-exports`, `GET .../verification-exports/{id}` and its
+`/download`) is deliberately deferred — it serves CLI tooling rather than SDK
+consumers. See `tests/endpoint_manifest.py` for the canonical list.
+
+### Out of scope
+
+- `/v1/platform/*` — platform-owner operations
+- `/v1/auth/*` — magic-link login flows (browser/dashboard, not API-key auth)
+- `/v1/customizer/*` — retired 2026-07
+
+Additional dashboard/session-scoped `/v1` routes exist server-side; they sit
+outside the SDK's API-key surface.
+
+### Cross-SDK policy notes
+
+The Python and TypeScript SDKs cover the same endpoint manifest, with two
+deliberate differences:
+
+1. **Deletes** — the TypeScript SDK returns `void` from every delete method;
+   the Python SDK returns the typed response body where the server sends one
+   (per-language internal consistency).
+2. **Audit export** — both SDKs return the raw file content together with the
+   parsed `X-ShieldCortex-Export-*` integrity headers. An absent `sha256` or
+   `signature` header means the export is unverifiable.
 
 ## Documentation
 

shieldcortex-0.2.0/README.md

@@ -0,0 +1,214 @@
+# shieldcortex
+
+[![PyPI](https://img.shields.io/pypi/v/shieldcortex)](https://pypi.org/project/shieldcortex/)
+[![Python](https://img.shields.io/pypi/pyversions/shieldcortex)](https://pypi.org/project/shieldcortex/)
+[![License](https://img.shields.io/pypi/l/shieldcortex)](LICENSE)
+
+Official Python SDK for the [ShieldCortex](https://shieldcortex.ai) API — AI memory security scanning.
+
+## How It Works
+
+AI agents store memories (user inputs, tool outputs, conversation history) to improve over time. But those memories are an attack surface — prompt injection, credential leaks, and encoding attacks can all be smuggled into memory stores.
+
+ShieldCortex scans content **before** it reaches your agent's memory through a 6-layer defence pipeline:
+
+```
+Agent receives content
+        │
+        ▼
+  ShieldCortex scan ──→ BLOCK   → reject, log threat
+        │
+        ▼
+      ALLOW ──→ safe to store in memory
+```
+
+The SDK sends content to the ShieldCortex cloud API and returns a verdict: **ALLOW**, **BLOCK**, or **QUARANTINE** — along with trust scores, threat indicators, and sensitivity classification.
+
+**Get an API key** at [shieldcortex.ai](https://shieldcortex.ai) (free tier: 500 scans/month).
+
+## Installation
+
+```bash
+pip install shieldcortex
+```
+
+With framework integrations:
+
+```bash
+pip install shieldcortex[crewai]     # CrewAI memory guard
+pip install shieldcortex[langchain]  # LangChain callback handler
+```
+
+## Quick Start
+
+```python
+from shieldcortex import ShieldCortex
+
+client = ShieldCortex(api_key="sc_live_...")
+
+# Scan content before storing in your agent's memory
+result = client.scan("user input to remember")
+
+if result.allowed:
+    save_to_memory(result)  # safe — store it
+else:
+    print(f"Blocked: {result.firewall.reason}")
+    print(f"Threats: {result.firewall.threat_indicators}")
+    # don't store — content failed security checks
+```
+
+## Async Support
+
+```python
+from shieldcortex import AsyncShieldCortex
+
+async with AsyncShieldCortex(api_key="sc_live_...") as client:
+    result = await client.scan("user input here")
+```
+
+## Batch Scanning
+
+Scan up to 100 items in a single request — useful for bulk-importing memory entries:
+
+```python
+from shieldcortex import BatchItem
+
+result = client.scan_batch([
+    BatchItem(content="memory entry 1"),
+    BatchItem(content="memory entry 2"),
+])
+print(f"Scanned: {result.total_scanned}, Threats: {result.threats}")
+```
+
+## CrewAI Integration
+
+Add a security gate between your CrewAI agent and its memory store. The guard scans all content before it's saved — blocking prompt injection and credential leaks:
+
+```python
+from shieldcortex import ShieldCortex
+from shieldcortex.integrations.crewai import ShieldCortexMemoryGuard, MemoryBlockedError
+
+client = ShieldCortex(api_key="sc_live_...")
+guard = ShieldCortexMemoryGuard(client, mode="strict")
+
+try:
+    guard.check("content to remember")
+    # Safe — save to memory store
+except MemoryBlockedError as e:
+    print(f"Blocked: {e.result.firewall.reason}")
+```
+
+## LangChain Integration
+
+Automatically scan all LLM inputs and outputs as they flow through your chain — no changes to your existing code:
+
+```python
+from shieldcortex import AsyncShieldCortex
+from shieldcortex.integrations.langchain import ShieldCortexCallbackHandler
+
+client = AsyncShieldCortex(api_key="sc_live_...")
+handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
+
+# Scans inputs on chain start, outputs on LLM end, and tool I/O
+llm = ChatOpenAI(callbacks=[handler])
+```
+
+## Audit Logs
+
+Every scan is logged. Query your history, export for compliance, or auto-paginate through all entries:
+
+```python
+from shieldcortex import AuditQuery
+
+# Query with filters
+logs = client.get_audit_logs(AuditQuery(level="BLOCK", limit=10))
+
+# Auto-paginate through all entries
+for entry in client.iter_audit_logs():
+    print(entry.id, entry.firewall_result)
+
+# Export as CSV — returns the raw body plus integrity headers
+export = client.export_audit_logs(format="csv")
+print(export.content)
+print(export.headers.sha256)  # None ⇒ export unverifiable
+```
+
+## Error Handling
+
+```python
+from shieldcortex.errors import AuthError, RateLimitError, ValidationError
+
+try:
+    result = client.scan("content")
+except AuthError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except ValidationError:
+    print("Invalid request")
+```
+
+## API Coverage
+
+The SDK covers the full customer surface documented in the SDK lockstep contract:
+
+| Category | Methods |
+|----------|---------|
+| **Scanning** | `scan()`, `scan_batch()`, `scan_skill()` |
+| **Audit** | `get_audit_logs()`, `get_audit_entry()`, `get_audit_stats()`, `get_audit_trends()`, `export_audit_logs()`, `iter_audit_logs()`, `ingest_audit_events()`, `get_iron_dome_stats()`, `get_iron_dome_events()` |
+| **Audit Export Manifests** | `list_audit_exports()`, `get_audit_export_manifest()`, `verify_audit_export()`, `list_audit_export_verifications()` |
+| **Quarantine** | `get_quarantine()`, `get_quarantine_item()`, `review_quarantine_item()` |
+| **API Keys** | `create_api_key()`, `list_api_keys()`, `revoke_api_key()` |
+| **Teams** | `get_team()`, `update_team()`, `get_team_members()`, `get_usage()` |
+| **Invites** | `create_invite()`, `list_invites()`, `delete_invite()`, `resend_invite()` |
+| **Billing** (deprecated) | `create_checkout_session()`, `create_portal_session()` — self-serve plans retired 2026-07; retained for grandfathered licence holders |
+| **Devices** | `get_devices()`, `register_device()`, `update_device()`, `device_heartbeat()` |
+| **Alerts** | `get_alerts()`, `create_alert()`, `update_alert()`, `delete_alert()` |
+| **Webhooks** | `get_webhooks()`, `create_webhook()`, `update_webhook()`, `delete_webhook()`, `test_webhook()`, `get_webhook_deliveries()` |
+| **Firewall Rules** | `get_firewall_rules()`, `get_active_firewall_rules()`, `create_firewall_rule()`, `update_firewall_rule()`, `delete_firewall_rule()` |
+| **Iron Dome** | `get_injection_patterns()`, `get_injection_patterns_sync()`, `create_injection_pattern()`, `update_injection_pattern()`, `test_injection_pattern()`, `delete_injection_pattern()`, `get_iron_dome_policies()`, `get_iron_dome_policy_sync()`, `create_iron_dome_policy()`, `update_iron_dome_policy()`, `set_default_iron_dome_policy()`, `delete_iron_dome_policy()` |
+| **Verification** | `submit_verification()`, `list_verifications()`, `get_verification()`, `get_verification_stats()`, `delete_verification()` |
+| **Skills** | `ingest_skill_scans()`, `list_skill_scans()` |
+| **Threats** | `report_threat()` |
+| **Incidents** | `replay_incidents()` |
+| **Recall** | `explain_recall()` |
+| **Sync** | `get_sync_health()`, `push_memories()`, `list_synced_memories()`, `push_memory_graph()` |
+| **Licence** | `get_license()`, `regenerate_license()` |
+
+### Deferred endpoints
+
+The audit **verification-export download chain** (`GET .../verifications/export`,
+`GET .../verification-exports`, `GET .../verification-exports/{id}` and its
+`/download`) is deliberately deferred — it serves CLI tooling rather than SDK
+consumers. See `tests/endpoint_manifest.py` for the canonical list.
+
+### Out of scope
+
+- `/v1/platform/*` — platform-owner operations
+- `/v1/auth/*` — magic-link login flows (browser/dashboard, not API-key auth)
+- `/v1/customizer/*` — retired 2026-07
+
+Additional dashboard/session-scoped `/v1` routes exist server-side; they sit
+outside the SDK's API-key surface.
+
+### Cross-SDK policy notes
+
+The Python and TypeScript SDKs cover the same endpoint manifest, with two
+deliberate differences:
+
+1. **Deletes** — the TypeScript SDK returns `void` from every delete method;
+   the Python SDK returns the typed response body where the server sends one
+   (per-language internal consistency).
+2. **Audit export** — both SDKs return the raw file content together with the
+   parsed `X-ShieldCortex-Export-*` integrity headers. An absent `sha256` or
+   `signature` header means the export is unverifiable.
+
+## Documentation
+
+- [ShieldCortex Docs](https://shieldcortex.ai/docs)
+- [API Reference](https://shieldcortex.ai/docs)
+- [Examples](examples/)
+
+## License
+
+MIT

shieldcortex-0.2.0/examples/audit_export.py

@@ -0,0 +1,48 @@
+"""Audit log querying and export example."""
+
+from shieldcortex import ShieldCortex, AuditQuery
+
+client = ShieldCortex(api_key="sc_live_YOUR_KEY_HERE")
+
+# Get summary stats
+stats = client.get_audit_stats(time_range="7d")
+print(f"Total operations: {stats.total_operations}")
+print(f"Allowed: {stats.allowed_count}")
+print(f"Blocked: {stats.blocked_count}")
+print(f"Quarantined: {stats.quarantined_count}")
+
+# Query blocked entries
+logs = client.get_audit_logs(AuditQuery(level="BLOCK", limit=5))
+print(f"\nRecent blocks ({logs.total} total):")
+for entry in logs.logs:
+    print(f"  [{entry.timestamp}] {entry.reason} (trust: {entry.trust_score})")
+
+# Auto-paginate through all entries
+print("\nAll audit entries:")
+for entry in client.iter_audit_logs(AuditQuery(level="BLOCK")):
+    print(f"  #{entry.id}: {entry.firewall_result}")
+
+# Export as CSV — returns the raw body plus X-ShieldCortex-Export-* integrity headers
+export = client.export_audit_logs(format="csv")
+with open("audit_export.csv", "w") as f:
+    f.write(export.content)
+print("\nExported to audit_export.csv")
+
+# Verify the export's integrity. sha256/signature/manifest_id are None when
+# the server did not send them — the export is unverifiable, never "".
+headers = export.headers
+if headers.sha256 is None or headers.signature is None:
+    print("Export is UNVERIFIABLE — integrity headers absent")
+else:
+    print(f"Entries: {headers.count}")
+    print(f"SHA-256: {headers.sha256}")
+    print(f"Signature ({headers.signature_algorithm}): {headers.signature}")
+    if headers.manifest_id is not None:
+        # Server-side check against the persisted, signed manifest
+        response = client.verify_audit_export(
+            headers.manifest_id, export_sha256=headers.sha256
+        )
+        result = response.verification
+        print(f"Manifest {headers.manifest_id}:")
+        print(f"  signature valid: {result.signature_valid}")
+        print(f"  sha256 matches:  {result.sha256_matches}")

{shieldcortex-0.1.0 → shieldcortex-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shieldcortex"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official Python SDK for the ShieldCortex API — AI memory security scanning"
 readme = "README.md"
 license = { text = "MIT" }