guardledger 0.1.0__tar.gz

guardledger-0.1.0/.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "sentinel",
+      "runtimeExecutable": "./.venv/bin/sentinel",
+      "runtimeArgs": ["serve"],
+      "port": 8787
+    }
+  ]
+}

guardledger-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# Sentinel configuration (copy to .env; .env is git-ignored)
+
+# Where the tamper-evident audit log lives (SQLite).
+SENTINEL_DB_PATH=./data/sentinel.db
+
+# Active policy file (YAML).
+SENTINEL_POLICY_PATH=./policies/starter.yaml
+
+# Minimal control API / dashboard.
+SENTINEL_API_HOST=127.0.0.1
+SENTINEL_API_PORT=8787
+
+# Comma-separated arg keys whose values are redacted before they ever hit the audit log.
+SENTINEL_REDACT_KEYS=api_key,apikey,token,password,passwd,secret,authorization,access_token,private_key

guardledger-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Something isn't working as documented
+labels: bug
+---
+
+**What happened**
+
+**What you expected**
+
+**Steps to reproduce**
+1.
+2.
+
+**Environment**
+- Sentinel version / commit:
+- Python version:
+- OS:
+
+**Logs / output** (do NOT paste live secrets or customer data)

guardledger-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+labels: enhancement
+---
+
+**The problem / use case** (what are you trying to do?)
+
+**Proposed solution**
+
+**Alternatives you considered**
+
+**Which framework / agent are you using?** (LangChain, OpenAI Agents, CrewAI, MCP, plain Python, …)

guardledger-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What this changes
+
+## Why
+
+## Checklist
+- [ ] `pytest` is green
+- [ ] `ruff check src tests` is clean
+- [ ] Added/updated tests (security-critical code — policy, audit, kill switch — is tests-first)
+- [ ] Docs updated if behavior changed
+- [ ] No secrets committed; the audit log stays append-only / tamper-evident

guardledger-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest

guardledger-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: release
+
+# Publishes to PyPI when a version tag (v*) is pushed, using PyPI Trusted Publishing
+# (OIDC — no API token stored in the repo). See PUBLISHING.md for the one-time setup.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

guardledger-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Dependencies
+node_modules/
+__pycache__/
+.venv/
+venv/
+*.egg-info/
+
+# Build / artifacts
+dist/
+build/
+*.log
+.wrangler/
+
+# Local audit/data stores (do not commit runtime data)
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite3
+data/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

