protocol-remediator

C/C++ प्रोटोकॉल/प्लेटफ़ॉर्म कोड की कमज़ोरियों (findings) को पुनरुत्पादनीय साक्ष्य के रूप में सामान्यीकृत करने और उम्मीदवार पैच को पृथक प्रतिलिपि में सत्यापित करने वाला MVP है। code-shield एक कार्य नाम है जिसमें नाम टकराव का जोखिम पहचाना गया था, इसलिए सार्वजनिक पैकेज और CLI के लिए तटस्थ आंतरिक नाम का उपयोग किया गया।

वर्तमान कार्यान्वयन का केंद्र पैच निर्माण मॉडल नहीं, बल्कि निम्नलिखित सत्यापन बंद-लूप है।

sanitizer 또는 SARIF
  -> Finding + EvidenceBundle
  -> source context
  -> manual/external-agent patch
  -> 원본 재현
  -> build
  -> patched reproducer
  -> tests
  -> static rescan
  -> bounded refuzz
  -> protocol oracle
  -> verified report

कार्यान्वित सुविधाएँ

• संस्करणित (versioned) Finding, EvidenceBundle, PatchProposal, VerificationReport JSON मॉडल
• detected → reproducible → contextualized → proposed → plausible → verified स्थिति संक्रमण
• AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer रिपोर्ट संग्रह
• SARIF 2.1 finding संग्रह
• सामान्यीकृत (normalized) finding का SARIF 2.1 निर्यात
• source location के आसपास ऑडिट योग्य context JSON निर्माण
• TOML-आधारित target/build/gate कॉन्फ़िगरेशन
• network-off, capability-drop, resource-limit लागू करने वाला Docker executor
• स्पष्ट opt-in की आवश्यकता वाला local executor
• मूल target प्रतिलिपि में finding का पुनरुत्पादन, फिर अलग प्रतिलिपि में patch सत्यापन
• patch checksum, reproducer checksum, path escape, symlink, फ़ाइल/लाइन सीमा जाँच
• test/fuzz harness/reproducer जैसे संरक्षित पथों के लिए patch अस्वीकृति
• बाहरी patch agent command अनुकूलक (adapter)
• प्रत्येक command के exit code, stdout/stderr, समय और gate परिणामों का संरक्षण

आवश्यकताएँ

• Python 3.11 या उच्चतर
• patch सत्यापन के लिए Git
• डिफ़ॉल्ट पृथक निष्पादन के लिए Docker
• उदाहरण चलाने के लिए Clang

कोई रनटाइम Python निर्भरता नहीं है।

स्थापना और परीक्षण

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

स्थापना के बिना चलाने के लिए:

PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v

गतिशील end-to-end suite, examples में C/C++ fixture matrix है। Clang ASan/UBSan के साथ CWE-121, CWE-190, CWE-416, CWE-787, CWE-476 का वास्तविक पुनरुत्पादन करने के बाद, प्रत्येक invariant को पुनर्स्थापित करने वाले patch के लिए सभी छह gates चलाए जाते हैं। fixture-वार इनपुट और सत्यापन सीमा examples/README.md में संकलित है।

unit-test framework के बिना केवल वास्तविक matrix चलाने के लिए:

PYTHONPATH=src python3 examples/run_fixture_matrix.py

अधिक C/C++ प्रकार के उदाहरण स्वतः उत्पन्न करके चलाने के लिए:

PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50

यह runner unittest का उपयोग नहीं करता और प्रत्येक उत्पन्न प्रोजेक्ट को उसी VerificationPipeline से गुज़ारता है। परिणाम summary डिफ़ॉल्ट रूप से artifacts/generated-corpus-summary.json में सहेजा जाता है।

Frontend कंसोल

वर्तमान कार्यान्वयन की स्थिति को परिचालन डैशबोर्ड के रूप में देखने योग्य Vite + React + TypeScript फ्रंटएंड frontend में है। यह कंसोल fixture matrix, generated corpus, Hermes API server कनेक्शन, सत्यापन gate और evidence safety invariant को एक ही स्क्रीन पर संगठित करता है।

cd frontend
npm install
npm run dev

डिफ़ॉल्ट विकास सर्वर http://127.0.0.1:5173 है। production build की जाँच निम्न से की जाती है।

cd frontend
npm run build

CLI

sanitizer finding संग्रह

protocol-remediator ingest-sanitizer \
  --log asan.log \
  --reproducer crash.input \
  --target-name parser \
  --revision 0123456789abcdef \
  --variant asan-x86_64 \
  --output intake/parser-crash

आउटपुट:

intake/parser-crash/finding.json
intake/parser-crash/evidence.json

SARIF संग्रह

protocol-remediator ingest-sarif \
  --sarif results.sarif \
  --output intake/sarif

SARIF निर्यात

protocol-remediator export-sarif \
  --finding intake/parser-crash/finding.json \
  --finding intake/another/finding.json \
  --output artifacts/findings.sarif

मॉडल-तटस्थ context निर्माण

protocol-remediator context \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --target-root /path/to/target \
  --output intake/parser-crash/context.json

मौजूदा patch सत्यापन

protocol-remediator verify \
  --config /path/to/target/target.toml \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --patch candidate.patch \
  --artifacts artifacts

Exit code verified होने पर 0, सत्यापन विफलता पर 1, और कॉन्फ़िगरेशन/इनपुट त्रुटि पर 2 होता है।

Hermes agent API सर्वर

जब Hermes API server चालू होता है, तो remediate स्थानीय command के बजाय HTTP API से patch का अनुरोध कर सकता है। डिफ़ॉल्ट endpoint POST /v1/patches है, जो finding/evidence/context और target workspace archive प्राप्त करके unified diff लौटाता है।

