Secure Agent Playbook

AI 에이전트를 위한 오픈소스 보안 플레이북입니다. 구조화된 OWASP 기반 절차를 통해 에이전트가 코드 리뷰부터 AI 에이전트 보안 감사까지 보안 엔지니어링 작업을 수행할 수 있게 합니다.

목차

• 왜 사용하나요?
• 이것은 무엇인가?
• 빠른 시작
• 스킬 카탈로그
• 에이전트
• 예시 출력
• 플레이
• 아키텍처
• OWASP 재단
• 관련 프로젝트
• 기여

왜 사용하나요?

플레이북 없이 AI 에이전트에게 "내 코드를 보안 관점에서 검토해줘"라고 요청하면 피상적인 체크리스트만 얻을 수 있습니다. 그러나 이 플레이를 사용하면 에이전트는 구조화된 OWASP 기반 절차를 따라 모든 취약점 클래스를 체계적으로 테스트하고, CWE 매핑, OpenCRE 상호 참조, 증거 스니펫, 구체적인 수정 코드가 포함된 결과를 생성합니다.

• 일관된 방법론 — 모든 평가는 임시 프롬프트가 아닌 문서화된 절차를 따릅니다. 실행과 검토자에 걸쳐 결과를 재현할 수 있습니다.
• 구조화되고 실행 가능한 결과 — 결과에는 심각도, CWE, 증거, 코드 예시가 포함된 수정 단계가 포함됩니다. 모호한 경고는 없습니다.
• 표준 간 추적성 — 결과는 OpenCRE를 통해 CWE, ASVS, WSTG, NIST 800-53에 연결되어 규정 준수 매핑을 제공합니다.
• 17가지 보안 스킬 — 종속성 CVE 스캔부터 프롬프트 인젝션 테스트, 멀티 에이전트 위협 모델링까지. Claude Code 플러그인으로 설치하거나 단독으로 사용할 수 있습니다.
• Claude Code 너머에서도 동작 — 스킬은 Claude Code 플러그인이고, 플레이는 모든 AI 에이전트가 따를 수 있는 독립형 절차입니다.

이것은 무엇인가?

이것은 프레임워크나 라이브러리가 아닙니다. 가져올 코드도 없습니다.

각 플레이는 체크리스트, 결정 기준, 출력 템플릿을 갖춘 단계별 보안 절차입니다. AI 에이전트가 이 절차를 따라 일관되고 증거 기반의 결과를 생성합니다. SOC 분석가의 플레이북과 같다고 생각하면 됩니다. 다만 AI 에이전트가 실행하도록 작성되었습니다.

빠른 시작

Claude Code 사용 시(권장):

1단계 — 플러그인 마켓플레이스 등록:

/plugin marketplace add OWASP/secure-agent-playbook

2단계 — 스킬 세트 설치:

/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

3단계 — 대화에서 작업을 언급하여 스킬 사용:

"Review this code for security issues"
"Scan my dependencies for CVEs"
"Audit this MCP server configuration"
"Test this chatbot for prompt injection"

Claude는 컨텍스트에 따라 관련 스킬을 자동으로 활성화합니다. 사용 가능한 모든 스킬은 스킬 카탈로그, 결과 예시는 예시 출력을 참조하세요.

조직 플러그인 — 조직 플러그인을 통해 설치하는 Claude 조직 관리자용:

1. 최신 릴리스로 이동
2. 릴리스 에셋에서 secure-agent-playbook.zip 다운로드
3. 조직 설정 > 플러그인 > 플러그인 추가에서 zip 업로드

참고: GitHub의 "Download ZIP" 버튼을 사용하지 마세요. 파일을 하위 디렉터리에 중첩시켜 플러그인 검증기가 거부합니다. 항상 릴리스 에셋 zip을 사용하세요.

로컬 개발 — GitHub 대신 로컬 클론으로 테스트하려면:

/plugin marketplace add /path/to/agent-security-playbook
/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Claude Code 없이 사용:

플레이를 모든 AI 에이전트 또는 수동 사용을 위한 절차로 직접 참조하세요.

• 에이전트를 플레이로 안내: "plugins/ai-security-skills/plays/agent-security-audit.md의 절차를 따르세요"
• 또는 수동 보안 검토를 위한 체크리스트로 플레이를 사용하세요

스킬 카탈로그

코드 및 인프라 보안 (code-security-skills)

AI 및 에이전트 보안 (ai-security-skills)

에이전트

에이전트는 스킬을 호출하고 구조화된 보고서를 생성하는 자율 보안 전문가입니다. 각 에이전트는 집중된 시스템 프롬프트, 범위가 제한된 도구 액세스, 사전 로드된 스킬을 보유합니다. 개별적으로 또는 조정된 팀으로 사용할 수 있습니다.

단독 사용 — 에이전트를 직접 호출:

"Use code-security-reviewer to review src/"
"Use dependency-auditor to scan this project"

팀 평가 — 에이전트 팀이 활성화되면 팀 리더가 전문가를 병렬로 파견하고 결과를 단일 보고서로 통합합니다:

"Run a full security assessment of this project"

팀 리더는 대상을 범위화하고 관련 전문가를 파견하며(초점 영역이 존재하지 않는 전문가는 건너뜀) 결과를 중복 제거하고, 도메인 간 위험 체인을 식별하며, templates/report.md를 사용하여 통합 보고서를 생성합니다.

에이전트 팀에는 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1이 필요합니다. 설정은 Claude Code 문서를 참조하세요. 개별 에이전트는 이 플래그 없이 작동합니다.

예시 출력

Node.js/Express 코드베이스에서 "Review src/auth/ for security issues"를 실행하면 다음과 같은 결과가 생성됩니다:

