GuardDog

GuardDog एक CLI उपकरण है जो दुर्भावनापूर्ण PyPI और npm पैकेजों, Go मॉड्यूल, Rust क्रेट्स, RubyGems, GitHub एक्शन, या VSCode एक्सटेंशन की पहचान करता है। यह पैकेज स्रोत कोड पर स्थिर विश्लेषण (YARA नियमों के माध्यम से) चलाता है और सप्लाई चेन हमलों का पता लगाने के लिए पैकेज मेटाडेटा का विश्लेषण करता है।

GuardDog को क्या अलग बनाता है: केवल संदिग्ध पैटर्न सूचीबद्ध करने के बजाय, GuardDog वास्तविक जोखिमों की पहचान करने के लिए निष्कर्षों को सहसंबंधित करता है, जो हमला श्रृंखलाओं पर आधारित होते हैं। एक पैकेज को उच्च जोखिम के रूप में फ़्लैग करने के लिए उसी फ़ाइल में किसी क्रिया को करने की क्षमता (जैसे, नेटवर्क एक्सेस) और एक खतरा संकेतक (जैसे, संदिग्ध डोमेन) दोनों की आवश्यकता होती है।

यह कोड डाउनलोड करके स्कैन करता है:

• NPM: npmjs.org पर होस्ट किए गए पैकेज
• PyPI: PyPI.org पर होस्ट की गई स्रोत फ़ाइलें (tar.gz) पैकेज
• Go: GitHub.com पर होस्ट किए गए रिपॉजिटरी के GoLang स्रोत फ़ाइलें
• Rust: crates.io पर होस्ट किए गए क्रेट्स
• RubyGems: rubygems.org पर होस्ट किए गए Gem पैकेज
• GitHub Actions: GitHub.com पर होस्ट किए गए रिपॉजिटरी के Javascript स्रोत फ़ाइलें
• VSCode Extensions: marketplace.visualstudio.com पर होस्ट किए गए एक्सटेंशन (.vsix) पैकेज

GuardDog कैसे काम करता है

GuardDog एक जोखिम-आधारित पहचान मॉडल का उपयोग करता है जो कोड क्षमताओं को खतरे वाले संकेतकों के साथ सहसंबंधित करता है:

1. पहचान: नियम या तो क्षमताओं (कोड क्या कर सकता है) या खतरों (संदिग्ध संकेतक) की पहचान करते हैं
2. सहसंबंध: एक ही फ़ाइल में पाई जाने वाली क्षमताएँ और खतरे जोखिम बनाते हैं (क्रॉस-फ़ाइल मिलान भी जोखिम बनाते हैं, जिनकी गंभीरता घटा दी जाती है)
3. स्कोरिंग: हमला श्रृंखला पूर्णता और परिष्कार के आधार पर जोखिमों को (0-10) स्कोर किया जाता है
4. रिपोर्टिंग: पैकेजों को विस्तृत जोखिम विवरण के साथ गंभीरता रेटिंग (low/medium/high) मिलती है

यह दृष्टिकोण क्यों?

पारंपरिक SAST उपकरण हर संदिग्ध पैटर्न को स्वतंत्र रूप से फ़्लैग करते हैं, जिससे अलर्ट थकान होती है। GuardDog समझता है कि:

• अकेले क्षमता दुर्भावनापूर्ण नहीं है (नेटवर्क लाइब्रेरीज़ को HTTP अनुरोध करने चाहिए)
• अकेले खतरे वाले संकेतक झूठी सकारात्मकता हो सकते हैं (परीक्षण फिक्स्चर, दस्तावेज़ीकरण)
• क्षमता + खतरा एक साथ वास्तविक जोखिम का संकेत देते हैं (ऐसा कोड जो कुछ दुर्भावनापूर्ण कर सकता है और करेगा)

जोखिम स्कोरिंग

पैकेजों को चार कारकों के आधार पर 0-10 का स्कोर मिलता है:

स्कोर लेबल:

• 0: कोई जोखिम नहीं मिला
• 0.1-3: कम जोखिम (एकल-चरण खतरे, कम विशिष्टता)
• 3.1-7.5: मध्यम जोखिम (आंशिक हमला श्रृंखला, मेटाडेटा संकेतक, या एकल-चरण कोड निष्कर्ष)
• 7.6-10: उच्च जोखिम (स्रोत कोड साक्ष्य के साथ बहु-चरण हमला श्रृंखला — समझौते की लगभग निश्चितता)

हमला श्रृंखला चरण (MITRE ATT&CK पर आधारित):

• प्रारंभिक: प्रारंभिक पहुंच, निष्पादन क्षमताएँ
• मध्य: दृढ़ता, रक्षा चोरी, क्रेडेंशियल एक्सेस
• अंतिम: कमांड और नियंत्रण, बहिर्गमन, प्रभाव

