Back to Details

commit-security-scan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Commit Security Scan

提交安全扫描

Analyze code changes (commits, PRs, diffs) using LLM-powered reasoning to detect security vulnerabilities. This skill reads code directly and applies patterns from the repository's threat model to identify issues across all STRIDE categories.
利用LLM驱动的推理分析代码变更（提交、PR、差异）以检测安全漏洞。该技能直接读取代码，并应用仓库威胁模型中的模式来识别所有STRIDE类别下的问题。

When to Use This Skill

何时使用该技能

  • PR review - Automated security scan on pull requests
  • Pre-commit check - Scan staged changes before committing
  • Branch comparison - Review security of feature branch changes
  • Code review assistance - Help reviewers spot security issues
  • PR评审 - 对拉取请求进行自动化安全扫描
  • 提交前检查 - 在提交前扫描暂存的变更
  • 分支对比 - 评审功能分支变更的安全性
  • 代码评审辅助 - 帮助评审人员发现安全问题

Prerequisites

前提条件

This skill requires:
  1. Threat model - 
    .factory/threat-model.md
    must exist
  2. Security config - 
    .factory/security-config.json
    for severity thresholds
IMPORTANT: If these files don't exist, you MUST generate them first before proceeding with the security scan.
To generate the prerequisites:
  1. Tell the user: "The threat model doesn't exist yet. I'll generate it first before scanning."
  2. Run the 
    threat-model-generation
    skill to create both files
  3. Once complete, continue with the security scan
Do NOT ask the user to run the skill manually - just do it automatically as part of this workflow.
使用该技能需要：
  1. 威胁模型 - 必须存在 
    .factory/threat-model.md
    文件
  2. 安全配置 - 用于设置严重程度阈值的 
    .factory/security-config.json
    文件
重要提示：如果这些文件不存在，必须先生成它们，然后再进行安全扫描。
生成前提条件的步骤：
  1. 告知用户：“威胁模型尚未存在。我将先生成它，之后再进行扫描。”
  2. 运行 
    threat-model-generation
    技能来创建这两个文件
  3. 生成完成后，继续进行安全扫描
请勿让用户手动运行该技能 - 作为此工作流的一部分自动执行即可。

Inputs

输入

The skill determines what to scan from the user's request:
Scan TypeHow to SpecifyExample
PR"Scan PR #123"
Scan PR #456 for security vulnerabilities
Commit range"Scan commits X..Y"
Scan commits abc123..def456
Single commit"Scan commit X"
Scan commit abc123
Staged changes"Scan staged changes"
Scan my staged changes for security issues
Uncommitted"Scan uncommitted changes"
Scan working directory changes
Branch comparison"Scan from X to Y"
Scan changes from main to feature-branch
Last N commits"Scan last N commits"
Scan the last 3 commits
If no scope is specified, prompt the user for clarification.
该技能根据用户的请求确定扫描范围：
扫描类型指定方式示例
PR"Scan PR #123"
Scan PR #456 for security vulnerabilities
提交范围"Scan commits X..Y"
Scan commits abc123..def456
单个提交"Scan commit X"
Scan commit abc123
暂存变更"Scan staged changes"
Scan my staged changes for security issues
未提交变更"Scan uncommitted changes"
Scan working directory changes
分支对比"Scan from X to Y"
Scan changes from main to feature-branch
最近N个提交"Scan last N commits"
Scan the last 3 commits
如果未指定范围，请提示用户说明。

Instructions

操作步骤

Follow these steps in order:
按以下顺序执行步骤：

Step 1: Verify Prerequisites (Auto-Generate if Missing)

步骤1：验证前提条件（缺失时自动生成）

Try to read these files:
  • .factory/threat-model.md
  • .factory/security-config.json
If either file is missing or cannot be read:
  1. Inform the user: "The security threat model doesn't exist yet. I'll generate it first - this may take a minute."
  2. Invoke the 
    threat-model-generation
    skill to analyze the repository and create both files
  3. Once generation completes, continue with Step 2
