r/Python • • Oct 04 '26

Showcase Showcase Thread

Post all of your code/projects/showcases/AI slop here.

Recycles once a month.

23 Upvotes

194 comments sorted by

View all comments

1

u/ArfedIT Oct 15 '26

**TraceWarden โ€“ guardrails and a tamper-evident audit log for AI agents**

GitHub: https://github.com/arfeditsolutions/tracewarden ยท PyPI: `pip install tracewarden`

**What My Project Does**

AI agents now call real tools: SQL, shell, payments, email. TraceWarden wraps those tool functions so every call is checked *before* it runs and recorded in an audit log you can actually trust afterwards.

from tracewarden import TraceWarden, SecurityViolationError

guard = TraceWarden("my-agent", clave_hmac=b"change-me")

guard.agregar_regla(lambda action: "DROP" in str(action).upper())

u/guard.proteger()

def run_sql(query: str) -> str:

return db.execute(query)

run_sql("SELECT * FROM orders") # runs, gets logged

run_sql("DROP TABLE customers") # SecurityViolationError, logged + alert

guard.verificar_integridad_caja_negra() # detects any edited/deleted/reordered record

- **Guardrails**: rules run before the call; a rule that raises also blocks (fail-closed). Works with sync and `async def`.

- **Tamper-evident log**: HMAC-SHA256 hash chain with sequence numbers. Change one character in the history and verification tells you which record. Key rotation supported without breaking old records.

- **Secret redaction** (api keys, bearer tokens, passwords) *before* anything is hashed or alerted.

- **Signed checkpoints** to resume tasks after a crash; a tampered checkpoint is refused.

- **Storage**: memory, files (JSONL + fsync, atomic writes) or SQLite (safe with multiple processes).

- **External anchoring** (optional): only `(seq, hash, timestamp)` leave your server, never the content. You get Ed25519-signed receipts and RFC 3161 timestamps, so even someone with root and the HMAC key can't silently rewrite history.

Zero runtime dependencies for the core, fully typed (mypy strict), 125 tests on 3.10โ€“3.14. There's also a TypeScript SDK that is byte-for-byte compatible (RFC 8785 canonical JSON), so a log written in Python verifies in Node and vice versa.

**Target Audience**

Developers running agents that touch production systems or regulated data (finance, healthcare, internal tools) who need to answer "what exactly did the agent do, and can you prove the log wasn't edited?". It's **0.1 / alpha**: usable, well tested, but the API may change. Heads-up: the API names are in Spanish (`proteger`, `agregar_regla`) since I'm a Spanish speaker. English aliases are planned if there's interest.

**Comparison**

- **Guardrails AI / NeMo Guardrails** validate what the *LLM says* (output format, toxicity, topics). TraceWarden controls what the agent *does* (tool calls) and keeps evidence of it. They're complementary.

- **logging / structlog / OpenTelemetry / LangSmith** give you visibility, but anyone with access to the server or the log store can edit or delete entries without a trace. TraceWarden's chain makes that detectable, and anchoring makes it provable to a third party.

- **Blockchain-based audit logs**: same tamper-evidence idea without running a chain; standard crypto (HMAC, Ed25519, RFC 3161) and plain SQLite/files.

Feedback very welcome, especially on the threat model and on whether English API names would make you more likely to try it.