guardledger-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,148 @@
+# ARCHITECTURE.md — Sentinel MVP
+
+> v0.1 · Phase 2. Stack ו-interception אושרו 2026-06-13. כולל threat model.
+
+---
+
+## 1. עקרונות מנחים
+
+1. **Default-deny** — פעולה שלא הותרה במפורש נחסמת.
+2. **Fail-closed** — אם שכבת ההכרעה עצמה נכשלת (שגיאה ב-policy/audit), הפעולה **נחסמת**, לא רצה. אבטחה > זמינות.
+3. **Append-only + tamper-evident** — ה-audit לא נמחק ולא משתנה; כל שינוי מתגלה ב-`verify`.
+4. **Interceptor מופשט** — הליבה (policy/audit/kill/detect) לא יודעת איך יורטה הפעולה. SDK wrapper היום, MCP-proxy מחר — אותה ליבה.
+5. **Sentinel הוא נקודת כשל high-value** — מתייחסים לקוד שלנו עצמו כמשטח תקיפה (סעיף 6).
+
+## 2. Stack (אושר)
+
+| רכיב | בחירה | נימוק |
+|---|---|---|
+| שפה | **Python 3.11+** | העולם של MeiroX + ecosystem הסוכנים; מסלול מהיר |
+| Interception | **SDK wrapper** (decorator/wrap) מאחורי `Interceptor` interface | מכסה את ה-tools הישירים של MeiroX, framework-agnostic, דטרמיניסטי ל-tests-first; MCP-proxy נכנס כ-adapter בלי שכתוב |
+| Audit store | **SQLite** + hash-chain | embeddable, tamper-evident פשוט, משדרג ל-Postgres |
+| Policy | **YAML** (`yaml.safe_load`) | declarative, קריא ללקוח, ניתן לעריכה ב-dashboard |
+| API/Dashboard | **FastAPI** + עמוד HTML מינימלי | קל, async, OpenAPI חינם |
+| בדיקות | **pytest** | tests-first על הליבה הקריטית |
+
+## 3. דיאגרמת רכיבים + data flow
+
+```
+   agent (למשל trading_agent)
+        │ tool_call(name, args)
+        ▼
+ ┌─────────────────────────────────────────────────────────┐
+ │ Interceptor (SDK wrapper)  →  sentinel.check(ToolCall)   │
+ └───────────────────────────────┬─────────────────────────┘
+                                  ▼
+        ┌──────────────────────────────────────────┐
+        │ 1. KillSwitch.active?  → block(reason=kill)│  (fail-closed)
+        │ 2. Detector.inspect()  → flags[]           │  (מסמן, לא חוסם)
+        │ 3. Policy.evaluate()   → allow/block/      │  (default-deny)
+        │                          require_approval  │
+        │ 4. combine → Decision                      │
+        └───────────────┬────────────────────────────┘
+            allow ───────┤────── block / require_approval
+              │          │
+   execute tool_fn       │ (לא מבוצע)
+   (try/except)          │
+              │          │
+              ▼          ▼
+        ┌──────────────────────────────────────────┐
+        │ AuditLog.append(record)  (hash-chained,    │
+        │   redacted, compliance-mapped)             │
+        └───────────────┬────────────────────────────┘
+                        ▼
+        ┌──────────────────────────────────────────┐
+        │ FastAPI: /actions /audit/verify /export    │
+        │          /policy /kill /status  + dashboard│
+        └────────────────────────────────────────────┘
+```
+
+**רצף לקריאה מותרת:** check → allow → execute → append record (status=`executed`/`error`).
+**רצף לקריאה חסומה:** check → block → append record (status=`blocked`/`killed`/`pending_approval`), ה-tool **לא** מבוצע.
+
+## 4. מודל הנתונים — רשומת Audit (לב המוצר)
+
+```
+AuditRecord
+  seq            int          # מונוטוני
+  ts             float/iso    # זמן
+  agent_id       str
+  session_id     str
+  tool           str
+  args           dict         # אחרי redaction
+  decision       enum         # allow | block | require_approval
+  policy_rule    str|null     # id הכלל שהתאים (או null=default-deny)
+  reason         str
+  flags          [str]        # מה-Detector
+  status         enum         # executed | blocked | error | pending_approval | killed
+  error          str|null
+  compliance     {eu_ai_act_art12: bool, owasp_agentic: [str]}
+  prev_hash      str(64)
+  hash           str(64)      # sha256( prev_hash + canonical_json(payload) )
+```
+
+**Hash-chain:** רשומת genesis עם `prev_hash="0"*64`. כל רשומה: `hash = sha256(prev_hash + canonical_json(הכל חוץ מ-hash))`. `verify()` מחשב מחדש את כל השרשרת ובודק (א) כל hash תואם, (ב) כל `prev_hash` תואם ל-hash הקודם. כל עריכה/מחיקה/שינוי-סדר באמצע → מתגלה. (truncation של הזנב — מיטיגציה ב-`ROADMAP.md`: anchoring חיצוני תקופתי.)
+
+> הערה: רשומה אחת לכל tool call, נכתבת אחרי ניסיון הביצוע (עטוף ב-try/except, כך ששגיאת tool עדיין נרשמת). הפער היחיד: process kill באמצע ביצוע. מיטיגציה (roadmap): two-phase logging (intent לפני, outcome אחרי).
+
+## 5. מודל ה-Policy (YAML)
+
+```yaml
+version: 1
+default: deny                 # default-deny
+rules:
+  - id: allow-reads
+    match: { tool: ["get_*", "read_*"] }     # glob
+    action: allow
+  - id: cap-order
+    match:
+      tool: place_order
+      args: { amount: { gt: 500 } }          # comparators: gt/gte/lt/lte/eq/in/contains
+    action: require_approval
+  - id: rate-limit-orders
+    match: { tool: place_order }
+    rate_limit: { max: 5, per_seconds: 60 }   # מעל הסף → block
+    action: allow
+  - id: forbid-deletes
+    match: { tool: "delete_*" }
+    action: block
+```
+
+הכרעה: **first-match-wins** (לפי סדר), אחרת `default`. תמיכה: glob על שם tool, comparators על args, rate_limit (sliding window in-memory ל-MVP), ו-`on_flag: block` אופציונלי להסלמה על flag מה-Detector.
+
+## 6. Threat Model (Sentinel עצמו כמשטח תקיפה)
+
+| # | איום | מיטיגציה ב-MVP | סטטוס/roadmap |
+|---|---|---|---|
+| T1 | **Bypass** — קריאה ל-tool לא-עטוף | helper `wrap_all` + תיעוד; default-deny על מה שמוכר | מגבלת SDK-mode; proxy/egress עתידי הופך bypass לבלתי-אפשרי |
+| T2 | **Audit tampering** — עריכת ה-DB | hash-chain → `verify` מגלה כל edit/reorder/delete | anchoring חיצוני נגד truncation (roadmap) |
+| T3 | **Log-as-exfil / log injection** | redaction לפני כתיבה; args כ-data בלבד; canonical JSON | — |
+| T4 | **Policy evasion** — args שמתחמקים מ-match | **default-deny** + טסטים על matchers | — |
+| T5 | **Kill switch failure** | נבדק בכל קריאה, **persisted** (שורד restart), **fail-closed** אם לא נקרא | — |
+| T6 | **Sentinel כ-vector** — ReDoS/YAML | `yaml.safe_load`, regexes חסומים | — |
+| T7 | **Secrets handling** | redaction; אין סודות בלוג; `.env` (לא מקומיט) | — |
+| T8 | **Fail-open** — שגיאה בליבה → tool רץ? | **fail-closed**: כל חריגה ב-check → block (נבדק בטסט) | — |
+
+## 7. מבנה הפרויקט
+
+```
+sentinel/
+  src/sentinel/
+    models.py       # ToolCall, Decision, AuditRecord
+    redaction.py    # redaction של סודות
+    policy.py       # טעינה + הכרעת YAML (default-deny, glob, comparators, rate-limit)
+    audit.py        # AuditLog: SQLite, hash-chain, verify, export
+    killswitch.py   # KillSwitch persisted (fail-closed)
+    detector.py     # heuristics v1 (lethal-trifecta, off-baseline, injection sigs)
+    compliance.py   # מיפוי Art.12 / OWASP Agentic
+    sentinel.py     # הליבה: check() + wrap() (Interceptor)
+    api.py          # FastAPI + dashboard
+    config.py
+  policies/example.yaml
+  examples/trading_agent.py   # סוכן דמו (beachhead פיננסי)
+  tests/                      # tests-first על policy/audit/kill
+```
+
+## 8. למה זה לא נועל אותנו
+
+`Interceptor` הוא interface. SDK wrapper הוא מימוש אחד; הליבה (`check()`) מקבלת `ToolCall` ולא יודעת מאיפה הגיע. MCP-proxy עתידי = adapter שבונה `ToolCall` מתעבורת MCP וקורא לאותו `check()`. אפס שכתוב של policy/audit/kill.

