shieldcortex
Official Python SDK for the ShieldCortex 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 (free tier: 500 scans/month).
Installation
pip install shieldcortex
With framework integrations:
pip install shieldcortex[crewai] # also installs CrewAI (the memory guard itself does not need it)
pip install shieldcortex[langchain] # LangChain callback handler
Quick Start
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
The sync client holds an httpx connection pool. Use it as a context manager
so the pool is closed when you are done:
from shieldcortex import ShieldCortex
with ShieldCortex(api_key="sc_live_...") as client:
result = client.scan("user input to remember")
In long-lived processes that keep a client around instead, call
client.close() when you are finished with it.
Async Support
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:
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}")
Memory Guard (CrewAI and others)
ShieldCortexMemoryGuard is a framework-agnostic pre-write check: call guard.check() before writing content to any memory store — from a CrewAI agent, another framework, or your own code. It scans the content and raises MemoryBlockedError if it is blocked (or, by default, quarantined). It does not hook into CrewAI automatically and does not import CrewAI; the [crewai] extra only installs CrewAI itself.
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
The callbacks scan chain inputs, LLM prompts, text in chat messages, tool inputs,
LLM outputs, and tool outputs, whenever LangChain fires the matching callback
(see LLM cache below for a case where it does not). Use the async handler
for ainvoke and astream, or the sync handler for invoke:
from langchain_openai import ChatOpenAI # or any LangChain chat model / LLM
from shieldcortex import AsyncShieldCortex, ShieldCortex
from shieldcortex.integrations.langchain import (
ContentBlockedError,
ShieldCortexCallbackHandler,
ShieldCortexSyncCallbackHandler,
)
model = ChatOpenAI()
async with AsyncShieldCortex(api_key="sc_live_...") as client:
handler = ShieldCortexCallbackHandler(client, raise_on_block=True)
try:
reply = await model.ainvoke("Hello", config={"callbacks": [handler]})
except ContentBlockedError as error: # also a ValueError
print(error.result.firewall.reason, error.source_identifier)
with ShieldCortex(api_key="sc_live_...") as client:
handler = ShieldCortexSyncCallbackHandler(client, raise_on_block=True)
reply = model.invoke("Hello", config={"callbacks": [handler]})
By default only BLOCK verdicts act. With raise_on_block=True, a block stops
the run with ContentBlockedError; otherwise it logs a warning. Use the matching
handler for the call mode: LangChain cannot propagate an async handler's block
from invoke.
- Chat message text means string content, string blocks, and dict blocks
whose
textis a string and whosetypeis"text"or absent. Images and other block types are not scanned. Empty prompts are skipped. - Streaming: LLM output is scanned when the model finishes. With
streamorastream, every chunk has already reached your code by then, so an output block stops the run after delivery and cannot prevent exposure. Buffer the stream yourself if blocked output must never be shown. Input scans still run before the model starts. - Tool outputs are reduced to text before scanning: strings as is; objects
with string
.content(such asToolMessage) by that content; a list.contentby its string items and the stringtextof its dict items, joined by newlines; anything else as JSON (default=str), falling back tostr(). Other blocks in a list.content, such as images or dicts without a stringtext(for example{"payload": "..."}), are dropped rather than JSON-encoded, so their contents are not scanned.Noneand non-string outputs that reduce to empty text are not scanned. - LLM cache: a bare (non-chat) LLM call answered entirely from a
LangChain LLM cache fires no callbacks: LangChain checks the cache before
on_llm_startand returns the cached text withouton_llm_end. Neither the prompt nor the cached output is scanned, and no block orfail_closederror can stop that call. Setcache=Falseon LLMs whose calls must be scanned (the default,cache=None, uses any cache set withset_llm_cache), or scan outside the model call. Chat models fireon_chat_model_startbefore their cache lookup, so a cached chat call still has its input scanned. - Sync-only tools under
ainvoke: LangChain runs a tool that has no coroutine in a worker thread and logs and swallows every exception the async handler raises there. Neither aBLOCKverdict nor afail_closedscan error stops that tool: it runs andainvokereturns its output. Give the tool an async implementation (coroutine=onStructuredTool, or_arun), or pass the sync handler with a sync client for those calls, e.g.await tool.ainvoke(args, config={"callbacks": [sync_handler]}); its exceptions do propagate on that route. - Scan errors: by default a
ShieldCortexErrorfrom the scan call (any HTTP error such as 401, 429 or 5xx, or a timeout) is logged and that scan is skipped, so the content passes. Other exceptions, such as connection errors, are not caught: withraise_on_block=Truethey stop the run, otherwise LangChain logs them.
Two opt-in options, available on both handlers:
| Option | Default | Effect |
|---|---|---|
fail_closed |
False |
With raise_on_block=True, a ShieldCortexError from a scan raises ContentBlockedError instead of being logged and skipped (except for sync-only tools under ainvoke with the async handler, see above). error.result is None and error.__cause__ is the original error. Requires raise_on_block=True; otherwise the constructor raises ValueError. |
block_on_quarantine |
False |
Treat QUARANTINE verdicts exactly like BLOCK (warn, or raise with raise_on_block=True). |
handler = ShieldCortexSyncCallbackHandler(
client, raise_on_block=True, fail_closed=True, block_on_quarantine=True
)
ContentBlockedError.result is typed ScanResult | None. Without
fail_closed it is never None at runtime, but type checkers will still ask
you to narrow it before reading error.result.firewall:
except ContentBlockedError as error:
if error.result is None: # fail_closed: the scan itself failed
print("scan failed:", error.__cause__)
else:
print(error.result.firewall.reason)
Audit Logs
Every scan is logged. Query your history, export for compliance, or auto-paginate through all entries:
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
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:
- Deletes — the TypeScript SDK returns
voidfrom every delete method; the Python SDK returns the typed response body where the server sends one (per-language internal consistency). - Audit export — both SDKs return the raw file content together with the
parsed
X-ShieldCortex-Export-*integrity headers. An absentsha256orsignatureheader means the export is unverifiable.
Documentation
License
MIT
Metadata
Release files for shieldcortex 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shieldcortex-0.5.0.tar.gz | 72.7 kB | With provenance | Details for shieldcortex-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shieldcortex-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for shieldcortex-0.5.0-py3-none-any.whl |
Total release size: 118.4 kB
Release files / shieldcortex-0.5.0.tar.gz
| Download URL | shieldcortex-0.5.0.tar.gz |
|---|---|
| Size | 72.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e2232b3c40a383eef7bee20aa40c24a8d62fe2a31fcaf88a8400e2103d8534b8
|
|
BLAKE2b-256 checksum How to use checksums |
77c002532d452586f81c4fde212970361e0465a2dfe206a72d918603805c793d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / shieldcortex-0.5.0-py3-none-any.whl
| Download URL | shieldcortex-0.5.0-py3-none-any.whl |
|---|---|
| Size | 45.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bf856eb448e600c139dd2d016582ae09769b77e4252523ccc308d319a3985c07
|
|
BLAKE2b-256 checksum How to use checksums |
0b836d4c38444e851abab86242a175f513f5deb4621cfc34cfe6eb16ceca096a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logSecurity for shieldcortex 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for shieldcortex-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.