swain-security-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Security Check

安全检查

Unified security scanning orchestrator. Checks scanner availability, runs all available scanners against the project, normalizes findings into a severity-bucketed report, and presents results in both JSON and markdown formats.

统一的安全扫描协调器。检查扫描器的可用性，针对项目运行所有可用的扫描器，将检测结果标准化为按风险等级划分的报告，并以JSON和Markdown两种格式呈现结果。

When invoked

调用方式

Run the security check script:

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 "$REPO_ROOT/skills/swain-security-check/scripts/security_check.py" .

For JSON output:

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 "$REPO_ROOT/skills/swain-security-check/scripts/security_check.py" --json .

运行安全检查脚本：

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 "$REPO_ROOT/skills/swain-security-check/scripts/security_check.py" .

如需JSON格式输出：

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 "$REPO_ROOT/skills/swain-security-check/scripts/security_check.py" --json .

Orchestration flow

协调流程

Check availability — detect which external scanners are installed (per SPEC-059)
Run scanners — invoke each available scanner against the project:
- gitleaks (secrets) —
```
gitleaks detect --source . --report-format json
```
- osv-scanner or trivy (dependency vulns) — scan lockfiles and manifests
- semgrep (static analysis) —
```
semgrep --config p/ai-best-practices
```
- Context-file scanner (built-in, always runs) — scan all agentic context files for injection patterns (SPEC-058, categories A-J)
- Repo hygiene (built-in, always runs) — .gitignore completeness, tracked .env files
Normalize — map all findings to unified format (scanner, file, line, severity, description, remediation)
Report — severity-bucketed output (critical/high/medium/low) with summary line

检查可用性 —— 检测已安装的外部扫描器（遵循SPEC-059规范）
运行扫描器 —— 调用每个可用的扫描器对项目进行扫描：
- gitleaks（密钥检测）——
```
gitleaks detect --source . --report-format json
```
- osv-scanner 或 trivy（依赖漏洞检测）—— 扫描锁文件和清单文件
- semgrep（静态分析）——
```
semgrep --config p/ai-best-practices
```
- 上下文文件扫描器（内置，始终运行）—— 扫描所有智能体上下文文件，检测注入模式（遵循SPEC-058规范，A-J类别）
- 仓库卫生检查（内置，始终运行）—— 检查.gitignore的完整性、是否追踪.env文件
标准化 —— 将所有检测结果映射为统一格式（扫描器、文件、行号、风险等级、描述、修复建议）
报告 —— 按风险等级（严重/高/中/低）划分的输出，附带汇总行

Graceful degradation

优雅降级

Missing external scanners are skipped with a warning — the scan never fails due to a missing tool. The two built-in scanners (context-file scanner and repo hygiene) always run, so the scan always produces results.

Each skipped scanner includes an install hint in the report.

缺失的外部扫描器会被跳过并给出警告——扫描不会因缺少工具而失败。两个内置扫描器（上下文文件扫描器和仓库卫生检查）始终运行，因此扫描始终会生成结果。

每个被跳过的扫描器都会在报告中包含安装提示。

Exit codes

退出码

Code	Meaning
0	No findings
1	Findings present
2	Error (e.g., invalid path)

代码	含义
0	无检测结果
1	存在检测结果
2	错误（如无效路径）

Report format

报告格式

Severity levels

风险等级

Critical — secrets in source, tracked .env files, instruction override patterns
High — role hijacking, privilege escalation, encoding obfuscation
Medium — missing .gitignore patterns, dependency vulnerabilities
Low — informational findings

严重 —— 源代码中的密钥、被追踪的.env文件、指令覆盖模式
高 —— 角色劫持、权限提升、编码混淆
中 —— 缺失.gitignore规则、依赖漏洞
低 —— 信息性检测结果

Per-finding fields

单条检测结果字段

Field	Description
scanner	Which scanner produced the finding
file_path	File where the finding was detected
line	Line number (0 if not applicable)
severity	critical, high, medium, or low
description	What was found
remediation	How to fix it

字段	描述
scanner	生成该检测结果的扫描器
file_path	检测到问题的文件路径
line	行号（不适用时为0）
severity	严重、高、中或低
description	检测到的内容
remediation	修复方法

Summary line

汇总行示例

Example:

1 critical, 2 high, 0 medium, 0 low findings (3 total) across 4 scanners

示例：

1个严重、2个高风险、0个中风险、0个低风险检测结果（共3个），来自4个扫描器

Integration points

集成点

swain-doctor (SPEC-061) — runs a lightweight context-file scan during session startup
swain-do (SPEC-063) — pre-claim security briefing for security-sensitive tasks
swain-init — configures gitleaks pre-commit hook during project onboarding
External security skills (SPEC-065) — hook interface for third-party security skills

swain-doctor（SPEC-061）—— 在会话启动时运行轻量级上下文文件扫描
swain-do（SPEC-063）—— 针对安全敏感任务提供预执行安全简报
swain-init —— 在项目初始化时配置gitleaks提交前钩子
外部安全技能（SPEC-065）—— 第三方安全技能的钩子接口

External Security Skill Hook Interface

外部安全技能钩子接口

Read references/external-hook-api.md for the hook registration contract, event schema, and integration patterns.

阅读references/external-hook-api.md了解钩子注册协议、事件Schema和集成模式。

Dependencies

依赖项

SPEC-058: Context-file injection scanner (
```
context_file_scanner.py
```
)
SPEC-059: Scanner availability detection (
```
scanner_availability.py
```
)
SPEC-065: External security skill hook interface (
```
external_hooks.py
```
)

SPEC-058: 上下文文件注入扫描器 (
```
context_file_scanner.py
```
)
SPEC-059: 扫描器可用性检测 (
```
scanner_availability.py
```
)
SPEC-065: 外部安全技能钩子接口 (
```
external_hooks.py
```
)