guardledger-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+MVP of the audit/flight-recorder wedge, plus first hardening pass.
+
+### Core
+- Declarative, default-deny **policy engine** (YAML): glob + arg comparators + rate limits.
+- Append-only, hash-chained **audit trail** (SQLite) with `verify` (tamper-evident) and a compliance `export`.
+- **Two-phase logging**: intent (pre-exec) + outcome (post-exec) records linked by `action_id`.
+- Persisted **kill switch** (global / per-agent) and `fail-closed` enforcement.
+- **Detector** heuristics: full lethal-trifecta (untrusted-content tracking), off-baseline, injection signatures, dangerous-arg (cmd/SQL/path/URL), PII-in-arg.
+- Secret **redaction** at write time; compliance mapping (EU AI Act Art. 12, OWASP Agentic).
+- **Monitor mode** (observe-only): logs the would-be verdict, never blocks — but the kill switch still enforces. The trust bridge before flipping to enforcement.
+
+### Interception
+- **SDK wrapper** (`@sentinel.guard`) — the default interceptor.
+- **MCP proxy** (`MCPProxy`) — second interceptor over the same `enforce()` path; no bypass.
+- **Sentinel-guarded MCP server** (`SentinelMCPServer`) — expose tools over real MCP with enforcement built in (optional `mcp` extra).
+- **Upstream MCP proxy** (`AsyncMCPProxy`) — man-in-the-middle over a live `mcp.ClientSession` (async `aenforce`).
+- **Framework-agnostic by default**: generic `policies/starter.yaml` + a generic demo (`sentinel demo`); `Sentinel.wrap_all()` guards a whole toolset; INTEGRATIONS.md covers plain functions / LangChain / OpenAI Agents / CrewAI / MCP. (Trading is now just a vertical example.)
+
+### Control plane
+- FastAPI **dashboard** + API: live feed, integrity verify, policy editor, kill switch, approvals.
+- **API auth** via `SENTINEL_API_TOKEN` on mutating endpoints; `sentinel serve` auto-generates one.
+- **Read-endpoint protection** (`SENTINEL_API_PROTECT_READS`) — gate the sensitive audit reads behind the token too.
+- **Human-in-the-loop approvals**: `require_approval` parks a call; operator approves; next identical call runs once.
+- Persistent **rate limiter** (survives restart / shared across processes).
+
+### Tooling
+- CLI: `serve | verify | export [--format json|otel] | kill | unkill | approvals | approve | demo`.
+- **Retention**: approval TTL + `sentinel gc` purges stale approvals / rate-limit state (audit log untouched).
+- **Multi-framework compliance mapping** (`sentinel compliance`): EU AI Act, GDPR, NIST AI RMF, ISO 42001, Colorado AI Act, SEC/FINRA — honest full/partial/none coverage (COMPLIANCE.md).
+- **EU AI Act Art.12 report** (`export --format art12`); OpenTelemetry GenAI export (JSON spans + real SDK emission).
+- **PyPI release automation** (Trusted Publishing) — see PUBLISHING.md.
+- Optional extras: `pip install "sentinel[mcp,otel]"`. Clean wheel/sdist build.
+- Pre-launch security: dashboard HTML-escaping (anti-XSS), disclaimers (alpha / not legal advice), concurrency-safe audit append.
+- CI (GitHub Actions, py3.11–3.13) with a ruff lint gate. Concurrency-safe SQLite (WAL + busy_timeout). Apache-2.0.
+
+78 tests passing.