Security Code Review — src/auth/
Scope: Node.js/Express, server-side, processes user credentials
Findings: CRITICAL 1 | HIGH 2 | MEDIUM 1 | LOW 0

[CRITICAL] 사용자 조회의 SQL 인젝션

• CWE: CWE-89
• OpenCRE: CRE-764-507 — 인젝션 방지
• OWASP 참조: A03:2021 인젝션
• 위치: src/auth/login.js:42
• 영향: 공격자는 조작된 id 매개변수를 통해 전체 users 테이블을 추출하거나, 인증을 우회하거나, 임의의 SQL을 실행할 수 있습니다.
• 증거:
  root@kitploit:~

  // src/auth/login.js:42
  const user = await db.query("SELECT * FROM users WHERE id=" + req.params.id);
  

• 수정: 매개변수화된 쿼리 사용:
  root@kitploit:~

  const user = await db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
  

• 신뢰도: HIGH

모든 스킬은 심각도, CWE, 증거, 수정 코드가 포함된 구조화된 결과를 생성합니다. 전체 샘플 평가 보고서는 examples/를 참조하세요.

플레이

AI/에이전트 보안 플레이

차별화 요소 — AI 에이전트 시대에 맞춰 특별히 설계된 보안 절차입니다. ai-security-skills 플러그인에 포함되어 있습니다.

코드 및 종속성 분석 플레이

모든 코드베이스에 즉각적이고 실용적인 가치를 제공합니다. code-security-skills 플러그인에 포함되어 있습니다.

계획

• Tier 2: 위협 모델링, ASVS 검증, 인프라 강화
• Tier 3: WSTG 테스트 체크리스트, DAST 오케스트레이션, 공격 표면 매핑
• Tier 5: SAMM 성숙도 평가, 규정 준수 매핑, 통합 보고

아키텍처

3계층 설계 — 모든 계층은 플러그인 소스 폴더 안에 있어 마켓플레이스 설치 시 스킬에 필요한 모든 것이 함께 번들로 제공됩니다:

• plugins/<name>/agents/ — 각 플러그인 내부에 함께 위치한 집중된 시스템 프롬프트를 가진 자율 보안 전문가입니다. 각 에이전트는 하나 이상의 스킬을 호출하고 격리된 컨텍스트에서 작동하며 구조화된 보고서를 생성합니다. 단독으로 또는 조정된 팀으로 작업할 수 있습니다.
• plugins/<name>/skills/ — Agent Skills 스펙을 따르는 자체 포함 SKILL.md 파일입니다. plugins/code-security-skills/ 및 plugins/ai-security-skills/를 통해 배포되며, .claude-plugin/marketplace.json을 통해 마켓플레이스에 등록됩니다. 각 스킬은 절차를 요약하고 동일한 플러그인 내의 해당 플레이를 참조합니다.
• plugins/<name>/plays/ — 상세한 체크리스트, 표, 결정 기준, 예제가 포함된 전체 참조 절차입니다. 스킬이 포괄적인 범위를 위해 이를 참조합니다.
• plugins/<name>/templates/ 및 plugins/<name>/data/ — 스킬이 런타임에 로드하는 출력 템플릿(finding.md, report.md)과 OWASP 참조 데이터셋(FIASSE v1.0.4, ASVS v5.0, 시큐어 코드 프롬프트)입니다.

에이전트가 오케스트레이션하고, 스킬이 실행하며, 플레이가 전체 절차를 제공합니다. 기여자는 플레이를 편집합니다. 즉, 이 플레이북은 모든 AI 에이전트와 함께 작동하며(플레이를 가리키기만 하면 됨) Claude Code 사용자는 에이전트와 스킬을 포함한 플러그인 기반 설치를 사용할 수 있습니다.

OWASP 재단

모든 플레이는 OWASP 표준 및 데이터셋을 참조합니다:

• OWASP Top 10 — 웹 애플리케이션 위험
• OWASP API Security Top 10 — API 특정 위험
• OWASP Top 10 for LLM Applications — AI/LLM 위험
• OWASP Agentic Security Initiative — 자율 에이전트 위험(Agentic 애플리케이션 Top 10)
• OWASP ASVS — 보안 검증 요구사항
• OWASP MASVS — 모바일 애플리케이션 보안 검증 표준
• OWASP AISVS — AI 보안 검증 표준
• OWASP WSTG — 테스트 방법론
• OWASP SAMM — 보안 프로그램 성숙도 모델
• OWASP Cheat Sheet Series — 개발자 보안 지침
• OWASP FIASSE — 본질적으로 적응 가능하고 보안 가능한 엔지니어링을 위한 프레임워크(v1.0.4)

관련 프로젝트

기여

자세한 지침은 CONTRIBUTING.md를 참조하세요.

새 플레이는 다음을 충족해야 합니다:

• 하나의 잘 정의된 보안 작업을 해결할 것
• 명확한 트리거 조건을 포함할 것(이 플레이는 언제 실행되어야 하나요?)
• 체크포인트가 있는 구조화된 절차를 따를 것
• 플러그인 내 templates/finding.md 형식을 사용하여 결과를 생성할 것
• 해당되는 경우 OWASP 표준을 참조할 것
• 탐지를 재구현하는 대신 기존 도구(semgrep, trivy, osv-scanner, trufflehog)를 선호할 것
• 마켓플레이스 설치와 함께 제공되도록 적절한 플러그인의 plays/ 폴더 안에 위치할 것

라이선스

크리에이티브 커먼즈 저작자표시 4.0 국제(CC-BY-4.0)에 따라 라이선스가 부여됩니다. 업스트림 OWASP 프로젝트 콘텐츠의 저작자 표시는 THIRD_PARTY_NOTICES.md를 참조하세요.