기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# IDE에서 코드 보안 스캔 실행
Kiro 또는 Claude 코드를 사용하여 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 서버는 처음 사용할 때 에이전트 공간, 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 Marketplace에서 **AWS Security Agent** Power를 설치합니다. 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 Code
설정, 전체 스캔, diff 스캔, 위협 모델 검토 및 문제 해결에 대한 기술을 제공하는 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 리소스를 자동으로 프로비저닝합니다.
| Resource | 이름 규칙 | 용도 |
| --- | --- | --- |
| 에이전트 공간 | 사용자가 선택하거나 자동으로 생성됨 | 스캔, 검토 및 펜테스트용 컨테이너 |
| IAM 서비스 역할 | `SecurityAgentScanRole` | 업로드된 코드를 읽기 `securityagent.amazonaws.com` 위해에서 수임 |
| S3 버킷 | `security-agent-scans-{account}-{region}` | 압축된 소스 코드 저장(30일 자동 만료 수명 주기) |
설정을 명시적으로 트리거하려면 IDE에 문의하십시오.
```
Set up the security agent
```
설정은 AWS 자격 증명을 확인하고, 에이전트 스페이스를 생성 또는 재사용하고, IAM 역할 및 S3 버킷을 프로비저닝하고, 준비 상태를 확인합니다. AWS 관리 콘솔에 에이전트 스페이스가 이미 있는 경우 설정이 에이전트 스페이스를 표시하고 사용할 에이전트 스페이스를 묻습니다.
**참고**
아직 구성되지 않은 경우 첫 번째 스캔 시 설정이 자동으로 실행됩니다. 별도로 실행할 필요가 없습니다.
## 전체 보안 스캔 실행
전체 프로젝트에서 보안 취약성을 스캔합니다.
```
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는 심각도(심각 → 높음 → 중간 → 낮음)별로 조사 결과를 하향 처리하여 각 조사 결과의 수정 지침을 사용하여 코드 수정을 적용합니다. 모든 수정 사항이 적용되면 자동으로 확인 diff 스캔을 실행하여 문제가 해결되었는지 확인합니다.
개별 조사 결과를 수정할 수도 있습니다.
```
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시간 | 전체 코드베이스에 대한 포괄적인 검토 | “프로젝트에서 보안 문제 스캔” |
| Diff 스캔 | 5\~15분 | 코드만 변경됨(사전 커밋, 사전 PR) | "변경 사항 스캔" 또는 "기본 스캔" |
| 위협 모델 | 5\~30분 | 디자인 문서(requirements.md, design.md) | “내 사양에서 위협 모델 검토 실행” |
## 환경 변수
| 변수 | 설명 | 기본값 |
| --- | --- | --- |
| `AWS_REGION` | SecurityAgent API 호출을 위한 AWS 리전 | `us-east-1` |
| `AWS_PROFILE` | AWS 자격 증명 프로필 이름 | 기본 프로필 |
| `FASTMCP_LOG_LEVEL` | MCP 서버 로그 수준(디버그, 정보, 경고, 오류) | `WARNING` |
## 문제 해결
### "구성되지 않았습니다. 먼저 설정을 실행합니다.”
`.security-agent/config.json`이 없거나 에이전트 스페이스가 더 이상 존재하지 않습니다. IDE에 설정을 실행하도록 요청합니다.
```
Set up the security agent
```
### AccessDenied로 스캔 실패
AWS 자격 증명에 사전 조건 섹션에 나열된 필수 IAM 권한이 있는지 확인합니다. 가장 일반적인 누락된 권한은 입니다`iam:CreateRole`(처음 설정에만 필요).
### 스캔 시간이 초과되거나 너무 오래 걸림
+ 대규모 코드베이스에서 전체 스캔은 1시간 이상 걸릴 수 있습니다.
+ 반복 개발을 위해 차등 스캔 사용 - 몇 분 안에 완료
+ 소스 아카이브에 불필요한 디렉터리가 포함되어 있지 않은지 확인합니다(MCP 서버는 공통 패턴을 자동으로 제외함).
### 비어 있는 차이 - 스캔 변경 없음
커밋되지 않은 변경 없이 diff 스캔을 실행하면 MCP 서버는 "변경 없음 vs HEAD"를 보고하고 스캔을 시작하지 않습니다. 먼저 변경 사항을 커밋 또는 스테이징하거나 다른 기본 참조를 지정합니다.
## 할당량 및 제한
+ 최대 소스 아카이브 크기: 2GB
+ S3 버킷 수명 주기: 30일 후 업로드된 코드 자동 삭제
## 다음 단계
첫 번째 IDE 보안 스캔을 실행한 후:
+ 자동 GitHub 통합에 대한 풀 요청 코드 검토 설명 활성화( 참조[GitHub 리포지토리에 대한 풀 요청 코드 검토 활성화](enable-code-review.md))
+ 조직별 정책 검증을 위한 보안 요구 사항 구성( 참조[보안 요구 사항 관리](security-requirements.md))
+ 정기적인 전체 스캔을 실행하여 전체 코드베이스에서 문제를 파악합니다( 참조[코드 검토 생성](perform-code-review-scan.md)).
+ 구현 전에 새로운 기능 사양에 대한 위협 모델 검토 사용