Grimdall for Python

One decorator. Any framework. Zero infra.

Grimdall is a local-only runtime security layer for AI agents. One import guards tool calls in any agent framework, with no proxy, no Docker, no signup, and no network calls. Policies, rate limits, budgets, approvals, and a tamper-evident audit trail live in your project's .grimdall/ directory and interoperate with the Grimdall CLI hooks and Node SDK on the same hash-chained audit.json.

Install

pip install grimdall

No dependencies beyond the Python standard library. Works offline, forever, for $0/month.

One decorator

from grimdall import Guard

guard = Guard()  # zero-config: reads .grimdall/ policies, appends the local audit chain

@guard.wrap
def run_shell(command: str) -> str:
    return f"[mock] executed: {command}"

run_shell("ls -la")   # allowed, logged as "allowed"
run_shell("rm -rf /") # raises GrimdallBlockedError, logged as "blocked"

Every decision is appended to the same SHA-256 hash-chained audit file as CLI-hook events, so a single audit.json can be verified end to end:

from grimdall import AuditTrail

AuditTrail(".grimdall").verify()  # raises AuditError on any tampering

Inline guardrails

from grimdall import Guard, Policy

guard = Guard()
guard.add_policy(
    Policy(
        deny=["github_delete_repo"],
        rate_limit={"max": 10, "per": "minute"},
        budget={"max_spend": 50.0, "period": "day"},
        require_approval=["deploy_production"],
    )
)

Evaluation order: identity/credential -> policy rules -> rate limits -> budget -> approval -> execute. Approval tools prompt in your terminal ([Allow/Deny/Allow 1h]) and a timeout or a missing TTY denies the call: approvals never fail open.

Any framework

from grimdall import Guard
from grimdall.integrations.langchain import GrimdallCallbackHandler

handler = GrimdallCallbackHandler(Guard())

Adapters ship for LangChain, openai-agents, CrewAI, and AutoGen under grimdall.integrations.*. Each is a thin shim over the same core Guard and never forces the framework to be installed.

Audit mode

When .grimdall/config.json sets "mode": "audit" (the CLI default), blocked decisions are recorded as would_block and the call proceeds. Run npx grimdall mode enforce to switch to hard enforcement.

Project layout

.grimdall/  (created for you)
├── policies.json   # default policies (CLI-compatible)
├── config.json     # mode + optional Slack webhook
├── audit.json      # tamper-evident hash chain
└── spend.json      # budget ledger

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for relayai-security.dev from gravatar.com relayai-security.dev

License

Apache Software License (Apache-2.0)

Requires

Python >=3.9

Provides Extra

langchain openai-agents crewai autogen all

Tags

ai agents guardrails security llm langchain crewai autogen openai-agents

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

grimdall-0.3.3.tar.gz (21.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

grimdall-0.3.3-py3-none-any.whl (20.9 kB view details)

Uploaded Python 3

File details

Details for the file grimdall-0.3.3.tar.gz.

File metadata

  • Download URL: grimdall-0.3.3.tar.gz
  • Upload date:
  • Size: 21.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for grimdall-0.3.3.tar.gz
Algorithm Hash digest
SHA256 58fcdd82566b61488cedefdb4d3f9a6af5cfdeb7f368a35d05b4fc6f3ed12ea7
MD5 688d5153cc661b70d74b318edcdbf3aa
BLAKE2b-256 44ade2013c3d27b9941590f1820aa91afed01b00c93eaffa5f57f84a5ccbc0e1

See more details on using hashes here.

Provenance

The following attestation bundles were made for grimdall-0.3.3.tar.gz:

Publisher: publish-python.yml on grimdalltech/grimdall-os

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file grimdall-0.3.3-py3-none-any.whl.

File metadata

  • Download URL: grimdall-0.3.3-py3-none-any.whl
  • Upload date:
  • Size: 20.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for grimdall-0.3.3-py3-none-any.whl
Algorithm Hash digest
SHA256 7d8a493824bfd5fcf09beecb3eb03ce882d5b7a3c202d6d9c918a1a42bbcf0c7
MD5 325cb0340e92037a5a852ec7ff6a4cb3
BLAKE2b-256 22386fad139ba5cbd0f09c5c7494ca4776e0e410d9621bbb0c26bb08c0697974

See more details on using hashes here.

Provenance

The following attestation bundles were made for grimdall-0.3.3-py3-none-any.whl:

Publisher: publish-python.yml on grimdalltech/grimdall-os

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page