guardledger-0.1.0/COMPLIANCE.md

@@ -0,0 +1,90 @@
+# COMPLIANCE.md — how Sentinel maps to existing AI / data law
+
+> ⚠️ **Indicative engineering mapping — not legal advice or a conformity assessment.**
+> Coverage describes what Sentinel *provides*, not whether *you* are compliant. Verify
+> against the current legal texts. `sentinel compliance` is the machine-readable source
+> of truth; this file mirrors it.
+>
+> Legend: **full** = Sentinel provides the control · **partial** = Sentinel provides
+> evidence/infrastructure, you do the rest · **none** = out of scope (listed honestly).
+
+## Coverage at a glance
+
+| Framework | Jurisdiction | full | partial | none |
+|---|---|:--:|:--:|:--:|
+| EU AI Act (2024/1689) | EU | 1 | 4 | 2 |
+| GDPR (2016/679) | EU/EEA | 0 | 4 | 1 |
+| NIST AI RMF 1.0 | US (voluntary) | 0 | 3 | 1 |
+| ISO/IEC 42001:2023 | International | 0 | 3 | 1 |
+| Colorado AI Act (SB 24-205) | US — Colorado | 0 | 3 | 1 |
+| SEC 17a-4 / FINRA 4511 | US — securities | 0 | 3 | 0 |
+
+Sentinel is an **evidence + control-plane** layer: it makes the *logging, oversight,
+and audit* obligations satisfiable. It does **not** do risk classification, conformity
+assessment, DPIAs, user-facing disclosure, or your organisational processes.
+
+## EU AI Act (Regulation 2024/1689)
+
+| Article | Requirement (paraphrased) | Coverage | How |
+|---|---|---|---|
+| Art. 12 | Automatic event logs over the system lifetime | **full** | Append-only hash-chained audit; `export --format art12` |
+| Art. 14 | Human oversight / stop button | partial | Kill switch + approvals; you design the oversight process |
+| Art. 19 / 26(6) | Retain logs (deployers ≥ 6 months) | partial | Durable + tamper-evident; you set retention/backup |
+| Art. 26 | Deployer monitoring, logs, oversight | partial | Action feed + audit + kill/approvals |
+| Art. 72 | Post-market monitoring | partial | Audit + detector flags are the raw data |
+| Art. 50 | Transparency to users / content marking | none | Sentinel governs actions, not disclosure |
+| Art. 9 / Annex IV | Risk-management system & technical docs | none | Organisational process |
+
+## GDPR (2016/679)
+
+| Article | Requirement | Coverage | How |
+|---|---|---|---|
+| Art. 5(1)(c) | Data minimisation | partial | Secret/PII redaction before logging; PII detector |
+| Art. 22 | Human intervention in automated decisions | partial | Approvals + kill provide the checkpoint |
+| Art. 30 | Records of processing | partial | Per-action audit trail |
+| Art. 32 | Security of processing | partial | Token-gated plane + tamper-evident logs |
+| Art. 17 | Right to erasure | none | Audit is append-only — keep PII out (redaction); erase in source systems |
+
+## NIST AI RMF 1.0 (+ GenAI profile)
+
+| Function | Coverage | How |
+|---|---|---|
+| GOVERN | partial | Default-deny policy + immutable audit |
+| MAP | none | Analytical/process activity |
+| MEASURE | partial | Detector flags + action feed = continuous monitoring |
+| MANAGE | partial | Kill switch + forensic audit for response/recovery |
+
+## ISO/IEC 42001:2023
+
+| Control theme | Coverage | How |
+|---|---|---|
+| Operational controls & monitoring | partial | Runtime enforcement + live monitoring + audit |
+| Event logging & records | partial | Tamper-evident audit; auditor export |
+| Incident management | partial | Detector + kill + audit |
+| Management-system processes (Cl. 4-10) | none | Organisational AIMS |
+
+## Colorado AI Act (SB 24-205, eff. 2026-06-30)
+
+| Obligation | Coverage | How |
+|---|---|---|
+| Risk-management program | partial | Policy + audit are core evidence |
+| Recordkeeping | partial | Per-action audit trail |
+| AG notice of algorithmic discrimination (≤90 days) | partial | Detector + audit help detect/evidence; notice is yours |
+| Consumer notice / right to contest | none | User-facing process |
+
+## SEC Rule 17a-4 / FINRA Rule 4511 (broker-dealer recordkeeping — for trading agents)
+
+| Obligation | Coverage | How |
+|---|---|---|
+| Non-rewriteable records / audit-trail alternative | partial | Hash-chained tamper-evident audit; true WORM needs object-lock storage (roadmap) |
+| Retention periods | partial | Durable store; configure long-term archival |
+| Supervision of automated trading | partial | Action feed + kill + approvals |
+
+## Generate live, evidence-backed reports
+
+```bash
+sentinel compliance --all                       # coverage summary (all frameworks)
+sentinel compliance --framework eu_ai_act       # full mapping + your audit evidence
+sentinel export --format art12                   # EU AI Act Art. 12 record-keeping report
+```
+Set `SENTINEL_SYSTEM_NAME` and `SENTINEL_PROVIDER` to stamp reports with your system identity.

