kirankotari/ossguard
GitHub: kirankotari/ossguard
一款基于 OpenSSF 安全最佳实践的 CLI 工具，能扫描、审计开源项目的安全配置缺失并自动修复，帮助项目快速达到供应链安全合规标准。
Stars: 2 | Forks: 0
OSSGuard
One CLI to guard any OSS project with OpenSSF security best practices
OSSGuard 可以扫描任何项目，并准确告诉你缺少了哪些 [OpenSSF](https://openssf.org/) 安全组件——然后将其修复。它支持 **Python、JavaScript、Go、Rust、Java、C/C++** 以及更多语言。
## 目录
- [快速开始](#quick-start)
- [安装](#installation)
- [命令](#commands)
- [核心](#core)
- [安全分析](#security-analysis)
- [依赖管理](#dependency-management)
- [合规与生成](#compliance--generation)
- [真实项目结果](#real-world-results)
- [用于 CI 的 JSON 输出](#json-output-for-ci)
- [GitHub Action](#github-action)
- [实现](#implementations)
- [文档](#documentation)
- [OSSGuard 如何与 OpenSSF 关联](#how-ossguard-relates-to-openssf)
- [贡献](#contributing)
- [许可证](#license)
## 快速开始
```
# 安装（选择其一）
pip install ossguard # Python 3.9+
brew install kirankotari/tap/ossguard # macOS / Linux
npx ossguard # Node.js (zero install)
# 扫描任意项目
ossguard scan .
# 全面安全审计
ossguard audit .
# Bootstrap 所有 OpenSSF 配置
ossguard init .
```
请参阅 [入门指南](docs/getting-started.md) 获取完整的操作演练。
## 安装
| 方法 | 命令 | 文档 |
|--------|---------|------|
| **pip** | `pip install ossguard` | [详情](docs/installation.md#pip) |
| **Homebrew** | `brew install kirankotari/tap/ossguard` | [详情](docs/installation.md#homebrew) |
| **npm / npx** | `npx ossguard` | [详情](docs/installation.md#npm--npx) |
| **Go** | `go install github.com/kirankotari/ossguard-go/cmd/ossguard@latest` | [详情](docs/installation.md#go) |
| **二进制文件** | 从 [releases](https://github.com/kirankotari/ossguard-go/releases) 下载 | [详情](docs/installation.md#binary-download) |
| **Docker** | `docker run ghcr.io/kirankotari/ossguard-go:0.1.3` | [详情](docs/installation.md#docker) |
有关完整的说明、Shell 补全和验证步骤，请参阅 [docs/installation.md](docs/installation.md)。
## 命令
OSSGuard 提供 **27 个命令**，分为四个类别。每个命令都接受项目路径作为位置参数，并支持 `--json` 以获取机器可读的输出。
### 核心
| 命令 | 描述 |
|---------|-------------|
| [`init`](docs/commands/core.md#init) | 初始化 SECURITY.md、Scorecard、Dependabot、CodeQL、SBOM、Sigstore 配置 |
| [`scan`](docs/commands/core.md#scan) | 只读安全态势检查 |
| [`audit`](docs/commands/core.md#audit) | 综合安全审计（配置 + 依赖项 + 可达性） |
| [`version`](docs/commands/core.md#version) | 显示版本 |
```
$ ossguard scan .
Project: requests
Language: python
✓ SECURITY.md
✗ Scorecard
✓ Dependabot
✓ CodeQL
✗ SBOM workflow
✗ Sigstore
```
```
$ ossguard audit .
Audit: transformers — Grade: C (1/6 config checks)
⚠ Missing Scorecard workflow
⚠ Missing Dependabot
⚠ Missing CodeQL
⚠ Missing SBOM workflow
⚠ Missing Sigstore
→ Run `ossguard init` to fix
```
### 安全分析
| 命令 | 描述 |
|---------|-------------|
| [`secrets`](docs/commands/security.md#secrets) | 扫描泄露的凭据（24 条检测规则） |
| [`baseline`](docs/commands/security.md#baseline) | OSPS 安全基线合规性（34 项控制，级别 1-3） |
| [`slsa`](docs/commands/security.md#slsa) | SLSA 构建级别评估（级别 1-4，12 项要求） |
| [`badge`](docs/commands/security.md#badge) | OpenSSF 最佳实践徽章就绪情况 |
| [`maturity`](docs/commands/security.md#maturity) | S2C2F 供应链成熟度（22 项实践，级别 1-4） |
| [`container`](docs/commands/security.md#container) | Dockerfile 安全 lint（12 条规则） |
| [`fuzz`](docs/commands/security.md#fuzz) | Fuzzing 就绪检查 + 入门测试工具生成 |
```
$ ossguard secrets .
Secrets scan: 123 files, 13 findings
src/requests/adapters.py:284 [medium] generic-secret
tests/certs/expired/ca/ca-private.key:1 [critical] private-key
tests/certs/valid/server/server.key:1 [critical] private-key
```
```
$ ossguard baseline .
Baseline Level 1 — L1: 100%, L2: 62%, L3: 0%
```
### 依赖管理
| 命令 | 描述 |
|---------|-------------|
| [`deps`](docs/commands/dependencies.md#deps) | 依赖项健康状况 — 漏洞（OSV），风险评分（deps.dev） |
| [`drift`](docs/commands/dependencies.md#drift) | 版本间的 SBOM 差异比对 |
| [`watch`](docs/commands/dependencies.md#watch) | 持续漏洞监控 |
| [`reach`](docs/commands/dependencies.md#reach) | 基于可达性过滤的漏洞分析 |
| [`update`](docs/commands/dependencies.md#update) | 基于安全优先级的依赖更新 |
| [`license`](docs/commands/dependencies.md#license) | 许可证合规性与冲突检测 |
| [`supply-chain`](docs/commands/dependencies.md#supply-chain) | 恶意软件包 + 误植域名检测 |
| [`tpn`](docs/commands/dependencies.md#tpn) | 第三方声明生成 |
### 合规与生成
| 命令 | 描述 |
|---------|-------------|
| [`policy`](docs/commands/compliance.md#policy) | 组织级安全策略执行 |
| [`ci`](docs/commands/compliance.md#ci) | 生成统一的 CI 安全流水线 |
| [`report`](docs/commands/compliance.md#report) | 导出 HTML 或 JSON 合规报告 |
| [`insights`](docs/commands/compliance.md#insights) | 生成或验证 SECURITY-INSIGHTS.yml |
| [`pin`](docs/commands/compliance.md#pin) | 将 GitHub Actions 固定到 commit SHA |
| [`fix`](docs/commands/compliance.md#fix) | 自动修复常见的安全问题 |
| [`sbom-gen`](docs/commands/compliance.md#sbom-gen) | 生成 SPDX 2.3 或 CycloneDX 1.5 SBOM |
| [`compare`](docs/commands/compliance.md#compare) | 比较两个项目的安全态势 |
有关每个命令的详细用法、标志和输出示例，请参阅 [docs/commands/](docs/commands/)。
## 真实项目结果
来自热门开源项目的扫描结果（2025 年 5 月）：
| 项目 | 评级 | 配置 | 基线 | 徽章 | 凭据 |
|---------|-------|--------|----------|-------|---------|
| [psf/requests](https://github.com/psf/requests) | **B** | 3/6 | 级别 1 | 银级 (80%) | 13 项发现 |
| [huggingface/transformers](https://github.com/huggingface/transformers) | **C** | 1/6 | 级别 0 | 进行中 (70%) | 1 项发现 |
| [scikit-learn/scikit-learn](https://github.com/scikit-learn/scikit-learn) | **B** | 3/6 | 级别 0 | 进行中 (70%) | — |
| [langchain-ai/langchain](https://github.com/langchain-ai/langchain) | **C** | 1/6 | 级别 0 | — | 23 项发现 |
| [fastapi/fastapi](https://github.com/fastapi/fastapi) | **B** | 2/6 | 级别 0 | — | 400+ 项发现 |
## 用于 CI 的 JSON 输出
每个命令都支持 `--json`，用于 CI/自动化流水线：
```
$ ossguard scan --json .
{
"repo_name": "requests",
"primary_language": "python",
"package_managers": ["pip"],
"has_github_actions": true,
"has_security_md": true,
"has_scorecard": false,
"has_dependabot": true,
"has_codeql": true,
"has_sbom_workflow": false,
"has_sigstore": false
}
```
有关 GitHub Actions、GitLab CI 和质量门禁的示例，请参阅 [docs/ci-integration.md](docs/ci-integration.md)。
## GitHub Action
OSSGuard 还可以作为 **GitHub Action** 使用，它会自动审查每个 Pull Request 的 OpenSSF 合规性，并直接在 PR 上发布结果。
将 `.github/workflows/ossguard.yml` 添加到任何代码库中：
```
name: OSSGuard
on:
pull_request:
branches: [main]
permissions:
contents: read
pull-requests: write
statuses: write
jobs:
security-review:
name: Security Review
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: kirankotari/ossguard-app@v1.0.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
### 你将在 PR 上看到的内容
OSSGuard 会发表一条包含安全审查表的评论，并设置 commit 状态检查：
状态检查会显示：
- **绿色**（成功）— 所有检查通过
- **黄色**（中性）— 发现警告，但不阻塞
- **红色**（失败）— 关键问题（例如，凭据泄露）
有关配置选项和全部 8 个分析器的完整列表，请参阅 [ossguard-app](https://github.com/kirankotari/ossguard-app)。
## 实现
OSSGuard 提供了三种语言实现，它们的命令集完全相同：
| | Python | Go | Node.js |
|---|---|---|---|
| **源码** | [ossguard-python](https://github.com/kirankotari/ossguard-python) | [ossguard-go](https://github.com/kirankotari/ossguard-go) | [ossguard-npm](https://github.com/kirankotari/ossguard-npm) |
| **安装** | `pip install ossguard` | `brew install kirankotari/tap/ossguard` | `npx ossguard` |
| **大小** | ~104 KB (wheel) | ~8.6 MB (静态二进制文件) | ~128 KB (tarball) |
| **UI** | 富文本表格，彩色面板 | 纯文本，对 CI 友好 | 纯文本 |
| **最适用于** | 开发者工作站 | CI 流水线，自动化 | Node.js 项目 |
| **命令数** | 27 | 27 | 27 |
有关详细比较，请参阅 [docs/implementations.md](docs/implementations.md)。
## 文档
| 文档 | 描述 |
|----------|-------------|
| [入门指南](docs/getting-started.md) | 首次设置与操作演练 |
| [安装](docs/installation.md) | 所有安装方法及验证步骤 |
| [命令参考](docs/commands/) | 所有 27 个命令的详细文档 |
| [架构](docs/architecture.md) | OSSGuard 的内部工作原理 |
| [CI 集成](docs/ci-integration.md) | GitHub Actions、GitLab CI 示例 |
| [实现](docs/implementations.md) | Python vs Go vs Node.js 比较 |
| [发布](docs/releasing.md) | 协同发布流程 |
| [常见问题](docs/faq.md) | 常见问题解答 |
## OSSGuard 如何与 OpenSSF 关联
OSSGuard 让采用 [OpenSSF](https://openssf.org/) 工作组构建的工具变得极其容易：
| OpenSSF 倡议 | OSSGuard 命令 |
|--------------------|------------------|
| [Scorecard](https://scorecard.dev/) | `scan`、`audit` |
| [SLSA](https://slsa.dev/) | `slsa` |
| [Sigstore](https://sigstore.dev/) | `init` (sigstore 工作流) |
| [SBOM Everywhere](https://github.com/ossf/sbom-everywhere) | `sbom-gen`、`drift` |
| [最佳实践徽章](https://www.bestpractices.dev/) | `badge` |
| [OSPS 基线](https://baseline.openssf.org/) | `baseline` |
| [S2C2F](https://github.com/ossf/s2c2f) | `maturity` |
| [CVD 指南](https://github.com/ossf/oss-vulnerability-guide) | `init` (SECURITY.md) |
| [SCM 最佳实践](https://best.openssf.org/SCM-BestPractices/) | `pin`、`init` (分支保护) |
## 许可证
Apache-2.0 — 详见 [LICENSE](LICENSE)。
标签：C/C++, CMS安全, DevSecOps, GitHub Action, Go, JavaScript, MITM代理, OpenSSF, Python, Ruby工具, Rust, SAST, 上游代理, 事务性I/O, 依赖管理, 安全合规, 安全基线, 安全防护, 教学环境, 无后门, 日志审计, 模块化设计, 盲注攻击, 网络代理, 网络流量审计, 自动化修复, 请求拦截, 逆向工具, 静态应用安全测试