This ensures the security scan always has the threat model context it needs for accurate analysis.
尝试读取以下文件：
  • .factory/threat-model.md
  • .factory/security-config.json
如果任一文件缺失或无法读取：
  1. 告知用户：“安全威胁模型尚未存在。我将先生成它 - 这可能需要一分钟。”
  2. 调用 
    threat-model-generation
    技能分析仓库并创建这两个文件
  3. 生成完成后，继续执行步骤2
这确保安全扫描始终拥有准确分析所需的威胁模型上下文。

Step 2: Get Changed Files

步骤2：获取变更文件

Based on the user's request, get the list of changed files and their diffs using git:
  • For PRs: use 
    gh pr diff
  • For commits/ranges: use 
    git diff
    or 
    git show
  • For staged changes: use 
    git diff --cached
Read the full content of each changed file for context.
根据用户的请求，使用git获取变更文件列表及其差异：
  • 对于PR：使用 
    gh pr diff
  • 对于提交/提交范围：使用 
    git diff
    或 
    git show
  • 对于暂存变更：使用 
    git diff --cached
读取每个变更文件的完整内容以获取上下文。

Step 3: Load Threat Model

步骤3：加载威胁模型

Read 
.factory/threat-model.md
and 
.factory/security-config.json
to understand:
  • The system's architecture and trust boundaries
  • Known vulnerability patterns for this codebase
  • Severity thresholds for findings
读取 
.factory/threat-model.md
和 
.factory/security-config.json
以了解：
  • 系统架构和信任边界
  • 此代码库的已知漏洞模式
  • 发现结果的严重程度阈值

Step 4: Analyze for Vulnerabilities

步骤4：漏洞分析

For each changed file, systematically check for STRIDE threats:
对每个变更文件，系统地检查STRIDE威胁：

S - Spoofing Identity

S - Spoofing Identity（身份伪造）

  • Missing or weak authentication checks
  • Session handling vulnerabilities
  • Token/credential exposure in code
  • Insecure cookie settings
  • 缺失或薄弱的身份验证检查
  • 会话处理漏洞
  • 代码中暴露的令牌/凭证
  • 不安全的Cookie设置

T - Tampering with Data

T - Tampering with Data（数据篡改）

  • SQL Injection: String concatenation/interpolation in SQL queries
  • Command Injection: User input in shell commands, 
    eval()
    , 
    exec()
  • XSS: Unescaped user input in HTML/templates
  • Mass Assignment: Blind assignment from request to model
  • Path Traversal: User input in file paths without validation
  • SQL Injection：SQL查询中的字符串拼接/插值
  • Command Injection：用户输入进入shell命令、
    eval()
    、
    exec()
  • XSS：HTML/模板中未转义的用户输入
  • Mass Assignment：从请求到模型的盲目赋值
  • Path Traversal：文件路径中未验证的用户输入

R - Repudiation

R - Repudiation（抵赖）

  • Missing audit logging for sensitive operations
  • Insufficient error logging
  • Log injection vulnerabilities
  • 敏感操作缺失审计日志
  • 错误日志不足
  • 日志注入漏洞

I - Information Disclosure

I - Information Disclosure（信息泄露）

  • IDOR: Direct object access without ownership verification
  • Verbose error messages exposing internals
  • Hardcoded secrets, API keys, credentials
  • Sensitive data in logs or responses
  • Debug endpoints exposed
  • IDOR：未验证所有权的直接对象访问
  • 暴露内部细节的详细错误消息
  • 硬编码的密钥、API密钥、凭证
  • 日志或响应中的敏感数据
  • 暴露的调试端点

D - Denial of Service

D - Denial of Service（拒绝服务）

  • Missing rate limiting on endpoints
  • Unbounded resource consumption (file uploads, queries)
  • Algorithmic complexity attacks (regex, sorting)
  • Missing pagination on list endpoints
  • 端点缺失速率限制
  • 无限制的资源消耗（文件上传、查询）
  • 算法复杂度攻击（正则表达式、排序）
  • 列表端点缺失分页