guardledger-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Sentinel
+
+Thanks for looking! Sentinel is an early (alpha) open-source project — issues, ideas, and
+PRs are all welcome.
+
+## Dev setup
+
+```bash
+make install   # venv + editable install with dev extras
+make test      # pytest
+make lint      # ruff
+```
+
+## Ground rules
+
+- **Tests-first on security-critical code** (policy engine, audit integrity, kill switch).
+  Add a test with (or before) the change.
+- Keep `ruff check src tests` clean and `pytest` green — CI enforces both (3.11–3.13).
+- The audit log is **append-only and tamper-evident** — never add anything that mutates
+  past records or breaks the hash chain.
+- Be honest in docs: compliance mappings are *indicative engineering aids, not legal advice*.
+
+## Security issues
+
+Report privately — see [SECURITY.md](SECURITY.md). Do not open a public issue for an
+unfixed vulnerability.
+
+## License
+
+By contributing, you agree your contributions are licensed under Apache-2.0.

guardledger-0.1.0/DECISIONS.md

@@ -0,0 +1,85 @@
+# DECISIONS.md — יומן החלטות Sentinel
+
+פורמט: תאריך · החלטה · נימוק · סטטוס.
+
+---
+
+## 2026-06-13 · Phase 0 — מתודולוגיית המחקר
+**החלטה:** מחקר תחרותי דרך 4 זרמים מקבילים (runtime security / identity+payments / standards+OSS / market+regulation), כל אחד מחזיר digest ממוקד עם מקורות אמיתיים בלבד.
+**נימוק:** כיסוי רחב במהירות + הפרדה בין איסוף-מודיעין (delegated) לבין הסינתזה האסטרטגית ודירוג ה-wedge (נשאר אצלי).
+**סטטוס:** ✅ הושלם → `RESEARCH.md`.
+
+## 2026-06-13 · ממצא מרכזי — ה-wedge המקורי תפוס
+**החלטה:** לא להיכנס דרך "Runtime Control Plane / AI firewall" גנרי כ-positioning ראשי.
+**נימוק:** 9 רכישות ב-12 חודשים, OSS חינמי (NeMo/Guardrails AI), bundling בענן, ו-CodeIntegrity (seed) בונה מוצר כמעט-זהה. תחרות מול חינם + מאות מיליוני $.
+**סטטוס:** ✅ הוכרע במחקר.
+
+## 2026-06-13 · בחירת wedge — **מאושר** ✅
+**החלטה:** wedge = **"compliance-grade flight recorder + kill switch"** — interception שמפיק audit trail חתום וממופה-רגולציה. **מוצר אופקי**, beachhead ראשון = סוכנים פיננסיים/מסחר אוטונומיים (MeiroX-style), ואז התרחבות.
+**נימוק:** השכבה הכי פחות צפופה, מגובה ב-deadline רגולטורי (EU AI Act Art. 12 — 2.8.2026), בת-ביצוע לבנאי יחיד, וזורעת את ה-Trust Graph דרך הדאטה. ראה `RESEARCH.md` §8.
+**סטטוס:** ✅ **אושר ע"י Itamar (2026-06-13).** עוברים ל-PRD.
+
+## 2026-06-13 · Phase 1 — PRD
+**החלטה:** הפרדה חדה: PRD מגדיר *מה* (תרחישים, scope, DoD); *איך* מיירטים (proxy/SDK/middleware) נדחה במכוון ל-ARCHITECTURE (נקודת החלטה נפרדת).
+**נימוק:** מנגנון ה-interception הוא ההחלטה הארכיטקטונית הכי קשה-להפוך — לא לקבע אותה ב-PRD לפני שמציגים trade-offs.
+**סטטוס:** ✅ `PRD.md` נכתב.
+
+## 2026-06-13 · Phase 2 — Stack ו-Interception — **מאושר** ✅
+**החלטה:** Python 3.11+ · interception = **SDK wrapper** מאחורי `Interceptor` interface (MCP-proxy כ-adapter עתידי) · audit = **SQLite + hash-chain** · policy = **YAML** · API = **FastAPI** + dashboard מינימלי · בדיקות = **pytest**.
+**נימוק:** ה-beachhead (סוכנים פיננסיים/MeiroX) משתמש ב-tools של קריאות ישירות, לא MCP — SDK wrapper מכסה אותם, framework-agnostic, ודטרמיניסטי ל-tests-first. עקרונות: default-deny, fail-closed, append-only. ראה `ARCHITECTURE.md`.
+**סטטוס:** ✅ אושר ע"י Itamar. עוברים לבנייה (Phase 3).
+
+## עקרונות אבטחה שנקבעו (מחייבים את כל הקוד)
+- **Fail-closed:** חריגה בליבת ההכרעה → block, לא execute.
+- **Default-deny:** אין כלל מתאים → block.
+- **Tests-first** על policy / kill switch / audit-integrity (קוד קריטי).
+- **Sentinel עצמו = משטח תקיפה** — threat model ב-`ARCHITECTURE.md` §6.
+
+## 2026-06-13 · Phase 3 — שינוי כפוי: HTTP layer
+**החלטה:** נבדק ש-FastAPI+uvicorn+pydantic מותקנים נקי על Python 3.14.3 → נשארנו עם FastAPI כמתוכנן (לא נפלנו ל-stdlib).
+**נימוק:** הסיכון היה wheels חסרים ל-3.14; אומת בפועל לפני התחייבות.
+**סטטוס:** ✅
+
+## 2026-06-13 · Phase 4 — בדיקות, demo, אבטחה — הושלם
+**החלטה:** 32 טסטים עוברים; E2E demo (5 תרחישים) עובד; tamper detection אומת חי; compliance export עובד; self-security check נקי (`SECURITY.md`).
+**הערה כנה:** ה-dashboard אומת פונקציונלית (טסטים + curl חי), אבל ה-preview-MCP לא הצליח להריץ אותו כי ה-sandbox חוסם גישה ל-.venv — מגבלת סביבה, לא באג. רץ תקין תחת `sentinel serve`.
+**סטטוס:** ✅ MVP הושלם.
+
+## 2026-06-13 · Post-MVP — הכל חוץ מחיבור MeiroX (לבקשת Itamar)
+**החלטה:** Itamar בחר לבצע את כל ההמשך **חוץ** מחיבור הבוט האמיתי — "רק בנינו את זה, אני לא סומך על זה ב-100%". החלטה נכונה: לא לשים שכבת בקרה לא-בדוקה לפני כסף אמיתי. תואם [[feedback_account_anxiety]].
+**בוצע ב-3 workstreams:**
+- **A (הקשחה):** auth לדאשבורד (Bearer token, `SENTINEL_API_TOKEN`), rate-limit מתמשך (SQLite), two-phase logging (intent+outcome, action_id), approval flow (HITL — park→approve→run-once).
+- **B (MCP-proxy):** `MCPProxy` מעל `Sentinel.enforce` משותף (refactor) — אין נתיב bypass.
+- **C (OSS):** Apache-2.0, OTel GenAI export (`gen_ai.*`), CI (3.11–3.13), classifiers, CHANGELOG.
+**סטטוס:** ✅ 51 טסטים עוברים. חיבור MeiroX נדחה במכוון עד שיש אמון מוכח.
+
+## 2026-06-13 · "תמשיך עד המטרה" — monitor mode, MCP server, OTel SDK, wheel
+**החלטה:** להמשיך אוטונומית עד סגירת כל הסקופ הבר-בנייה (בלי MeiroX, בלי פרסום חיצוני שדורש הרשאות).
+- **Monitor mode** (`mode="monitor"` / `SENTINEL_MODE=monitor`): observe-only — מתעד את ההכרעה-שהייתה אבל לא חוסם; ה-kill switch עדיין אוכף. גשר האמון: אפשר "shadow" על סוכן אמיתי בלי סיכון — בלי לגעת ב-MeiroX החי.
+- **SentinelMCPServer**: שרת MCP אמיתי (חבילת `mcp`, optional extra) שחושף tools עם אכיפה מובנית; `handle_call` טהור ונבדק בלי תלות ב-mcp.
+- **OTel SDK exporter** (`record_spans`, extra `otel`): פולט spans אמיתיים, לא רק JSON.
+- **wheel + sdist** נבנו ואומתו בהתקנה ל-venv נקי → `pip install sentinel` עובד.
+**סטטוס:** ✅ 58 טסטים. נשאר רק לא-קוד (design partner אמיתי) + פרסום PyPI (דורש חשבון — לא מבוצע אוטומטית).
+
+## 2026-06-13 · Trust hardening (תשובה ל"מה עוד נשאר")
+**החלטה:** לסגור 3 פערים אמיתיים שמעלים אמינות (לא gold-plating): (1) SQLite **WAL + busy_timeout** דרך `db.py` משותף — מונע "database is locked" כשהדאשבורד קורא בזמן שסוכן כותב; (2) `SENTINEL_API_PROTECT_READS` לנעילת קריאות ה-audit הרגישות מאחורי token; (3) **ruff** lint gate ב-CI.
+**הערה כנה:** בקומיט הראשון של הסבב טענתי בטעות "lint clean" — ruff מצא 5 (B008/B904). תוקן בקומיט עוקב; עכשיו נקי באמת (exit 0).
+**סטטוס:** ✅ 61 טסטים, ruff נקי. **מכאן והלאה עוד קוד = תשואה פוחתת בלי משתמש אמיתי** — ההמלצה לעצור את הגולת-זהב ולתקֵף עם monitor-mode dogfood.
+
+## 2026-06-13 · "תעשה את שאר הדברים" (חוץ מ-MeiroX) — סבב אחרון
+**החלטה:** Itamar ביקש מפורשות: לא לחבר את הבוט, אבל לבנות את כל השאר. בוצע:
+- **detector חזק** — full trifecta (untrusted-content tracking), dangerous-arg (cmd/SQL/path/URL), PII.
+- **Retention** — approval TTL + purge, rate-limit purge, `sentinel gc`. (ה-audit לא נמחק לעולם — רשומת compliance; מחיקה תשבור את השרשרת.)
+- **Upstream MCP MITM אמיתי** — `AsyncMCPProxy` מעל `mcp.ClientSession` חי (refactor ל-`aenforce` async; ה-sync לא השתנה).
+- **EU AI Act Art.12 report** רציני (`export --format art12`).
+- **release ל-PyPI** (Trusted Publishing) + PUBLISHING.md — מוכן, **לא בוצע** (דורש חשבון PyPI; פעולה כלפי-חוץ).
+**סטטוס:** ✅ 71 טסטים, ruff נקי. נשאר: פרסום (שלך), design partner (אנושי), MeiroX (הוחרג מפורשות).
+
+## 2026-06-13 · Pre-launch hardening + שכבת compliance רב-מסגרתית
+**החלטה:** לפני השקה — (א) תיקון ממצאי pre-launch: XSS בדאשבורד (escaping), disclaimers (alpha/not-legal-advice ב-README + Art.12), retry על כתיבת audit מקבילית, מדיניות disclosure. (ב) "כל מה שחסר לפי החוקים ל-AI": `frameworks.py` — קטלוג של 6 רגולציות אמיתיות (EU AI Act, GDPR, NIST AI RMF, ISO 42001, Colorado AI Act, SEC/FINRA) עם מיפוי **כֵּן** full/partial/none, `sentinel compliance` CLI, ו-COMPLIANCE.md.
+**כנות:** מתוך 27 חובות — רק 1 full, 20 partial, 6 none. Sentinel = שכבת evidence/control, *לא* "הופך אותך ל-compliant". הכל מסומן indicative/not-legal-advice.
+**סטטוס:** ✅ 78 טסטים, ruff נקי. נשאר רק: מילוי איש קשר אבטחה, שם PyPI, push ל-CI — ואז השקה.
+
+## 2026-06-14 · הכללה: לכל סוכן AI, לא רק MeiroX/מסחר
+**החלטה:** Itamar ביקש שזה יהיה לכל סוכן שאנשים בונים עם AI, לא רק הבוט שלו. בוצע: `policies/starter.yaml` גנרי (read/write/destructive/payments/egress/code-exec), `examples/generic_agent.py` כ-demo הראשי (`sentinel demo` מצביע עליו), `Sentinel.wrap_all()` לעטיפת toolset שלם, ו-`INTEGRATIONS.md` (plain/LangChain/OpenAI/CrewAI/LlamaIndex/MCP). default policy ב-Config שונה ל-starter.yaml; trading_agent נשאר כדוגמה vertical (מצמיד example.yaml). README/DEMO/PyPI שם = guardledger.
+**סטטוס:** ✅ 79 טסטים, ruff נקי. שני ה-demos עובדים (גנרי + מסחר).

guardledger-0.1.0/DEMO.md

@@ -0,0 +1,90 @@
+# DEMO.md — running Sentinel end-to-end
+
+## Setup (once)
+
+```bash
+cd sentinel
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+cp .env.example .env      # optional; sensible defaults work without it
+```
+
+## 1. The end-to-end demo (the headline)
+
+```bash
+sentinel demo            # a GENERIC agent; vertical example: python examples/trading_agent.py
+```
+
+A generic AI agent runs **through** Sentinel (the trading version shows the same controls
+for a financial agent). You'll see the same scenarios either way:
+
+| Scenario | Tool call | What Sentinel does |
+|---|---|---|
+| Normal trading | `get_quote`, `get_balance`, `place_order($100)` | **allowed** + logged |
+| Oversized order | `place_order(TSLA, $5000)` | **blocked** — policy needs approval above $500 |
+| Suspicious (trifecta) | `read_api_secret()` then `http_post(...)` | **allowed but FLAGGED** — secret-then-egress |
+| Suspicious (injection) | `get_news("…ignore previous instructions…")` | **allowed but FLAGGED** — injection signature |
+| Destructive | `delete_account()` | **blocked** — forbidden by policy |
+| Kill switch | `get_quote()` after `kill` | **blocked** — agent stopped |
+
+It ends by printing the audit summary and confirming the hash chain is intact.
+
+## 2. Prove the audit is tamper-evident
+
+```bash
+sentinel verify          # -> ok: true
+
+# now tamper with the SQLite log directly (simulating an attacker hiding a trade)
+python - <<'PY'
+import sqlite3
+c = sqlite3.connect("data/sentinel.db")
+c.execute("UPDATE audit SET args=? WHERE seq=4", ('{"amount": 1}',))
+c.commit(); c.close()
+PY
+
+sentinel verify          # -> ok: false, first_bad_seq: 4  (exit code 1)
+```
+
+This is the wedge: you cannot quietly rewrite what the agent did.
+
+## 3. Export a compliance report
+
+```bash
+sentinel export --out report.json
+```
+
+Every record carries an integrity status plus `eu_ai_act_art12` and OWASP Agentic
+tags — hand it to a compliance reviewer or auditor.
+
+## 4. The dashboard (live control plane)
+
+```bash
+sentinel serve           # -> http://127.0.0.1:8787
+```
+
+The dashboard polls the same audit DB, so:
+
+- **watch** actions land live with their decision, status, flags, and matched rule;
+- click **VERIFY CHAIN** to re-check integrity on demand;
+- click **KILL ALL** — then in another terminal run `sentinel demo` again: the agent
+  is **blocked on its next call**, because the kill state is shared through SQLite.
+  This is a real cross-process kill switch, not a toy.
+- edit the **policy** YAML and save (validated before it's written).
+
+> Note: the live dashboard couldn't be auto-screenshotted here because the preview
+> sandbox blocks the project's `.venv`; it runs fine under plain `sentinel serve`,
+> and its endpoints are covered by `tests/test_api.py`.
+
+## 5. Measure the overhead
+
+```bash
+python examples/benchmark.py    # ~0.4 ms/call on a dev laptop (incl. 2 durable audit writes)
+```
+
+## 6. See the compliance mapping
+
+```bash
+sentinel compliance --all                  # full/partial/none across 6 regulations
+sentinel compliance --framework eu_ai_act  # mapping + your audit evidence
+```
+