उदाहरण सर्वर चलाना:

PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
  --host 127.0.0.1 \
  --port 8765

स्थापना के बाद console script का भी उपयोग किया जा सकता है।

hermes-agent-server --host 127.0.0.1 --port 8765

ऑपरेशनल backend command जोड़ते समय --backend-command को argument-स्तर पर दोहराया जाता है। {context}, {workspace}, {patch_output} placeholder समर्थित हैं।

hermes-agent-server \
  --backend-command my-patch-agent \
  --backend-command --context \
  --backend-command {context} \
  --backend-command --workspace \
  --backend-command {workspace} \
  --backend-command --output \
  --backend-command {patch_output}

target.toml में Hermes mode इस प्रकार निर्दिष्ट किया जाता है।

[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30

फिर मौजूदा remediate command का उपयोग वैसे ही किया जाता है।

protocol-remediator remediate \
  --config examples/length-prefixed-parser/target.hermes.toml \
  --finding artifacts/hermes-cli-input/finding.json \
  --evidence artifacts/hermes-cli-input/evidence.json \
  --artifacts artifacts/hermes-cli

विकास के लिए end-to-end जाँच निम्न runner से चलाई जाती है। यह runner एक अस्थायी Hermes server प्रारंभ करता है, API client से patch प्राप्त करता है, और फिर सत्यापन बंद-लूप को पूरी तरह चलाता है।

PYTHONPATH=src python3 examples/run_hermes_demo.py

बाहरी command agent निर्माण और सत्यापन

Hermes का उपयोग किए बिना सीधे स्थानीय command को कॉल करने के लिए target.toml में agent command को स्ट्रिंग array के रूप में निर्दिष्ट करें।

[agent]
mode = "command"
command = [
  "my-patch-agent",
  "--context",
  "{context}",
  "--workspace",
  "{workspace}",
  "--output",
  "{patch_output}",
]
timeout_seconds = 900

फिर निम्न command चलाएँ।

protocol-remediator remediate \
  --config /path/to/target/target.toml \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --artifacts artifacts

core किसी विशेष LLM API को सीधे कॉल नहीं करता। यह एक अनुबंध है कि Hermes backend या बाहरी command context पढ़कर unified diff उत्पन्न करे। agent कार्य मूल target पर नहीं, बल्कि अस्थायी प्रतिलिपि में निष्पादित होता है।

target कॉन्फ़िगरेशन

पूरा उदाहरण target.toml में है।

[project]
name = "my-protocol"
language = "c++"
root = "."

[executor]
mode = "docker"
image = "my-frozen-toolchain@sha256:..."
timeout_seconds = 300
network = false

[reproduction]
failure_regex = "AddressSanitizer|heap-buffer-overflow"

[verification]
required_gates = [
  "build",
  "reproducer",
  "tests",
  "rescan",
  "refuzz",
  "protocol",
]

[gates]
build = [["cmake", "-S", ".", "-B", "build"], ["cmake", "--build", "build"]]
reproducer = [["./build/fuzz_target", "{reproducer}"]]
tests = [["ctest", "--test-dir", "build", "--output-on-failure"]]
rescan = [["./tools/run-sast", "--fail-on-new"]]
refuzz = [["./tools/refuzz", "--seconds", "60"]]
protocol = [["./tools/protocol-oracle"]]

प्रत्येक command shell स्ट्रिंग नहीं है, बल्कि argument array है। समर्थित placeholder:

• {workspace}: executor को दिखाई देने वाला अस्थायी target पथ
• {reproducer}: checksum सत्यापन के बाद अस्थायी target में प्रतिलिपि किया गया reproducer पथ

build और reproducer हमेशा आवश्यक हैं। डिफ़ॉल्ट नीति में सभी छह gates अनिवार्य हैं। यदि target की विशेषताओं के कारण कोई gate उपयोग योग्य नहीं है, तो required_gates में स्पष्ट रूप से समायोजन करना चाहिए, और यह रिपोर्ट में वैसे ही रहता है।

artifact

प्रत्येक सत्यापन run निम्नलिखित को संरक्षित करता है।

artifacts/run_<id>/
  candidate.patch
  context.json
  evidence.input.json
  finding.input.json
  finding.final.json
  patch-proposal.json
  patch-stats.json
  verification-report.json

verification-report.json में baseline और patched command के आउटपुट शामिल होते हैं। PoC या लॉग में secrets शामिल हो सकते हैं, इसलिए artifact संग्रहण पर अलग पहुँच और संरक्षण नीति लागू करनी चाहिए।

सुरक्षा सीमाएँ

• डिफ़ॉल्ट अनुशंसा pinned Docker image और network=false है।
• local executor को सीधे allow_local=true घोषित करना चाहिए और अविश्वसनीय target पर उपयोग नहीं करना चाहिए।
• बाहर जाने वाली LLM command की डेटा नीति operator तय करता है। core स्वतः अपलोड नहीं करता।
• plausible वह स्थिति है जिसमें केवल build और मूल reproducer पास हुए हैं।
• verified भी program equivalence का प्रमाण नहीं है और मानव अनुमोदन का विकल्प नहीं है।
• स्वचालित merge कार्यान्वित नहीं किया गया है।

अगली कार्यान्वयन प्राथमिकताएँ

1. वास्तविक ProFuzzBench/AFLNet target adapter
2. protocol message sequence और state trace collector
3. CodeQL वैकल्पिक adapter तथा C/C++ source/sink model emitter
4. ASan/UBSan/MSan और architecture matrix निष्पादन
5. सामान्य corpus-आधारित differential protocol oracle
6. AutoPatchBench runner और मात्रात्मक benchmark report

अनुसंधान का आधार और डिज़ाइन निर्णय docs/research में संग्रहीत हैं।