TGPSKI/skeptic
GitHub: TGPSKI/skeptic
skeptic 是一个本地仓库信任审计器，专注于检测能导致级联供应链妥协的结构性信任边界漏洞。
Stars: 1 | Forks: 0
# 怀疑者
[](https://pkg.go.dev/github.com/TGPSKI/skeptic/cmd/skeptic)
[](https://go.dev/)
[](LICENSE)
一个本地仓库信任审计器。
`skeptic` 检测能够引发级联供应链妥协的结构性信任边界漏洞。它针对的是攻击**条件**，而非仅仅是攻击产物——这类弱点是 CVE 扫描器、SAST 工具和密钥扫描器无法覆盖的。
**仅使用标准库**的 Go 语言，单一二进制文件，229 条内置规则（外加规则包摄入），零运行时依赖，并实现与恶意内容的代理隔离。
[功能定位](#what-skeptic-is) | [局限性说明](#what-skeptic-is-not) | [设计](#design) | [检测引擎](#detection-engine) | [规则摄入与规则包](#rule-ingestion-and-rule-packs) | [语料库](#corpus) | [GitHub Action](#github-action) | [运行时](#runtimes)
## 快速开始
```
sudo make install # build + install
skeptic init # bootstrap config
skeptic scan # scan
skeptic mcp # start the MCP server
skeptic serve # start the daemon
skeptic ingest # ingest threat intelligence
skeptic corpus # manage the encrypted threat artifact corpus
```
## `skeptic` 的功能定位
`skeptic` 扫描文件系统，以发现现有工具覆盖间隙中的攻击向量：
- **CI/CD 信任边界违规** — 可变的 Action 引用、不安全的 `pull_request_target` 模式、过度授权的自动化身份、未锁定的安装以及 CI 密钥卫生缺陷。
- **代理生态系统投毒** — 恶意的 `SKILL.md` 指令、MCP 工具遮蔽、记忆持久化注入以及工具输出指令注入。
- **“无人审查”的攻击面** — 锁文件注入、IDE 和编辑器配置投毒、构建缓存产物、备份文件、操作系统元数据等低审查路径。
- **跨发现项关联** — 基于目录、仓库级别、内容哈希、基本名称和 Git 时间的关联，以揭示复合风险（`COR-`、`DRIFT-`）。
## `skeptic` 的局限性
- **不是 CVE 扫描器。** 请使用 Trivy、Grype、osv-scanner 检测软件包漏洞。
- **不是 SAST 工具。** 不进行 AST 解析，不进行数据流污点追踪。
- **不是密钥扫描器。** 请使用 Gitleaks 或 trufflehog 检测凭据泄露。
- **不是 EDR。** 扫描静态文件，而非运行时行为。
将 `skeptic` 与这些工具并行运行，以检测它们未覆盖的间隙。
## 设计原则
- 填补现有安全工具遗漏的间隙。
- 对于相同输入和规则集，输出具有确定性。
- 单一静态 Go 二进制文件，仅使用标准库。
- 仅使用 RE2 正则表达式，无不安全模式。
- 显式错误检查——无静默失败。
- 可审计性和可追溯的配置。
- 原子文件写入，无路径逃逸。
## 检测引擎
除了正则表达式模式匹配外，引擎还应用：
- **行为链** — 跨文件内容的多步骤有序/无序检测（16 条链，`BHV-`）
- **12 种有效载荷解码器** — base64、base32、十六进制、URL、gzip、zlib、PowerShell、Unicode、HTML、ROT13、quoted-printable、PEM；可配置深度，并基于熵的加成递归
- **身份图分析** — 对 AWS、Azure、GCP 和 Kubernetes 的 IAM/RBAC/OIDC 配置进行 BFS 遍历
- **跨发现项关联** — 基于目录、仓库级别、内容哈希、文件基本名称和 Git 时间的关联（`COR-`、`DRIFT-`）
- **香农熵异常检测** — 用于嵌入式加密/编码有效载荷的滑动窗口分析
- **NFKC 规范化** — 对抗全宽/同形字规避
- **Aho-Corasick 预过滤** — 用于大型语料库加速的可选字面关键字自动机
- **XOR 暴力破解** — 对高熵内容进行可选的单字节 XOR 解码（`--xor-brute`）
- **多语言检测** — 文本文件中的二进制魔数字节
- **增量缓存** — 带有规则集哈希失效的 mtime + size + SHA256 状态文件
- **豁免抑制** — 带有 SHA256 固定文件范围的 JSON 豁免文件；`waive` 创建条目，`--waivers` 在扫描时应用它们
- **风险评分** — 0–100 综合评分，具有按严重性递减的边际效应
- **工具上下文豁免** — 在特定工具上下文中运行时，`--tool-name` 可减少误报
### 规则包与摄入
规则包用于通过来自多个来源的实时威胁情报扩展内置规则集。规则包使用 Ed25519 分离签名进行签名，以确保完整性和真实性。
`skeptic ingest` 从 URL、文件和目录创建签名规则包。
### 语料库
`skeptic corpus` 为恶意文件提供加密静态存储和扫描隔离。此功能在扫描期间将代理与摄入的恶意内容隔离。
`corpus` 处理初始化、加密存储、内容验证、清单完整性、路径安全以及具有预期检测增量报告的隔离扫描。
```
skeptic corpus init # create the corpus directory with AES-256-GCM key
skeptic corpus fetch -s ./SKILL.md # ingest a malicious SKILL.md file
skeptic corpus info # show the corpus status
skeptic corpus scan --learn # scan the corpus and learn the expected rules
```
## GitHub Action
将怀疑者添加到任何工作流：
```
- uses: TGPSKI/skeptic@v1
```
```
- uses: TGPSKI/skeptic@v1
with:
scan-style: hybrid
threat-mode: machine-identity
fail-on: none # advisory only
```
完整输入/输出参考和用法示例请参见 [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md)。
## 运行时
### CLI 扫描
```
skeptic scan {repo_path} # positional path
skeptic scan --path {repo_path} # explicit flag
skeptic scan -p {repo_path} -f json # shorthand flags
skeptic scan --preset ci --fail-on high # CI gating
```
### MCP 服务器
MCP 服务器通过 stdio JSON-RPC 提供代理工具访问。配置您的 MCP 客户端：
```
{
"mcpServers": {
"skeptic": {
"command": "skeptic",
"args": ["mcp"]
}
}
}
```
暴露的工具：`skeptic_scan_repo`、`skeptic_waive`、`skeptic_ingest_url`，以及当提供 `--daemon-url` 时的守护进程桥接工具。完整工具参考请参见 [docs/SERVER.md](docs/SERVER.md)。
### 守护进程
守护进程添加了定时后台扫描，并暴露一个 HTTP API 用于状态、报告和触发扫描。
```
# 终端 1: 启动 daemon
skeptic serve --scan-interval 5m
# 终端 2: 通过 daemon 桥接启动 MCP 服务器
skeptic mcp --daemon-url http://127.0.0.1:7788 --daemon-token-file .skeptic/daemon.token
```
守护进程默认绑定到回环地址，并使用令牌进行身份验证。参见 [docs/SERVER.md](docs/SERVER.md)。
## 安装
### 通过 go install
```
go install github.com/TGPSKI/skeptic/cmd/skeptic@latest
```
### 二进制文件 + 补全脚本（推荐）
```
sudo make install
```
此操作构建二进制文件，将其复制到 `/usr/local/bin/`，并将 bash、zsh 和 fish 的 shell 补全脚本安装到它们各自的标准系统目录中。安装过程会优雅地跳过其补全目录不可写的任何 shell。
如有需要，可覆盖路径：
```
sudo make install INSTALL_DIR=/opt/bin ZSH_COMPLETION_DIR=/usr/share/zsh/site-functions
```
### 仅二进制文件
```
make build
sudo install -m 755 bin/skeptic /usr/local/bin/skeptic
```
### 仅补全脚本
```
sudo make install-completions
```
或生成到 stdout 以便手动放置：
```
skeptic completion bash > ~/.local/share/bash-completion/completions/skeptic
skeptic completion zsh > ~/.local/share/zsh/site-functions/_skeptic
skeptic completion fish > ~/.config/fish/completions/skeptic.fish
```
### 用户本地安装（无需 sudo）
```
make build
mkdir -p ~/.local/bin
install -m 755 bin/skeptic ~/.local/bin/skeptic
# completions（如需则创建目录）
mkdir -p ~/.local/share/bash-completion/completions
skeptic completion bash > ~/.local/share/bash-completion/completions/skeptic
mkdir -p ~/.local/share/zsh/site-functions
skeptic completion zsh > ~/.local/share/zsh/site-functions/_skeptic
mkdir -p ~/.config/fish/completions
skeptic completion fish > ~/.config/fish/completions/skeptic.fish
```
确保 `~/.local/bin` 在你的 `PATH` 中。对于 zsh，在 `.zshrc` 中的 `compinit` 之前添加 `fpath=(~/.local/share/zsh/site-functions $fpath)`。
### 卸载
```
sudo make uninstall
```
## 开发
### 测试和 linting
```
make build # compile binary
make check # pre-commit: fmt (fail on diff) + vet
make test # unit tests
make test-race # unit tests with race detector
make integration # fast integration tests (~10s)
make ci # full CI suite (race + integration)
make lint # golangci-lint (errcheck, staticcheck, funlen, etc.)
make bench # benchmarks (all packages)
make coverage-check # coverage gate (fail if < 60%)
```
完整目标列表请参见 `make help`。
## CLI 模式
### CI 门控
```
skeptic scan -p . --preset ci -f sarif --fail-on high > skeptic.sarif
```
### 基线 + 仅差异比较
```
skeptic scan -p . -f json --write-baseline ./baseline.json
skeptic scan -p . --baseline ./baseline.json --diff-only -f json
```
### 增量开发者扫描
```
skeptic scan --mode developer -p . --incremental --state-cache .skeptic-state.json
```
### 聚焦机器身份或 AI 工作负载评估
```
skeptic scan -p . --threat-mode machine-identity --scan-style hybrid -f json
skeptic scan -p . --threat-mode ai-workload --scan-style hybrid -f json
```
### 事件响应分诊（显示所有内容）
```
skeptic scan --mode ir -p . --scan-style hybrid
```
### 威胁情报摄入
```
skeptic ingest \
--source "https://example.com/advisory" \
--allow-host "example.com" \
--ecosystems "general,pypi,npm,github-actions,container,mcp,agent-skills,go,cargo" \
--rule-quality strict \
--out "rulepacks/campaigns/ingested-rules.json"
```
### 签名的外部规则包
```
skeptic gen-rule-keypair --private-out signing.key.pem --public-out signing.pub.pem
skeptic sign-rulepack --rules-file ./rules.json --private-key signing.key.pem
skeptic scan --rules-file ./rules.json --rules-pubkey signing.pub.pem --require-signed-rules
```
## CLI 参考
### 主要标志
| 标志 | 短标志 | 默认值 | 描述 |
| ------------------- | ------ | ----------- | ------------------------------------------------------------ |
| `--path` | `-p` | `.` | 要扫描的根路径（也可作为位置参数接受） |
| `--format` | `-f` | `text` | 输出格式：`text |
| `--config` | `-c` | auto | 配置文件路径（`.json`、`.yaml`、`.env`） |
| `--mode` | | `developer` | 操作模式：`developer |
| `--preset` | | — | 简写预设：`quick |
| `--profile` | | `repo` | 扫描配置文件：`repo |
| `--scan-style` | | `pattern` | 检测风格：`pattern |
| `--threat-mode` | | `all` | 关注点：`all |
| `--fail-on` | | `critical` | 严重性门控：从 `none` 到 `critical` |
| `--fail-on-score` | | `0` | 风险评分门控（0–100，0 表示禁用） |
| `--incremental` | | `false` | 通过 mtime/哈希缓存跳过未更改的文件 |
| `--baseline` | | — | 用于差异比较的先前 JSON 报告 |
| `--waivers` | | — | JSON 豁免文件；匹配的发现项将保持 `suppressed=true` |
配置解析顺序：模式默认值 < 预设覆盖 < 配置文件值 < 显式 CLI 标志。
完整标志列表：`skeptic --help` 或参见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
### 全局标志
| 标志 | 短标志 | 描述 |
| ------------------- | ------ | -------------------------------------------- |
| `--verbose N` | `-v` | 详细级别：0=警告，1=信息，2=调试，3=性能 |
| `--quiet` | `-q` | 禁止非错误输出 |
| `--config F` | `-c` | 配置文件（空=自动发现 `.skeptic.*`） |
| `--log-file F` | | 日志文件路径 |
| `--cpu-profile F` | | 将 CPU 分析写入文件 |
| `--mem-profile F` | | 退出时写入堆分析文件 |
| `--trace F` | | 将执行跟踪写入文件 |
| `--perf-debug` | | 启用所有分析 + 逐文件计时 |
### 子命令
| 命令 | 用途 |
| --------------------- | --------------------------------------------- |
| `scan` *（默认）* | 扫描并报告 |
| `init` | 引导配置文件和 XDG 数据目录 |
| `config show` | 打印已解析的配置 |
| `config use ` | 设置活动的命名配置文件 |
| `corpus` | 管理加密的威胁工件语料库 |
| `ingest` | 从威胁情报源生成规则包 |
| `serve` | 持久化调度器 + 本地 HTTP API |
| `mcp` | 用于代理工具的 stdio MCP 服务器 |
| `waive` | 为发现项创建 SHA256 固定的豁免条目 |
| `bundle` | 打包二进制文件 + 规则以便分发 |
| `export-evidence` | 用于事件响应移交的签名证据包 |
| `sign-rulepack` | 使用 Ed25519 签名外部规则包 |
| `gen-rule-keypair` | 生成 Ed25519 密钥对 |
| `verify-rulepack` | 验证规则包签名 |
| `verify-bundle` | 验证签名的分发包 |
| `completion` | Shell 补全脚本（bash、zsh、fish） |
| `version` | 打印构建信息和规则计数 |
标签：CI/CD安全, DevSecOps, EVTX分析, Go语言开发, Llama, TLS抓取, 上游代理, 云计算, 代理安全, 供应链攻击检测, 信任边界分析, 单二进制部署, 威胁情报管理, 安全扫描, 工具安全, 开发者安全, 文档结构分析, 日志审计, 时序注入, 标准库依赖, 网络安全, 规则引擎, 软件安全, 隐私保护, 零运行时依赖