secure-at-inception

从一开始就确保安全

主动扫描所有新生成或修改的代码，防止安全漏洞进入代码库。提供智能扫描决策、缓存和筛选功能，只关注新的问题。

---

文件类型 → 扫描类型参考

扫描类型	触发文件	MCP 工具
SAST（代码）	源文件：.js、.ts、.py、.java、.go、.rb、.php、.cs、.swift、.kt、.scala、.rs、.c、.cpp、.dart 等	snyk_code_scan
SCA（依赖项）	清单：package.json、requirements.txt、pom.xml、build.gradle、Gemfile、go.mod、Cargo.toml、*.csproj、composer.json 等	snyk_sca_scan
IaC	基础设施：.tf、.tfvars、K8s YAML（含 apiVersion/kind）、template.json/.yaml、ARM JSON、serverless.yml	snyk_iac_scan

跳过：二进制文件、非 IaC JSON/YAML、文档（.md、.txt、.rst）、资源文件、测试夹具。

---

阶段 1：检测变更

步骤 1.1：收集变更文件

通过以下任一方式检查变更（按优先顺序排列）：

1. Git diff（如果位于 git 仓库中）：

   git diff --name-only HEAD
   git diff --name-only --cached  # staged files
   git status --porcelain
   

2. 会话上下文：跟踪当前会话中创建/修改的文件
3. 用户指定的路径：如果用户提供了特定文件或目录

步骤 1.2：按扫描类型对文件分类

使用上方的“文件类型 → 扫描类型参考”表，将每个变更文件对应到适当的扫描类型。IaC YAML 与通用 YAML 的区别在于是否包含 apiVersion/kind（Kubernetes）或 AWSTemplateFormatVersion（CloudFormation）。

---

阶段 2：执行扫描

并行运行 SAST、SCA 和 IaC 扫描——它们彼此独立。根据下方参数执行各适用扫描类型（由“文件类型 → 扫描类型参考”表确定）。

步骤 2.1：SAST 扫描（snyk_code_scan）

• path：包含变更源文件的目录（或项目根目录）；如果变更文件少于 5 个，则逐个扫描，否则扫描父目录
• severity_threshold："medium"（默认值）或按配置设置

步骤 2.2：SCA 扫描（snyk_sca_scan）

• path：项目根目录或包含清单的目录
• all_projects：true（用于单体仓库）
• severity_threshold："medium"（默认值）或按配置设置
• 注意：SCA 会扫描整个依赖树，而不只是直接变更。

步骤 2.3：IaC 扫描（snyk_iac_scan）

• path：包含 IaC 文件的目录
• severity_threshold："medium"（默认值）或按配置设置

---

阶段 3：筛选新问题

在报告前应用以下筛选条件，仅显示由当前变更引入的问题。

SAST：仅当发现项所在的文件和行号位于 git diff -U0 的修改行范围内时才纳入。解析 @@ -X,Y +A,B @@ 区块以确定变更范围；排除范围外的发现项，因为它们是已有问题。

SCA：仅当新建或更新的软件包当前存在的漏洞数量更多或严重性更高时才纳入。应用净改善规则——如果变更降低了总体漏洞数量或严重性，则不要阻止。

IaC：仅当错误配置位于新添加或修改的资源块中时才纳入。

---

阶段 4：报告和决策

步骤 4.1：严重性阈值配置

模式	阻止条件	警告条件	允许
严格	低及以上	-	-
标准	高及以上	中	低
宽松	仅严重	高	中、低

步骤 4.2：生成报告

## Secure At Inception Scan Results

### Summary
| Scan Type            | New Issues | Blocked |
|----------------------|------------|---------|
| Code (SAST)          | X          | Yes/No  |
| Dependencies (SCA)   | Y          | Yes/No  |
| Infrastructure (IaC) | Z          | Yes/No  |

### New Code Vulnerabilities (SAST)
| Severity | Type          | File       | Line | Description           |
|----------|---------------|------------|------|-----------------------|
| High     | SQL Injection | src/db.ts  | 45   | User input in query   |

### New Dependency Vulnerabilities (SCA)
| Severity | Package          | Vulnerability        | Fix Version |
|----------|------------------|----------------------|-------------|
| Critical | [email protected]   | Prototype Pollution  | 4.17.21     |

### New Infrastructure Issues (IaC)
| Severity | Resource       | Issue                 | Recommendation           |
|----------|----------------|-----------------------|--------------------------|
| High     | aws_s3_bucket  | Public access enabled | Set block_public_access  |

### Recommended Actions
1. `/snyk-fix SNYK-JS-LODASH-1234` - Fix lodash vulnerability
2. Review `src/db.ts:45` for SQL injection fix

### Decision: [BLOCKED / ALLOWED]
[Reason based on severity threshold]

步骤 4.3：阻止决策逻辑

If any NEW issue severity >= threshold:
  BLOCKED - do not proceed until fixed
  Provide specific fix commands
Else:
  ALLOWED - safe to proceed
  Note any warnings for future attention

---

阶段 5：跟踪指标

每次扫描发现问题并有助于修复问题后，运行 snyk_send_feedback，并提供以下参数：

• path：项目根目录（绝对路径）
• preventedIssuesCount：发现的新问题数量（增量，而非累计值）
• fixedExistingIssuesCount：0（此技能用于预防，不修复已有问题）

仅统计在新代码中发现、且若没有此次扫描就会被提交的问题。

最佳实践

• 自动运行：在生成或修改代码后，以及建议提交前运行；也可按需运行以执行明确的安全检查。
• 缓存结果：以 file + content_hash 为键缓存结果，TTL 为 12 小时；仅重新扫描已更改的文件，并按目录批处理。
• 误报：使用 .snyk 策略文件屏蔽已确认的误报，然后重新运行以验证：

  ignore:
    SNYK-JS-EXAMPLE-12345:
      - '*':
          reason: 'False positive - input is validated upstream'
          expires: 2025-12-31
  

• 调整阈值：从 Standard 模式开始；如果阻止过于频繁，则切换到 Relaxed 模式；发生低/中严重性事件后，则切换到 Strict 模式。
• CI/CD 集成：在创建拉取请求或向功能分支推送时调用；如果超过阈值，则阻止合并。

---

错误处理

情况	操作
身份验证错误	运行 snyk_auth 并重试；如果仍然失败，则提示用户手动进行身份验证
扫描超时	缩小范围后重试一次；如果仍然失败，则报告部分结果
未检测到更改	报告“未检测到代码更改——无需扫描”；按需提供完整项目扫描
仅包含不受支持的文件	报告“更改中没有可扫描的文件”，并列出跳过的文件类型及原因

---

限制

1. 仅处理新问题：绝不因已有问题而阻止操作（这些问题应由修复流程处理）
2. 尽量减少干扰：积极过滤，避免告警疲劳
3. 快速反馈：典型更改的扫描应在 30 秒内完成
4. 非破坏性：绝不修改代码，只报告发现的问题
5. 可执行的输出：每项发现都必须提供明确的修复途径