GuardDog के लिए नया Datadog Agent एकीकरण और Cloud SIEM कंटेंट पैक देखें।

आरंभ करना

स्थापना

GuardDog चलाने का सबसे आसान तरीका uvx का उपयोग करना है:

uvx guarddog pypi scan requests

इसे स्थानीय रूप से स्थापित करने के लिए:

uv tool install guarddog
# or
pip install guarddog

या Docker इमेज का उपयोग करें:

docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'

नोट: Windows पर, केवल समर्थित स्थापना विधि Docker है।

नमूना उपयोग

# Scan the most recent version of the 'requests' package
guarddog pypi scan requests

# Scan a specific version of the 'requests' package
guarddog pypi scan requests --version 2.28.1

# Scan the 'request' package using 2 specific heuristics
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# Scan the 'requests' package using all rules but one
guarddog pypi scan requests --exclude-rules exec-base64

# Scan a local package archive
guarddog pypi scan /tmp/triage.tar.gz

# Scan a local package directory
guarddog pypi scan /tmp/triage/

# Scan a package stored in S3 (a folder/prefix or a single archive object)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz

# Scan every package referenced in a requirements.txt file of a local folder
guarddog pypi verify workspace/guarddog/requirements.txt

# Scan every package referenced in a requirements.txt file and output a sarif file - works only for verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# Output JSON to standard output - works for every command
guarddog pypi scan requests --output-format=json

# All the commands also work on npm, go, crates, rubygems
guarddog npm scan express

guarddog go scan github.com/DataDog/dd-trace-go

guarddog go verify /tmp/repo/go.mod

# Scan Rust crates
guarddog crates scan serde

guarddog crates verify /tmp/repo/Cargo.lock

# Scan RubyGems packages
guarddog rubygems scan rails

guarddog rubygems verify /tmp/repo/Gemfile.lock

# Additionally can support scanning GitHub actions that are implemented in JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action

guarddog github_action verify /tmp/repo/.github/workflows/main.yml

# Scan VSCode extensions from the marketplace
guarddog extension scan ms-python.python

# Scan a specific version of a VSCode extension
guarddog extension scan ms-python.python --version 2023.20.0

# Scan a local VSCode extension directory or VSIX archive
guarddog extension scan /tmp/my-extension/

# Run in debug mode
guarddog --log-level debug npm scan express

सैंडबॉक्स्ड स्कैनिंग

पैकेज स्कैन करते समय, GuardDog स्रोत कोड विश्लेषण को कर्नेल-स्तरीय सैंडबॉक्स के अंदर चलाता है (Linux पर Landlock के माध्यम से, macOS पर Seatbelt के माध्यम से, nono का उपयोग करके)। सैंडबॉक्स सभी नेटवर्क एक्सेस को अवरुद्ध करता है और फ़ाइलसिस्टम संचालन को केवल विश्लेषण के लिए आवश्यक पथों तक सीमित करता है। यह दुर्भावनापूर्ण पैकेजों से सुरक्षा करता है जो आर्काइव निष्कर्षण या स्कैनिंग के दौरान कोड निष्पादित करने का प्रयास करते हैं।

डिफ़ॉल्ट रूप से, सैंडबॉक्स आवश्यक है: यदि यह प्लेटफ़ॉर्म पर उपलब्ध नहीं है, तो स्कैन असुरक्षित रूप से चलने के बजाय विफल हो जाता है। इसके बिना स्कैन करने के लिए, आपको स्पष्ट रूप से --no-sandbox पास करना होगा:

# Default: require the sandbox, exit with an error if it's unavailable
guarddog pypi scan requests

# Explicitly disable the sandbox
guarddog pypi scan requests --no-sandbox

रिमोट पैकेजों के लिए, तीन चरण विभिन्न विशेषाधिकार स्तरों के साथ चलते हैं:

1. डाउनलोड और मेटाडेटा विश्लेषण सैंडबॉक्स के बिना चलते हैं (नेटवर्क एक्सेस की आवश्यकता होती है)
2. आर्काइव निष्कर्षण सैंडबॉक्स किए गए सबप्रोसेस में चलता है (नेटवर्क अवरुद्ध, फ़ाइलसिस्टम प्रतिबंधित)
3. स्रोत कोड विश्लेषण (YARA) सैंडबॉक्स लागू होने के बाद मुख्य प्रक्रिया में चलता है (नेटवर्क अवरुद्ध, फ़ाइलसिस्टम निकाली गई फ़ाइलों तक प्रतिबंधित)

सैंडबॉक्स को आर्काइव निष्कर्षण के दौरान पथ ट्रैवर्सल और कोड निष्पादन कमजोरियों को कम करने के लिए पेश किया गया था (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871)।

S3 से पैकेज स्कैन करना

