
स्वचालित सुरक्षा विश्लेषण पाइपलाइन जो GitHub रिपॉजिटरी पर CodeQL क्वेरी चलाती है और सही भेद्यता को झूठी सकारात्मकता से वर्गीकृत और फ़िल्टर करने के लिए LLM का उपयोग करती है।
Vulnhalla के पीछे के शोध और प्रेरणा के विस्तृत अवलोकन के लिए, आधिकारिक CyberArk Threat Research ब्लॉग पोस्ट देखें:
Vulnhalla: CodeQL Haystack से सही भेद्यताओं का चयन
आरंभ करने से पहले, सुनिश्चित करें कि आपके पास है:
Python 3.10 – 3.13 (Python 3.11 या 3.12 अनुशंसित)
CodeQL CLI
codeql आपके PATH में है, या आप .env में पथ सेट करेंगे (चरण 2 देखें)(वैकल्पिक) GitHub API टोकन
LLM API कुंजी
सभी कॉन्फ़िगरेशन एक ही फ़ाइल में है: .env
git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla
.env.example को .env में कॉपी करें:cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)
.env को संपादित करें और अपने मान भरें:OpenAI के लिए उदाहरण:
CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2
# Optional: Logging Configuration
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
LOG_FILE= # Optional: path to log file (e.g., logs/vulnhalla.log)
LOG_FORMAT=default # default or json
# LOG_VERBOSE_CONSOLE=false # If true, WARNING/ERROR use full format (timestamp - logger - level - message)
📖 पूर्ण कॉन्फ़िगरेशन संदर्भ के लिए: सभी समर्थित प्रदाताओं (OpenAI, Azure, Gemini, Bedrock), आवश्यक/वैकल्पिक वेरिएबल्स, और विस्तृत उदाहरणों के लिए नीचे कॉन्फ़िगरेशन संदर्भ देखें।
Windows (PowerShell):
# List available Python versions
py -0p
# Pick any supported Python: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Close and reopen terminal (required)
pipx install poetry
poetry --version
macOS / Linux:
# Check your Python version
python3 --version
# Use any supported Python: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Restart terminal (required)
pipx install poetry
poetry --version
Windows (PowerShell):
# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12 # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup
macOS / Linux:
# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12 # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup
# Analyze a specific repository, for example:
poetry run vulnhalla redis/redis
# Re-download even if database already exists
poetry run vulnhalla redis/redis --force
# Show help
poetry run vulnhalla --help
यह स्वचालित रूप से:
output/results/ में सहेजेगायदि आपके पास पहले से डिस्क पर CodeQL डेटाबेस है (जैसे, मैन्युअल रूप से या पिछले रन से बनाया गया), तो आप --local / -l फ़्लैग का उपयोग करके GitHub फ़ेच चरण को छोड़ सकते हैं:
Windows (PowerShell):
poetry run vulnhalla --local C:\path\to\my-codeql-db
macOS / Linux:
poetry run vulnhalla --local /path/to/my-codeql-db
नोट:
--localफ़्लैग एक CodeQL डेटाबेस निर्देशिका की अपेक्षा करता है, स्रोत कोड फ़ोल्डर की नहीं। आप यह जांच कर सत्यापित कर सकते हैं कि फ़ोल्डर मेंcodeql-database.ymlफ़ाइल है।
# Open UI to view existing results (without running analysis)
poetry run vulnhalla-ui
# Validate configuration: CodeQL, LLM, Logging (without running analysis)
poetry run vulnhalla-validate
# List analyzed repositories and their issue counts
poetry run vulnhalla-list
# Run example pipeline (analyzes videolan/vlc and redis/redis)
poetry run vulnhalla-example
Vulnhalla में विश्लेषण परिणामों को ब्राउज़ करने और एक्सप्लोर करने के लिए एक पूर्ण-विशेषताओं वाला यूज़र इंटरफ़ेस शामिल है।
poetry run vulnhalla-ui
UI नीचे एक नियंत्रण पट्टी के साथ दो-पैनल वाला शीर्ष क्षेत्र प्रदर्शित करता है:
शीर्ष क्षेत्र (साथ-साथ, आकार बदलने योग्य):
बायाँ पैनल (समस्याओं की सूची):
दायाँ पैनल (विवरण):
नीचे नियंत्रण पट्टी:
↑/↓ - समस्या सूची में नेविगेट करें (पंक्ति-दर-पंक्ति)Tab / Shift+Tab - पैनलों के बीच फ़ोकस बदलेंEnter - चयनित समस्या के लिए विवरण दिखाएं/ - सर्च इनपुट बॉक्स पर फ़ोकस करें (बाएँ पैनल में)Esc - सर्च साफ़ करें और समस्याओं की तालिका पर फ़ोकस लौटाएंr - डिस्क से परिणाम पुनः लोड करें[ / ] - बाएँ/दाएँ पैनल का आकार बदलें (विभाजन स्थिति समायोजित करें)q - एप्लिकेशन से बाहर निकलें[ का उपयोग करें, दाईं ओर ले जाने के लिए ] का उपयोग करेंपाइपलाइन चलाने के बाद, परिणाम output/results/<LANG>/<ISSUE_TYPE>/ में व्यवस्थित होते हैं:
output/results/c/Copy_function_using_source_size/
├── 1_raw.json # Original CodeQL issue data
├── 1_final.json # LLM conversation and classification
├── 2_raw.json
├── 2_final.json
└── ...
प्रत्येक *_final.json में शामिल है:
प्रत्येक *_raw.json में शामिल है:
output/databases/<LANG>/<ORG>/<REPO>)CodeQL CLI नहीं मिला:
अपनी .env फ़ाइल में CODEQL_PATH को अपने CodeQL एक्ज़ीक्यूटेबल के पूर्ण पथ पर सेट करें।
Windows पर: पथ .cmd के साथ समाप्त होना चाहिए (जैसे, C:\path\to\codeql\codeql.cmd)।
GitHub दर सीमाएँ:
अपनी .env फ़ाइल में GITHUB_TOKEN सेट करें (टोकन https://github.com/settings/tokens से प्राप्त करें)।
LLM समस्याएँ:
जांचें कि .env फ़ाइल में आपकी API कुंजियाँ आपके चयनित प्रदाता से मेल खाती हैं।
UI में आयात त्रुटियाँ:
सुनिश्चित करें कि आप प्रोजेक्ट रूट निर्देशिका से चला रहे हैं, या python examples/ui_example.py का उपयोग करें जो पथ सेटअप को संभालता है।
सभी कॉन्फ़िगरेशन आपकी .env फ़ाइल में पर्यावरण वेरिएबल्स के माध्यम से प्रबंधित होते हैं। यहां एक पूर्ण संदर्भ है:
| Variable | किसके लिए आवश्यक | विवरण |
|---|---|---|
CODEQL_PATH | सभी | CodeQL एक्ज़ीक्यूटेबल का पथ। यदि CodeQL PATH में है तो डिफ़ॉल्ट codeql है। यदि PATH में नहीं है तो पूर्ण पथ का उपयोग करें (जैसे, Windows पर C:\path\to\codeql\codeql.cmd) |
PROVIDER | सभी | LLM प्रदाता: openai, azure, gemini, bedrock, anthropic, mistral, groq, openrouter, ollama, आदि। |
MODEL | सभी | मॉडल नाम (जैसे, gpt-4o, gpt-4-turbo, gemini-2.5-flash) |
OpenAI:
| Variable | विवरण |
|---|---|
OPENAI_API_KEY | platform.openai.com से आपकी OpenAI API कुंजी |
Azure OpenAI:
| Variable | विवरण |
|---|---|
AZURE_OPENAI_API_KEY या AZURE_API_KEY | आपकी Azure OpenAI API कुंजी |
AZURE_OPENAI_ENDPOINT या AZURE_API_BASE | आपका Azure OpenAI एंडपॉइंट URL (जैसे, https://your-resource.openai.azure.com) |
AZURE_OPENAI_API_VERSION या AZURE_API_VERSION | API संस्करण (डिफ़ॉल्ट: 2024-08-01-preview) |
Gemini (Google):
| Variable | विवरण |
|---|---|
GOOGLE_API_KEY | Google AI Studio से आपकी Google API कुंजी |
AWS Bedrock:
| Variable | आवश्यक | विवरण |
|---|---|---|
AWS_REGION_NAME | हाँ | AWS क्षेत्र (जैसे, us-east-1, us-west-2) |
AWS_PROFILE | नहीं* | SSO/क्रेडेंशियल फ़ाइल प्रमाणीकरण के लिए AWS प्रोफ़ाइल नाम |
AWS_ACCESS_KEY_ID | नहीं* | AWS एक्सेस कुंजी (यदि प्रोफ़ाइल उपयोग नहीं कर रहे हैं) |
AWS_SECRET_ACCESS_KEY | नहीं* | AWS गुप्त कुंजी (यदि प्रोफ़ाइल उपयोग नहीं कर रहे हैं) |
AWS_SESSION_TOKEN | नहीं | अस्थायी STS क्रेडेंशियल के लिए सत्र टोकन |
* प्रमाणीकरण: AWS_PROFILE या AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ STS के लिए वैकल्पिक AWS_SESSION_TOKEN) का उपयोग करें।
Bedrock .env उदाहरण (SSO):
PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=your-profile
⚠️ पूर्वापेक्षाएँ:
- AWS क्रेडेंशियल Bedrock मॉडल को कॉल करने की अनुमति के साथ कॉन्फ़िगर होने चाहिए (SSO, IAM प्रोफ़ाइल, या एक्सेस कुंजियाँ)
- SSO उपयोगकर्ताओं के लिए: Vulnhalla का उपयोग करने से पहले
aws sso login --profile your-profileचलाएं🔧 महत्वपूर्ण - मॉडल चयन: Bedrock मॉडल चुनते समय, सुनिश्चित करें कि यह टूल कॉलिंग/फ़ंक्शन कॉलिंग का समर्थन करता है (सभी Bedrock मॉडल नहीं करते)। टूल कॉलिंग Vulnhalla के विश्लेषण प्रवाह का एक प्रमुख हिस्सा है, इसलिए संगत मॉडल चुनने से कार्यक्षमता और परिणामों में बड़ा अंतर आता है। संगत मॉडल में शामिल हैं: Claude 3.x, Mistral, या Cohere Command R।
| Variable | डिफ़ॉल्ट | विवरण |
|---|---|---|
GITHUB_TOKEN | - | उच्च दर सीमा के लिए GitHub API टोकन। GitHub Settings > Tokens से प्राप्त करें |
GITHUB_API_URL | https://api.github.com | GitHub API URL। GitHub Enterprise के लिए, अपने सर्वर का API URL सेट करें (जैसे, https://github.your-company.com/api/v3) |
GITHUB_SSL_VERIFY | true | SSL प्रमाणपत्र सत्यापन। स्व-हस्ताक्षरित या आंतरिक CA प्रमाणपत्रों वाले GitHub Enterprise के लिए false सेट करें |
LLM_TEMPERATURE | 0.2 | LLM temperature (0.0-2.0)। कम = अधिक निर्धारणात्मक। अनुशंसित: 0.2 पर रखें |
LLM_TOP_P | 0.2 | LLM top-p सैंपलिंग (0.0-1.0)। कम = अधिक केंद्रित। अनुशंसित: 0.2 पर रखें |
LOG_LEVEL | INFO | लॉगिंग स्तर: DEBUG, INFO, WARNING, या ERROR। कंसोल आउटपुट की विस्तारता को नियंत्रित करता है |
LOG_FILE | - | लॉग फ़ाइल का वैकल्पिक पथ (जैसे, logs/vulnhalla.log)। यदि सेट है, तो लॉग कंसोल और फ़ाइल दोनों में लिखे जाते हैं। फ़ाइल लॉगिंग विस्तृत आउटपुट के लिए DEBUG स्तर का उपयोग करती है |
LOG_FORMAT | default | लॉग प्रारूप शैली: default (मानव-पठनीय), या json (संरचित JSON प्रारूप) |
LOG_VERBOSE_CONSOLE | false | यदि true, WARNING/ERROR/CRITICAL पूर्ण प्रारूप का उपयोग करते हैं (timestamp - logger - level - message)। डिफ़ॉल्ट: WARNING/ERROR सरल प्रारूप का उपयोग करते हैं (LEVEL - message), INFO हमेशा न्यूनतम (केवल message) |
THIRD_PARTY_LOG_LEVEL | ERROR | तृतीय-पक्ष लाइब्रेरीज़ (LiteLLM, urllib3, requests) के लिए लॉग स्तर। विकल्प: DEBUG, , , । डिफ़ॉल्ट अधिकांश तृतीय-पक्ष शोर दबाता है |
⚠️ महत्वपूर्ण: जब तक आप प्रभाव को पूरी तरह से नहीं समझते,
LLM_TEMPERATUREयाLLM_TOP_Pन बढ़ाएं। कम मान मॉडल को स्थिर और निर्धारणात्मक रखते हैं, जो सुरक्षा विश्लेषण के लिए महत्वपूर्ण है। उच्च मान मॉडल को असंगत, रचनात्मक, या मतिभ्रम करने वाला बना सकते हैं।
📝 नोट: अतिरिक्त कॉन्फ़िगरेशन उदाहरणों के लिए, प्रोजेक्ट रूट में
.env.exampleफ़ाइल देखें।
Vulnhalla स्टार्टअप पर आपके कॉन्फ़िगरेशन को सत्यापित करता है। यदि आवश्यक वेरिएबल्स गायब या अमान्य हैं, तो आपको स्पष्ट त्रुटि संदेश दिखाई देंगे जो बताएंगे कि क्या ठीक करने की आवश्यकता है।
सामान्य सत्यापन त्रुटियाँ:
PROVIDER देखें)CODEQL_PATH सेट है लेकिन फ़ाइल मौजूद नहीं है)LLM निम्नलिखित स्थिति कोड का उपयोग करता है:
UI इन्हें मैप करता है:
1337 → "True Positive"1007 → "False Positive"7331 या 3713 → "Needs More Data"प्रोजेक्ट में pytest का उपयोग करके बुनियादी परीक्षण अवसंरचना शामिल है:
# Run all tests
poetry run pytest
# Run with verbose output
poetry run pytest -v
परीक्षण सूट में स्मोक टेस्ट शामिल हैं जो यह सत्यापित करते हैं कि परीक्षण अवसंरचना सही ढंग से सेट अप है।
प्रोजेक्ट स्थिर प्रकार जाँच के लिए mypy का उपयोग करता है:
poetry run mypy src
प्रकार जाँच pyproject.toml में [tool.mypy] के अंतर्गत कॉन्फ़िगर की गई है।
कॉन्फ़िगरेशन क्रमिक अपनाने की अनुमति देने के लिए प्रति-मॉड्यूल ओवरराइड के साथ एक रूढ़िवादी आधार रेखा का उपयोग करता है।
निर्भरताएँ pyproject.toml में Poetry के माध्यम से प्रबंधित की जाती हैं:
requests - GitHub API के लिए HTTP अनुरोधpySmartDL - CodeQL डेटाबेस के लिए स्मार्ट डाउनलोड प्रबंधकlitellm - कई प्रदाताओं का समर्थन करने वाला एकीकृत LLM इंटरफ़ेसpython-dotenv - पर्यावरण वेरिएबल प्रबंधनPyYAML - CodeQL पैक फ़ाइलों के लिए YAML पार्सिंगtextual - टर्मिनल UI फ्रेमवर्कpytest - परीक्षण फ्रेमवर्क (डेव निर्भरता)mypy - स्थिर प्रकार जाँचकर्ता (डेव निर्भरता)CodeQL क्वेरी data/queries/<LANG>/ में व्यवस्थित हैं:
issues/ - सुरक्षा समस्या का पता लगाने वाली क्वेरीtools/ - सहायक क्वेरी (फ़ंक्शन ट्री, क्लासेस, ग्लोबल वेरिएबल्स, मैक्रोज़)प्रत्येक निर्देशिका में CodeQL पैक को परिभाषित करने वाली qlpack.yml फ़ाइल होती है।
कॉपीराइट (c) 2025 CyberArk Software Ltd. सर्वाधिकार सुरक्षित।
यह रिपॉज़िटरी Apache License, Version 2.0 के अंतर्गत लाइसेंस प्राप्त है - अधिक विवरण के लिए LICENSE.txt देखें।
हम इस रिपॉज़िटरी में सभी प्रकार के योगदानों का स्वागत करते हैं। आरंभ करने के निर्देशों और हमारे विकास कार्यप्रवाहों के विवरण के लिए, कृपया हमारा contributing guide देखें।
कृपया हमारी Code of Conduct पढ़ें और उसका पालन करें। हम सभी योगदानकर्ताओं के लिए एक स्वागत योग्य और समावेशी वातावरण प्रदान करने के लिए प्रतिबद्ध हैं।
यदि आपके पास कोई फ़ीचर अनुरोध या प्रोजेक्ट समस्याएँ हैं तो बेझिझक GitHub issues के माध्यम से हमसे संपर्क करें।
INFOWARNINGERROR