nanda-rani/safeएक प्रासंगिक सुरक्षा ऑडिटिंग प्रणाली जो शोध कलाकृतियों के लिए है
SAFE अनुसंधान आर्टिफैक्ट्स में Semgrep और Trivy निष्कर्षों का नियंत्रित, रिपॉजिटरी-जागरूक सुरक्षा मूल्यांकन करता है।
यह दो स्वतंत्र वर्गीकरण कार्यों का समर्थन करता है: प्रत्यक्ष binary भविष्यवाणी (SECURITY_RELEVANT या NON_SECURITY) और विस्तृत multiclass प्रासंगिक वर्गीकरण (तीन लेबल — देखें तीन लेबल)। प्रत्येक कार्य zero-shot या agentic मोड में चल सकता है।
इसे केवल आवश्यकता है:
artifact_id एक शोध-आर्टिफैक्ट फ़ोल्डर हो।artifact_id द्वारा कुंजीबद्ध एक पेपर PDF/टेक्स्ट संग्रह।यह किसी भी लेबल किए गए मूल्यांकन डेटा पर प्रशिक्षण या ट्यूनिंग नहीं करता है। लेबल किया गया डेटा केवल अनुमान के बाद, भविष्यवाणियों का मूल्यांकन करने के लिए उपयोग किया जाता है, और वर्गीकरणकर्ता द्वारा कभी नहीं देखा जाता है। SAFE कभी भी आर्टिफैक्ट कोड निष्पादित नहीं करता है; रिपॉजिटरी टेक्स्ट को अविश्वसनीय साक्ष्य के रूप में माना जाता है, निर्देशों के रूप में नहीं।
इस रिलीज़ में पूर्ण safe_audit स्रोत, CLI, और परीक्षण शामिल हैं, साथ ही तीन पूरी तरह से सिंथेटिक उदाहरण आर्टिफैक्ट्स का एक स्व-निहित भी शामिल है जिसे आप बिना किसी बाहरी डेटा के अंत से अंत तक चला सकते हैं। इसमें वास्तविक शोध-आर्टिफैक्ट कॉर्पस, ग्राउंड-ट्रुथ लेबल, और पेपर में उपयोग किए गए मूल्यांकन निष्कर्ष शामिल नहीं हैं।
त्वरित शुरुआत: स्थापना के बाद, डेमो चलाएं — यह बिना किसी डेटा सेटअप के तुरंत काम करता है। config.example.yaml, जिसे बाद में कॉन्फ़िगरेशन के अंतर्गत कवर किया गया है, आपके अपने निष्कर्षों/आर्टिफैक्ट्स के लिए एक टेम्पलेट है और जब तक आप इसे संपादित नहीं करते तब तक नहीं चलेगा।
cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
API कुंजी सेट करें:
export OPENAI_API_KEY="your-key"
किसी संगठन LiteLLM प्रॉक्सी के लिए, इसके बजाय config.litellm.example.yaml का उपयोग करें — यह इनलाइन टिप्पणी किया गया है। क्रेडेंशियल और कस्टम हेडर मान पर्यावरण चर से पढ़े जाते हैं और SAFE कॉन्फ़िगरेशन या परिणाम फ़ाइलों में कभी संग्रहीत नहीं होते हैं।
demo/ में तीन छोटे, पूरी तरह से सिंथेटिक उदाहरण आर्टिफैक्ट्स शामिल हैं — कोई भी वास्तविक प्रकाशित शोध आर्टिफैक्ट से व्युत्पन्न या संबंधित नहीं — प्रति वर्गीकरण लेबल एक, ताकि समीक्षक बिना किसी बाहरी डेटा के पूर्ण पाइपलाइन का अभ्यास कर सकें:
demo-contextual-risk/ — एक खिलौना फेडरेटेड-लर्निंग चेकपॉइंट एग्रीगेटर जो कॉलर-आपूर्ति किए गए URL से torch.load के साथ डाउनलोड किए गए चेकपॉइंट को डिसीरियलाइज़ करता है। अविश्वसनीय, नेटवर्क-स्रोत इनपुट एक असुरक्षित डिसीरियलाइज़ेशन सिंक तक पहुंचता है, जिसे SAFE द्वारा CONTEXTUAL_RISK वर्गीकृत करने की अपेक्षा की जाती है।demo-hardening-recommendation/ — एक खिलौना बेंचमार्क हार्नेस जो सभी हार्डकोडेड Python लिटरल्स वाली कमांड लाइनों के विरुद्ध subprocess.run(..., shell=True) चलाता है, जिसमें कोई कॉलर-नियंत्रित इनपुट नहीं होता है। SAFE द्वारा इसे HARDENING_RECOMMENDATION वर्गीकृत करने की अपेक्षा की जाती है: शेल पैटर्न वास्तविक है और ध्वजांकित करने योग्य है, लेकिन कोई बाहरी चीज़ इसे प्राप्त या प्रभावित नहीं कर सकती है।demo-false-positive/ — एक परीक्षण-फिक्स्चर जनरेटर जो एक काल्पनिक डीकंप्रेसन-बम सलाह के साथ पुराने Pillow संस्करण से जुड़ा हुआ है। कोड केवल नई इन-मेमोरी छवियां बनाता है और कभी बाहरी डेटा नहीं खोलता है, इसलिए सलाह का वास्तविक कोड पथ कभी नहीं पहुंचा जाता है। SAFE द्वारा इसे FALSE_POSITIVE वर्गीकृत करने की अपेक्षा की जाती है।demo/findings.csv में प्रति आर्टिफैक्ट एक निष्कर्ष होता है, और demo/demo-zero-shot.yaml / demo/demo-agentic.yaml चलाने के लिए तैयार कॉन्फ़िगरेशन हैं (artifact_root: . कॉन्फ़िगरेशन फ़ाइल के सापेक्ष हल होता है, इसलिए demo/ के अंदर से चलाएं):
cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml
परिणाम क्रमशः demo/runs/demo-zero-shot/ और demo/runs/demo-agentic/ में आते हैं (देखें आउटपुट)।
CONTEXTUAL_RISKHARDENING_RECOMMENDATIONFALSE_POSITIVEकोई अतिरिक्त श्रेणी और कोई नियतात्मक लेबल-परिवर्तन नियम उपयोग नहीं किया जाता है। किसी आर्टिफैक्ट के अपने कोड में एक प्रलेखित, पृथक शोध/सुरक्षा तंत्र को HARDENING_RECOMMENDATION वर्गीकृत किया जाता है, क्योंकि अंतर्निहित अभ्यास अभी भी वास्तविक है भले ही अलगाव यथार्थवादी शोषण क्षमता को सीमित करता है।
SECURITY_RELEVANT: एक वैध प्रासंगिक जोखिम या सख्तीकरण चिंता, जिसमें जानबूझकर, पृथक सुरक्षा-शोध व्यवहार शामिल है।NON_SECURITY: एक गलत, बेमेल, गैर-लागू, अनुपस्थित, या स्पष्ट रूप से अप्रयुक्त प्रभावित-सुविधा निष्कर्ष।मूल्यांकनकर्ता बहु-वर्ग भविष्यवाणियों से एक बाइनरी दृश्य भी प्राप्त करता है: FALSE_POSITIVE NON_SECURITY बन जाता है; हर अन्य बहु-वर्ग लेबल SECURITY_RELEVANT बन जाता है। प्रत्यक्ष और व्युत्पन्न बाइनरी परिणाम स्पष्ट रूप से अलग रहते हैं।
project/
├── config.yaml
├── data/
│ └── findings.csv
└── artifacts/
├── artifact_001/
├── artifact_002/
└── artifact_003/
मैपिंग सटीक है: artifact_id = artifact_001 artifacts/artifact_001/ पर हल होता है।
आवश्यक CSV कॉलम:
artifact_id;tool;finding_id
वैकल्पिक कॉलम:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
एक प्रारंभिक अनाम इंडेक्स कॉलम को अनदेखा किया जाता है। अतिरिक्त कॉलम इनपुट मॉडल द्वारा संरक्षित किए जाते हैं।
उदाहरण:
artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes
scripts/run_scanners.py और scripts/build_findings_csv.py ऊपर वर्णित findings.csv और आर्टिफैक्ट लेआउट को सीधे आपके अपने कोड से उत्पन्न करते हैं, Semgrep और Trivy का उपयोग करके।
Semgrep स्थापित करें (किसी भी OS पर समान रूप से काम करता है, Linux सहित):
pip install semgrep
Linux पर Trivy स्थापित करें — या तो apt रिपॉजिटरी (Debian/Ubuntu):
sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy
या आधिकारिक इंस्टॉल स्क्रिप्ट, जो किसी भी Linux वितरण पर काम करती है और एक बाइनरी रिलीज़ को /usr/local/bin में स्थापित करती है (उस निर्देशिका के लिए sudo से परे कोई रूट पैकेज आवश्यक नहीं):
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin
जारी रखने से पहले दोनों को PATH पर सत्यापित करें:
semgrep --version
trivy --version
फिर artifact_root/ के अंतर्गत प्रति आर्टिफैक्ट एक निर्देशिका व्यवस्थित करें और चलाएं:
python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv
पहला कमांड प्रत्येक आर्टिफैक्ट निर्देशिका के विरुद्ध Semgrep और Trivy (भेद्यता और गुप्त स्कैनिंग) चलाता है और कच्चे स्कैनर JSON को सहेजता है। दूसरा उस JSON को SAFE-संगत findings.csv में पार्स करता है (कॉलम इनपुट संरचना से मेल खाते हैं; file प्रत्येक आर्टिफैक्ट निर्देशिका के सापेक्ष रिपोर्ट किया जाता है)। केवल एक टूल चलाने के लिए किसी भी स्क्रिप्ट पर --skip-semgrep/--skip-trivy पास करें। run_scanners.py पर --config डिफ़ॉल्ट auto के बजाय एक विशिष्ट Semgrep नियमसेट को पिन करता है, जो सुविधाजनक है लेकिन प्रतिलिपि-योग्य रूप से पिन नहीं किया गया है।
यह अनुभाग SAFE को आपके अपने निष्कर्ष CSV और आर्टिफैक्ट फ़ोल्डरों के विरुद्ध चलाने के लिए है (ऊपर इनपुट संरचना देखें)। यदि आप केवल SAFE को चलते हुए देखना चाहते हैं, तो इसके बजाय डेमो का उपयोग करें — नीचे config.example.yaml एक टेम्पलेट है और जैसा है वैसा नहीं चलेगा।
config.example.yaml की प्रतिलिपि बनाएं:
cp config.example.yaml config.yaml
फिर चलाने से पहले अपने स्वयं के डेटा को इंगित करने के लिए input_csv और artifact_root (और वैकल्पिक रूप से paper_root) संपादित करें।
मुख्य सेटिंग्स:
model / provider: सटीक OpenAI मॉडल पहचानकर्ता (या LiteLLM उपनाम), और प्रॉक्सी URL और क्रेडेंशियल पर्यावरण-चर नाम के साथ openai या litellm।analysis_mode: zero_shot या agentic।classification_task: binary या multiclass; analysis_mode से स्वतंत्र।max_agent_steps: केवल agentic कॉन्फ़िगरेशन में आवश्यक।max_workers / max_output_tokens / max_schema_retries: समवर्तीता, प्रति-प्रतिक्रिया आउटपुट सीमा, और स्कीमा-अमान्य प्रतिक्रियाओं के लिए मॉडल-कॉल पुनः प्रयास बजट।resume / resume_policy: incomplete विफलताओं, लापता आर्टिफैक्ट्स, और अप्रयासित निष्कर्षों को पुनः प्रयास करता है; failed_only केवल विफलताओं को पुनः प्रयास करता है जबकि दर्ज की गई सफलताओं को बनाए रखता है।cost: वैकल्पिक लाइव लागत लेखांकन और max_run_cost_usd समाप्ति।डिफ़ॉल्ट मॉडल gpt-5.6-sol है। यदि उपलब्धता, लागत, या विलंबता आवश्यकताएं भिन्न हैं तो इसे स्पष्ट रूप से बदलें।
safe-audit run --config config.yaml
या कंसोल कमांड स्थापित किए बिना:
PYTHONPATH=src python -m safe_audit.cli run --config config.yaml
शामिल सिंथेटिक डेटा के विरुद्ध एक चलाने योग्य मिलान तुलना के लिए, डेमो देखें (demo/demo-zero-shot.yaml और demo/demo-agentic.yaml)। वे केवल analysis_mode और run_name में भिन्न हैं। Zero-shot आधार साक्ष्य पर एक मॉडल कॉल करता है। Agentic मोड उसी साक्ष्य से शुरू होता है और समान संरचित परिणाम लौटाने से पहले सीमित केवल-पठन रिपॉजिटरी टूल्स को कॉल कर सकता है।
runs/<run_name>/
├── config.resolved.yaml
├── run_metadata.json
├── summary.json
├── results.jsonl
├── results.csv
├── profiles/
├── evidence/
├── raw/<finding_uid>/
│ ├── 0001-request.json
│ ├── 0001-response.json (या 0001-error.json)
│ └── final-output.txt
└── logs/
├── events.jsonl
├── result_attempts.jsonl
└── run_sessions.jsonl
results.csv विश्लेषण के लिए है। results.jsonl पूर्ण संरचित रिकॉर्ड संरक्षित करता है। साक्ष्य और कच्चे मॉडल आउटपुट ऑडिटिंग और त्रुटि विश्लेषण का समर्थन करते हैं। दोनों विहित हैं: उनमें प्रत्येक निष्कर्ष के लिए केवल नवीनतम रिकॉर्ड होता है, जबकि logs/result_attempts.jsonl केवल-जोड़ है और हर ऐतिहासिक परिणाम संरक्षित करता है।
फिर से शुरू करने पर, SAFE पहले प्रत्येक विफल निष्कर्ष के सहेजे गए कच्चे प्रतिक्रियाओं को वर्तमान सख्त पार्सर के साथ फिर से पार्स करता है; एक विशिष्ट रूप से मान्य वर्गीकरण बिना API कॉल के पुनर्प्राप्त किया जाता है। केवल अपरिवर्तनीय विफलताओं को मॉडल अनुमान के लिए निर्धारित किया जाता है। आंशिक रूप से पूर्ण रन की केवल-विफल निरंतरता के लिए, समान output_root और run_name रखें और सेट करें:
resume: true
resume_policy: failed_only
लेबल किए गए गोल्ड CSV (एक security_label या security_class कॉलम के साथ) के विरुद्ध भविष्यवाणियों का मूल्यांकन करने के लिए:
safe-audit evaluate --results runs/<run_name>/results.jsonl --gold GOLD.csv --output runs/<run_name>/evaluation.json
PYTHONPATH=src python -m unittest discover -s tests -v
परीक्षण सूट एक नकली प्रदाता का उपयोग करता है और इसलिए API कुंजी की आवश्यकता नहीं होती है।