GuardDog S3 में संग्रहीत पैकेज को स्कैन कर सकता है, या तो फ़ोल्डर/उपसर्ग के रूप में या एकल आर्काइव ऑब्जेक्ट के रूप में:

guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz

यह आपके मौजूदा AWS क्रेडेंशियल्स (पर्यावरण चर, ~/.aws, SSO, या एक IAM भूमिका) का उपयोग करता है। GuardDog कुछ भी करने से पहले STS के माध्यम से प्रमाणीकरण सत्यापित करता है और यदि कोई मान्य क्रेडेंशियल नहीं मिलता है तो त्रुटि के साथ बाहर निकलता है। ऑब्जेक्ट्स को एक अस्थायी निर्देशिका में सिंक किया जाता है, किसी भी अन्य अविश्वसनीय सामग्री की तरह सैंडबॉक्स के तहत स्कैन किया जाता है, और बाद में डिस्क से हटा दिया जाता है।

नियम

GuardDog दो प्रकार के पहचान नियमों का उपयोग करता है, दोनों जोखिम-आधारित स्कोरिंग इंजन में भाग लेते हैं:

• स्रोत कोड नियम (YARA): पैकेज स्रोत कोड का स्थिर विश्लेषण जो क्षमताओं और खतरों का पता लगाता है
• मेटाडेटा नियम (Python डिटेक्टर): सप्लाई चेन हमले के संकेतकों का पता लगाने वाले पैकेज रजिस्ट्री मेटाडेटा का विश्लेषण

प्रत्येक इकोसिस्टम के लिए नियमों की पूरी सूची के लिए, RULES.md देखें।

नए नियम लिखने के मार्गदर्शन के लिए, WRITING_RULES.md देखें।

GitHub Action में GuardDog चलाना

GuardDog को अपनी CI पाइपलाइन में एकीकृत करने का सबसे आसान तरीका SARIF आउटपुट प्रारूप का लाभ उठाना है, और इसे GitHub की code scanning सुविधा पर अपलोड करना है।

इसका उपयोग करके, आपको मिलता है:

• GuardDog स्कैन आउटपुट के आधार पर आपके पुल अनुरोधों पर स्वचालित टिप्पणियाँ
• GitHub UI में सीधे अंतर्निहित झूठी सकारात्मकता प्रबंधन

GuardDog का उपयोग करने वाला नमूना GitHub Action:

name: GuardDog

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  guarddog:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
    name: Scan dependencies
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v7

      - run: uvx guarddog pypi verify requirements.txt --output-format sarif --exclude-rules repository_integrity_mismatch > guarddog.sarif

      - name: Upload SARIF file to GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          category: guarddog-builtin
          sarif_file: guarddog.sarif

विकास

GuardDog का स्थानीय संस्करण चलाना

• सुनिश्चित करें कि poetry के पास python >=3.10 वाला env है poetry env use 3.10.0
• निर्भरताएँ स्थापित करें poetry install
• guarddog चलाएँ poetry run guarddog या poetry shell चलाएँ फिर guarddog चलाएँ

यूनिट परीक्षण

सभी यूनिट परीक्षण चलाना: make test

पैकेज मेटाडेटा ह्यूरिस्टिक्स के विरुद्ध यूनिट परीक्षण चलाना: make test-metadata-rules (परीक्षण यहाँ हैं)।

बेंचमार्किंग

आप false positives और false negatives निर्धारित करने के लिए वैध और दुर्भावनापूर्ण पैकेजों पर GuardDog चला सकते हैं। ./tests/samples देखें

कोड गुणवत्ता जाँच

टाइप चेकर को इसके साथ चलाएँ

mypy --install-types --non-interactive guarddog

और लिंटर को इसके साथ चलाएँ

flake8 guarddog --count --select=E9,F63,F7,F82 --show-source --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data
flake8 guarddog --count --max-line-length=120 --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data --ignore=E203,W503

पर्यावरण चर के माध्यम से कॉन्फ़िगरेशन

GuardDog के व्यवहार को पर्यावरण चर का उपयोग करके अनुकूलित किया जा सकता है:

सामान्य कॉन्फ़िगरेशन

मेटाडेटा नियम कॉन्फ़िगरेशन

आर्काइव निष्कर्षण सुरक्षा सीमाएँ

GuardDog पैकेज आर्काइव निकालते समय कई सुरक्षा जाँच लागू करता है, ताकि कम्प्रेशन बम और फ़ाइल डिस्क्रिप्टर थकावट हमलों से सुरक्षा मिल सके:

अनुरक्षक

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

लेखक

• Ellen Wang
• Christophe Tafani-Dereeper

आभार

प्रेरणा:

• Backstabber’s Knife Collection: A Review of Open Source Software Supply Chain Attacks
• What are Weak Links in the npm Supply Chain?
• A Survey on Common Threats in npm and PyPi Registries
• A Benchmark Comparison of Python Malware Detection Approaches
• Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages