What are you scanning?
│
├── Third-party package/dependency?
│   ├── Before installing a new package → guarddog <ecosystem> scan <package-name>
│   ├── Existing requirements.txt/package.json → guarddog <ecosystem> verify <file>
│   └── Downloaded/untrusted code archive → guarddog <ecosystem> scan /path/to/archive
│
├── Your own Python code?
│   └── Use bandit instead: bandit -r ./project
│
├── Your own JavaScript/multi-language code?
│   └── Use graudit instead: graudit -d js ./project
│
└── Mix of own code + dependencies?
    ├── Step 1: guarddog verify dependencies
    └── Step 2: bandit/graudit for your code

# Install via pip (requires Python 3.10+)
pip install guarddog

# Or use Docker (isolated, no local install needed)
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm -v "$(pwd):/workspace" ghcr.io/datadog/guarddog'

# Verify installation
guarddog --version

# If pip install fails, ensure Python 3.10+
python --version

# If semgrep dependency issues occur
pip install --upgrade semgrep guarddog

# Check if guarddog is in PATH
which guarddog || echo "Add to PATH or use full path"

# Scan a local directory for malicious Python patterns
guarddog pypi scan /path/to/python/project/

# Scan a local .tar.gz package archive
guarddog pypi scan /path/to/package.tar.gz

# Output results as JSON for parsing
guarddog pypi scan /path/to/project --output-format=json

# Scan a local directory for malicious JavaScript/Node.js patterns
guarddog npm scan /path/to/nodejs/project/

# Scan a local npm package archive
guarddog npm scan /path/to/package.tgz

# Output results as JSON
guarddog npm scan /path/to/project --output-format=json

# Scan all packages in requirements.txt (fetches from PyPI)
guarddog pypi verify /path/to/requirements.txt

# Scan all packages in package-lock.json or package.json
guarddog npm verify /path/to/package-lock.json

# Output as SARIF (for CI/CD integration)
guarddog pypi verify requirements.txt --output-format=sarif > guarddog.sarif

# Check a PyPI package before installing
guarddog pypi scan requests

# Check specific version
guarddog pypi scan requests --version 2.28.1

# Check an npm package before installing
guarddog npm scan express

# Scan with specific rules only
guarddog pypi scan /path --rules exec-base64 --rules code-execution

# Scan with all rules except one
guarddog pypi scan /path --exclude-rules repository_integrity_mismatch

# For npm
guarddog npm scan /path --rules npm-exec-base64 --rules npm-serialize-environment

# Quick scan with JSON output for immediate triage
guarddog pypi scan ./suspicious-package --output-format=json 2>&1 | head -100

# Focus on critical malware rules only
guarddog pypi scan ./project --rules exec-base64 --rules exfiltrate-sensitive-data --rules code-execution --rules download-executable

# Step 1: Verify all dependencies (ALWAYS DO THIS FIRST)
guarddog pypi verify ./requirements.txt
guarddog npm verify ./package-lock.json

# Step 2: Scan local project code
guarddog pypi scan ./src/
guarddog npm scan ./src/

# Before pip install <package>
guarddog pypi scan <package-name>

# Check specific version
guarddog pypi scan <package-name> --version X.Y.Z

# Before npm install <package>
guarddog npm scan <package-name>

# Scan a Python project
guarddog pypi scan ./my-python-project/

# Scan a Node.js project
guarddog npm scan ./my-nodejs-project/

# Check Python dependencies
guarddog pypi verify ./requirements.txt

# Check Node.js dependencies
guarddog npm verify ./package-lock.json

# Get detailed JSON report for Python
guarddog pypi scan ./project --output-format=json > python-scan.json

# Get detailed JSON report for Node.js
guarddog npm scan ./project --output-format=json > npm-scan.json

guarddog --log-level debug pypi scan ./project

name: Security Scan
on: [push, pull_request]

jobs:
  guarddog-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install GuardDog
        run: pip install guarddog
      
      - name: Verify Python Dependencies
        run: guarddog pypi verify requirements.txt --output-format=sarif > guarddog-python.sarif
        continue-on-error: true
      
      - name: Verify npm Dependencies
        run: guarddog npm verify package-lock.json --output-format=sarif > guarddog-npm.sarif
        continue-on-error: true
      
      - name: Upload SARIF Results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: guarddog-python.sarif

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: guarddog-verify
        name: GuardDog Dependency Check
        entry: guarddog pypi verify requirements.txt
        language: system
        files: requirements\.txt$
        pass_filenames: false

Scanning ./malicious-package
Found 2 potentially malicious indicators:
  - exec-base64: Identified base64-encoded code execution in setup.py
  - exfiltrate-sensitive-data: Package reads SSH keys and sends to external URL

# 1. Check dependencies for malware (GuardDog)
guarddog pypi verify requirements.txt
guarddog npm verify package-lock.json

# 2. Scan Python code for vulnerabilities (Bandit)
bandit -r ./src -f json -o bandit-results.json

# 3. Check for hardcoded secrets (Graudit)
graudit -d secrets ./src

# 4. Audit shell scripts (ShellCheck)
find . -name "*.sh" -exec shellcheck {} \;

# Increase parallelism for faster scanning
export GUARDDOG_PARALLELISM=8

# Increase timeout for complex files
export GUARDDOG_SEMGREP_TIMEOUT=30

# Limit file size for faster scans
export GUARDDOG_SEMGREP_MAX_TARGET_BYTES=5000000