halo-record

छेड़छाड़-रोधी AI एजेंटों के लिए रनटाइम रिकॉर्ड: वह ऑडिट ट्रेल जिसे विक्रेता चलाता है लेकिन संपादित नहीं कर सकता।

आपके एजेंट का हर कदम (टूल कॉल, मॉडल कॉल, डेटा एक्सेस, अनुमोदन) एक एपेंड-संरचित, हैश-चेन लॉग में एक रिकॉर्ड बन जाता है। चेन का चेकपॉइंट रखने वाला कोई भी पक्ष उसके पीछे के रिकॉर्ड को सत्यापित कर सकता है कि उन्हें कभी बदला नहीं गया, बिना उन्हें बनाने वाले पर भरोसा किए। जब किसी ग्राहक की सुरक्षा टीम पूछती है "आपके एजेंट ने हमारे डेटा के साथ क्या किया?", तो आप उन्हें एक पैराग्राफ के बजाय एक लिंक देते हैं। सुरक्षा समीक्षाएँ पहले से ही SOC 2 चेकलिस्ट के साथ AI प्रश्न पूछ रही हैं, और आज एक लिखित आश्वासन अभी भी पास हो जाता है। इस प्रोजेक्ट के पीछे का दांव यह है कि यह अधिक समय तक नहीं चलेगा।

रिकॉर्ड प्रारूप खुला है और लागू करने के लिए स्वतंत्र है। यह पैकेज संदर्भ कार्यान्वयन है: रिकॉर्डर, वेरिफायर, विटनेस क्लाइंट, और रिपोर्ट सर्वर।

आप इस कोड पर भरोसा क्यों कर सकते हैं

आपसे कहा जा रहा है कि अपने एजेंट के अंदर एक रिकॉर्डर लगाएं। आपको इसे विश्वास पर नहीं लेना चाहिए:

• शून्य रनटाइम निर्भरताएँ। केवल स्टैंडर्ड लाइब्रेरी। pip install halo-record बिल्कुल एक पैकेज स्थापित करता है।
• कोई नेटवर्क कॉल नहीं, विटनेस को छोड़कर, जो ऑप्ट-इन है और केवल एक रिकॉर्ड गिनती और एक चेन फिंगरप्रिंट प्राप्त करता है। रिकॉर्ड सामग्री आपके इंफ्रास्ट्रक्चर को कभी नहीं छोड़ती।
• कच्चे इनपुट कभी रिकॉर्ड में प्रवेश नहीं करते। तर्कों को हैश किया जाता है और केवल एक रिडैक्टेड सारांश के रूप में संग्रहीत किया जाता है — कभी भी कच्चा मान नहीं। रिडक्शन बेस्ट-एफर्ट है (सामान्य सीक्रेट और PII प्रारूपों पर regex): इसे डिफेंस-इन-डेप्थ मानें, गारंटी नहीं।
• ऑडिट करने के लिए पर्याप्त छोटा। लगभग 4,300 पंक्तियों का Python। इसे एक दोपहर में पूरा पढ़ें।
• Apache-2.0.

60-सेकंड का डेमो

कोई एजेंट आवश्यक नहीं। uv के साथ, कुछ भी स्थापित करने की आवश्यकता नहीं:

uvx --from halo-record halo demo --serve

या क्लासिक तरीका:

pip install halo-record
halo demo --serve

दोनों में से कोई भी दो ग्राहकों के साथ एक काल्पनिक सपोर्ट-एजेंट विक्रेता तैयार करता है, चेन को विटनेस करता है, उनकी गेटेड Runtime Reports परोसता है, और आपके ब्राउज़र में ऑपरेटर कंसोल खोलता है। फिर टैम्पर टेस्ट आज़माएं: किसी एक .jsonl फ़ाइल से एक पंक्ति हटाएं और रीलोड करें। रिपोर्ट इसे पकड़ लेती है।

अपना खुद का एजेंट रिकॉर्ड करें

बाउंड्री पर एक पंक्ति:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

log= के बिना, रिकॉर्ड ~/.halo/my-agent.jsonl पर जाते हैं (प्रति एजेंट एक चेन)। या जो आप पहले से चलाते हैं उसके लिए एडॉप्टर का उपयोग करें (नीचे मैट्रिक्स देखें)। फिर रिपोर्ट रेंडर करें:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

क्विकस्टार्ट तब समाप्त होता है जब आप अपने खुद के एजेंट की Runtime Report को ब्राउज़र में देख रहे होते हैं। यदि आपको JSONL फ़ाइल मिली और कोई रिपोर्ट नहीं, तो कुछ गड़बड़ है: एक issue खोलें।

जो आप पहले से चलाते हैं उससे जुड़ें

हर रिकॉर्ड एक source टैग रखता है, इसलिए रिपोर्ट खुलासा करती है कि साक्ष्य का प्रत्येक टुकड़ा कैसे एकत्र किया गया था। कैप्चर किए गए और इंगेस्ट किए गए रिकॉर्ड एक ही चेन में रहते हैं।

जो कुछ भी OpenTelemetry GenAI spans उत्सर्जित करता है (CrewAI, LlamaIndex, और OTel इंस्ट्रुमेंटेशन वाले अधिकांश एजेंट फ्रेमवर्क) OTel एडॉप्टर के माध्यम से चेन में आ जाता है, और TypeScript पैकेज Vercel AI SDK और JS एजेंट इकोसिस्टम के लिए नेटिव एडॉप्टर भेजता है। आपके स्टैक के लिए एडॉप्टर गायब है? एक issue खोलें। अधिकांश एडॉप्टर लगभग सौ पंक्तियों के होते हैं।

अपने कोडिंग एजेंट को रिकॉर्ड करें

Claude Code हर टूल कॉल के बाद एक PostToolUse हुक फायर करता है। इसे halo hook पर इंगित करें और प्रत्येक क्रिया — फ़ाइल लेखन, शेल कमांड, MCP कनेक्टर कॉल — एक स्थानीय चेन में एक रिकॉर्ड बन जाती है। कोई कोड परिवर्तन नहीं; एक settings प्रविष्टि:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

इसे ~/.claude/settings.json में जोड़ें और रिकॉर्ड ~/.halo/audit.jsonl में पहुँचते हैं ($HALO_LOG से ओवरराइड करें)। शुद्ध-ऑर्केस्ट्रेशन उपकरण जो किसी डेटा, नेटवर्क या बाहरी स्थिति को नहीं छूते हैं, छोड़ दिए जाते हैं — चेन ट्रस्ट-बाउंड्री क्रियाओं को रिकॉर्ड करती है, सोच को नहीं। सारांश के बिना सामग्री हैश रिकॉर्ड करने के लिए HALO_HASH_ONLY=1 सेट करें। HALO_AGENT_VERSION (और वैकल्पिक रूप से HALO_AGENT_MODEL) सेट करें ताकि हर रिकॉर्ड को उस एजेंट बिल्ड से बांधा जा सके जिसने इसे बनाया — जब कोई ऑडिटर पूछता है कि किसी दिए गए विंडो में कौन सा संस्करण चल रहा था, तो एक्सपोर्ट स्मृति के बजाय कॉलम द्वारा उत्तर देता है।

यदि आपको रिपोर्ट को इसका उत्तर देने की आवश्यकता है कि "यह रन किन नियमों के तहत हुआ?", तो HALO_AUTHORITY_FILE को सत्र के लिए प्रभावी अथॉरिटी के JSON स्नैपशॉट पर सेट करें। इसे प्राइवेसी-सुरक्षित रखें: हैश और रेफ्स, कच्चे प्रॉम्प्ट नहीं, निजी पॉलिसी टेक्स्ट नहीं, सीक्रेट नहीं, या पूर्ण टूल स्कीमा नहीं।

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

