halo-record

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

आपके एजेंट द्वारा उठाया गया हर कदम (टूल कॉल, मॉडल कॉल, डेटा एक्सेस, अनुमोदन) एक append-संरचित, हैश-चेन्ड लॉग में एक रिकॉर्ड बन जाता है। चेन का चेकपॉइंट रखने वाला कोई भी पक्ष यह सत्यापित कर सकता है कि उसके पीछे के रिकॉर्ड कभी बदले नहीं गए, बिना उन्हें बनाने वाले किसी पर भरोसा किए। जब ग्राहक की सुरक्षा टीम पूछती है "आपके एजेंट ने हमारे डेटा के साथ क्या किया?", तो आप उन्हें एक पैराग्राफ के बजाय एक लिंक थमा देते हैं। सुरक्षा समीक्षाएँ पहले से ही 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 कनेक्टर कॉल — एक स्थानीय चेन में रिकॉर्ड बन जाती है। कोई कोड परिवर्तन नहीं; एक सेटिंग्स प्रविष्टि:

{
  "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): Agentic Applications 2026 के लिए OWASP Top 10 और LLM Top 10 में एजेंट-व्यवहार जोखिमों के पीछे का रनटाइम साक्ष्य — गोल हाइजैक, टूल दुरुपयोग, पहचान और विशेषाधिकार दुरुपयोग — एजेंट ने वास्तव में क्या किया, किन टूल और डेटा के साथ, यह दर्ज किया गया।
• AARM (CSA): AARM द्वारा निर्दिष्ट छेड़छाड़-स्पष्ट एक्शन रसीद (R5/R6) बनाता है — चेन्ड और स्वतंत्र रूप से साक्षी। halo-record रसीद परत है; पूर्ण AARM प्रणाली के लिए इसे एक enforcement गेटवे के साथ जोड़ें। 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, चर्चाएँ और pull requests स्वागत योग्य हैं — आधार नियमों के लिए CONTRIBUTING.md देखें (संक्षिप्त संस्करण: परीक्षण आवश्यक, छोटे PR, स्कीमा परिवर्तनों पर पहले चर्चा होती है)।

लाइसेंस

Apache-2.0