本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 IDE 執行程式碼安全掃描
使用 Kiro 或 Claude Code 直接從 IDE 執行 AWS Security Agent 程式碼安全掃描。IDE 整合可讓您掃描本機原始程式碼是否有安全漏洞、僅對變更的程式碼執行差異掃描，以及對設計文件執行威脅模型檢閱，而無須離開您的開發環境。問題清單會與您的程式碼一起顯示，並附有修補指引，而且您可以直接從 IDE 套用自動修正。
## IDE 整合的運作方式
IDE 整合使用 AWS Security Agent MCP （模型內容通訊協定） 伺服器將您的 IDE 連線至 AWS Security Agent 服務：
1. MCP 伺服器將您的原始碼封裝為 ZIP 封存檔。
1. 封存會上傳至您 AWS 帳戶中伺服器自動佈建的 S3 儲存貯體。
1. 伺服器會呼叫 AWS Security Agent API 來啟動掃描。
1. AWS Security Agent 會分析程式碼是否有安全漏洞，以及是否符合組織的安全需求。
1. 調查結果會傳回 IDE，其中包含程式碼位置、描述、嚴重性評分和修復建議。
MCP 伺服器會處理所有協同運作：客服人員空間佈建、S3 儲存貯體建立、IAM 角色設定、程式碼封裝和掃描輪詢，因此您只需在本機設定 AWS 登入資料。
**注意**
唯一的先決條件是在本機環境中設定的 AWS 登入資料 （例如，透過 `aws configure`、AWS SSO 或環境變數）。MCP 伺服器會在第一次使用時自動佈建 Agent Space、IAM 服務角色和 S3 儲存貯體。
## 先決條件
開始前，請確保您具備以下條件：
+ 在本機設定具有下列許可的 AWS 登入資料：
+ `iam:CreateRole`、 `iam:PutRolePolicy`（適用於服務角色的一次性設定）
+ `s3:CreateBucket`, `s3:PutObject`, `s3:PutPublicAccessBlock`, `s3:PutLifecycleConfiguration`
+ `securityagent:CreateAgentSpace`, `securityagent:UpdateAgentSpace`, `securityagent:ListAgentSpaces`, `securityagent:BatchGetAgentSpaces`
+ `securityagent:CreateCodeReview`, `securityagent:StartCodeReviewJob`, `securityagent:BatchGetCodeReviewJobs`
+ `securityagent:ListFindings`, `securityagent:BatchGetFindings`
+ `securityagent:StartCodeRemediation` （適用於自動修正）
+ `sts:GetCallerIdentity`
+ 已安裝 [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 套件執行器）
+ Python 3.10 或更新版本
+ 下列其中一個 IDEs：
+ [Kiro](https://kiro.dev) （安裝 AWS Security Agent Power)
+ Claude Code （安裝 AWS Security Agent 外掛程式）
## 安裝 MCP 伺服器
### Kiro
從 Kiro 市集安裝 **AWS Security Agent** Power。電源會綁定 MCP 伺服器組態、轉向指示和生命週期掛鉤，以提供自動安全掃描建議。
或者，在專案的 中手動設定 MCP 伺服器`.kiro/mcp.json`：
```
{
"mcpServers": {
"security-agent": {
"command": "uvx",
"args": ["awslabs.security-agent-mcp-server@latest"],
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1",
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
}
```
### Claude 程式碼
安裝 AWS Security Agent 外掛程式，提供設定、完整掃描、差異掃描、威脅模型檢閱和修復的技能。
在專案的 中設定 MCP 伺服器`.mcp.json`：
```
{
"mcpServers": {
"awslabs.security-agent-mcp-server": {
"command": "uvx",
"args": ["awslabs.security-agent-mcp-server@latest"],
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1",
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
}
```
**提示**
如果您不想在本機安裝 Python，也可以透過 Docker 執行 MCP 伺服器。請參閱 Docker 組態的 [MCP 伺服器文件](https://github.com/awslabs/mcp)。
## 首次設定
第一次使用時，MCP 伺服器會自動佈建必要的 AWS 資源：
| 資源 | 名稱慣例 | 用途 |
| --- | --- | --- |
| 客服人員空間 | 使用者選擇或自動建立 | 掃描、檢閱和滲透的容器 |
| IAM 服務角色 | `SecurityAgentScanRole` | 由 擔任`securityagent.amazonaws.com`以讀取上傳的程式碼 |
| S3 bucket (S3 儲存貯體) | `security-agent-scans-{account}-{region}` | 存放壓縮的原始碼 (30 天自動過期生命週期） |
若要明確觸發設定，請詢問您的 IDE：
```
Set up the security agent
```
設定會驗證您的 AWS 登入資料、建立或重複使用 Agent Space、佈建 IAM 角色和 S3 儲存貯體，並確認準備狀態。如果您已有來自 AWS 管理主控台的 Agent Spaces，則設定會顯示它們並詢問要使用哪個。
**注意**
如果尚未設定，設定會在第一次掃描時自動執行。您不需要單獨執行。
## 執行完整的安全性掃描
掃描整個專案是否有安全漏洞：
```
Scan this project for security issues
```
IDE：
1. 封存您的原始程式碼 （不包括 `.git`、、`node_modules`組建成品和其他非必要目錄）
1. 將封存上傳至 S3
1. 啟動完整的程式碼檢閱任務
1. 輪詢以完成 （通常大約 1 小時）
1. 呈現依嚴重性分組的問題清單
### 掃描進度
完整掃描通常需要約 1 小時，取決於程式碼庫大小。IDE 每 5 分鐘檢查一次進度，並在結果就緒時通知您。您可以隨時要求狀態：
```
How's the scan going?
```
## 執行差異掃描
如需在開發期間更快速的意見回饋，請僅掃描自 git 參考以來變更的程式碼：
```
Scan my changes against main for security issues
```
根據預設，如果您未指定基本參考，掃描會將您未遞交的變更與 進行比較`HEAD`。您可以明確指定不同的基底：
```
Diff scan my uncommitted changes
```
差異掃描會同時上傳完整的儲存庫內容和 git diff 修補程式，然後執行僅著重於變更行的分析。結果通常會在 5-15 分鐘內送達。
如需 S3 diff 掃描 API 的詳細資訊，請參閱 [使用 S3 執行差異碼掃描](run-diff-scan-s3.md)。
## 執行威脅模型檢閱
使用 STRIDE 方法分析安全姿勢變更的設計文件：
```
Run a threat model review on my spec
```
IDE 可識別您的 `requirements.md`和 `design.md` 檔案 （通常在 下`.kiro/specs/`)、將它們與您的原始程式碼一起上傳，並執行威脅模型分析。結果識別：
+ 依 STRIDE 分類的安全威脅 （詐騙、竄改、複寫、資訊揭露、拒絕服務、提升權限）
+ 每個威脅的嚴重性評分
+ 對程式碼庫中特定資產的影響
+ 緩解的建議
**提示**
從規格產生實作任務之前，請執行威脅模型檢閱。這會在編寫程式碼之前發現安全設計問題。
## 檢閱調查結果
掃描完成時，問題清單會顯示在依嚴重性分組的 IDE 中：
```
🟣 CRITICAL: SQL Injection in user-service.ts
File: src/api/user-service.ts:45
User input flows directly into SQL query without parameterization
🔴 HIGH: Hardcoded credentials in config.ts
File: src/config/database.ts:12
Database password stored in source code
```
詳細的報告也會寫入 `.security-agent/findings-{scan_id}.md`，其中包含每個調查結果的完整資訊，包括風險類型、可信度分數、程式碼位置和修補程式碼。
若要檢視先前掃描的結果：
```
Show my security findings
```
## 套用自動修正
檢閱問題清單後，套用自動化修復：
```
Fix the security findings
```
IDE 會依嚴重性 （關鍵 → 高 → 中 → 低） 處理調查結果，並使用每個調查結果的修補指引套用程式碼修正。套用所有修正後，會自動執行驗證差異掃描以確認問題已解決。
您也可以修正個別問題清單：
```
Fix the SQL injection in user-service.ts
```
**重要**
在遞交之前，請務必檢閱自動修正。確認修正不會破壞現有功能或引入迴歸。
## 自動掃描建議 (Kiro)
使用 Kiro Power 時，AWS Security Agent 可以在您對安全敏感的程式碼進行變更後自動建議 diff 掃描。Power 安裝勾點，評估每個完成的編碼轉彎，並在變更影響時建議掃描：
+ 身分驗證或授權邏輯
+ 密碼編譯或秘密處理
+ 輸入驗證或資料清理
+ 網路請求或外部整合
+ 安全組態 (CORS、標頭、工作階段處理）
您可以隨時刪除 來選擇退出自動建議`.kiro/hooks/security-diff-scan-suggester.kiro.hook`。
## 可用的掃描類型
| 掃描類型 | 持續時間 | 使用案例 | 命令 |
| --- | --- | --- | --- |
| 完整掃描 | 約 1 小時 | 完整檢閱整個程式碼庫 | 「掃描我的專案是否有安全問題」 |
| 差異掃描 | 5-15 分鐘 | 僅變更程式碼 （遞交前、PR 前） | "掃描我的變更" 或 "Diff scan against main" |
| 威脅模型 | 5-30 分鐘 | 設計文件 (requirements.md：//、design.md：//) | 「在我的規格上執行威脅模型檢閱」 |
## 環境變數
| 變數 | 描述 | 預設 |
| --- | --- | --- |
| `AWS_REGION` | SecurityAgent API 呼叫的 AWS 區域 | `us-east-1` |
| `AWS_PROFILE` | AWS 登入資料設定檔名稱 | 預設設定檔 |
| `FASTMCP_LOG_LEVEL` | MCP 伺服器日誌層級 (DEBUG、INFO、WARNING、 ERROR) | `WARNING` |
## 疑難排解
### 「未設定。先執行設定。」
您的 `.security-agent/config.json` 遺失或代理程式空間不再存在。要求 IDE 執行設定：
```
Set up the security agent
```
### AccessDenied 掃描失敗
確保您的 AWS 登入資料具有先決條件區段中列出的必要 IAM 許可。最常見的缺少許可是 `iam:CreateRole`（只有在第一次設定時才需要）。
### 掃描逾時或花費太長的時間
+ 在大型程式碼庫上完整掃描可能需要超過 1 小時
+ 使用差異掃描進行反覆開發 - 它們會在幾分鐘內完成
+ 檢查您的來源封存不包含不必要的目錄 (MCP 伺服器會自動排除常見模式）
### 空差 — 掃描沒有變更
如果您執行 diff 掃描時沒有未遞交的變更，MCP 伺服器會報告「沒有變更 vs HEAD」，而且不會啟動掃描。先遞交或暫存變更，或指定不同的基礎參考。
## 配額和限制
+ 來源封存大小上限：2 GB
+ S3 儲存貯體生命週期：上傳的程式碼會在 30 天後自動刪除
## 後續步驟
執行第一次 IDE 安全掃描之後：
+ 啟用自動 GitHub 整合的提取請求程式碼檢閱註解 （請參閱 [啟用 GitHub 儲存庫的提取請求程式碼檢閱](enable-code-review.md))
+ 設定組織特定政策驗證的安全需求 （請參閱 [管理安全需求](security-requirements.md))
+ 執行定期完整掃描以在整個程式碼庫中發現問題 （請參閱 [建立程式碼檢閱](perform-code-review-scan.md))
+ 在實作之前，對新功能規格使用威脅模型檢閱