स्नैपशॉट को एक्शन रिकॉर्ड के समान हैश चेन में सील कर दिया जाता है। एक अच्छा डिफ़ॉल्ट शुरुआत में एक सत्र-स्तरीय स्नैपशॉट है, साथ ही नियमों, Skills, हुक, MCP टूल रजिस्ट्री, या कॉम्पैक्शन पॉलिसी बदलने पर एक नया स्नैपशॉट। लंबे सत्रों को हल्का रखने के लिए, पहले पूर्ण स्नैपशॉट के बाद समान authority.snapshot_id वाले लगातार रिकॉर्ड कॉम्पैक्ट किए जाते हैं: बाद के रिकॉर्ड केवल {"snapshot_id": "...", "same_as_previous": true} रखते हैं। पॉइंटर हैश-चेन रहता है, लेकिन भारी refs/omissions/stale-if ब्लॉक हर क्रिया पर दोहराया नहीं जाता। फिर, सामान्य:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

कोई भी एजेंट रनटाइम जो पोस्ट-एक्शन हुक उजागर करता है, उसी कमांड को फीड कर सकता है — हुक stdin पर एक इवेंट को JSON के रूप में पढ़ता है और एक रिकॉर्ड जोड़ता है।

अखंडता बनाम पूर्णता (यह भाग पढ़ें)

इस बारे में सटीक रहें कि प्रत्येक परत क्या साबित करती है — क्योंकि ये अलग-अलग दावे हैं, और अंतर ही बिंदु है:

स्व-धारित चेन एक स्थापित हेड के सापेक्ष अखंडता साबित करती है: किसी चेन हेड को देखते हुए जो कोई पहले से रखता है, उसके पीछे के रिकॉर्ड में कोई भी संपादन, पुनर्क्रमण या विलोपन पता लगाने योग्य हो जाता है। अकेले — ऑपरेटर के बाहर किसी के द्वारा हेड देखे जाने से पहले — एक चेन आंतरिक स्थिरता साबित करती है, इतिहास नहीं: एक ऑपरेटर एक रिकॉर्ड गिरा सकता है और फिर से सील कर सकता है, और नई फ़ाइल सत्यापित हो जाएगी। चेन ऐतिहासिक रूप से प्रतिबद्ध हो जाती है जिस क्षण उसका हेड ऑपरेटर के नियंत्रण से बाहर निकल जाता है।

वही विटनेस है: ऑपरेटर के बाहर एक पक्ष जो चेन के आवधिक फिंगरप्रिंट रखता है (एक गिनती और एक हेड हैश, कुछ और नहीं)। चेकपॉइंट प्रतिबद्ध इतिहास को फिर से लिखने का पता लगाने योग्य बनाते हैं, और एक छूटा हुआ चेकपॉइंट स्वयं एक दृश्य घटना है:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

एक और सीमा, स्पष्ट रूप से कही गई: न तो चेन और न ही विटनेस यह साबित करता है कि हर वास्तविक-दुनिया की क्रिया रिकॉर्डर से गुज़री। यह कैप्चर पूर्णता है — स्टैक में रिकॉर्डर कहाँ बैठता है इसकी एक संपत्ति (नेटिव इंस्ट्रुमेंटेशन, हुक, गेटवे इंगेशन), किसी हैश की नहीं। रिकॉर्ड इसी कारण से एक source टैग रखते हैं।

कोई भी विटनेस चला सकता है। आपके द्वारा स्वयं चलाया गया विटनेस इतिहास को आपके प्रति प्रतिबद्ध करता है; इसे आपके ग्राहक के प्रति प्रतिबद्ध करने के लिए एक ऐसे विटनेस की आवश्यकता होती है जिस पर उन्हें भरोसा करने का कारण हो। प्रोटोकॉल किसी भी तरह खुला है।

एक होस्टेड, मान्यता प्राप्त विटनेस इस प्रोजेक्ट के खुद को बनाए रखने का तरीका है। प्रारंभिक पहुँच: [email protected]।

यह अनुपालन स्टैक में कहाँ बैठता है

halo-record एक साक्ष्य परत है, प्रमाणन नहीं। यह वह आर्टिफैक्ट बनाता है जिसे मूल्यांकन फ्रेमवर्क अलग-अलग शब्दों में माँगते रहते हैं:

