GuardDog: A Risk-Based CLI Tool for Detecting Malicious Open-Source Packages
GuardDog is a command-line tool developed by Datadog that identifies malicious packages across multiple ecosystems, including PyPI, npm, Go modules, Rust crates, RubyGems, GitHub Actions, and VSCode extensions. Unlike traditional static analysis tools, GuardDog correlates findings to assess actual risks based on attack chains rather than flagging isolated suspicious patterns. This approach reduces alert fatigue by focusing on packages that exhibit both malicious capabilities and threat indicators within the same file or across files.
The tool operates by analyzing both source code and metadata, using Semgrep rules for static code analysis and custom heuristics for metadata evaluation. GuardDog assigns a risk score (0–10) to each package based on factors such as severity, attack chain completeness, specificity, and sophistication.
GuardDog’s heuristics were reverse-engineered from decompiled malicious packages to detect patterns such as command overwrites, Base64-encoded execution, steganography, and exfiltration of sensitive data (e.g., AWS credentials).
How GuardDog Works
- Detection: The tool applies two types of rules—source code rules (YARA-based Semgrep patterns) and metadata rules (Python detectors)—to identify capabilities (e.g., network access, file execution) and threats (e.g., suspicious domains, compromised maintainer emails). For example, a Semgrep rule might flag HTTP requests to domains with .xyz extensions, while a metadata rule could detect a package maintainer’s email domain being re-registered post-release, a sign of account compromise.
- Correlation: Findings are cross-referenced to determine if capabilities and threats coexist in the same file or across files. A package is only flagged as high risk if both conditions are met, such as code with network access capabilities making requests to a malicious domain. Cross-file matches are also considered but with downgraded severity.
- Scoring: Risks are scored (0–10) using a weighted formula: severity (30%), attack chain completeness (20%), specificity (30%), and sophistication (20%). For instance, a package with a multi-stage attack chain (e.g., initial access + exfiltration) and evidence of advanced techniques (e.g., steganography) would receive a higher score than one with isolated, low-specificity indicators.
- Reporting: Packages are categorized by severity (low, medium, high) with detailed breakdowns of detected risks. Output formats include JSON, SARIF (for GitHub Code Scanning integration), and console logs. The tool also supports sandboxed scanning to mitigate extraction-based vulnerabilities (e.g., CVE-2022-23530), blocking network access and restricting filesystem operations during analysis.
Scans are divided into three phases—metadata analysis (unsandboxed), archive extraction (sandboxed subprocess), and source code analysis (main process with restricted access)—to prevent malicious packages from executing code during extraction.
Use Cases
GuardDog is primarily used in ML pipeline and dependency scanning to preemptively identify malicious packages before installation. Its capabilities extend to multiple ecosystems, making it versatile for teams managing dependencies in Python, JavaScript, Go, Rust, Ruby, and GitHub Actions.
- Pre-installation scanning: Teams can scan individual packages (e.g., guarddog pypi scan requests) or entire dependency files (e.g., guarddog pypi verify requirements.txt) to detect risks before integrating them into projects. This is particularly critical for ML workflows where dependencies may introduce backdoors or data exfiltration risks.
- CI/CD integration: GuardDog supports SARIF output, allowing integration with GitHub Actions for automated pull request comments and false-positive management. For example, a workflow can scan dependencies on every push to main and upload SARIF results to GitHub’s code scanning feature, enabling real-time threat visibility.
- S3-based package scanning: GuardDog can analyze packages stored in Amazon S3, either as individual archives or folder prefixes. This is useful for organizations storing artifacts in cloud storage and needing to validate their security before deployment.
- GitHub Actions and VSCode extensions: GuardDog extends beyond traditional package managers to scan JavaScript-based GitHub Actions and VSCode extensions, addressing risks in developer tooling and CI pipelines.
The tool’s flexibility is further demonstrated by its support for version-specific scans (e.g., --version 2.28.1), rule exclusions (e.g., --exclude-rules exec-base64), and custom rule sets (e.g., --rules code-execution).
Key Features and Capabilities
GuardDog’s design prioritizes accuracy and actionability through its risk-based scoring and correlation engine.
- Multi-ecosystem support: GuardDog scans packages from PyPI, npm, Go modules, Rust crates, RubyGems, GitHub Actions, and VSCode extensions, covering the majority of open-source dependency sources used in modern software development.
- Semgrep and YARA integration: Source code analysis leverages Semgrep’s taint tracking to detect data flows (e.g., sensitive data exfiltration) and YARA rules for pattern matching. This combination enables detection of both known and novel attack techniques, such as steganography or obfuscated Base64 execution.
- Metadata heuristics: GuardDog evaluates package metadata for supply chain attack indicators, including typosquatting (e.g., packages named reuqests or PensorFlow), compromised maintainer emails, and missing package descriptions. These heuristics align with observed tactics in real-world attacks, such as the SolarWinds breach or CodeCov incidents.
- Attack chain correlation: Unlike traditional SAST tools that flag isolated findings, GuardDog correlates capabilities (e.g., network access) with threats (e.g., suspicious domains) to identify actionable risks. This reduces false positives by requiring evidence of both malicious intent and execution pathways.
- Sandboxed execution: All scans run in a restricted environment to prevent malicious packages from executing code during analysis. This mitigates risks like path traversal or arbitrary code execution during archive extraction, as demonstrated in vulnerabilities such as CVE-2022-23530.
- Risk scoring and prioritization: Packages receive a composite score (0–10) based on severity, attack chain completeness, specificity, and sophistication.
- SARIF and GitHub integration: GuardDog’s SARIF output format enables seamless integration with GitHub’s code scanning feature, providing automated pull request feedback and false-positive management.
- S3 and cloud compatibility: GuardDog supports scanning packages stored in Amazon S3, using existing AWS credentials for authentication.
- Custom rule development: Users can extend GuardDog’s detection capabilities by writing new Semgrep or metadata rules.
Recent updates to GuardDog (e.g., version 3.2.0) have expanded its capabilities, including support for Rust crates, improved npm provenance checks, and fixes for false positives in heuristics like Base64 obfuscation detection.
The project’s permissive Apache 2.0 license encourages adoption and customization by security teams and researchers.