guardlayer 0.6.2__tar.gz → 0.6.3__tar.gz

{guardlayer-0.6.2 → guardlayer-0.6.3}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.6.3] - 2026-09-29
+
+### Added
+- **`guardlayer audit report`**: what GuardLayer decided, or in observe mode would have decided, by rule and by tool, with
+  the latest notable entries and a count of redactions (`--since-days`, `--min`, `--json`). Built for pilots: run it daily
+  and sort each entry into correct, false alarm or unsure.
+- **Docs: "One-week pilot on your own work"**: install from PyPI into its own environment, observe-mode config, hook on one
+  project, a five-minute daily review, when to start enforcing, and what to report back.
+
 ## [0.6.2] - 2026-09-29
 
 ### Security

{guardlayer-0.6.2 → guardlayer-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: guardlayer
-Version: 0.6.2
+Version: 0.6.3
 Summary: A lightweight security layer that filters the inputs and outputs of LLM and agent applications — prompt injection, jailbreaks, leakage, secrets, PII and unsafe actions.
 Project-URL: Homepage, https://github.com/Lijithvmv/Guard-Layer
 Project-URL: Documentation, https://lijithvmv.github.io/Guard-Layer/

{guardlayer-0.6.2 → guardlayer-0.6.3}/deploy/docker-compose.yml

@@ -3,7 +3,7 @@
 services:
   guardlayer:
     build: ..
-    image: guardlayer:0.6.2
+    image: guardlayer:0.6.3
     environment:
       GUARDLAYER_API_KEY: ${GUARDLAYER_API_KEY:?set GUARDLAYER_API_KEY}
       GUARDLAYER_CONFIG: /etc/guardlayer/guardlayer.toml

{guardlayer-0.6.2 → guardlayer-0.6.3}/deploy/kubernetes/guardlayer.yaml

@@ -60,7 +60,7 @@ spec:
             matchLabels: {app.kubernetes.io/name: guardlayer}
       containers:
         - name: guardlayer
-          image: guardlayer:0.6.2          # build from the repo Dockerfile and push to your registry; pin by digest
+          image: guardlayer:0.6.3          # build from the repo Dockerfile and push to your registry; pin by digest
           imagePullPolicy: IfNotPresent
           ports:
             - {name: http, containerPort: 8000}

guardlayer-0.6.3/docs/getting-started/pilot.md

@@ -0,0 +1,125 @@
+# Try it on your own work: a one-week pilot
+
+The fastest way to learn whether GuardLayer fits is to run it on the agent you already use, on real work, **without
+letting it block anything**. Observe mode records what GuardLayer *would* have done; after a week you read the report
+and decide what to enforce.
+
+This page uses Claude Code as the agent, since it's the easiest to try. The same steps work for your own LangGraph or
+OpenAI Agents SDK agent (see the end of the page).
+
+## Day 0: set up (15 minutes)
+
+**1. Install into its own environment**, the way any user would:
+
+=== "Windows"
+
+    ```powershell
+    py -m venv C:\guardlayer-pilot
+    C:\guardlayer-pilot\Scripts\pip install guardlayer
+    C:\guardlayer-pilot\Scripts\guardlayer --version
+    ```
+
+=== "macOS / Linux"
+
+    ```bash
+    python3 -m venv ~/guardlayer-pilot
+    ~/guardlayer-pilot/bin/pip install guardlayer
+    ~/guardlayer-pilot/bin/guardlayer --version
+    ```
+
+**2. Create a pilot config** next to it, `pilot.toml`:
+
+```toml
+preset = "observe"                 # record what would happen; enforce nothing
+
+[audit]
+path = "pilot-audit.jsonl"         # relative to this file
+min_verdict = "allow"              # log every decision, so the report has the full picture
+```
+
+The audit log stores hashes of text, not the text itself (unless you add `include_text = true`), so it doesn't become a
+copy of your secrets.
+
+**3. Check it behaves** before connecting it to anything:
+
+```bash
+guardlayer --config pilot.toml tool-call Bash '{"command": "pytest -q"}'     # ALLOW
+guardlayer --preset balanced tool-call Bash '{"command": "rm -rf ~"}'        # BLOCK (what enforcement would do)
+```
+
+**4. Connect it to one project only.** Generate the hook settings and paste them into that project's
+`.claude/settings.json`, not your user-level settings, so only this project is observed:
+
+```bash
+guardlayer --config pilot.toml hook claude-code --print-config
+```
+
+The command in the output points at your pilot environment and config. In observe mode the hook never blocks or asks;
+Claude Code behaves exactly as before, apart from about a second per tool call on Windows (less on macOS and Linux).
+
+!!! tip "Repositories full of attack samples"
+    If the project is a security tool with injection strings in its tests, add `[session] trusted_tools = ["Read", "Grep"]`
+    to `pilot.toml`, or every read of those files will count as hostile content.
+
+## Days 1–7: work normally, review for five minutes a day
+
+```bash
+guardlayer audit report pilot-audit.jsonl --since-days 1
+```
+
+The report shows how many decisions were notable, what enforcement *would* have done (`(observed)`), which rules fired
+on which tools, and how many results had secrets or personal data redacted. For each notable entry, put it in one of
+three buckets:
+
+| Bucket | Example | What it means |
+|---|---|---|
+| **Correct** | a destructive command, a secret about to leave in a web request | the rule earns its place |
+| **False alarm** | a normal `git push --force` on your own branch sent to review | tune it: observe that rule longer, allow the tool, or adjust the config |
+| **Unsure** | a flagged page you can't judge | keep watching |
+
+Also note **misses**: anything you saw the agent do that you'd have wanted stopped or reviewed, but the report doesn't
+show. Misses matter as much as false alarms.
+
+Keep the log honest: `guardlayer audit verify pilot-audit.jsonl` checks nobody (including you) edited it.
+
+## Day 7: decide what to enforce
+
+Enforce only what had no false alarms, and keep observing the rest:
+
+```toml
+preset = "observe"
+
+[guard]
+enforce = ["secret", "tool_policy:*"]     # redact secrets and enforce the tool policy; everything else still observed
+```
+
+Run another week, then move to `balanced` (or `strict` for agents holding production credentials). See
+[Roll out without breaking anything](../recipes/rollout.md) for the full sequence.
+
+## Your own agent instead of Claude Code
+
+```py
+from guardlayer.config import build_guard
+from guardlayer.integrations.langgraph import guard_tools
+
+guard = build_guard("pilot.toml")                 # the same observe config and audit log
+tools = guard_tools(guard, [search, fetch_url, run_shell])
+```
+
+For the OpenAI Agents SDK use `guardrails(guard)`, and for anything else `guard_tool` (see Integrations). The daily
+report works the same way.
+
+## What to send back
+
+A pilot is most useful when its findings come back. Open an issue with, for each false alarm or miss:
+
+- the **rule name** and **tool** from the report, and the decision (`block`, `review`, `flag`);
+- one sentence on why it was wrong, or what should have been caught;
+- the GuardLayer version (`guardlayer --version`).
+
+Never paste secrets, customer data or full tool output. The rule name and a description are enough.
+
+## Removing it
+
+Delete the hook entries from the project's `.claude/settings.json` and remove the pilot environment. Session state lives
+in `~/.guardlayer/sessions`; delete that folder too if you want no trace.

{guardlayer-0.6.2 → guardlayer-0.6.3}/docs/recipes/rollout.md

@@ -18,7 +18,8 @@ Nothing is blocked, held or redacted. Every result carries a `shadow_verdict`, a
 ## 2. Look at what would have happened
 
 ```bash
-guardlayer evidence export guardlayer-audit.jsonl          # a summary by control and verdict
+guardlayer audit report guardlayer-audit.jsonl --since-days 1   # by rule, by tool, latest; "(observed)" = would have fired
+guardlayer evidence export guardlayer-audit.jsonl               # the same log as control-mapped evidence
 ```
 
 Or read the log directly: each line has `verdict`, `shadow_verdict`, `observed_rules`, `categories` and `direction`. Look

{guardlayer-0.6.2 → guardlayer-0.6.3}/mkdocs.yml

@@ -75,6 +75,7 @@ nav:
   - Getting started:
       - Install: getting-started/install.md
       - Quickstart: getting-started/quickstart.md
+      - One-week pilot on your own work: getting-started/pilot.md
   - Concepts:
       - How a verdict is reached: concepts/how-it-works.md
       - Guarding agent actions: concepts/agents.md

{guardlayer-0.6.2 → guardlayer-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "guardlayer"
-version = "0.6.2"
+version = "0.6.3"
 description = "A lightweight security layer that filters the inputs and outputs of LLM and agent applications — prompt injection, jailbreaks, leakage, secrets, PII and unsafe actions."
 readme = "README.md"
 requires-python = ">=3.10"

{guardlayer-0.6.2 → guardlayer-0.6.3}/src/guardlayer/__init__.py

@@ -7,7 +7,7 @@ Quick start:
     <Verdict.BLOCK: 'block'>
 """
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 
 from guardlayer.audit import AuditLogger, AuditSigner, AuditVerification, verify_audit_log  # noqa: E402
 from guardlayer.canary import Canary, CanaryManager  # noqa: E402

{guardlayer-0.6.2 → guardlayer-0.6.3}/src/guardlayer/audit.py

@@ -23,6 +23,7 @@ import hashlib
 import json
 import logging
 import threading
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import IO, Any
@@ -249,3 +250,78 @@ def verify_audit_log(
     if expected_head is not None and prev != expected_head:
         return AuditVerification(False, count, prev, signed, "head hash differs from the expected head (log truncated or replaced)", None)
     return AuditVerification(True, count, prev if count else None, signed)
+
+
+# ------------------------------------------------------------------------------------------ review report
+_ORDER = {"allow": 0, "flag": 1, "review": 2, "block": 3}
+
+
+def audit_report(path: str | Path, *, since_days: float | None = None, min_verdict: str = "flag", latest: int = 15) -> dict[str, Any]:
+    """Summarise what GuardLayer decided, or would have decided in observe mode, for a human reviewer.
+
+    For each entry the effective decision is the stricter of `verdict` and `shadow_verdict`, so an observe-mode pilot
+    shows what enforcement would have done. Counts by rule and by tool, and the latest notable entries, are returned;
+    raw text is never needed (entries hold only hashes unless `include_text` was on).
+    """
+    threshold = _ORDER[str(Verdict(min_verdict).value)]
+    cutoff = time.time() - since_days * 86400 if since_days else None
+    total, notable, observed_only, redacted, sessions = 0, 0, 0, 0, set()
+    by_rule: dict[str, dict[str, Any]] = {}
+    by_tool: dict[str, int] = {}
+    recent: list[dict[str, Any]] = []
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            if not line.strip():
+                continue
+            entry = json.loads(line)
+            if cutoff and entry.get("timestamp", 0) < cutoff:
+                continue
+            total += 1
+            meta = entry.get("metadata") or {}
+            if meta.get("session_id"):
+                sessions.add(meta["session_id"])
+            redacted += bool(entry.get("modified"))
+            enforced = entry.get("verdict", "allow")
+            shadow = entry.get("shadow_verdict") or "allow"
+            effective = max(enforced, shadow, key=lambda v: _ORDER.get(v, 0))
+            if _ORDER.get(effective, 0) < threshold:
+                continue
+            notable += 1
+            only_observed = _ORDER.get(enforced, 0) < threshold
+            observed_only += only_observed
+            tool = meta.get("tool") or entry.get("direction", "?")
+            by_tool[tool] = by_tool.get(tool, 0) + 1
+            rules = sorted({d.get("rule", "?") for d in entry.get("detections", [])})
+            for rule in rules:
+                slot = by_rule.setdefault(rule, {"count": 0, "decisions": {}, "tools": set()})
+                slot["count"] += 1
+                slot["decisions"][effective] = slot["decisions"].get(effective, 0) + 1
+                slot["tools"].add(tool)
+            recent.append({"time": entry.get("timestamp"), "session": meta.get("session_id"), "tool": tool,
+                           "direction": entry.get("direction"), "decision": effective, "observed_only": only_observed,
+                           "rules": rules, "why": next((d.get("message") for d in entry.get("detections", [])), "")})  # fmt: skip
+    for slot in by_rule.values():
+        slot["tools"] = sorted(slot["tools"])
+    return {"entries": total, "sessions": len(sessions), "notable": notable, "observed_only": observed_only, "redacted": redacted,
+            "by_rule": dict(sorted(by_rule.items(), key=lambda kv: -kv[1]["count"])),
+            "by_tool": dict(sorted(by_tool.items(), key=lambda kv: -kv[1])), "latest": recent[-latest:][::-1]}  # fmt: skip
+
+
+def format_audit_report(report: dict[str, Any]) -> str:
+    lines = [f"{report['entries']} entries, {report['sessions']} sessions; {report['notable']} notable "
+             f"({report['observed_only']} only observed: what enforcement would have done); "
+             f"{report['redacted']} with secrets or personal data redacted"]  # fmt: skip
+    if report["by_rule"]:
+        lines += ["", "By rule:"]
+        for rule, slot in report["by_rule"].items():
+            decisions = ", ".join(f"{k} {v}" for k, v in sorted(slot["decisions"].items(), key=lambda kv: -_ORDER.get(kv[0], 0)))
+            lines.append(f"  {rule:32} {slot['count']:5}   {decisions}   tools: {', '.join(slot['tools'])}")
+    if report["latest"]:
+        lines += ["", "Latest:"]
+        for e in report["latest"]:
+            when = time.strftime("%Y-%m-%d %H:%M", time.localtime(e["time"] or 0))
+            tag = " (observed)" if e["observed_only"] else ""
+            lines.append(f"  {when}  {e['decision']:6}{tag:11} {e['tool']:14} {', '.join(e['rules'])}")
+            if e["why"]:
+                lines.append(f"      {e['why']}")
+    return "\n".join(lines)

{guardlayer-0.6.2 → guardlayer-0.6.3}/src/guardlayer/cli.py

@@ -94,6 +94,12 @@ def main(argv: list[str] | None = None) -> int:
     verify.add_argument("--expected-head", help="A head hash recorded earlier, to detect a truncated log.")
     keygen = audit_sub.add_parser("keygen", help="Generate an Ed25519 signing key pair: PREFIX.key and PREFIX.pub.")
     keygen.add_argument("prefix")
+    report = audit_sub.add_parser("report", help="What GuardLayer decided (or would have, in observe mode): by rule, by tool, latest.")
+    report.add_argument("path")
+    report.add_argument("--since-days", type=float, help="Only entries from the last N days.")
+    report.add_argument("--min", default="flag", choices=["flag", "review", "block"], help="Lowest decision to include.")
+    report.add_argument("--latest", type=int, default=15, help="How many recent notable entries to list.")
+    report.add_argument("--json", action="store_true", help="Machine-readable output.")
 
     evidence = sub.add_parser("evidence", help="Control-mapped compliance evidence from an audit log.")
     evidence_sub = evidence.add_subparsers(dest="evidence_command", required=True)
@@ -222,8 +228,12 @@ def main(argv: list[str] | None = None) -> int:
 
 
 def _audit(args: argparse.Namespace) -> int:
-    from guardlayer.audit import AuditSigner, verify_audit_log
+    from guardlayer.audit import AuditSigner, audit_report, format_audit_report, verify_audit_log
 
+    if args.audit_command == "report":
+        data = audit_report(args.path, since_days=args.since_days, min_verdict=args.min, latest=args.latest)
+        print(json.dumps(data, indent=2) if args.json else format_audit_report(data))
+        return 0
     if args.audit_command == "keygen":
         key, pub = Path(f"{args.prefix}.key"), Path(f"{args.prefix}.pub")
         if key.exists() or pub.exists():

{guardlayer-0.6.2 → guardlayer-0.6.3}/tests/test_agent_guard.py

@@ -387,3 +387,32 @@ def test_config_audit_path_per_process(tmp_path):
     guard.scan_input(ATTACK)
     expected = tmp_path / f"audit-{socket.gethostname()}-{os.getpid()}.jsonl"
     assert expected.exists() and verify_audit_log(expected).ok
+
+
+def test_audit_report_shows_what_observe_mode_would_have_done(tmp_path, capsys):
+    from guardlayer import AuditLogger
+    from guardlayer.audit import audit_report
+    from guardlayer.cli import main
+
+    log = tmp_path / "audit.jsonl"
+    observe = GuardLayer.from_preset("observe")
+    observe.add_hook(AuditLogger(log))
+    s = observe.session("pilot")
+    s.scan_tool_call("Bash", {"command": "rm -rf ~"})
+    s.scan_tool_call("Bash", {"command": "git push --force"})
+    s.scan_tool_call("Bash", {"command": "pytest -q"})
+    enforce = GuardLayer()
+    enforce.add_hook(AuditLogger(log))
+    enforce.scan_output("key AKIAIOSFODNN7EXAMPLE")
+
+    r = audit_report(log)
+    assert r["entries"] == 4 and r["sessions"] == 1 and r["redacted"] == 1
+    assert r["notable"] == 2 and r["observed_only"] == 2  # nothing was enforced in observe mode
+    assert r["by_rule"]["destructive_command"]["decisions"] == {"block": 1}
+    assert r["by_rule"]["risky_command"]["decisions"] == {"review": 1}
+    assert audit_report(log, min_verdict="block")["notable"] == 1
+    assert r["latest"][0]["rules"] == ["risky_command"]  # newest first
+
+    assert main(["audit", "report", str(log)]) == 0
+    out = capsys.readouterr().out
+    assert "destructive_command" in out and "(observed)" in out and "1 with secrets" in out