GuardDog 项目使用教程

1. 项目的目录结构及介绍

GuardDog 是一个用于识别恶意 PyPI 和 npm 包或 Go 模块的 CLI 工具。以下是项目的目录结构及其介绍：

guarddog/
├── README.md
├── requirements.txt
├── guarddog/
│   ├── __init__.py
│   ├── cli.py
│   ├── heuristics/
│   │   ├── __init__.py
│   │   ├── pypi.py
│   │   ├── npm.py
│   │   └── go.py
│   ├── rules/
│   │   ├── __init__.py
│   │   ├── semgrep_rules.yaml
│   │   └── custom_rules.yaml
│   └── utils/
│       ├── __init__.py
│       ├── scanner.py
│       └── logger.py
├── tests/
│   ├── __init__.py
│   ├── test_cli.py
│   └── test_heuristics.py
└── setup.py

• README.md: 项目介绍和使用说明。
• requirements.txt: 项目依赖文件。
• guarddog/: 项目主目录。
  • __init__.py: 模块初始化文件。
  • cli.py: 命令行接口文件。
  • heuristics/: 启发式规则目录。
    • pypi.py, npm.py, go.py: 分别针对 PyPI、npm 和 Go 模块的启发式规则。
  • rules/: 规则目录。
    • semgrep_rules.yaml: Semgrep 规则文件。
    • custom_rules.yaml: 自定义规则文件。
  • utils/: 工具目录。
    • scanner.py: 扫描工具。
    • logger.py: 日志工具。
• tests/: 测试目录。
  • test_cli.py: 命令行接口测试。
  • test_heuristics.py: 启发式规则测试。
• setup.py: 安装脚本。

2. 项目的启动文件介绍

项目的启动文件是 guarddog/cli.py。这个文件定义了命令行接口，用户可以通过命令行调用 GuardDog 进行扫描操作。

# guarddog/cli.py
import click
from guarddog.heuristics import pypi, npm, go
from guarddog.utils import scanner, logger

@click.group()
def cli():
    pass

@cli.command()
@click.argument('package')
def scan(package):
    logger.info(f"Scanning package: {package}")
    result = scanner.scan(package)
    logger.info(f"Scan result: {result}")

if __name__ == '__main__':
    cli()

3. 项目的配置文件介绍

项目的配置文件主要有两个：requirements.txt 和 setup.py。

• requirements.txt: 列出了项目运行所需的依赖包。

click==8.0.0
semgrep==0.70.0

• setup.py: 用于安装项目的脚本，定义了项目的元数据和依赖。

from setuptools import setup, find_packages

setup(
    name='guarddog',
    version='1.0.0',
    packages=find_packages(),
    install_requires=[
        'click==8.0.0',
        'semgrep==0.70.0',
    ],
    entry_points={
        'console_scripts': [
            'guarddog=guarddog.cli:cli',
        ],
    },
)

通过这些配置文件，用户可以轻松地安装和管理 GuardDog 项目。