• सुरक्षा प्रश्नावली और SOC 2 समीक्षाएँ: स्क्रीनशॉट और गद्य के बजाय एक सत्यापन योग्य Runtime Report के साथ AI अनुभागों का उत्तर दें।
• AIUC-1: मानक के Accountability नियंत्रणों के लिए आवश्यक छेड़छाड़-रोधी लॉगिंग (E015.4) और प्राधिकरण घटनाओं के साथ पूर्ण-निष्पादन-श्रृंखला रिकॉर्ड (E015.2) बनाता है — निरंतर रनटाइम साक्ष्य, ऑडिट समय पर पुनर्निर्मित नहीं।
• OWASP (GenAI Security Project): OWASP Top 10 for Agentic Applications 2026 और LLM Top 10 में एजेंट-व्यवहार जोखिमों के पीछे रनटाइम साक्ष्य — लक्ष्य अपहरण, टूल दुरुपयोग, पहचान और विशेषाधिकार दुरुपयोग — रिकॉर्ड किया गया कि एजेंट ने वास्तव में कौन से टूल और डेटा के साथ क्या किया।
• AARM (CSA): AARM द्वारा निर्दिष्ट छेड़छाड़-रोधी एक्शन रसीद (R5/R6) बनाता है — श्रृंखलाबद्ध और स्वतंत्र रूप से विटनेस किया गया। halo-record रसीद परत है; पूर्ण AARM सिस्टम के लिए इसे एक प्रवर्तन गेटवे के साथ जोड़ें। AARM.md देखें।
• Agentic Trust Controls: ATC के साक्ष्य नियंत्रणों के पीछे रनटाइम रिकॉर्ड — एक श्रृंखलाबद्ध रिकॉर्ड में छेड़छाड़-रोधी एक्शन लॉगिंग (RBM-03) और अथॉरिटी एटेस्टेशन (AID-05), दोनों से परे विटनेस परत के साथ। ATC.md देखें।
• EU AI Act: उच्च-जोखिम AI सिस्टम के लिए लॉगिंग और रिकॉर्ड-कीपिंग दायित्व।
• ISO 42001 / NIST AI RMF: प्रबंधन-सिस्टम नियंत्रणों के पीछे परिचालन साक्ष्य।

इनमें से कोई भी अपने आप में कुछ प्रमाणित नहीं करता। यह आपके मूल्यांकनकर्ता को देखने के लिए कुछ सत्यापन योग्य देता है। सीमाएँ — halo-record जान-बूझकर क्या नहीं करता, और समीक्षक के पूछने पर क्या कहना चाहिए — LIMITS.md में प्रलेखित हैं।

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

अखंडता मॉडल

किसी रिकॉर्ड का हैश निकालने के लिए: integrity.hash को छोड़कर रिकॉर्ड लें, integrity.prev_hash को पिछले रिकॉर्ड के हैश पर सेट करके; RFC 8785 (JSON Canonicalization Scheme) के साथ कैननिकलाइज़ करें; बाइट्स का SHA-256 करें। पहले रिकॉर्ड का prev_hash 64 शून्य होता है। सत्यापन हर हैश की पुनर्गणना करता है और हर लिंक की जाँच करता है। किसी सीक्रेट की आवश्यकता नहीं; यही बिंदु है।

लगता है आप वेरिफायर के ध्यान में आए बिना चेन से छेड़छाड़ कर सकते हैं? प्रयास और परिणाम यहाँ रहते हैं।

पूर्ण फ़ील्ड संदर्भ: halo-record.schema.json।

TypeScript

वही रिकॉर्डर Node के लिए उपलब्ध है: halo-record-ts। समान चेन प्रारूप, समान विटनेस प्रोटोकॉल। किसी भी भाषा में लिखे गए रिकॉर्ड किसी भी वेरिफायर से सत्यापित होते हैं।

योगदान

Issues, discussions, और pull requests का स्वागत है — आधार नियमों के लिए CONTRIBUTING.md देखें (संक्षिप्त संस्करण: परीक्षण आवश्यक, छोटे PRs, स्कीमा परिवर्तन पहले चर्चा किए जाते हैं)।

लाइसेंस

Apache-2.0