E - Elevation of Privilege

E - Elevation of Privilege（权限提升）

  • Missing authorization checks on endpoints
  • Role/permission bypass opportunities
  • Privilege escalation through parameter manipulation
  • 端点缺失授权检查
  • 角色/权限绕过机会
  • 通过参数操纵进行权限提升

Step 5: Assess Each Finding

步骤5：评估每个发现结果

For each potential vulnerability:
  1. Trace data flow: Follow user input from source to sink
    • Where does the input come from? (request params, body, headers, files)
    • Does it pass through validation/sanitization?
    • Where does it end up? (database, shell, response, file system)
  2. Check for existing mitigations:
    • Is there validation elsewhere in the codebase?
    • Are there middleware/decorators that protect this code?
    • Does the framework provide automatic protection?
  3. Determine severity:
    • CRITICAL: Remote code execution, auth bypass, data breach
    • HIGH: SQL injection, XSS, IDOR, privilege escalation
    • MEDIUM: Information disclosure, missing security headers
    • LOW: Best practice violations, minor issues
  4. Assess confidence:
    • HIGH: Clear vulnerable pattern, direct data flow, no mitigations
    • MEDIUM: Possible vulnerability, some uncertainty about context
    • LOW: Suspicious pattern, likely has mitigations we can't see
对于每个潜在漏洞：
  1. 追踪数据流：跟随用户输入从源头到终点
    • 输入来自何处？（请求参数、主体、头部、文件）
    • 是否经过验证/清理？
    • 最终流向何处？（数据库、shell、响应、文件系统）
  2. 检查现有缓解措施：
    • 代码库其他位置是否有验证？
    • 是否有中间件/装饰器保护此代码？
    • 框架是否提供自动保护？
  3. 确定严重程度：
    • CRITICAL（严重）：远程代码执行、身份验证绕过、数据泄露
    • HIGH（高）：SQL Injection、XSS、IDOR、权限提升
    • MEDIUM（中）：信息泄露、缺失安全头部
    • LOW（低）：最佳实践违规、次要问题
  4. 评估置信度：
    • HIGH（高）：明确的漏洞模式、直接数据流、无缓解措施
    • MEDIUM（中）：可能存在漏洞，对上下文有一定不确定性
    • LOW（低）：可疑模式，可能存在我们未发现的缓解措施

Step 6: Generate Report

步骤6：生成报告

