Previous

Next

GuardDog Rules Overview

GuardDog Scan & Ecosystem Overview - 1

GuardDog Scan & Ecosystem Overview - 2

Overview

GuardDog is a CLI tool that allows you to identify malicious PyPI and npm packages, Go modules, and GitHub actions. It runs a set of heuristics on the package source code (through Semgrep rules) and on the package metadata.

This integration monitors configured dependency files using GuardDog scans and sends the scan output to Datadog for analysis, providing visual insights through out-of-the-box dashboards and the Log Explorer. It also helps monitor and respond to security threats with ready-to-use Cloud SIEM detection rules.

Note:

• Minimum Agent version: 7.73.0

Setup

Installation

The GuardDog check is already included with the Datadog Agent package, so no extra installation is required. You must also install the GuardDog package (see Install GuardDog under Configuration).

Configuration

Install GuardDog

Note: - GuardDog requires Python version 3.10 or higher. - The Datadog Agent must have access to the GuardDog executable path.

1. Install GuardDog using pip:

   pip3 install guarddog
   

2. Run this command to find the GuardDog executable path:

   which guarddog
   

   This path is required for the guarddog_path parameter in the guarddog.d/conf.yaml file.

Log collection

1. Collecting logs is disabled by default in the Datadog Agent. Enable it in datadog.yaml:

   logs_enabled: true
   

2. Add this configuration block to your guarddog.d/conf.yaml file to start monitoring dependency files using GuardDog. See the sample guarddog.d/conf.yaml for available configuration options.

   logs:
     - type: integration
       service: guarddog
       source: guarddog
   
   init_config:
       ## @param guarddog_path - string - required
       ## Absolute path to the GuardDog file. Example: /usr/local/bin/guarddog
       #
       guarddog_path: <ABSOLUTE_PATH_OF_GUARDDOG>
   
   instances:
       ## @param package_ecosystem - string - required
       ## The type of package ecosystem. Supported values: pypi, npm, go and github_action
       #
     - package_ecosystem: <PACKAGE_ECOSYSTEM>
       ## @param dependency_file_path - string - required
       ## Absolute path to the dependency file you want to monitor. Example: /app/requirements.txt
       #
       dependency_file_path: <DEPENDENCY_FILE_PATH>
       ## @param min_collection_interval - number - required
       ## This changes the collection interval of the check. Default value is 86400 seconds(1 day). For more information, see:
       ## https://docs.datadoghq.com/developers/write_agent_check/#collection-interval
       #
       min_collection_interval: 86400
   

   Note:

   • We recommend you do not change the service and source values, as these parameters are integral to the pipeline’s operation.
   • To track more than one dependency file, add additional entries under instances:

     instances:
       - package_ecosystem: pypi
         dependency_file_path: /app/requirements.txt
         min_collection_interval: 86400
       - package_ecosystem: npm
         dependency_file_path: /app/package.json
         min_collection_interval: 86400
       - package_ecosystem: go
         dependency_file_path: /app/go.mod
         min_collection_interval: 86400
       - package_ecosystem: github_action
         dependency_file_path: /app/action.yml
         min_collection_interval: 86400
     

3. Ensure the dd-agent user has read access to all dependency files you configure and traverse permission on every parent directory in the file path.

4. Restart the Agent.

Validation

Run the Agent’s status subcommand and look for guarddog under the Checks section.

Data Collected

Logs

The GuardDog integration collects scan logs.

Metrics

The GuardDog integration does not include any metrics.

Events

The GuardDog integration does not include any events.

Troubleshooting

If you see a Permission denied error, run the following command to give the Datadog Agent permission for the GuardDog executable:

chmod o+rx /path/to/guarddog

If the issue persists, ensure that the parent directories in the path are accessible to the Datadog Agent. Run the following command to grant permissions to the parent directory:

chmod o+x /path/to/parent_directory

For any further assistance, contact Datadog support.