# datadog/guarddog architecture

> Architecture diagram of the GitHub repository datadog/guarddog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datadog/guarddog
- Repository: https://github.com/datadog/guarddog

## Overview

##### Project Overview and Purpose
- Recognize that GuardDog is a CLI-based security scanning tool. Its purpose is to detect malicious packages by running a variety of heuristics on both package metadata and source code.
- It targets multiple ecosystems (PyPI, npm, Go, GitHub Actions) and leverages Semgrep and Yara rules to identify potential threats.

##### Identifying the Main Components from the File Tree and README
- Command Line Interface (CLI) and Entry Point:
- Main entry in guarddog/__main__.py and cli.py.
- This component handles user commands, parsing arguments, and dispatching actions.
- Analyzers:
- Located under guarddog/analyzer, split into two primary areas:
▪ Source Code Heuristics (guarddog/analyzer/sourcecode) – uses Semgrep/Yara rules.
▪ Package Metadata Heuristics (guarddog/analyzer/metadata) – specific checks for PyPI, npm, Go, and GitHub Actions.
- Scanners:
- Under guarddog/scanners, which includes scanners tailored for each ecosystem (e.g., pypi_package_scanner.py, npm_package_scanner.py, etc.). These modules are responsible for obtaining the package data (either locally or remotely) and initiating scans.
- Reporters:
- For instance, guarddog/reporters/sarif.py generates output (SARIF, JSON, etc.).
- External Integrations and Interactions:
- Components that interact with external package registries (using HTTP calls, downloads) for fetching packages.
- Custom Rules integration found under guarddog/analyzer/sourcecode and configuration for importing additional Semgrep/Yara rules.
- Utilities & Configuration:
- Located in guarddog/utils (e.g., config, package_info, archives) managing common tasks.
- Testing, Documentation, and Deployment:
- Test directory structure (tests) along with scripts and Docker-related files that aid in CI/CD and containerized deployments.

##### Relationships and Data Flows
- The CLI is the user-facing interface. When a scan or verify command is issued:
- The CLI parses input and delegates to a corresponding scanner module.
- The Scanner module retrieves the package (locally or from a remote location) and passes the package data to the Analyzer.
- Depending on the package type, the Analyzer then uses specific heuristics (either under sourcecode or metadata) to analyze the package.
- After scanning:
- The Reporter component formats the analysis results (e.g., as JSON or SARIF).
- Optional external interactions:
- Downloading packages from external registries (PyPI, npm, GitHub, etc.) and integration with CI (as shown in the GitHub Action YAML snippet in the README).

##### Architectural Patterns and Design Principles
- Modular Design: Each component (CLI, scanners, analyzers, reporters) is distinctly separated, facilitating modularity and ease of extension (for example, adding new heuristics or supporting new ecosystems).
- Separation of Concerns: Different directories (analyzer vs. scanners vs. reporters) imply a clean separation where each is responsible for a specific aspect of the scanning process.
- Pipeline Flow: User command → Package Fetch → Analysis (branching into sourcecode/metadata heuristics) → Reporting output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level User Command
    U["User Command"]:::utility

    %% CLI Interface
    CLI["CLI Interface\n(Entry Point)"]:::cli

    %% External Package Registry
    PR["Package Registry"]:::external

    %% Scanners for Ecosystems
    SC["Scanners for Ecosystems\n(PyPI, npm, Go, GitHub Actions)"]:::scanner

    %% Analyzers Subgraph
    subgraph "Analyzers"
        A1["Source Code Heuristics\n(Semgrep/Yara Rules)"]:::analyzer
        A2["Package Metadata Heuristics\n(PyPI, npm, Go, GitHub Actions)"]:::analyzer
    end

    %% Reporters/Output Generators
    R["Reporters (SARIF/JSON)"]:::reporter

    %% Utilities & Configuration
    UTL["Utilities & Configuration"]:::utility

    %% Data Flow
    U -->|"initiates"| CLI
    CLI -->|"dispatches"| SC
    PR -->|"fetch package"| SC
    SC -->|"sends package data"| A1
    SC -->|"sends package data"| A2
    A1 -->|"formats results"| R
    A2 -->|"formats results"| R

    %% Dependencies on Utilities (dotted arrows)
    CLI -.->|"uses"| UTL
    SC -.->|"uses"| UTL
    A1 -.->|"uses"| UTL
    A2 -.->|"uses"| UTL
    R -.->|"uses"| UTL

    %% Click Events
    click CLI "https://github.com/datadog/guarddog/blob/main/guarddog/__main__.py"
    click CLI "https://github.com/datadog/guarddog/blob/main/guarddog/cli.py"
    click A1 "https://github.com/datadog/guarddog/tree/main/guarddog/analyzer/sourcecode"
    click A2 "https://github.com/datadog/guarddog/tree/main/guarddog/analyzer/metadata"
    click SC "https://github.com/datadog/guarddog/tree/main/guarddog/scanners"
    click R "https://github.com/datadog/guarddog/blob/main/guarddog/reporters/sarif.py"
    click UTL "https://github.com/datadog/guarddog/tree/main/guarddog/utils"

    %% Styles
    classDef cli fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef scanner fill:#ccf,stroke:#333,stroke-width:2px;
    classDef analyzer fill:#cfc,stroke:#333,stroke-width:2px;
    classDef reporter fill:#fcf,stroke:#333,stroke-width:2px;
    classDef utility fill:#eeeeee,stroke:#333,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#333,stroke-width:2px;
```