Create 
security-findings.json
with this structure:
json
{
  "scan_id": "scan-YYYY-MM-DD-XXX",
  "scan_date": "<ISO 8601 timestamp>",
  "scan_type": "pr|commit|range|staged|working",
  "commit_range": "<base>..<head>",
  "pr_number": null,
  "threat_model_version": "<from security-config.json>",
  "findings": [
    {
      "id": "VULN-001",
      "severity": "HIGH",
      "stride_category": "Tampering",
      "vulnerability_type": "SQL Injection",
      "cwe": "CWE-89",
      "file": "src/api/users.py",
      "line_range": "45-49",
      "code_context": "<vulnerable code snippet>",
      "analysis": "<explanation of why this is vulnerable>",
      "exploit_scenario": "<how an attacker could exploit this>",
      "threat_model_reference": "Section 5.2 - SQL Injection",
      "existing_mitigations": [],
      "recommended_fix": "<how to fix the vulnerability>",
      "confidence": "HIGH",
      "reasoning": "<why this confidence level>"
    }
  ],
  "summary": {
    "total_findings": 0,
    "by_severity": { "CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0 },
    "by_stride": {
      "Spoofing": 0,
      "Tampering": 0,
      "Repudiation": 0,
      "InfoDisclosure": 0,
      "DoS": 0,
      "ElevationOfPrivilege": 0
    },
    "files_analyzed": 0
  }
}
创建 
security-findings.json
文件，结构如下：
json
{
  "scan_id": "scan-YYYY-MM-DD-XXX",
  "scan_date": "<ISO 8601 timestamp>",
  "scan_type": "pr|commit|range|staged|working",
  "commit_range": "<base>..<head>",
  "pr_number": null,
  "threat_model_version": "<from security-config.json>",
  "findings": [
    {
      "id": "VULN-001",
      "severity": "HIGH",
      "stride_category": "Tampering",
      "vulnerability_type": "SQL Injection",
      "cwe": "CWE-89",
      "file": "src/api/users.py",
      "line_range": "45-49",
      "code_context": "<vulnerable code snippet>",
      "analysis": "<explanation of why this is vulnerable>",
      "exploit_scenario": "<how an attacker could exploit this>",
      "threat_model_reference": "Section 5.2 - SQL Injection",
      "existing_mitigations": [],
      "recommended_fix": "<how to fix the vulnerability>",
      "confidence": "HIGH",
      "reasoning": "<why this confidence level>"
    }
  ],
  "summary": {
    "total_findings": 0,
    "by_severity": { "CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0 },
    "by_stride": {
      "Spoofing": 0,
      "Tampering": 0,
      "Repudiation": 0,
      "InfoDisclosure": 0,
      "DoS": 0,
      "ElevationOfPrivilege": 0
    },
    "files_analyzed": 0
  }
}

Step 7: Report Results

步骤7：报告结果

  1. Save findings to 
    security-findings.json
  2. Report summary to user (findings count by severity, triggered thresholds)
  3. Check severity thresholds from 
    security-config.json
    and note if any are triggered
  1. 将发现结果保存到 
    security-findings.json
  2. 向用户报告摘要（按严重程度统计的发现数量、触发的阈值）
  3. 检查 
    security-config.json
    中的严重程度阈值，并记录是否有阈值被触发

CWE Reference

CWE参考

Common CWE mappings for findings:
Vulnerability TypeCWE
SQL InjectionCWE-89
Command InjectionCWE-78
XSS (Reflected)CWE-79
XSS (Stored)CWE-79
Path TraversalCWE-22
IDORCWE-639
Missing AuthenticationCWE-306
Missing AuthorizationCWE-862
Hardcoded CredentialsCWE-798
Sensitive Data ExposureCWE-200
Mass AssignmentCWE-915
Open RedirectCWE-601
SSRFCWE-918
XXECWE-611
Insecure DeserializationCWE-502
发现结果对应的常见CWE映射：
漏洞类型CWE
SQL InjectionCWE-89
Command InjectionCWE-78
XSS (Reflected)CWE-79
XSS (Stored)CWE-79
Path TraversalCWE-22
IDORCWE-639
Missing AuthenticationCWE-306
Missing AuthorizationCWE-862
Hardcoded CredentialsCWE-798
Sensitive Data ExposureCWE-200
Mass AssignmentCWE-915
Open RedirectCWE-601
SSRFCWE-918
XXECWE-611
Insecure DeserializationCWE-502

Example Invocations

调用示例

Scan a PR:
Scan PR #123 for security vulnerabilities
Scan staged changes before committing:
Scan my staged changes for security issues
Scan a feature branch:
Scan changes from main to feature/user-auth for vulnerabilities
Scan recent commits:
Scan the last 5 commits for security issues
扫描PR：
Scan PR #123 for security vulnerabilities
提交前扫描暂存变更：
Scan my staged changes for security issues
扫描功能分支：
Scan changes from main to feature/user-auth for vulnerabilities
扫描最近提交：
Scan the last 5 commits for security issues

References

参考资料

  • Analysis examples: 
    analysis-examples.md
    (in this skill directory)
  • Threat model: 
    .factory/threat-model.md
  • Security config: 
    .factory/security-config.json
  • OWASP Top 10
  • CWE Top 25
  • 分析示例：
    analysis-examples.md
    （位于此技能目录中）
  • 威胁模型：
    .factory/threat-model.md
  • 安全配置：
    .factory/security-config.json
  • OWASP Top 10
  • CWE Top 25