Vulnhalla

स्वचालित CodeQL विश्लेषण LLM वर्गीकरण के साथ

Vulnhalla के पीछे के शोध और प्रेरणा के विस्तृत अवलोकन के लिए, आधिकारिक CyberArk Threat Research ब्लॉग पोस्ट देखें:

Vulnhalla: CodeQL Haystack से सही भेद्यताओं का चयन

Vulnhalla संपूर्ण सुरक्षा विश्लेषण पाइपलाइन को स्वचालित करता है:

1. GitHub से किसी दी गई प्रोग्रामिंग भाषा के रिपॉज़िटरी प्राप्त करना
2. उनके संबंधित CodeQL डेटाबेस डाउनलोड करना (यदि उपलब्ध हों)
3. सुरक्षा या कोड-गुणवत्ता समस्याओं का पता लगाने के लिए उन डेटाबेस पर CodeQL क्वेरी चलाना
4. समस्याओं को वर्गीकृत और फ़िल्टर करने के लिए LLM (ChatGPT, Gemini, आदि) के साथ परिणामों का पोस्ट-प्रोसेसिंग

---

🚀 त्वरित आरंभ

चरण 1: पूर्वापेक्षाएँ

आरंभ करने से पहले, सुनिश्चित करें कि आपके पास है:

• Python 3.10 – 3.13 (Python 3.11 या 3.12 अनुशंसित)

  • Python 3.14+ समर्थित नहीं है (यह टूल grpcio का उपयोग करता है जो Python 3.14+ द्वारा समर्थित नहीं है)
  • python.org से डाउनलोड करें

• CodeQL CLI

  • CodeQL CLI releases से डाउनलोड करें
  • सुनिश्चित करें कि codeql आपके PATH में है, या आप .env में पथ सेट करेंगे (चरण 2 देखें)

• (वैकल्पिक) GitHub API टोकन

  • डेटाबेस डाउनलोड करते समय उच्च दर सीमा के लिए
  • GitHub Settings > Tokens से प्राप्त करें

• LLM API कुंजी

  • OpenAI, Azure, Gemini, या Bedrock क्रेडेंशियल (आपके प्रदाता पर निर्भर करता है)

चरण 2: पर्यावरण कॉन्फ़िगर करें

सभी कॉन्फ़िगरेशन एक ही फ़ाइल में है: .env

1. रिपॉज़िटरी क्लोन करें:

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. .env.example को .env में कॉपी करें:

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. .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), आवश्यक/वैकल्पिक वेरिएबल्स, और विस्तृत उदाहरणों के लिए नीचे कॉन्फ़िगरेशन संदर्भ देखें।

चरण 3: Poetry इंस्टॉल करें (अनुशंसित: pipx)

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

चरण 4: निर्भरताएँ इंस्टॉल करें और सेटअप करें

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

चरण 5: पाइपलाइन चलाएँ

# 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

यह स्वचालित रूप से:

1. CodeQL डेटाबेस प्राप्त करेगा
2. सभी डाउनलोड किए गए डेटाबेस पर CodeQL क्वेरी चलाएगा
3. LLM के साथ परिणामों का विश्लेषण करेगा और output/results/ में सहेजेगा
4. परिणाम ब्राउज़ करने के लिए UI खोलेगा

स्थानीय CodeQL डेटाबेस का उपयोग करना

यदि आपके पास पहले से डिस्क पर 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

---

🖥️ यूज़र इंटरफ़ेस (UI)

Vulnhalla में विश्लेषण परिणामों को ब्राउज़ करने और एक्सप्लोर करने के लिए एक पूर्ण-विशेषताओं वाला यूज़र इंटरफ़ेस शामिल है।

UI चलाना

poetry run vulnhalla-ui

UI लेआउट

UI नीचे एक नियंत्रण पट्टी के साथ दो-पैनल वाला शीर्ष क्षेत्र प्रदर्शित करता है:

शीर्ष क्षेत्र (साथ-साथ, आकार बदलने योग्य):

• बायाँ पैनल (समस्याओं की सूची):

  • DataTable दिखाता है: ID, Repo, Issue Name, File, LLM decision, Manual decision
  • समस्याओं की संख्या और सॉर्ट संकेतक
  • नीचे सर्च इनपुट बॉक्स, टाइप करते ही अपडेट होता है (केस-असंवेदनशील)।

• दायाँ पैनल (विवरण):

  • LLM decision अनुभाग: LLM का वर्गीकरण दिखाता है (True Positive, False Positive, या Needs More Data)
  • Metadata अनुभाग: Issue name, Repo, File, Line, Type, Function name
  • Code अनुभाग:
    • 📌 प्रारंभिक कोड संदर्भ (पहला कोड स्निपेट जो LLM ने देखा)
    • 📥 अतिरिक्त कोड (वह कोड जो LLM ने बातचीत के दौरान अनुरोध किया) - केवल तभी दिखाया जाता है यदि अतिरिक्त कोड मौजूद है
    • भेद्य पंक्ति लाल रंग में हाइलाइट की गई
  • Summary अनुभाग: LLM का अंतिम उत्तर/निर्णय
  • Manual Decision Select: मैन्युअल निर्णय सेट करने के लिए नीचे ड्रॉपडाउन (True Positive, False Positive, Uncertain, या Not Set)

नीचे नियंत्रण पट्टी:

• Language: C (एकमात्र भाषा वर्तमान में समर्थित)
• llm desicion ड्रॉपडाउन द्वारा फ़िल्टर करें: All, True Positive, False Positive, Needs more Info to decide
• क्रिया बटन: Refresh, Run Analysis
• की बाइंडिंग्स सहायता टेक्स्ट

की बाइंडिंग्स

• ↑/↓ - समस्या सूची में नेविगेट करें (पंक्ति-दर-पंक्ति)
• Tab / Shift+Tab - पैनलों के बीच फ़ोकस बदलें
• Enter - चयनित समस्या के लिए विवरण दिखाएं
• / - सर्च इनपुट बॉक्स पर फ़ोकस करें (बाएँ पैनल में)
• Esc - सर्च साफ़ करें और समस्याओं की तालिका पर फ़ोकस लौटाएं
• r - डिस्क से परिणाम पुनः लोड करें
• [ / ] - बाएँ/दाएँ पैनल का आकार बदलें (विभाजन स्थिति समायोजित करें)
• q - एप्लिकेशन से बाहर निकलें

इंटरैक्टिव विशेषताएँ

कॉलम सॉर्टिंग

• किसी भी कॉलम हेडर पर क्लिक करें उस कॉलम द्वारा सॉर्ट करने के लिए
• डिफ़ॉल्ट सॉर्टिंग: Repo (आरोही) द्वारा, फिर ID (आरोही) द्वारा

आकार बदलने योग्य पैनल