# Lagune > 모든 코드베이스를 위한 Security-Driven Hardening Lagune은 오픈 소스이자 방어 전용인 Security-Driven Hardening(SDH) 워크플로입니다. 어떤 언어로 작성된 코드베이스든 모든 순간에 AI 에이전트가 보안을 강화하도록 돕습니다. 개발 전에는 charter가 보안 규칙을 정하고, 코드를 작성하는 동안에는 범용 /lagune 명령어가 보안을 강화하며, 5단계 Blue Team 흐름은 시스템이 실제로 무엇을 하는지 탐지해 그 컨텍스트에서 중요한 수정을 이끌어 갑니다. 명령어는 skills CLI로 에이전트에 설치하며, API 키가 필요 없습니다. --- # 설치: 모든 AI 에이전트를 위한 보안 강화 > 에이전트가 지원하면 플러그인으로, 그 밖의 경우에는 skills CLI로 어떤 프로젝트에든 Lagune을 설치한 뒤, 프로젝트에 맞는 보안 전문 지식을 고르세요. 표준 URL: https://lagune.ai/ko-KR/docs 언어: ko-KR 원문: https://lagune.ai/docs 마지막 업데이트: 2026-11-03 **Lagune**은 AI 에이전트가 프로젝트를 더 안전하게 만들도록 돕습니다. 코드를 대상으로 실행하면 에이전트가 시스템이 실제로 하는 일을 파악하고, 그 시스템에 중요한 보안 작업을 차근차근 안내합니다. **Lagune**은 [Security-Driven Hardening (SDH)](https://lagune.ai/ko-KR/docs/references/paper) 방법론의 첫 번째 프로젝트입니다. **오픈 소스 응원하기** **Lagune**이 마음에 드시나요? [**GitHub**에서 ⭐ 하나 눌러 주세요](https://github.com/wellwelwel/lagune) ## 에이전트 선택하기 - [Claude Code](https://lagune.ai/ko-KR/docs/install/claude-code): Anthropic의 에이전트 기반 코딩 도구 - [Codex](https://lagune.ai/ko-KR/docs/install/codex): OpenAI의 코딩 에이전트 - [Cursor](https://lagune.ai/ko-KR/docs/install/cursor): AI 코드 에디터 - [GitHub Copilot](https://lagune.ai/ko-KR/docs/install/github-copilot-cli): GitHub의 AI 페어 프로그래머 - [Gemini CLI](https://lagune.ai/ko-KR/docs/install/gemini-cli): Google의 오픈 소스 터미널 에이전트 - [Antigravity](https://lagune.ai/ko-KR/docs/install/antigravity-cli): Google의 에이전트 기반 개발 플랫폼 - [OpenCode](https://lagune.ai/ko-KR/docs/install/opencode): 오픈 소스 코딩 에이전트 - [Devin for Terminal](https://lagune.ai/ko-KR/docs/install/devin-cli): Cognition의 터미널 에이전트 - [Factory Droid](https://lagune.ai/ko-KR/docs/install/factory-droid): Factory의 소프트웨어 개발 에이전트 - [Grok Build](https://lagune.ai/ko-KR/docs/install/grok-build): xAI의 코딩 에이전트 - [Qwen Code](https://lagune.ai/ko-KR/docs/install/qwen-code): Qwen의 터미널 코딩 에이전트 - [Kimi Code](https://lagune.ai/ko-KR/docs/install/kimi-code): Moonshot AI의 코딩 에이전트 - [Muse Code](https://lagune.ai/ko-KR/docs/install/muse-code): Meta의 코딩 에이전트 - [Pi](https://lagune.ai/ko-KR/docs/install/pi): 미니멀한 터미널 코딩 에이전트 - [Hermes Agent](https://lagune.ai/ko-KR/docs/install/hermes-agent): Nous Research의 오픈 소스 에이전트 - [범용](https://lagune.ai/ko-KR/docs/install/universal): Cline, Kiro CLI, Windsurf, Zed 외 66개 **정보** - **Lagune**은 내부적으로 **Node.js**에서 실행되지만, 개발 언어는 무엇이든 자유롭게 쓸 수 있습니다. - 완전히 오프라인으로 실행하려면 `npm i -D lagune@0.16.0` 명령어로 프로젝트에 **Lagune**을 설치하세요. ## 카테고리 **Lagune**의 보안 지식은 [**카테고리**](https://lagune.ai/ko-KR/docs/categories)별로 묶인 [**전문 지식**](https://lagune.ai/ko-KR/docs/catalog) 형태로 제공됩니다. - **OWASP** (`owasp`): OWASP가 추적하는 애플리케이션 보안 위험에 대비한 보안 강화: 인젝션, 취약한 접근 통제, 인증과 암호화 실패 - **인프라** (`infra`): 컨테이너, 워크로드, 서버리스 설정 보안 강화: Dockerfile, Compose, Pod 보안, FaaS IAM과 트리거 - **AI / LLM** (`ai`): 프롬프트 인젝션과 도구, 에이전트, 검색, MCP의 안전하지 않은 연결을 막는 AI와 LLM 통합 보안 강화 - **Lovable** (`lovable`): AI로 생성한 Supabase 앱(Lovable 등) 보안 강화: RLS 허점, 유출된 service_role 키, 안전하지 않은 기본값 - **JavaScript** (`javascript`): eval과 child_process 기반 RCE, 경로 탐색(path traversal), 프로토타입 오염을 막는 JavaScript와 런타임 보안 강화 - **Python** (`python`): pickle과 YAML 역직렬화를 통한 RCE, str.format 기반 속성 탐색, 클래스 오염을 막는 Python 보안 강화 - **Rust** (`rust`): 불건전한 unsafe API, transmute 오용, 정수 오버플로, FFI 경계의 정의되지 않은 동작을 막는 Rust 보안 강화 - **Java** (`java`): 원격 코드 실행으로 이어지는 ObjectInputStream 역직렬화 가젯 체인을 막는 Java 보안 강화 - **Ruby** (`ruby`): 원격 코드 실행으로 이어지는 Marshal.load와 YAML 역직렬화 가젯 체인을 막는 Ruby 보안 강화 - **PHP** (`php`): 타입 저글링을 이용한 인증 우회, 객체 인젝션 가젯 체인, 안전하지 않은 기본 설정을 막는 PHP 보안 강화 - **Go** (`go`): typed nil 인터페이스 버그, 고루틴 데이터 레이스, 보안 관련 경로의 안전하지 않은 동시성을 막는 Go 보안 강화 - **C / C++** (`c-cpp`): 코드 실행으로 이어지는 포맷 문자열 버그, 버퍼 오버플로, 범위를 벗어난 쓰기를 막는 C와 C++ 보안 강화 - **.NET** (`dotnet`): BinaryFormatter 역직렬화를 통한 RCE와 XSS로 이어지는 인코더 우회를 막는 .NET과 C# 보안 강화 선택한 카테고리의 키를 붙여 `npx lagune write add --categories` 명령어를 실행하세요. **팁** 프로젝트는 `owasp` 카테고리로 시작하며, [`/lagune-charter`](https://lagune.ai/ko-KR/docs/commands/charter) 명령어가 프로젝트를 읽고 근거가 확인된 카테고리를 추가합니다. ## 요구 사항 시스템에 [**Node.js (LTS)**](https://nodejs.org/en/download/package-manager)가 설치되어 있어야 합니다. ## 배지 달기 ✨ **Lagune**을 사용하고 계신가요? **README**에 배지를 달아 보세요: **투톤** ![Secured By Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Secured%20By&labelColor=303952) ```md [![Secured By Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Secured%20By&labelColor=303952)](https://lagune.ai) ``` ![Security Powered By Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Security%20Powered%20By&labelColor=303952) ```md [![Security Powered By Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Security%20Powered%20By&labelColor=303952)](https://lagune.ai) ``` ![Security-Driven Hardening with Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Security-Driven%20Hardening&labelColor=303952) ```md [![Security-Driven Hardening with Lagune](https://img.shields.io/badge/Lagune-2f7bff?logo=springsecurity&logoColor=white&label=Security-Driven%20Hardening&labelColor=303952)](https://lagune.ai) ``` **단색** ![Secured By Lagune](https://img.shields.io/badge/Secured%20By%20Lagune-2f7bff?logo=springsecurity&logoColor=white) ```md [![Secured By Lagune](https://img.shields.io/badge/Secured%20By%20Lagune-2f7bff?logo=springsecurity&logoColor=white)](https://lagune.ai) ``` ![Security Powered By Lagune](https://img.shields.io/badge/Security%20Powered%20By%20Lagune-2f7bff?logo=springsecurity&logoColor=white) ```md [![Security Powered By Lagune](https://img.shields.io/badge/Security%20Powered%20By%20Lagune-2f7bff?logo=springsecurity&logoColor=white)](https://lagune.ai) ``` ![Security-Driven Hardening](https://img.shields.io/badge/Security--Driven%20Hardening-2f7bff?logo=springsecurity&logoColor=white) ```md [![Security-Driven Hardening](https://img.shields.io/badge/Security--Driven%20Hardening-2f7bff?logo=springsecurity&logoColor=white)](https://lagune.ai) ``` ## 다음 단계 **Lagune**의 각 [**스킬**](https://lagune.ai/ko-KR/docs/get-started/commands)이 무엇을 하는지 살펴보세요. ## 자주 묻는 질문 ### Lagune은 무엇인가요? Lagune은 AI 에이전트가 어떤 코드베이스든 보안을 강화하도록 돕는, 오픈 소스이자 방어 전용인 보안 워크플로입니다. 코드를 대상으로 실행하면 시스템이 실제로 하는 일을 탐지하고, 그 컨텍스트에 중요한 보안 수정을 안내합니다. ### Lagune은 어떻게 설치하나요? 사용하는 에이전트를 고르세요: Claude Code, GitHub Copilot CLI, Muse Code, Antigravity CLI, Cursor, Kimi Code, OpenCode, Codex CLI, Factory Droid, Grok Build, Devin CLI, Hermes Agent에서는 플러그인으로, Gemini CLI와 Qwen Code에서는 확장 프로그램으로, Pi에서는 패키지로 Lagune을 설치하고, 그 밖의 에이전트에서는 npx skills add wellwelwel/lagune 명령어로 설치합니다. 새 프로젝트에서도 기존 프로젝트에서도 작동합니다. ### Lagune을 쓰려면 API 키가 필요한가요? 아니요. 사용 중인 AI 에이전트를 통해 실행되므로 API 키가 필요 없습니다. ### 요구 사항은 무엇인가요? 시스템에 Node.js (LTS)가 설치되어 있어야 합니다. ### Lagune은 어떤 프로그래밍 언어를 지원하나요? 모든 언어를 지원합니다. Lagune은 내부적으로 Node.js에서 실행되지만, 어떤 프로그래밍 언어로 작성된 프로젝트든 점검하고 보안을 강화합니다. ### Lagune은 프로젝트에 무엇을 추가하나요? 프로젝트의 보안 상태를 담는 .lagune/ 디렉터리입니다. 이 디렉터리는 무언가를 처음 기록하는 명령어가 만듭니다. 또한 skills CLI는 슬래시 명령어를 프로젝트 안에 설치해 에이전트가 그곳에서 읽게 하고, 플러그인은 슬래시 명령어를 에이전트 안에 보관합니다. ### Lagune은 어떻게 업데이트하나요? 설치한 방법 그대로 업데이트합니다. 각 에이전트의 설치 페이지에서 그 에이전트로 Lagune을 업데이트하는 방법을 안내하며, skills CLI에서는 npx skills update 명령어로 업데이트합니다. 보안 원칙, 각 단계의 산출물, 직접 만든 전문 지식은 그대로 유지됩니다. ### 프로젝트는 어떤 전문 지식을 사용하나요? 프로젝트의 카테고리에 속한 내장 전문 지식과 프로젝트가 직접 만든 전문 지식입니다. charter 단계는 프로젝트를 읽고 근거가 확인된 카테고리를 기록하며, npx lagune write add --categories 명령어로 카테고리를 바꿀 수 있습니다. ### 프로젝트 개발을 다 끝내야 보안 작업을 시작할 수 있나요? 아니요. /lagune 명령어는 작성되는 작업의 보안을 그 자리에서 강화합니다: 어떤 프롬프트든 받아 요청한 것을 만들고, 보안 원칙에 따라 안전한 기본값으로 보안을 강화합니다. 이미 있는 코드는 5단계 Blue Team 흐름으로 점검합니다. ### Lagune으로 기존 프로젝트를 점검할 수 있나요? 네. 5단계 Blue Team 흐름이 이미 있는 코드를 점검합니다: charter 단계에서 보안 규칙을 정하고, detect 단계에서 시스템이 하는 일과 위험이 있는 곳을 파악하며, plan 단계에서 발견 사항마다 점수를 매기고 알맞은 수정을 짝지어 줍니다. 이어서 harden 단계에서 수정을 적용하고, verify 단계에서 수정이 실제로 효과가 있는지 증명한 뒤 종결합니다. ### Lagune을 쓰는 것과 에이전트에게 그냥 취약점과 보안 결함을 찾아 달라고 하는 것은 무엇이 다른가요? 에이전트가 혼자 코드를 읽으면 취약점처럼 보이는 것은 찾아내지만, 보안 통제처럼 보이는 것은 그냥 지나칩니다. 차단할 주소 목록이 있으면 누군가 이미 위험을 처리한 것처럼 보이기 때문에, 그 목록이 대부분의 주소를 놓친다는 사실을 아무도 확인하지 않은 채 코드가 배포됩니다. Lagune은 이 기본 전제를 뒤집습니다: 코드에 이미 있는 방어 장치는 확인하기 전까지 증명되지 않은 것으로 보고, 카탈로그의 모든 전문 지식에 명시적인 판정을 내리며, verify 단계는 보안 통제가 있는지가 아니라 위험이 사라졌는지를 묻습니다. 또한 각 발견 사항은 실행을 거듭해도 하나의 추적 항목으로 유지되므로, 위험이 해소되었음을 증명하고 종결할 수 있습니다. 반면 그냥 요청하면 매번 다른 보고서가 나와서 비교할 기준이 없습니다. ### Lagune으로 개발하는 것과 에이전트에게 그냥 안전한 코드를 작성해 달라고 하는 것은 무엇이 다른가요? 안전한 코드를 달라고만 하면 무엇이 안전한지는 에이전트가 정하게 되고, 무엇을 요청해야 하는지 이미 안다고 가정하게 됩니다. 보안 요구 사항은 대개 요청 안에 이미 들어 있지만, 요청한 사람도 에이전트도 알아차리지 못합니다: 사용자가 접근할 수 있는 강의를 보여 주는 페이지를 요청하는 것 자체가 인가 규칙을 말하는 것이고, 한 번도 작성되지 않은 검사는 코드에 눈여겨볼 흔적을 전혀 남기지 않습니다. /lagune 명령어는 첫 줄을 작성하기 전에 보안 원칙과 앞으로 만들 것에 맞는 전문 지식을 불러오고, 다 만든 뒤에는 사용한 방어 기준에 비추어 결과를 다시 읽습니다. 안전한 방식이 안전하지 않은 방식보다 비용이 더 드는 경우는 드물기 때문에, 결과를 가르는 것은 어느 쪽을 택해야 하는지 아는 것이며, 바로 그 지식이 처음부터 주어집니다. ### Lagune은 DAST(동적 애플리케이션 보안 테스트)를 실행하거나 실행 중인 애플리케이션을 테스트하나요? 아니요. Lagune은 코드를 읽을 뿐, 시스템을 실행하거나 조작된 요청을 보내지 않습니다. verify 단계는 보안 통제가 소스 코드에 존재하고 올바르게 구현되었는지를 확인합니다. 이는 실제로 운영 중인 대상에서 보안 통제가 공격을 견디는지와는 다른 질문이므로, "cannot tell from the code"(코드만으로는 판단할 수 없음)는 슬그머니 통과로 처리하는 대신 내리는 정당한 판정입니다. DAST는 런타임에 관한 질문에, Lagune은 소스 코드에 관한 질문에 답하므로 어느 쪽도 다른 쪽을 대신하지 않습니다. 선택 사항인 prove 명령어조차 이 선을 지킵니다: prove 명령어의 테스트가 검증하는 것은 언제나 안전한 동작이며, 공격 페이로드가 아닙니다. ### Lagune이 펜테스트(침투 테스트)를 대신할 수 있나요? 아니요, 절대 그렇지 않습니다! 펜테스트는 승인을 받은 전문가가 실제로 운영 중인 시스템을 상대로 직접 판단하며 진행하는 작업으로, 여러 발견 사항을 엮어 보고 공격 표면별 규칙으로는 설명할 수 없는 비즈니스 로직까지 파고듭니다. 펜테스트에서 나온 발견 사항은 detect 단계에 우려 사항으로 넘겨 Lagune의 Blue Team 흐름에 넣을 수 있으므로, 전문가가 보고한 내용도 계획하고, 보안을 강화하고, 검증할 수 있습니다. ## 보안 정책 [SECURITY.md](https://github.com/wellwelwel/lagune/blob/main/SECURITY.md) 파일을 확인하세요. ## 라이선스 **Lagune**은 [Apache License 2.0](https://github.com/wellwelwel/lagune/blob/main/LICENSE)에 따라 배포됩니다. Copyright © 2026-present [Weslley Araújo](https://github.com/wellwelwel) 및 [기여자](https://github.com/wellwelwel/lagune/graphs/contributors). --- # Antigravity CLI에 Lagune 플러그인 설치하기 > Antigravity CLI에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/antigravity-cli 언어: ko-KR 원문: https://lagune.ai/docs/install/antigravity-cli 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash agy plugin install https://github.com/wellwelwel/lagune/tree/plugin-antigravity ``` ## 업데이트 **Lagune**을 업데이트하려면 다시 설치하세요: ```bash agy plugin install https://github.com/wellwelwel/lagune/tree/plugin-antigravity ``` ## 명령어 명령어는 플러그인 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. 세션의 첫 메시지로 보낸 명령어는 두 도구를 불러오기 전에 실행되므로 대신 **npx**를 사용합니다. 두 도구와 **npx**를 미리 허용하려면 `~/.gemini/antigravity-cli/settings.json` 파일에 다음 규칙을 추가하세요: ```json { "permissions": { "allow": [ "mcp(lagune_lagune/lagune_read)", "mcp(lagune_lagune/lagune_write)", "command(regex:npx --yes lagune@[0-9.]+)" ] } } ``` ## 자주 묻는 질문 ### Antigravity CLI에 Lagune을 설치하려면 어떻게 하나요? agy plugin install https://github.com/wellwelwel/lagune/tree/plugin-antigravity 명령어를 실행하세요. ### Antigravity CLI에서 Lagune을 업데이트하려면 어떻게 하나요? agy plugin install https://github.com/wellwelwel/lagune/tree/plugin-antigravity 명령어를 다시 실행하세요. ### Antigravity CLI에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하세요. ### Antigravity CLI가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Antigravity CLI 설정에서 mcp(lagune_lagune/lagune_read), mcp(lagune_lagune/lagune_write), command(regex:npx --yes lagune@[0-9.]+) 규칙을 허용하세요. npx 규칙은 세션의 첫 메시지로 보낸 명령어에 적용됩니다. --- # Claude Code에 Lagune 플러그인 설치하기 > 터미널, 확장 프로그램 또는 데스크톱 앱의 Claude Code에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/claude-code 언어: ko-KR 원문: https://lagune.ai/docs/install/claude-code 마지막 업데이트: 2026-11-03 **터미널** 터미널에서 플러그인을 설치하세요: ```bash claude plugin install lagune --marketplace wellwelwel/lagune ``` 또는 **Claude Code** 세션에서 설치하세요: ```text /plugin marketplace add wellwelwel/lagune /plugin install lagune@lagune ``` **확장 프로그램** - `/plugin` 명령어를 입력하고 **Manage plugins**를 선택하세요. - **Marketplaces** 탭에서 `wellwelwel/lagune` 마켓플레이스를 추가하세요. - **Plugins** 탭에서 `lagune` 플러그인을 설치하세요. **데스크톱** - 터미널이나 확장 프로그램에서 **Lagune**을 설치하세요. 확장 프로그램에서는 **Install for you**를 선택하세요. - 데스크톱 앱에서 새 세션을 시작하세요. 데스크톱 앱은 개인용으로 설치한 플러그인을 불러옵니다. ## 업데이트 **터미널** **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash claude plugin marketplace update lagune claude plugin update lagune@lagune ``` 계속 최신 상태로 유지하려면 `lagune` 마켓플레이스의 **Enable auto-update** 옵션을 `/plugin` 메뉴에서 선택하세요. **확장 프로그램** - `/plugin` 명령어를 입력하고 **Manage plugins**를 선택하세요. - **Marketplaces** 탭을 여세요. - `lagune` 마켓플레이스의 새로고침 아이콘을 선택하세요. **데스크톱** - 터미널이나 확장 프로그램에서 **Lagune**을 업데이트하세요. - 데스크톱 앱에서 새 세션을 시작하세요. ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하거나, `/lagune:lagune-charter` 명령어처럼 플러그인 이름을 붙여 입력하세요. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. 두 도구를 미리 허용하려면 한 프로젝트에만 적용할 때는 `.claude/settings.json` 파일에, 모든 프로젝트에 적용할 때는 `~/.claude/settings.json` 파일에 다음 규칙을 추가하세요: ```json { "permissions": { "allow": [ "mcp__plugin_lagune_lagune__lagune_read", "mcp__plugin_lagune_lagune__lagune_write" ] } } ``` **skills.sh**로 설치한 경우처럼 엔진이 **npx**를 통해 실행될 때는 `Bash(npx --yes lagune@*)` 규칙을 허용하세요. 샌드박스를 켰다면 `registry.npmjs.org` 도메인도 `sandbox.network.allowedDomains` 목록에 추가하세요. ## 자주 묻는 질문 ### Claude Code에 Lagune을 설치하려면 어떻게 하나요? claude plugin install lagune --marketplace wellwelwel/lagune 명령어를 실행하세요. 세션이나 확장 프로그램에서는 플러그인 관리자에서 wellwelwel/lagune 마켓플레이스를 추가하고 lagune 플러그인을 설치하세요. 터미널이나 확장 프로그램에서 개인용으로 설치하면 데스크톱 앱도 플러그인을 불러옵니다. ### Claude Code에서 Lagune을 업데이트하려면 어떻게 하나요? claude plugin marketplace update lagune 명령어에 이어 claude plugin update lagune@lagune 명령어를 실행하거나, /plugin 메뉴에서 lagune 마켓플레이스의 Enable auto-update 옵션을 선택하세요. 확장 프로그램에서는 /plugin 명령어로 Manage plugins를 열고 lagune 마켓플레이스의 새로고침 아이콘을 선택하세요. 데스크톱 앱은 다음 세션에서 업데이트를 불러옵니다. ### Claude Code에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하거나, /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하세요. ### Claude Code가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Claude Code 설정에서 mcp__plugin_lagune_lagune__lagune_read 규칙과 mcp__plugin_lagune_lagune__lagune_write 규칙을 허용하고, 엔진이 npx를 통해 실행될 때는 Bash(npx --yes lagune@*) 규칙도 허용하세요. --- # Codex CLI에 Lagune 플러그인 설치하기 > Codex CLI에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 샌드박스 안에서 엔진을 실행하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/codex 언어: ko-KR 원문: https://lagune.ai/docs/install/codex 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash codex plugin marketplace add wellwelwel/lagune codex plugin add lagune@lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash codex plugin marketplace upgrade lagune ``` ## 명령어 `$` 기호에 이어 플러그인 이름을 붙인 명령어를 입력하고, 그 뒤에 입력 내용을 덧붙이세요. 예를 들어 `$lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. `$` 기호를 입력하면 명령어 목록이 나타나고, 하나를 고르면 전체 이름이 입력됩니다. --- **권한** **Codex**의 샌드박스는 네트워크에 접근할 수 없습니다. 처음 한 번, 그리고 업데이트할 때마다 직접 터미널에서 프로젝트에 엔진을 설치하세요: ```bash npm i -D lagune@0.16.0 ``` ## 자주 묻는 질문 ### Codex CLI에 Lagune을 설치하려면 어떻게 하나요? codex plugin marketplace add wellwelwel/lagune 명령어에 이어 codex plugin add lagune@lagune 명령어를 실행하세요. ### Codex CLI에서 Lagune을 업데이트하려면 어떻게 하나요? codex plugin marketplace upgrade lagune 명령어를 실행하세요. ### Codex CLI에서 Lagune 명령어를 실행하려면 어떻게 하나요? $lagune:lagune-charter 명령어처럼 $ 기호에 이어 플러그인 이름을 붙인 명령어를 입력하고, 그 뒤에 입력 내용을 덧붙이세요. ### Codex 샌드박스 안에서도 Lagune이 작동하나요? 네. 처음 한 번, 그리고 업데이트할 때마다 직접 터미널에서 npm i -D lagune@0.16.0 명령어로 프로젝트에 엔진을 설치하면 작동합니다. --- # Cursor에 Lagune 플러그인 설치하기 > Cursor와 Cursor CLI에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/cursor 언어: ko-KR 원문: https://lagune.ai/docs/install/cursor 마지막 업데이트: 2026-11-03 **Cursor** - **Customize**를 여세요. - **From GitHub Repository**를 선택하고 `https://github.com/wellwelwel/lagune` 주소를 입력하세요. - **Lagune**의 **Install**을 선택하고 프로젝트 범위나 사용자 범위를 고르세요. **Cursor CLI** - 터미널에서 마켓플레이스를 추가하세요: ```bash agent plugin marketplace add https://github.com/wellwelwel/lagune --git-ref plugin-cursor ``` - `/plugins` 명령어를 `agent` 세션에서 입력하세요. - **Lagune**을 설치하세요. **Claude Code**에 **Lagune**이 이미 설치되어 있다면 **Cursor CLI**가 그곳에서 불러옵니다. ## 업데이트 **Cursor** - **Customize**를 여세요. - `lagune` 마켓플레이스의 **Refresh**를 선택하세요. **Cursor CLI** - 터미널에서 마켓플레이스를 교체하세요: ```bash agent plugin marketplace remove lagune agent plugin marketplace add https://github.com/wellwelwel/lagune --git-ref plugin-cursor ``` - `/plugins` 명령어를 `agent` 세션에서 입력하세요. - **Lagune**을 다시 설치하세요. ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하세요. --- **권한** **Cursor**에서는 명령어가 **npx**를 통해 엔진을 실행하며, 기본 Auto-review 모드가 이를 확인 없이 허용합니다. **Cursor CLI**에서는 엔진이 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. 두 도구를 미리 허용하려면 한 프로젝트에만 적용할 때는 `.cursor/cli.json` 파일에, 모든 프로젝트에 적용할 때는 `~/.cursor/cli-config.json` 파일에 다음 규칙을 추가하세요: ```json { "permissions": { "allow": [ "Mcp(plugin-lagune-lagune:lagune_read)", "Mcp(plugin-lagune-lagune:lagune_write)" ] } } ``` **skills.sh**로 설치한 경우처럼 엔진이 **npx**를 통해 실행될 때는 `Shell(npx:--yes lagune@*)` 규칙을 허용하세요. ## 자주 묻는 질문 ### Cursor에 Lagune을 설치하려면 어떻게 하나요? Cursor에서는 Customize를 열고 From GitHub Repository를 선택한 다음, https://github.com/wellwelwel/lagune 주소를 입력하고 Lagune을 설치하세요. Cursor CLI에서는 agent plugin marketplace add https://github.com/wellwelwel/lagune --git-ref plugin-cursor 명령어를 실행한 다음 /plugins 메뉴에서 Lagune을 설치하세요. ### Cursor에서 Lagune을 업데이트하려면 어떻게 하나요? Cursor에서는 Customize에서 lagune 마켓플레이스의 Refresh를 선택하세요. Cursor CLI에서는 lagune 마켓플레이스를 제거했다가 다시 추가한 다음, /plugins 메뉴에서 Lagune을 다시 설치하세요. ### Cursor에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하세요. ### Cursor가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Cursor의 기본 Auto-review 모드가 이미 허용합니다. Cursor CLI에서는 Mcp(plugin-lagune-lagune:lagune_read) 규칙과 Mcp(plugin-lagune-lagune:lagune_write) 규칙을 허용하고, 엔진이 npx를 통해 실행될 때는 Shell(npx:--yes lagune@*) 규칙도 허용하세요. --- # Devin CLI에 Lagune 플러그인 설치하기 > Devin CLI에 Lagune을 플러그인으로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/devin-cli 언어: ko-KR 원문: https://lagune.ai/docs/install/devin-cli 마지막 업데이트: 2026-11-03 **Devin**에 로그인한 다음 터미널에서 플러그인을 설치하세요: ```bash devin auth login devin plugins install wellwelwel/lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash devin plugins update lagune ``` ## 명령어 명령어는 플러그인 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. `/` 메뉴에서도 명령어 목록을 볼 수 있습니다. ## 자주 묻는 질문 ### Devin CLI에 Lagune을 설치하려면 어떻게 하나요? devin auth login 명령어로 로그인한 다음 devin plugins install wellwelwel/lagune 명령어를 실행하세요. ### Devin CLI에서 Lagune을 업데이트하려면 어떻게 하나요? devin plugins update lagune 명령어를 실행하세요. ### Devin CLI에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하세요. / 메뉴에서도 명령어 목록을 볼 수 있습니다. --- # Factory Droid에 Lagune 플러그인 설치하기 > Factory Droid에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 엔진 도구를 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/factory-droid 언어: ko-KR 원문: https://lagune.ai/docs/install/factory-droid 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash droid plugin marketplace add wellwelwel/lagune droid plugin install lagune@lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash droid plugin marketplace update lagune droid plugin update lagune@lagune ``` ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하세요. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. **Factory Droid**가 권한을 요청하면 각 도구를 항상 허용하도록 선택하세요. `lagune` 마켓플레이스의 새 커밋을 동기화한 뒤에는 다시 요청하며, 이 동기화는 **Factory Droid**가 시작할 때 일어날 수 있습니다. ## 자주 묻는 질문 ### Factory Droid에 Lagune을 설치하려면 어떻게 하나요? droid plugin marketplace add wellwelwel/lagune 명령어에 이어 droid plugin install lagune@lagune 명령어를 실행하세요. ### Factory Droid에서 Lagune을 업데이트하려면 어떻게 하나요? droid plugin marketplace update lagune 명령어에 이어 droid plugin update lagune@lagune 명령어를 실행하세요. ### Factory Droid에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하세요. ### Factory Droid가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Factory Droid가 권한을 요청하면 lagune_read 도구와 lagune_write 도구를 항상 허용하도록 선택하세요. lagune 마켓플레이스의 새 커밋을 동기화한 뒤에는 다시 요청합니다. --- # Gemini CLI에 Lagune 확장 프로그램 설치하기 > Gemini CLI에 Lagune을 확장 프로그램으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/gemini-cli 언어: ko-KR 원문: https://lagune.ai/docs/install/gemini-cli 마지막 업데이트: 2026-11-03 터미널에서 확장 프로그램을 설치하세요: ```bash gemini extensions install https://github.com/wellwelwel/lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash gemini extensions update lagune ``` 계속 최신 상태로 유지하려면 `--auto-update` 옵션을 붙여 설치하세요. ## 명령어 명령어는 확장 프로그램 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. **Gemini CLI**는 신뢰할 수 있는 폴더에서만 두 도구를 실행합니다. 두 도구를 미리 허용하려면 다음 규칙을 `~/.gemini/policies/lagune.toml` 파일로 저장하세요: ```toml [[rule]] mcpName = "lagune" toolName = ["lagune_read", "lagune_write"] decision = "allow" priority = 100 ``` **skills.sh**로 설치한 경우처럼 엔진이 **npx**를 통해 실행될 때는 같은 파일에 다음 규칙을 추가하세요: ```toml [[rule]] toolName = "run_shell_command" commandRegex = 'npx --yes lagune@\d+\.\d+\.\d+\s' decision = "allow" priority = 100 ``` ## 자주 묻는 질문 ### Gemini CLI에 Lagune을 설치하려면 어떻게 하나요? gemini extensions install https://github.com/wellwelwel/lagune 명령어를 실행하세요. ### Gemini CLI에서 Lagune을 업데이트하려면 어떻게 하나요? gemini extensions update lagune 명령어를 실행하거나, --auto-update 옵션을 붙여 확장 프로그램을 설치하세요. ### Gemini CLI에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어처럼 확장 프로그램 이름을 붙여 입력하세요. ### Gemini CLI가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. lagune 서버의 lagune_read 도구와 lagune_write 도구를 허용하는 정책 규칙을 추가하고, 엔진이 npx를 통해 실행될 때는 run_shell_command 도구에서 npx --yes lagune@ 뒤에 버전이 붙은 명령어를 허용하는 규칙도 추가하세요. --- # GitHub Copilot CLI에 Lagune 플러그인 설치하기 > GitHub Copilot CLI에 Lagune을 플러그인으로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/github-copilot-cli 언어: ko-KR 원문: https://lagune.ai/docs/install/github-copilot-cli 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash copilot plugin marketplace add wellwelwel/lagune copilot plugin install lagune@lagune ``` 에디터에서는 [**skills.sh**](https://lagune.ai/ko-KR/docs/install/universal)로 **GitHub Copilot**용 **Lagune**을 설치하세요. ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash copilot plugin marketplace update lagune copilot plugin update lagune@lagune ``` ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하세요. ## 자주 묻는 질문 ### GitHub Copilot CLI에 Lagune을 설치하려면 어떻게 하나요? copilot plugin marketplace add wellwelwel/lagune 명령어에 이어 copilot plugin install lagune@lagune 명령어를 실행하세요. ### GitHub Copilot CLI에서 Lagune을 업데이트하려면 어떻게 하나요? copilot plugin marketplace update lagune 명령어에 이어 copilot plugin update lagune@lagune 명령어를 실행하세요. ### GitHub Copilot CLI에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하세요. ### VS Code의 GitHub Copilot에서도 Lagune을 사용할 수 있나요? 네. VS Code나 다른 에디터에서는 플러그인 대신 skills.sh로 Lagune을 설치하세요. --- # Grok Build에 Lagune 플러그인 설치하기 > Grok Build에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/grok-build 언어: ko-KR 원문: https://lagune.ai/docs/install/grok-build 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash grok plugin install wellwelwel/lagune@plugin-grok --trust ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash grok plugin update lagune ``` ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하거나, `/lagune:lagune-charter` 명령어처럼 플러그인 이름을 붙여 입력하세요. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. 두 도구를 미리 허용하려면 `~/.grok/config.toml` 파일에 다음 규칙을 추가하세요: ```toml [permission] allow = ["MCPTool(lagune__lagune_read)", "MCPTool(lagune__lagune_write)"] ``` **skills.sh**로 설치한 경우처럼 엔진이 **npx**를 통해 실행될 때는 `Bash(npx --yes lagune@*)` 규칙을 허용하세요. ## 자주 묻는 질문 ### Grok Build에 Lagune을 설치하려면 어떻게 하나요? grok plugin install wellwelwel/lagune@plugin-grok --trust 명령어를 실행하세요. ### Grok Build에서 Lagune을 업데이트하려면 어떻게 하나요? grok plugin update lagune 명령어를 실행하세요. ### Grok Build에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하거나, /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하세요. ### Grok Build가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Grok Build 설정에서 MCPTool(lagune__lagune_read) 규칙과 MCPTool(lagune__lagune_write) 규칙을 허용하고, 엔진이 npx를 통해 실행될 때는 Bash(npx --yes lagune@*) 규칙도 허용하세요. --- # Hermes Agent에 Lagune 플러그인 설치하기 > Hermes Agent에 Lagune을 플러그인으로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/hermes-agent 언어: ko-KR 원문: https://lagune.ai/docs/install/hermes-agent 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash hermes plugins install wellwelwel/lagune --enable ``` - **Hermes Agent**가 자체 카탈로그에 없는 플러그인을 확인해 달라고 하면 **승인하세요**. - 저장소의 **Node.js** 의존성 설치를 제안하면 **거절하세요**. ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash hermes plugins update lagune ``` ## 명령어 명령어는 플러그인 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가, `/lagune:lagune` 명령어를 입력하면 `/lagune` 명령어가 실행됩니다. ## 자주 묻는 질문 ### Hermes Agent에 Lagune을 설치하려면 어떻게 하나요? hermes plugins install wellwelwel/lagune --enable 명령어를 실행하세요. 확인을 요청하면 플러그인을 승인하고, 저장소의 Node.js 의존성 설치는 거절하세요. ### Hermes Agent에서 Lagune을 업데이트하려면 어떻게 하나요? hermes plugins update lagune 명령어를 실행하세요. ### Hermes Agent에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어와 /lagune:lagune 명령어처럼 플러그인 이름을 붙여 입력하세요. --- # Kimi Code에 Lagune 플러그인 설치하기 > Kimi Code에 Lagune을 플러그인으로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/kimi-code 언어: ko-KR 원문: https://lagune.ai/docs/install/kimi-code 마지막 업데이트: 2026-11-03 **Kimi Code** 세션에서 플러그인을 설치하고 **Trust and install**을 선택한 다음, 새 세션을 시작해 플러그인을 불러오세요: ```text /plugins install https://github.com/wellwelwel/lagune /new ``` ## 업데이트 **Lagune**을 업데이트하려면 다시 설치하세요: ```text /plugins install https://github.com/wellwelwel/lagune /new ``` ## 명령어 명령어는 플러그인 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. `/` 메뉴에는 명령어가 `/skill:lagune:lagune-charter` 형식으로 표시되며, 이 형식으로 입력해도 실행됩니다. ## 자주 묻는 질문 ### Kimi Code에 Lagune을 설치하려면 어떻게 하나요? Kimi Code 세션에서 /plugins install https://github.com/wellwelwel/lagune 명령어를 실행하고 Trust and install을 선택한 다음 /new 명령어를 실행하세요. ### Kimi Code에서 Lagune을 업데이트하려면 어떻게 하나요? /plugins install https://github.com/wellwelwel/lagune 명령어를 다시 실행한 다음 /new 명령어를 실행하세요. ### Kimi Code에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하거나, /skill:lagune:lagune-charter 명령어처럼 / 메뉴에 표시되는 형식으로 입력하세요. --- # Muse Code에 Lagune 플러그인 설치하기 > Muse Code에 Lagune을 플러그인으로 설치하고, 최신 상태로 유지하며, 샌드박스 안에서 엔진을 실행하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/muse-code 언어: ko-KR 원문: https://lagune.ai/docs/install/muse-code 마지막 업데이트: 2026-11-03 터미널에서 플러그인을 설치하세요: ```bash muse plugins marketplace add lagune wellwelwel/lagune muse plugins install lagune@lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 마켓플레이스를 새로 고친 다음 플러그인을 다시 설치하세요: ```bash muse plugins marketplace update lagune muse plugins remove lagune muse plugins install lagune@lagune ``` ## 명령어 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하거나, `/lagune:lagune-charter` 명령어처럼 플러그인 이름을 붙여 입력하세요. --- **권한** **Muse Code**의 샌드박스는 엔진을 다운로드할 수 없습니다. 처음 한 번, 그리고 업데이트할 때마다 직접 터미널에서 프로젝트에 엔진을 설치하세요: ```bash npm i -D lagune@0.16.0 ``` ## 자주 묻는 질문 ### Muse Code에 Lagune을 설치하려면 어떻게 하나요? muse plugins marketplace add lagune wellwelwel/lagune 명령어에 이어 muse plugins install lagune@lagune 명령어를 실행하세요. ### Muse Code에서 Lagune을 업데이트하려면 어떻게 하나요? muse plugins marketplace update lagune 명령어를 실행한 다음 muse plugins remove lagune 명령어와 muse plugins install lagune@lagune 명령어로 다시 설치하세요. ### Muse Code에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune-charter 명령어처럼 이름 그대로 입력하거나, /lagune:lagune-charter 명령어처럼 플러그인 이름을 붙여 입력하세요. ### Muse Code 샌드박스 안에서도 Lagune이 작동하나요? 네. 처음 한 번, 그리고 업데이트할 때마다 직접 터미널에서 npm i -D lagune@0.16.0 명령어로 프로젝트에 엔진을 설치하면 작동합니다. --- # OpenCode에 Lagune 플러그인 설치하기 > OpenCode 1.x와 2.x에 Lagune을 플러그인으로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/opencode 언어: ko-KR 원문: https://lagune.ai/docs/install/opencode 마지막 업데이트: 2026-11-03 **OpenCode 2.x** 터미널에서 플러그인을 설치하세요: ```bash opencode plugin add lagune ``` 또는 `plugins` 목록(`opencode.json` 파일)에 추가하세요: ```json { "plugins": ["lagune"] } ``` **OpenCode 1.x** 터미널에서 프로젝트에 플러그인을 설치하거나, `-g` 옵션을 붙여 모든 프로젝트에 설치하세요: ```bash opencode plugin lagune ``` 또는 `plugin` 목록(`opencode.json` 파일)에 추가하세요: ```json { "plugin": ["lagune"] } ``` ## 업데이트 **OpenCode 2.x** **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash opencode plugin update lagune opencode reload ``` **OpenCode 1.x** **Lagune**을 업데이트하려면 기존 릴리스 위에 새 릴리스를 덮어 설치하되, 모든 프로젝트에 설치했다면 `-g` 옵션을 붙이세요: ```bash opencode plugin lagune@0.16.0 --force ``` ## 명령어 **OpenCode 2.x** `@` 기호를 입력하고 `@lagune-charter` 명령어처럼 실행할 명령어를 고른 다음, 같은 메시지에 입력 내용을 이어서 작성하세요. **OpenCode 1.x** 명령어는 `/lagune-charter` 명령어처럼 이름 그대로 입력하세요. 명령어는 `/skills` 목록에 표시되며, `/` 메뉴에는 표시되지 않습니다. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. **OpenCode**는 두 도구를 권한 요청 없이 실행합니다. ## 자주 묻는 질문 ### OpenCode에 Lagune을 설치하려면 어떻게 하나요? OpenCode 2.x에서는 opencode plugin add lagune 명령어를 실행하세요. OpenCode 1.x에서는 opencode plugin lagune 명령어를 실행하고, 모든 프로젝트에 설치하려면 -g 옵션을 붙이세요. ### OpenCode에서 Lagune을 업데이트하려면 어떻게 하나요? OpenCode 2.x에서는 opencode plugin update lagune 명령어에 이어 opencode reload 명령어를 실행하세요. OpenCode 1.x에서는 opencode plugin lagune@0.16.0 --force 명령어를 실행하세요. ### OpenCode에서 Lagune 명령어를 실행하려면 어떻게 하나요? OpenCode 2.x에서는 @ 기호를 입력하고 @lagune-charter 명령어처럼 실행할 명령어를 고른 다음, 같은 메시지에 입력 내용을 이어서 작성하세요. OpenCode 1.x에서는 /lagune-charter 명령어처럼 이름 그대로 입력하거나, /skills 목록에서 찾으세요. ### OpenCode는 Lagune이 실행되기 전에 권한을 요청하나요? 아니요. OpenCode는 엔진의 두 도구인 lagune_read 도구와 lagune_write 도구를 권한 요청 없이 실행합니다. --- # Pi에 Lagune 패키지 설치하기 > Pi에 Lagune을 npm 또는 GitHub에서 패키지로 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/pi 언어: ko-KR 원문: https://lagune.ai/docs/install/pi 마지막 업데이트: 2026-11-03 **npm** 터미널에서 패키지를 설치하세요: ```bash pi install npm:lagune ``` **GitHub** **GitHub**에서 최신 커밋을 설치하세요. 이렇게 설치하면 엔진이 **npx**를 통해 실행됩니다: ```bash pi install git:github.com/wellwelwel/lagune ``` ## 업데이트 **npm** **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash pi update npm:lagune ``` **GitHub** **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash pi update git:github.com/wellwelwel/lagune ``` `pi update --extensions` 명령어는 설치한 모든 패키지를 업데이트하고, `pi update` 명령어만 실행하면 **Pi**만 업데이트됩니다. ## 명령어 명령어는 `skill:` 접두사를 붙여 입력하세요. 예를 들어 `/skill:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. ## 자주 묻는 질문 ### Pi에 Lagune을 설치하려면 어떻게 하나요? pi install npm:lagune 명령어를 실행하거나, GitHub의 최신 커밋을 설치하려면 pi install git:github.com/wellwelwel/lagune 명령어를 실행하세요. ### Pi에서 Lagune을 업데이트하려면 어떻게 하나요? pi update npm:lagune 명령어를 실행하거나, GitHub에서 설치했다면 pi update git:github.com/wellwelwel/lagune 명령어를 실행하세요. pi update --extensions 명령어는 설치한 모든 패키지를 업데이트합니다. ### Pi에서 Lagune 명령어를 실행하려면 어떻게 하나요? /skill:lagune-charter 명령어처럼 skill: 접두사를 붙여 입력하세요. --- # Qwen Code에 Lagune 확장 프로그램 설치하기 > Qwen Code에 Lagune을 확장 프로그램으로 설치하고, 최신 상태로 유지하며, 엔진 실행을 미리 허용하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/qwen-code 언어: ko-KR 원문: https://lagune.ai/docs/install/qwen-code 마지막 업데이트: 2026-11-03 터미널에서 확장 프로그램을 설치하세요: ```bash qwen extensions install lagune ``` ## 업데이트 **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash qwen extensions update lagune ``` 계속 최신 상태로 유지하려면 `--auto-update` 옵션을 붙여 설치하세요. ## 명령어 명령어는 확장 프로그램 이름을 붙여 입력하세요. 예를 들어 `/lagune:lagune-charter` 명령어를 입력하면 `/lagune-charter` 명령어가 실행됩니다. --- **권한** 엔진은 두 도구를 통해 실행됩니다: `lagune_read` 도구는 프로젝트를 읽기만 하고, `lagune_write` 도구는 `.lagune/` 폴더에만 씁니다. 두 도구를 미리 허용하려면 한 프로젝트에만 적용할 때는 `.qwen/settings.json` 파일에, 모든 프로젝트에 적용할 때는 `~/.qwen/settings.json` 파일에 다음 규칙을 추가하세요: ```json { "permissions": { "allow": ["mcp__lagune__lagune_read", "mcp__lagune__lagune_write"] } } ``` **skills.sh**로 설치한 경우처럼 엔진이 **npx**를 통해 실행될 때는 `Shell(npx --yes lagune@*)` 규칙을 허용하세요. ## 자주 묻는 질문 ### Qwen Code에 Lagune을 설치하려면 어떻게 하나요? qwen extensions install lagune 명령어를 실행하세요. ### Qwen Code에서 Lagune을 업데이트하려면 어떻게 하나요? qwen extensions update lagune 명령어를 실행하거나, --auto-update 옵션을 붙여 확장 프로그램을 설치하세요. ### Qwen Code에서 Lagune 명령어를 실행하려면 어떻게 하나요? /lagune:lagune-charter 명령어처럼 확장 프로그램 이름을 붙여 입력하세요. ### Qwen Code가 권한 요청 없이 Lagune을 실행할 수 있나요? 네. Qwen Code 설정에서 mcp__lagune__lagune_read 규칙과 mcp__lagune__lagune_write 규칙을 허용하고, 엔진이 npx를 통해 실행될 때는 Shell(npx --yes lagune@*) 규칙도 허용하세요. --- # skills.sh로 어떤 에이전트에든 Lagune 설치하기 > skills CLI로 어떤 AI 에이전트에든 Lagune을 설치하고 최신 상태로 유지하세요. 표준 URL: https://lagune.ai/ko-KR/docs/install/universal 언어: ko-KR 원문: https://lagune.ai/docs/install/universal 마지막 업데이트: 2026-11-03 **터미널** [**skills.sh**](https://www.skills.sh/wellwelwel/lagune)로 터미널에서 **Lagune** 명령어를 설치하세요: ```bash npx skills add wellwelwel/lagune ``` **프롬프트** 에이전트에 다음 프롬프트를 붙여 넣으세요: ```md `npx --yes skills add wellwelwel/lagune` 명령어를 실행하고, 생성된 스킬 지침을 지금 바로 따라 줘. 필요하면 먼저 임시 파일로 리디렉션해서 출력 전체를 읽어 줘. 상대 경로는 출력에 표시된 지원 파일 디렉터리를 기준으로 해석해 줘. ``` ## 업데이트 **터미널** **Lagune**을 업데이트하려면 다음 명령어를 실행하세요: ```bash npx skills update ``` **프롬프트** **Lagune**을 업데이트하려면 에이전트에 다음 프롬프트를 붙여 넣으세요: ```md `npx --yes skills update -y` 명령어를 실행하고, 필요하면 먼저 임시 파일로 리디렉션해서 출력 전체를 읽어 줘. ``` --- **에이전트마다 설치 방법은 하나만** **Lagune**은 **skills.sh**와 **플러그인** 중 한 가지 방법으로만 설치하고, 둘을 함께 사용하지 마세요. **권한** 명령어는 엔진을 `npx --yes lagune@0.16.0` 형태로 실행하며, 이를 미리 허용하는 규칙은 [에이전트별 설치 페이지](https://lagune.ai/ko-KR/docs)에서 안내합니다. 네트워크에 접근할 수 없는 샌드박스에서는 처음 한 번, 그리고 업데이트할 때마다 직접 터미널에서 프로젝트에 엔진을 설치하세요: ```bash npm i -D lagune@0.16.0 ``` ## 자주 묻는 질문 ### 어떤 AI 에이전트에든 Lagune을 설치하려면 어떻게 하나요? 프로젝트에서 npx skills add wellwelwel/lagune 명령어를 실행하거나, 설치 프롬프트를 에이전트에 붙여 넣으세요. ### skills CLI로 설치한 Lagune을 업데이트하려면 어떻게 하나요? npx skills update 명령어를 실행하거나, 업데이트 프롬프트를 에이전트에 붙여 넣으세요. ### Lagune을 skills CLI와 플러그인으로 동시에 설치할 수 있나요? 아니요. 둘 다 설치하면 에이전트가 모든 명령어를 두 번씩 표시하거나, 한쪽만 사용하고 다른 쪽은 숨깁니다. --- # AI 에이전트를 위한 보안 스킬 > Lagune으로 AI 에이전트가 얻는 스킬: 기존 프로젝트를 점검하거나, 개발하는 동안 새 작업을 안전하게 만들 수 있으며, 모두 보안 원칙을 따릅니다. 표준 URL: https://lagune.ai/ko-KR/docs/get-started/commands 언어: ko-KR 원문: https://lagune.ai/docs/get-started/commands 마지막 업데이트: 2026-11-03 **Lagune**을 [설치](https://lagune.ai/ko-KR/docs)하면 **AI** 에이전트가 여러 스킬을 쓸 수 있게 됩니다. 사용 방법은 두 가지이며, 둘 다 **보안 원칙**을 따릅니다: 개발하면서 새 작업을 안전하게 만들거나, 프로젝트를 대상으로 전체 감사를 실행하는 것입니다. **⌨️ 구현 / 개발** 작업을 다 끝낸 뒤에 보안을 챙길 필요는 없습니다. **지금** 작성하고 있는 작업에는 [**`/lagune`**](https://lagune.ai/ko-KR/docs/commands/lagune) 명령어를 사용하세요: | 스킬 | 해 주는 일 | | --------------------------------------------- | -------------------------------------------------------------- | | [**/lagune-charter**](https://lagune.ai/ko-KR/docs/commands/charter) | `/lagune` 명령어가 토대로 삼는 프로젝트 보안 규칙 설정 | | [**/lagune**](https://lagune.ai/ko-KR/docs/commands/lagune) | 요청한 작업을 만들고, 보안 원칙에 따라 작성하는 동안 보안 강화 | **언제든 사용하기** [**`/lagune`**](https://lagune.ai/ko-KR/docs/commands/lagune) 명령어는 실행될 때마다 보안 원칙의 규칙을 지킵니다. 어떤 프롬프트든 받아 요청한 것을 만들고, 나중이 아니라 작업하는 동안 안전한 기본값으로 보안을 강화합니다. --- #### 특수 스킬 | 스킬 | 하는 일 | | --------------------------------------------------- | --------------------------------------------------------------------------- | | [**/lagune-specialize**](https://lagune.ai/ko-KR/docs/commands/specialize) | 아티클, 익스플로잇 또는 주제를 바탕으로 **Lagune**에 새 보안 전문 지식 추가 | **🔬 감사: Blue Team 흐름** 전체 **Blue Team 흐름**입니다: 프로젝트가 하는 일을 읽고, 위험을 파악하고, 그 위험을 해소합니다. 각 단계는 앞 단계를 토대로 하므로, 목록을 위에서 아래로 따라가기만 하면 됩니다: | # | 스킬 | 해 주는 일 | | --- | --------------------------------------------- | ---------------------------------------------------------------------- | | 1 | [**/lagune-charter**](https://lagune.ai/ko-KR/docs/commands/charter) | 제안을 받거나 원하는 대로 다듬은 프로젝트 보안 규칙 설정 | | 2 | [**/lagune-detect**](https://lagune.ai/ko-KR/docs/commands/detect) | 코드를 읽고 시스템이 하는 일과 위험이 있는 곳 파악 | | 3 | [**/lagune-plan**](https://lagune.ai/ko-KR/docs/commands/plan) | detect 단계에서 찾은 내용을 발견 사항별 수정이 담긴 방어 계획으로 정리 | | 4 | [**/lagune-harden**](https://lagune.ai/ko-KR/docs/commands/harden) | 계획의 수정을 하나씩 안전하게 코드에 적용 | | 5 | [**/lagune-verify**](https://lagune.ai/ko-KR/docs/commands/verify) | 적용한 수정이 실제로 효과가 있는지 증명하고, 효과가 있는 수정은 마무리 | --- #### 특수 스킬 | 스킬 | 하는 일 | | --------------------------------------------------- | -------------------------------------------------------------------------------------------- | | [**/lagune-specialize**](https://lagune.ai/ko-KR/docs/commands/specialize) | 아티클, 익스플로잇 또는 주제를 바탕으로 **Lagune**에 새 보안 전문 지식 추가 | | [**/lagune-prove**](https://lagune.ai/ko-KR/docs/commands/prove) | 탐지된 발견 사항을 하나하나 책임 있는 공개에 쓸 수 있는, 실행 가능한 방어 전용 증명으로 변환 | --- #### 내부 스킬 | 스킬 | 하는 일 | | ------------------------------------------- | --------------------------- | | [**/lagune-repair**](https://lagune.ai/ko-KR/docs/commands/repair) | **Lagune**의 내부 추적 복구 | **팁** 보안은 비용이 아니라 투자입니다: 처음에 들인 만큼, 겪지 않은 사고에서 몇 배로 아끼게 됩니다 🙋🏻‍♂️ ## 자주 묻는 질문 ### Lagune은 어떤 스킬을 추가하나요? 개발하는 동안 작업의 보안을 강화하는 /lagune 명령어와, 5단계 Blue Team 감사 흐름을 이루는 /lagune-charter, /lagune-detect, /lagune-plan, /lagune-harden, /lagune-verify 명령어입니다. 그 밖에 /lagune-specialize 명령어와 /lagune-prove 명령어도 있습니다. ### Lagune의 Blue Team 흐름은 무엇인가요? 5단계로 이루어진 감사입니다: charter(규칙 정하기), detect(위험 파악하기), plan(점수를 매기고 수정 계획하기), harden(수정 적용하기), verify(수정이 실제로 효과가 있는지 증명하고 종결하기). ### /lagune 명령어와 감사 흐름은 무엇이 다른가요? /lagune 명령어는 따라야 할 흐름 없이, 작성하는 동안 새 작업을 안전하게 만듭니다. 감사 흐름은 기존 프로젝트를 대상으로 다섯 단계를 차례로 실행합니다. --- # 대시보드 > 명령어 하나로 열리는 로컬 실시간 뷰에서 프로젝트의 보안 원칙, 발견 사항, 카탈로그를 확인하세요. 표준 URL: https://lagune.ai/ko-KR/docs/get-started/dashboard 언어: ko-KR 원문: https://lagune.ai/docs/get-started/dashboard 마지막 업데이트: 2026-11-03 하위 명령어 없이 **Lagune**을 바로 실행하면 `.lagune/` 폴더를 인터랙티브한 실시간 뷰로 볼 수 있습니다. 임의의 포트에서 대시보드를 띄우고 엽니다: ```bash npx lagune ``` - [x] **실시간 새로고침** - [x] **비공개**이며 **로컬**에서 동작 - [x] 첫 보안 원칙부터 `.lagune/` 폴더에 담긴 모든 내용 표시 - [x] 브라우저에서 프로젝트의 카테고리를 직접 **관리** - [x] `node_modules` 폴더도 `package.json` 파일도 필요 없음 📦 ![Lagune 대시보드의 보안 원칙 화면](https://lagune.ai/img/dashboard/02.webp) ![Lagune 대시보드의 발견 사항 화면](https://lagune.ai/img/dashboard/03.webp) ![Lagune 대시보드의 사이드 퀘스트 화면](https://lagune.ai/img/dashboard/04.webp) ![Lagune 대시보드의 발견 사항 상세 화면](https://lagune.ai/img/dashboard/05.webp) ![Lagune 대시보드의 카탈로그 화면](https://lagune.ai/img/dashboard/06.webp) **팁** - 🚪 원하는 포트를 지정하려면 `--port` 옵션을 사용하세요. - ⏏️ 중지하려면 `Ctrl+C` 키를 누르세요. ## 자주 묻는 질문 ### Lagune 대시보드는 어떻게 여나요? 프로젝트 루트에서 하위 명령어 없이 npx lagune 명령어를 실행하세요. 임의의 포트에서 .lagune/ 폴더의 실시간 뷰를 띄우고 브라우저에서 엽니다. ### 대시보드는 비공개인가요? 네. 자신의 컴퓨터에서만 실행되며, 다른 컴퓨터에서는 접근할 수 없는 로컬 주소를 사용합니다. ### 대시보드에서 프로젝트를 변경할 수 있나요? 브라우저에서 카테고리만 변경할 수 있습니다. 대시보드에 표시되는 나머지는 모두 읽기 전용입니다. --- # /lagune: AI가 작성하는 동안 코드 보안 강화 > 요청한 작업을 만들고, 보안 원칙에 따라 작성하는 즉시 보안을 강화합니다. 따로 따라야 할 흐름은 없습니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/lagune 언어: ko-KR 원문: https://lagune.ai/docs/commands/lagune 마지막 업데이트: 2026-11-03 ⌨️ 요청한 작업을, 작성하는 순간부터 안전하게 완성합니다. **`/lagune`** 명령어는 어느 단계에서든 어떤 프롬프트든 받아 원하는 것을 만들고, 결과를 돌려주기 전에 안전한 기본값으로 보안을 강화합니다. ## 사용법 어떤 프롬프트에든 **`/lagune`** 명령어를 붙이고, 평소처럼 작업 내용을 설명하세요. **📘 에이전트 지침** ```md # 에이전트를 위한 내 프로젝트 지침 ## 보안 - 코드를 만들거나 수정할 때마다 `/lagune` 스킬을 사용해서 기본적으로 안전성을 높여 줘. ``` - 예: **AGENTS.md**, **CLAUDE.md**, **.github/copilot-instructions.md**, **.cursorrules** 등 **💬 새 기능** ```prompt /lagune 사용자가 프로필에 원하는 사진을 업로드할 수 있게 해 줘. ``` **💬 버그 수정** ```prompt /lagune 사용자가 폼을 제출해도 아무 일도 일어나지 않아. 원인이 뭔지 살펴보고 고쳐 줘. ``` **💬 리팩터링** ```prompt /lagune 페이로드 로직을 분리하고 개선해 줘 ``` **선택 사항이지만 있으면 더 좋은 보안 원칙** **`/lagune`** 명령어는 보안 원칙이 있든 없든 실행됩니다. 보안 원칙이 있으면 프로젝트만의 규칙이 만드는 모든 것에 반영됩니다. [`/lagune-charter`](https://lagune.ai/ko-KR/docs/commands/charter) 명령어로 한 번만 정해 두세요. ## 작동 방식 Lagune에는 아무것도 기록하지 않은 채, 작업을 다음 세 과정으로 감쌉니다: 1. 보안 원칙이 있으면 불러와 그 원칙이 구현 전체를 규율하게 하고, 아직 없으면 기본적으로 안전한 기준선을 대신 적용합니다. 2. 프로젝트의 [카탈로그](https://lagune.ai/ko-KR/docs/catalog)를 살펴보고 작업과 관련된 전문 지식만 불러옵니다. 감사 흐름이 필요할 때만 불러오는 바로 그 지식입니다. 3. 코드를 작성하면서 방어를 적용하고, 작업을 돌려주기 전에 자신의 결과물을 다시 읽어 보안 통제가 실제로 효과가 있는지 확인합니다. 그 결과, 프로젝트에는 첫 줄부터 안전하고 제대로 작동하는 코드가 남습니다. **언제든 사용하기** detect 단계도, plan 단계도, 뒷정리도 필요 없습니다. **`/lagune`** 명령어는 막 만든 프로젝트 뼈대에도, 성숙한 코드베이스의 변경에도 똑같이 잘 맞으며, 나중이 아니라 작업하는 동안 보안을 강화합니다. ## 하지 않는 일 - `.lagune` 디렉터리에는 산출물도 추적 정보도 전혀 기록하지 않으므로, 만들어 내는 것은 요청한 대로 보안이 강화된 코드뿐입니다. - 프롬프트를 들어주려고 규칙을 느슨하게 하지 않으므로, 요청한 내용이 보안 원칙에 어긋난다면 그대로 안전하지 않게 만드는 대신 먼저 멈추고 알려 줍니다. ## 자주 묻는 질문 ### /lagune 명령어는 무엇을 하나요? 어느 단계에서든 어떤 프롬프트든 받아 요청한 것을 만들고, 결과를 돌려주기 전에 안전한 기본값으로 보안을 강화합니다. 방어는 나중이 아니라 코드를 작성하는 동안 적용됩니다. ### /lagune 명령어를 쓰려면 보안 원칙이 있어야 하나요? 아니요. 보안 원칙이 있든 없든 실행됩니다. 보안 원칙이 있으면 프로젝트만의 규칙이 만드는 모든 것에 반영되고, 없으면 기본적으로 안전한 기준선을 대신 적용합니다. ### /lagune 명령어와 Blue Team 흐름은 무엇이 다른가요? /lagune 명령어는 따라야 할 흐름 없이, 작성하는 동안 새 작업을 안전하게 만듭니다. Blue Team 흐름은 기존 프로젝트를 대상으로 다섯 감사 단계를 차례로 실행합니다. ### /lagune 명령어는 발견 사항을 추적하거나 산출물을 기록하나요? 아니요. .lagune 디렉터리에는 산출물도 추적 정보도 전혀 기록하지 않습니다. 만들어 내는 것은 요청한 대로 보안이 강화된 코드뿐입니다. ### 에이전트가 /lagune 명령어를 자동으로 쓰게 하려면 어떻게 하나요? 에이전트의 지침 파일(AGENTS.md, CLAUDE.md, .cursorrules 등)에 코드를 만들거나 수정할 때마다 /lagune 스킬을 사용하라는 지침을 추가하세요. --- # /lagune-charter: 보안 원칙 정하기 > 이후 모든 단계가 지키는 규칙인 프로젝트의 보안 원칙을 정하고, 프로젝트를 읽어 근거가 확인된 전문 지식 카테고리를 기록합니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/charter 언어: ko-KR 원문: https://lagune.ai/docs/commands/charter 마지막 업데이트: 2026-11-03 🧬 프로젝트가 무엇인지 **Lagune**에 알려 주면, 그 설명을 보안 규칙으로 바꿉니다(설명이 없으면 프로젝트만 보고 규칙을 도출합니다). charter는 모든 단계를 규율하는 계층으로, 이후 단계가 빠짐없이 지켜야 하는 보안 우선 원칙의 모음입니다. 프로젝트 보안 태세를 위한 컴파일 타임 검사라고 보면 됩니다. ## 사용법 **직접 설명하기** ```prompt /lagune-charter 내 프로젝트는 비디오 게임을 파는 온라인 스토어야. 고객은 상품을 장바구니에 담고 신용카드나 무통장 입금으로 결제해. 고객은 자기 주문과 각 주문의 상태를 볼 수 있어. ``` **Lagune의 제안 받기** ```prompt /lagune-charter ``` > _결제 라이브러리, 로그인 설정, 고객과 연결된 주문 모델이 있습니다. 무언가를 판매하는 온라인 스토어 같습니다. 고객이 결제하고 자기 주문을 추적합니다..._ ☁️ ## 도출하는 내용 **Lagune**은 설명이나 **PRD**를 방향으로 삼아 보안 측면에서 어떤 의미가 있는지 도출한 뒤, 프로젝트를 읽어 설명한 범위보다 더 깊이 살핍니다. 예를 들면 다음과 같습니다. - 주문을 담는 장바구니가 있다는 것은 **데이터베이스**가 있다는 뜻입니다. - 예: `"데이터는 어디에 저장되나요?"`, `"누가 접근할 수 있나요?"`, `"데이터가 유출되지는 않나요?"`. - 고객이 자기 주문을 볼 수 있다는 것은 어떤 형태로든 **로그인이나 접근 통제**가 있다는 뜻입니다. - 예: `"한 고객이 다른 고객의 주문에 접근할 수 있나요?"`, `"세션은 보호되고 있나요?"`. - 카드와 무통장 입금으로 결제를 받는다는 것은 **돈과 민감한 데이터가 오간다**는 뜻입니다. - 예: `"카드 정보가 저장되나요?"`, `"결제를 검증하고 있나요?"`. 설명과 프로젝트는 서로를 보완합니다. 설명이 의도를 정하고, 의존성과 README, 설정을 읽으면 설명에서 언급하지 않은 부분이 드러납니다. 그래도 중요한 점이 분명하지 않으면 **Lagune**은 추측하지 않고 짧고 쉬운 질문을 합니다. 이를 바탕으로 **Lagune**은 프로젝트에 맞춘 보안 규칙을 만들며, 이 규칙은 필요할 때 언제든 검토하고 조정할 수 있습니다. **더 잘 활용하기** - 프로젝트에 맞는 보안 규칙을 직접 정의할 수도 있습니다. - 관련 정보를 자세히 알려 줄수록 최종 보고서가 좋아집니다. - 프로젝트가 무엇인지, 어떻게 작동하는지, 내부에서 무슨 일이 일어나는지 설명하세요. - 최종 사용자는 누구인가요? 사용자가 할 수 있는 일과 할 수 없는 일은 무엇인가요? - 동작에 관한 정보는 기술적인 정보만큼 가치가 있습니다. - charter 기록은 `.lagune/memory/charter.md` 파일에 있습니다. ## 기록하는 카테고리 전문 지식은 이후 단계가 필요할 때만 불러오는 보안 지식으로, 프로젝트의 [카탈로그](https://lagune.ai/ko-KR/docs/catalog)에 [카테고리](https://lagune.ai/ko-KR/docs/categories) 단위로 추가됩니다. 프로젝트에 기록된 카테고리가 없는 동안에는 charter가 프로젝트를 읽어 근거가 확인된 카테고리(프로젝트의 언어, LLM 호출, 컨테이너 등)를 각각 기록하고, 요약에서 그 이름을 알려 줍니다. 카테고리가 기록된 뒤에는 charter가 이를 그대로 두고, 프로젝트에서 아직 쓰지 않는 카테고리가 있으면 그 이름만 알려 줍니다. 카테고리는 언제든 직접 바꿀 수 있습니다. ```bash npx lagune write add --categories python npx lagune write remove --categories python ``` ## 다음 단계 규칙을 정했다면 [`/lagune-detect`](https://lagune.ai/ko-KR/docs/commands/detect) 명령어로 시스템이 실제로 무엇을 하는지 파악하세요. ## 자주 묻는 질문 ### Lagune의 charter란 무엇인가요? charter는 Lagune에서 모든 단계를 규율하는 계층으로, 이후 단계가 빠짐없이 지켜야 하는 보안 우선 원칙의 모음입니다. 프로젝트 보안 태세를 위한 컴파일 타임 검사라고 보면 됩니다. ### charter는 어디에 저장되나요? .lagune/memory/charter.md 파일에 저장됩니다. ### charter 규칙을 직접 작성할 수 있나요? 네. Lagune은 설명과 코드를 바탕으로 규칙을 제안하고, 사용자는 그 규칙을 고쳐 쓰거나, 빼거나, 새로 추가하거나, 적용 범위를 좁힐 수 있습니다. ### charter가 전문 지식 카테고리를 정해 주나요? 기록된 카테고리가 없을 때만 그렇습니다. 그 경우 프로젝트를 읽어 근거가 확인된 카테고리(사용하는 언어나 LLM 호출 등)를 각각 기록합니다. 카테고리가 한번 기록되면 다시는 바꾸지 않습니다. --- # /lagune-detect: 시스템과 위험 파악하기 > 코드를 읽고 시스템이 무엇을 하는지, 위험이 어디에 있는지 파악합니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/detect 언어: ko-KR 원문: https://lagune.ai/docs/commands/detect 마지막 업데이트: 2026-11-03 🔬 시스템이 실제로 무엇을 하는지, 위험이 어디에 있는지 알아보세요. detect 단계는 코드를 읽고 실제로 찾은 것만, 이후 단계에 필요한 근거와 함께 기록합니다. 이 단계의 가장 중요한 지침은 지어내지 않고 탐지하는 것입니다. ## 사용법 **전체 스캔** ```prompt /lagune-detect ``` **경로 지정하기** ```prompt /lagune-detect src/routes/ src/auth.ts ``` **우려 사항 설명하기** ```prompt /lagune-detect 고객 데이터가 절대 노출되지 않는지 확인해 줘 ``` ## 파악하는 내용 **Lagune**은 코드를 읽고 찾은 것을 파악합니다. 각 발견 사항은 무엇이 문제인지, 왜 중요한지, 근거가 무엇인지를 담습니다. 예를 들면 다음과 같습니다. - **파일 업로드**: 시스템이 사용자에게서 파일을 받습니다. - _중요한 이유_: 이미지로 위장한 파일에 악성 코드가 숨어 있을 수 있습니다. - _근거_: `POST /upload` 핸들러가 파일의 실제 형식을 확인하지 않고 클라이언트가 보낸 MIME 타입을 그대로 신뢰합니다. - **로그인과 세션**: 사용자가 로그인해 자기 계정에 접근합니다. - _중요한 이유_: 세션 처리가 허술하면 다른 사람이 계정을 탈취할 수 있습니다. - _근거_: 세션 발급 로직에서 만료 시간을 설정하지 않은 채 세션을 발급합니다. 이 과정에서 detect 단계는 프로젝트 [카탈로그](https://lagune.ai/ko-KR/docs/catalog)의 모든 전문 지식을 코드와 대조해 판정을 내리고, 해당 컨텍스트가 코드에 있는 전문 지식을 적용한 뒤, harden과 verify 단계가 다시 사용하는 목록인 **Applied specializations** 항목에 기록합니다. 이렇게 해서 시스템이 무엇을 하고 위험이 어디에 있는지 보여 주는 명확한 맵이 생기며, 다음 단계에서 바로 활용할 수 있습니다. **팁** - 다시 실행하면 맵이 갱신되어, 해결된 발견 사항은 빠지고 새 발견 사항이 추가됩니다. - 탐지 맵은 `.lagune/memory/detect.md` 파일에 있습니다. ## 다음 단계 [`/lagune-plan`](https://lagune.ai/ko-KR/docs/commands/plan) 명령어로 맵을 계획으로 바꾸세요. ## 자주 묻는 질문 ### /lagune-detect 명령어는 무엇을 하나요? 코드를 읽고 시스템이 무엇을 하는지, 위험이 어디에 있는지 파악하며, 실제로 찾은 것만 기록합니다. 지어내지 않고 탐지하는 것이 원칙입니다. ### Lagune에서 발견 사항이란 무엇인가요? 발견 사항은 탐지된 위험 하나를 말하며, 무엇이 문제인지, 왜 중요한지, 코드상의 근거를 담습니다. plan, harden, verify 단계가 이어서 다루는 추적 단위입니다. ### 탐지 맵은 어디에 저장되나요? .lagune/memory/detect.md 파일에 저장됩니다. ### detect 단계는 어떤 전문 지식을 사용하나요? 프로젝트 카탈로그에 있는 모든 전문 지식을 코드와 대조해 판정합니다. detect 단계는 해당 컨텍스트가 있는 전문 지식을 적용하고 Applied specializations 항목에 기록합니다. --- # /lagune-plan: 발견 사항에 점수를 매기고 수정 계획 세우기 > detect 단계가 찾은 내용을 방어 계획으로 바꾸고, 각 발견 사항에 카테고리와 CVSS v4.0 점수를 매긴 뒤 수정을 짝지어 줍니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/plan 언어: ko-KR 원문: https://lagune.ai/docs/commands/plan 마지막 업데이트: 2026-11-03 🛡️ detect 단계가 찾은 내용을 방어 계획으로 바꿉니다. 각 발견 사항에 카테고리와 CVSS v4.0 점수를 매기고, 적용할 수정을 짝지어 줍니다. ## 사용법 **전체 계획하기** ```prompt /lagune-plan ``` **경로 지정하기** ```prompt /lagune-plan src/routes/upload.ts ``` **걱정되는 부분에 집중하기** ```prompt /lagune-plan 민감한 데이터가 새어 나갈 수 있는 곳 ``` ## 작동 방식 이 단계는 detect 단계에서 이어집니다. 시스템이 무엇을 하는지와 각 부분에 어떤 위험이 있는지는 detect 단계가 이미 찾았으므로, plan 단계는 위험을 다시 설명하지 않고 얼마나 심각한지 점수를 매긴 뒤 어떻게 대응할지 정합니다. plan 단계는 코드를 전혀 읽지 않으므로, 모든 수정은 반드시 detect 단계가 실제로 탐지한 대상을 가리키게 됩니다. 평가는 CVSS v4.0 방식을 따르며, 각 발견 사항에 카테고리, CVSS v4.0 벡터(detect 단계와 charter가 담아 둔 내용에서 추론하고 [`cvss` 훅](https://lagune.ai/ko-KR/docs/hooks/cvss)으로 점수를 계산한 것), 그 점수가 속하는 우선순위 구간을 매깁니다. 각 수정에는 그 수정이 지키는 charter 원칙도 함께 적힙니다. 예를 들면 다음과 같습니다. - **파일 업로드** (우선순위: **Critical**) - _카테고리_: 제한 없는 파일 업로드(CWE-434). - _CVSS_: CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N (9.3, Critical). - _이 우선순위인 이유_: 누구나 인터넷으로 업로드 기능에 접근할 수 있고, 이 기능은 고객 파일을 저장하는 서버에 있습니다. - _지키는 원칙_: III. 모든 입력은 검증되기 전까지 신뢰할 수 없습니다. - _수정_: 파일의 실제 형식과 크기를 확인하고, 저장할 때 이름을 바꾸고, 업로드한 파일은 코드로 실행될 수 없는 곳에 저장합니다. 이렇게 해서 점수와 우선순위가 매겨진 수정 목록이 만들어지며, 각 수정은 발견 사항과 연결되어 다음 단계에서 바로 적용할 수 있습니다. 점수는 추정하지 않고 항상 계산합니다. 벡터는 프로젝트의 노출 정도와 중요도를 Environmental 지표로 담고 있으므로, 누구나 이 벡터를 FIRST나 NVD 계산기에 붙여 넣어 같은 점수를 다시 얻을 수 있습니다. **팁** - 전적으로 detect 단계의 결과를 바탕으로 합니다. 파악된 적 없는 파일이나 걱정되는 부분이 있으면, 먼저 그 대상에 `/lagune-detect` 명령어를 실행하라고 안내합니다. - 다시 실행하면 계획이 갱신되어, 완료된 수정은 빠지고 새 수정이 추가됩니다. - 방어 계획은 `.lagune/memory/plan.md` 파일에 있습니다. **detect 단계에 의존** plan 단계는 [`/lagune-detect`](https://lagune.ai/ko-KR/docs/commands/detect) 명령어가 이미 파악한 내용만으로 작동하므로, detect 단계를 먼저 실행하세요. ## 다음 단계 [`/lagune-harden`](https://lagune.ai/ko-KR/docs/commands/harden) 명령어로 계획을 적용하세요. ## 자주 묻는 질문 ### Lagune은 취약점의 우선순위를 어떻게 정하나요? /lagune-plan 명령어가 각 발견 사항에 카테고리와 cvss 훅이 계산한 CVSS v4.0 점수를 매기고, 적용할 수정을 짝지어 줍니다. ### Lagune은 CVSS v4.0을 사용하나요? 네. 각 발견 사항에는 CVSS v4.0 벡터와 점수가 붙습니다. 점수는 cvss 훅이 FIRST 계산기와 같은 산식으로 계산하므로, 누구나 그 계산기에 벡터를 붙여 넣어 점수를 다시 도출할 수 있습니다. ### plan 단계에서 코드를 읽나요? 아니요. plan 단계는 코드를 전혀 읽지 않으므로, 모든 수정은 반드시 detect 단계가 실제로 탐지한 대상을 가리키게 됩니다. --- # /lagune-harden: 코드에 보안 수정 적용하기 > 방어 계획의 수정을 하나씩 안전하게 코드에 적용합니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/harden 언어: ko-KR 원문: https://lagune.ai/docs/commands/harden 마지막 업데이트: 2026-11-03 🔧 방어 계획의 수정을 하나씩 안전하게 코드에 적용합니다. ## 사용법 **전체 적용하기** ```prompt /lagune-harden ``` **경로 지정하기** ```prompt /lagune-harden src/routes/upload.ts ``` **우선순위 지정하기** ```prompt /lagune-harden Critical과 High 우선순위 ``` ## 작동 방식 각 수정은 plan 단계에서 이미 정해졌으므로, harden 단계는 그대로 적용하기만 합니다. 코드를 건드리는 유일한 단계이기 때문에 신중하게 진행합니다. 모든 변경을 검토하기 쉽도록 수정을 하나씩 적용하고, 수정을 끼워 맞추려고 보안 통제를 약화하는 일은 절대 없습니다. 업로드 수정을 예로 들면 다음과 같습니다. - **파일 업로드** (상태: **Applied**) - _바뀐 내용_: 파일의 실제 형식과 크기를 확인하고, 예상하지 못한 파일은 거부하고, 저장할 때 이름을 바꾸고, 코드로 실행될 수 없는 곳에 저장합니다. - _위치_: `handleUpload` 함수와 이 함수가 호출하는 스토리지 헬퍼입니다. 수정을 완전히 적용할 수 없으면 harden 단계는 안전하게 할 수 있는 만큼만 적용하고, 나머지는 **Partial** 또는 **Blocked**로 표시해 열린 상태로 둡니다. **Applied는 검증 완료가 아님** Applied는 아직 증명되었다는 뜻이 아닙니다. 증명은 [verify](https://lagune.ai/ko-KR/docs/commands/verify) 단계가 맡습니다. **팁** - 전적으로 방어 계획을 바탕으로 합니다. 계획에 없는 수정이나 파일이 있으면, 먼저 그 대상에 `/lagune-plan` 명령어를 실행하라고 안내합니다. - 다시 실행하면 기록을 현재 상태와 대조해 갱신합니다. 되돌린 변경은 빠지고, 새로 적용한 수정이 추가됩니다. - 강화 기록은 `.lagune/memory/harden.md` 파일에 있습니다. **plan 단계에 의존하며 코드를 변경함** harden 단계는 [`/lagune-plan`](https://lagune.ai/ko-KR/docs/commands/plan) 명령어의 결과를 바탕으로 합니다. 코드를 변경하는 유일한 단계입니다. ## 다음 단계 [`/lagune-verify`](https://lagune.ai/ko-KR/docs/commands/verify) 명령어로 각 수정이 실제로 효과가 있는지 증명하세요. ## 자주 묻는 질문 ### /lagune-harden 명령어가 코드를 변경하나요? 네. 코드를 건드리는 유일한 단계로, 방어 계획의 수정을 하나씩 적용합니다. ### Applied, Partial, Blocked는 무슨 뜻인가요? Lagune이 각 수정에 기록하는 상태입니다. Applied는 수정을 적용했다는 뜻이고, Partial은 일부만 적용했다는 뜻이며, Blocked는 적용할 수 없었다는 뜻입니다. Applied는 아직 증명되었다는 뜻이 아닙니다. ### Lagune은 묻지 않고 수정을 적용하나요? 편집에 승인이 필요한지는 Lagune이 아니라 사용하는 에이전트와 그 에이전트를 실행하는 권한 모드가 정하며, Lagune은 자체 확인 절차를 추가하지 않습니다. 그래도 수정을 맞추려고 보안 통제를 약화하는 일은 절대 없으며, 수정이 charter 규칙과 충돌하면 작업을 멈추고 먼저 알려 줍니다. --- # /lagune-verify: 보안 통제가 유효한지 증명하기 > 적용한 각 수정이 실제로 효과가 있는지 증명하고, 효과가 증명된 항목을 마무리합니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/verify 언어: ko-KR 원문: https://lagune.ai/docs/commands/verify 마지막 업데이트: 2026-11-03 ⚖️ 코드를 읽고 harden 단계가 기록한 내용과 대조해 적용한 각 수정이 실제로 효과가 있는지 증명한 뒤, 효과가 증명된 항목을 마무리합니다. ## 사용법 **전체 검증하기** ```prompt /lagune-verify ``` **경로 지정하기** ```prompt /lagune-verify src/routes/upload.ts ``` **우선순위 지정하기** ```prompt /lagune-verify Critical과 High 우선순위 ``` ## 작동 방식 harden 단계가 기록한 각 위치의 코드를 읽고, 기록된 내용과 실제로 일치하는지 확인합니다. 증명이란 바로 이 대조, 즉 코드와 기록을 맞대어 보는 일입니다. 각 보안 통제는 다음 세 가지 판정 중 하나를 받습니다. | 판정 | 의미 | | ---------------------------- | ------------------------------------------------------------------- | | ✅ Risk closed | 코드가 기록된 내용을 정확히 그대로 수행함 | | ❌ Risk not closed | 보안 통제가 아직 열려 있으므로 verify 단계가 harden 단계로 돌려보냄 | | ❓ Cannot tell from the code | 코드만으로는 근거를 확인할 수 없음 | 해소되었음이 증명된 위험은 사용자의 확인을 받아 체인 전체에서 종결합니다. 예를 들면 다음과 같습니다. - **파일 업로드** (판정: **✅ Risk closed**) - _증명 방법_: 업로드 핸들러를 읽어, 기록된 내용 그대로 파일 내용으로 실제 형식을 판별하고, 크기 제한을 적용하며, 그 밖의 파일은 모두 거부하는 것을 확인했습니다. - _근거_: 파일 내용으로 실제 형식을 판별하는 `handleUpload` 함수입니다. 위험이 해소되지 않았다면 verify 단계는 그 사실을 분명히 알리고, 수정이 아직 열려 있으므로 [`/lagune-harden`](https://lagune.ai/ko-KR/docs/commands/harden) 명령어로 돌아가도록 안내합니다. **팁** - 전적으로 강화 기록을 바탕으로 합니다. - 판정을 위해 코드를 읽기만 하며, 판정을 통과시키려고 보안 통제를 약화하거나 코드를 고쳐 쓰는 일은 절대 없습니다. - 다시 실행하면 판정을 현재 상태와 대조해 갱신합니다. 오래된 판정은 빠지고, 더는 해소된 상태가 아닌 위험은 다시 잡아냅니다. - 위험이 해소된 것으로 증명되면 한 번 확인을 요청한 뒤, 해당 발견 사항을 체인 전체(detect, plan, harden, 추적)에서 지웁니다. - 별도의 보고서는 작성하지 않습니다. 각 판정은 `.lagune/memory/harden.md` 파일 안의 해당 보안 통제 블록에 기록되며, harden 단계가 다음 실행 때 이를 읽습니다. **harden 단계에 의존** verify 단계는 [`/lagune-harden`](https://lagune.ai/ko-KR/docs/commands/harden) 명령어의 결과를 바탕으로 합니다. ## 사이클의 마무리 범위 안의 모든 항목이 종결되면 사이클이 안정 상태가 됩니다. 사이클은 코드가 바뀔 때만 다시 열립니다. 보안은 종결할 수 있으므로, 이 흐름에는 끝없는 루프가 아니라 도달할 끝이 있습니다. ## 자주 묻는 질문 ### Lagune은 수정을 어떻게 검증하나요? /lagune-verify 명령어가 코드를 읽고 harden 단계가 기록한 내용과 대조해, Risk closed(위험 해소), Risk not closed(위험 미해소), Cannot tell from the code(코드만으로는 판단 불가) 세 가지 판정 중 하나를 내립니다. ### 종결이란 무엇인가요? verify 단계에서 위험이 해소된 것으로 증명되면 해당 발견 사항을 종결합니다. 즉 사용자의 확인을 받아 체인 전체에서 제거하므로, 더 이상 다시 처리되지 않습니다. ### 보안 작업에도 끝이 있나요? 네. SDH에서 보안은 종결할 수 있습니다. 해소가 증명된 발견 사항은 종결되므로, 이 흐름에는 끝없는 루프가 아니라 도달할 끝이 있습니다. --- # 카테고리 > Lagune 프로젝트에서 사용할 수 있는 전문 지식 카테고리와 변경 방법을 소개합니다. OWASP부터 JavaScript, Python, Go, Rust의 언어별 보안 강화까지 다룹니다. 표준 URL: https://lagune.ai/ko-KR/docs/categories 언어: ko-KR 원문: https://lagune.ai/docs/categories 마지막 업데이트: 2026-11-03 **Lagune**은 내장 [**전문 지식**](https://lagune.ai/ko-KR/docs/catalog)을 **13개 카테고리**로 묶습니다. 프로젝트가 사용하는 카테고리에 따라 어떤 내장 전문 지식이 프로젝트의 [**카탈로그**](https://lagune.ai/ko-KR/docs/catalog)에 들어갈지 정해지며, 카테고리는 시스템이 하는 일과 시스템을 작성한 언어, 두 가지로 나뉩니다. 기록된 카테고리가 없으면 프로젝트는 `owasp` 카테고리만 사용합니다. [`/lagune-charter`](https://lagune.ai/ko-KR/docs/commands/charter) 명령어는 프로젝트를 살펴보고 근거가 확인된 카테고리를 모두 기록하며, 카테고리는 언제든 직접 바꿀 수 있습니다. ## 시스템이 하는 일 | 카테고리 | 키 | 보안 강화 대상 | | -------- | --------- | --------------------------------------------------------------------------------------------- | | OWASP | `owasp` | OWASP가 추적하는 애플리케이션 보안 위험: 인젝션, 취약한 접근 통제, 인증 실패, 암호화 실패 | | 인프라 | `infra` | 컨테이너, 워크로드, 서버리스 설정: Dockerfile, Compose, Pod 보안, FaaS IAM과 트리거 | | AI / LLM | `ai` | 프롬프트 인젝션과 도구, 에이전트, 검색, MCP의 안전하지 않은 연결로부터 AI와 LLM 연동 보호 | | Lovable | `lovable` | AI가 생성한 Supabase 앱(Lovable 등): RLS 누락, 유출된 `service_role` 키, 안전하지 않은 기본값 | ## 시스템을 작성한 언어 | 카테고리 | 키 | 보안 강화 대상 | | ---------- | ------------ | --------------------------------------------------------------------------------------------------- | | JavaScript | `javascript` | 런타임 전반의 `eval` 및 `child_process` 기반 RCE, 경로 탐색(path traversal), 프로토타입 오염 | | Python | `python` | `pickle` 및 YAML 역직렬화 RCE, `str.format` 문자열 탐색(traversal), 클래스 오염 | | Rust | `rust` | 건전하지 않은(unsound) `unsafe` API, `transmute` 오용, 정수 오버플로, FFI 경계의 정의되지 않은 동작 | | C / C++ | `c-cpp` | 코드 실행으로 이어지는 포맷 문자열 버그, 버퍼 오버플로, 경계 밖 쓰기(out-of-bounds write) | | PHP | `php` | 타입 저글링을 이용한 인증 우회, 객체 인젝션 가젯 체인, 안전하지 않은 기본 설정 | | Go | `go` | typed nil 인터페이스 버그, 고루틴 데이터 레이스, 보안 관련 코드 경로의 안전하지 않은 동시성 | | Java | `java` | 원격 코드 실행으로 이어지는 `ObjectInputStream` 역직렬화 가젯 체인 | | Ruby | `ruby` | 원격 코드 실행에 이르는 `Marshal.load` 및 YAML 역직렬화 가젯 체인 | | .NET / C# | `dotnet` | `BinaryFormatter` 역직렬화 RCE, XSS로 이어지는 인코더 우회 | **팁** **Lagune**은 언어에 구애받지 않습니다. 프로젝트가 어떤 언어로 작성되었든 전체 흐름이 그대로 읽어 내며, 이 카테고리는 한 언어에만 있는 함정을 더 깊이 다룰 뿐입니다. ## 언제든 추가하고 제거하기 카테고리는 한번 정하면 바꿀 수 없는 약속이 아니라 출발점입니다. 지금 프로젝트에 맞는 카테고리를 사용하고, `write add` 및 `write remove` 명령어로 키를 지정해 언제든 바꾸세요. 터미널에서 `--categories` 옵션을 값 없이 사용하면 대화형 선택 화면이 열립니다(스페이스 키로 선택하거나 해제하고 엔터 키로 확정하며, 아무것도 선택하지 않으면 건너뜁니다). 터미널 밖에서는 옵션 뒤에 카테고리를 이어서 넘기세요. **추가** ```bash npx lagune write add --categories # interactive npx lagune write add --categories owasp npx lagune write add --categories owasp rust ``` **제거** ```bash npx lagune write remove --categories # interactive npx lagune write remove --categories owasp npx lagune write remove --categories owasp rust ``` 처음 실행하는 `write add` 또는 `write remove` 명령어는 `owasp` 카테고리에서 시작하므로, 카테고리를 모두 제거하면 기본값으로 돌아가지 않고 빈 목록이 남습니다. 모든 변경 사항은 `.lagune/configs.json` 파일에 기록되므로 팀 전체가 같은 카테고리 구성으로 작업합니다. ## 프로젝트가 사용하는 카테고리 확인하기 `read list --categories` 명령어는 모든 카테고리와 프로젝트의 사용 여부를 보여 줍니다. ```bash npx lagune read list --categories # Categories # • owasp [used] Harden against the application security risks OWASP tracks # • javascript [available] Harden JavaScript and its runtimes # • php [available] Harden PHP against type-juggling auth bypass # • go [available] Harden Go against typed-nil interface bugs # ... # # No category is recorded yet, so this project uses the default: owasp. ``` 각 카테고리에 어떤 전문 지식이 들어 있는지는 [**카탈로그**](https://lagune.ai/ko-KR/docs/catalog)에서 확인하세요. [`/lagune-specialize`](https://lagune.ai/ko-KR/docs/commands/specialize) 명령어로 직접 만든 전문 지식은 카테고리와 관계없이 카탈로그에 포함됩니다. ## 자주 묻는 질문 ### 카테고리는 어떻게 추가하나요? 카테고리의 키를 --categories 옵션에 넘기세요. 예를 들어 npx lagune write add --categories javascript 명령어를 실행합니다. 기록된 카테고리가 없는 동안에는 charter 단계도 프로젝트를 살펴보고 근거가 확인된 카테고리를 기록합니다. ### 카테고리를 여러 개 사용할 수 있나요? 네. 같은 줄에 하나씩 이어서 나열하세요. ### 프로젝트에는 어떤 카테고리를 사용해야 하나요? 기본값인 owasp 카테고리로 시작한 뒤, 사용하는 언어나 스택에 맞는 카테고리를 추가하세요. 전문 지식은 필요할 때만 불러오므로, 단계에서 그 카테고리의 전문 지식이 필요해지기 전까지는 카테고리에 드는 비용이 전혀 없습니다. --- # 카탈로그: 필요할 때만 불러오는 보안 전문 지식 > 프로젝트 카탈로그의 전문 지식을 불러오는 방식을 설명합니다. 각 단계가 필요할 때만 불러오며, 직접 불러올 수도 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/catalog 언어: ko-KR 원문: https://lagune.ai/docs/catalog 마지막 업데이트: 2026-11-03 🧠 **Lagune**의 전문 지식은 특정 주제에 집중한, 언어에 구애받지 않는 보안 지식 모듈입니다. 기본으로 불러오는 일 없이 필요할 때만 불러옵니다. 전문 지식은 명령어가 아닙니다. 프로젝트의 카탈로그는 프로젝트가 사용하는 전문 지식의 모음으로, 프로젝트 [카테고리](https://lagune.ai/ko-KR/docs/categories)의 내장 전문 지식과 프로젝트가 직접 만든 전문 지식으로 이루어집니다. detect 단계와 verify 단계는 실행 중에 전문 지식을 찾아 쓰며, 언제든 원하는 전문 지식을 직접 불러올 수도 있습니다. **개요** *인터랙티브 카탈로그 개요는 웹 페이지에서 볼 수 있습니다. 모든 내장 전문 지식은 아래 표에 있습니다.* **작동 방식** ## 직접 실행하기 전문 지식을 직접 사용하려면 에이전트에게 `read catalog ` 명령어로 불러오라고 요청하고, 같은 프롬프트에 작업 내용을 적으세요. 그러면 그 지식이 요청한 작업에 적용됩니다. **Lagune** 흐름과 관계없는 프롬프트를 포함해 어떤 프롬프트에서도 사용할 수 있습니다. 예를 들어 **Python**으로 안전한 **RegExp** 모음을 생성하는 자유 형식 프롬프트를 직접 작성하면 다음과 같습니다. ```prompt `npx lagune read catalog regex` 명령어로 regex 전문 지식을 불러온 다음, @src/utils/regex.py 파일에 이메일과 사용자 이름을 검증하는 정규 표현식 모음을 만들어 줘. ``` 이때 결정론적 훅이 각 **RegExp**의 **ReDoS** 취약 여부를 테스트해 안전한 패턴만 남기고, 다음과 같은 결과를 만듭니다. ```python import re EMAIL = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$") USERNAME = re.compile(r"^[a-zA-Z0-9_]{3,20}$") def is_email(value: str) -> bool: return EMAIL.match(value) is not None def is_username(value: str) -> bool: return USERNAME.match(value) is not None ``` **ReDoS 검사기 사용해 보기** [**devina.io/redos-checker**](https://devina.io/redos-checker) 사이트에서 패턴을 직접 테스트해 보세요. ## 내장 전문 지식 내장 전문 지식은 [**카테고리**](https://lagune.ai/ko-KR/docs/categories)별로 묶여 있습니다. **Lagune**에 기본으로 포함된 전문 지식은 다음과 같습니다. | 전문 지식 | 카테고리 | 다루는 내용 | | --------------------- | --------------------------- | ------------------------------------------------------------------------------- | | `regex` | `owasp` | **ReDoS**: 조작된 입력에서 처리 시간이 폭증하는 패턴. | | `network` | `owasp` | **SSRF와 리디렉션**: 사용자가 입력한 요청 대상이나 리디렉션 대상. | | `interpreter` | `owasp`, `lovable` | **코드 인젝션**: `eval`, 동적 include, 이름 기반 디스패치. | | `sql` | `owasp` | **관계형 데이터베이스**: 인젝션, ORM 원시 쿼리 호출, 권한, 엔진이 닿는 범위. | | `path` | `owasp` | **파일 시스템 경로**: 경로 탐색, 널 바이트, NTFS 스트림, 파일 심기. | | `upload` | `owasp` | **파일 업로드**: 형식과 시그니처, 악성 콘텐츠, 저장소, 제한. | | `access-control` | `owasp`, `lovable` | **인증, 인가, 세션**: IDOR, 대량 할당(mass assignment), 테넌트, 세션. | | `credential-endpoint` | `owasp`, `lovable` | **추측 공격과 봇**: 무차별 대입, 패스워드 스프레잉, 크리덴셜 스터핑, 요청 제한. | | `federation` | `owasp` | **토큰 신뢰**: OAuth/OIDC, SAML, JWT 검증, QR 로그인. | | `http-request` | `owasp` | **요청 출처**: CSRF, CORS 설정 오류, 위조된 클라이언트 IP. | | `transport` | `owasp` | **통신 채널 보안**: TLS 설정, HTTPS와 평문 통신, HSTS, 인증서 피닝. | | `crypto` | `owasp`, `lovable` | **저장 데이터 암호화**: 취약하거나 직접 만든 알고리즘, CSPRNG, 키 관리. | | `secrets` | `owasp`, `lovable` | **하드코딩된 자격 증명**: 소스 코드에 그대로 적힌 키, 토큰, 비밀번호. | | `api-endpoint` | `owasp` | **REST가 아닌 API 표면**: GraphQL, gRPC, WebSocket 인가, DoS, 스키마. | | `payment` | `owasp`, `lovable` | **결제 흐름**: 서버 측 결제 게이트웨이 검증, 서명된 콜백, 멱등성. | | `xml` | `owasp` | **XML 파싱**: XXE, 외부 엔티티, billion laughs 확장. | | `csv` | `owasp` | **수식 인젝션**: `=`/`+`/`-`/`@` 문자로 시작하는 스프레드시트 셀. | | `container` | `owasp`, `infra` | **컨테이너 설정**: root 실행, 케이퍼빌리티, 소켓 마운트, 이미지 보안 강화. | | `infra` | `infra` | **코드형 인프라**: Terraform, Dockerfile, GitHub Actions. | | `serverless` | `owasp`, `infra`, `lovable` | **FaaS 함수**: 최소 권한 IAM, 이벤트 입력, 컨텍스트, 시크릿. | | `llm` | `ai`, `lovable` | **AI와 LLM 위험**: 프롬프트 인젝션, 과도한 권한(agency), RAG, MCP, 출력. | | `supabase` | `lovable` | **Supabase 백엔드**: 기본적으로 꺼져 있는 RLS, AI가 잘못 생성한 정책, 키 모델. | | `browser` | `javascript`, `lovable` | **클라이언트 측 위험**: XSS, CSP, 프레이밍, 스토리지 등. | | `javascript` | `javascript` | **언어 수준 위험**: RCE, 프로토타입 오염 등. | | `python` | `python` | **언어 수준 위험**: `pickle` RCE, 클래스 오염, `-O` 등. | | `rust` | `rust` | **`unsafe` 건전성**: safe 호출자에서 비롯되는 UB, `transmute`, 오버플로. | | `java` | `java` | **역직렬화와 모바일 코드**: `readObject` 체인, 객체 하이재킹. | | `ruby` | `ruby` | **역직렬화와 `open`**: `Marshal`/YAML 객체 복원, 파이프 관련 특이 동작. | | `php` | `php` | **타입 저글링과 `unserialize`**: 매직 해시, POP 체인. | | `go` | `go` | **typed nil과 데이터 레이스**: `nil != nil`, 메모리를 공유하는 고루틴. | | `c-cpp` | `c-cpp` | **포맷 문자열**: `printf(user_input)`, `%n` 기반 write-what-where. | | `dotnet` | `dotnet` | **플랫폼 수준 위험**: `BinaryFormatter` RCE, `@Html.Raw`, enum 검증 누락. | 내장 지식은 대부분 OWASP 자료의 핵심을 정리한 것입니다. 각 전문 지식이 OWASP의 공식 공격 페이지 및 Cheat Sheet 페이지와 어떻게 대응하는지는 [**OWASP 출처**](https://lagune.ai/ko-KR/docs/references/owasp-sources)에서 전체 내용을 확인하세요. 일부 스택 전용 모듈은 OWASP 대신 해당 벤더의 자체 가이드를 바탕으로 합니다. 예를 들어 `supabase` 전문 지식은 Supabase 문서와 CVE-2025-48757을 바탕으로 합니다. ## 직접 만든 전문 지식 내장 전문 지식은 새 명령어 없이, 지식 파일 하나와 인덱스 행 하나를 추가하는 방식으로 늘어납니다. 직접 만드는 전문 지식도 같은 방식으로, [`/lagune-specialize`](https://lagune.ai/ko-KR/docs/commands/specialize) 명령어로 추가합니다. 글이나 주제를 알려 주면 그 핵심을 정리해 프로젝트에 새 전문 지식을 만들며, 파일은 `.lagune/catalog/` 폴더에, 항목은 `.lagune/configs.json` 파일에 기록됩니다. 직접 만든 전문 지식은 카테고리와 관계없이 항상 카탈로그에 포함되며, 이름이 같은 내장 전문 지식을 가립니다. **Lagune 내부에서 필요할 때 자동으로 불러오는 전문 지식** detect 단계나 verify 단계는 전문 지식이 다루는 컨텍스트를 만나면 `read catalog ` 명령어로 해당 전문 지식을 스스로 불러옵니다. 이 과정은 단계의 일부로 자동으로 진행되므로 직접 불러올 필요가 없습니다. ## 사용할 수 있는 전문 지식 확인하기 터미널에서 프로젝트의 카탈로그를 나열하면 전문 지식이 한 줄에 하나씩 태그와 함께 표시됩니다. ```bash npx lagune read catalog # regex: Regular Expression [required] # network: Requests, Webhook, URL Fetch, Socket, IMDS, Redirect # interpreter: Evaluator, Sink, Shell, Dynamic Execution # ... ``` `[required]` 표시가 붙은 전문 지식은 작업 내용과 관계없이 항상 적용됩니다. 목록에 어떤 내장 전문 지식이 들어가는지는 프로젝트의 [**카테고리**](https://lagune.ai/ko-KR/docs/categories)에 따라 달라집니다. **기본으로 불러오지 않는 전문 지식** 모든 검사를 기본으로 실행하는 대신, 프로젝트의 실제 모습에 맞는 지식만 불러옵니다. ## 자주 묻는 질문 ### Lagune의 전문 지식이란 무엇인가요? 특정 주제에 집중한, 언어에 구애받지 않는 보안 지식 모듈로, 기본으로 불러오는 일 없이 필요할 때만 불러옵니다. 에이전트 스킬과 달리 명령어가 아닙니다. ### 프로젝트의 카탈로그란 무엇인가요? 프로젝트가 사용하는 전문 지식으로, 프로젝트 카테고리의 내장 전문 지식과 프로젝트가 직접 만든 전문 지식으로 이루어집니다. 기록된 카테고리가 없으면 OWASP만 사용합니다. ### 전문 지식은 기본으로 불러오나요? 아니요. 프로젝트의 실제 모습에 맞춰 필요할 때만 불러옵니다. ### 전문 지식을 직접 불러오려면 어떻게 하나요? 작업 내용을 적는 프롬프트에, 에이전트가 npx lagune read catalog 명령어를 실행하도록 하는 요청도 함께 적으세요. --- # /lagune-specialize: 일반 텍스트로 보안 전문 지식 학습시키기 > 제공한 보안 자료나 주제의 핵심을 정리해, 필요할 때만 불러오는 새 전문 지식으로 만듭니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/specialize 언어: ko-KR 원문: https://lagune.ai/docs/commands/specialize 마지막 업데이트: 2026-11-03 🎓 자료나 주제를 주고 **Lagune**에 새 전문 지식을 가르치세요. 자료를 읽고 그 핵심을 정리해 특정 주제에 집중한 방어 전용 전문 지식으로 만듭니다. 이 전문 지식은 [내장 전문 지식](https://lagune.ai/ko-KR/docs/catalog)과 형식이 똑같아서, 이후 detect 단계와 verify 단계가 다른 전문 지식처럼 불러옵니다. 하는 일은 점검과 설명뿐이며, 공격 입력이나 익스플로잇을 작성하지 않고 코드도 건드리지 않습니다. **글에서** ```prompt # 링크나 참고 자료: Lagune이 핵심을 정리해 방어 지식으로 만듭니다 /lagune-specialize https://owasp.org/www-community/attacks/SQL_Injection ``` **익스플로잇에서** ```prompt # 공격을 자료로 삼는 경우: 그래도 전문 지식은 방어를 다룹니다 /lagune-specialize "' OR 1=1 -- 입력이 쿼리 문자열에 SQL을 끼워 넣음" ``` **주제에서** ```prompt # 또는 다룰 주제만 적으세요 /lagune-specialize SQL 인젝션 ``` **공격은 자료가 될 수 있어도 결과물이 되지는 않음** 방어가 목적이라면 공격을 자료로 지정해도 괜찮습니다. 익스플로잇 분석 글은 방어 지식으로 정리할 학습 자료가 됩니다. 이렇게 만든 전문 지식은 언제나 점검하고 설명할 뿐이며, 실제로 작동하는 익스플로잇이나 페이로드, 회피 기법은 절대 만들지 않습니다. ## 작성하는 파일 결과물은 프로젝트 안의 파일 2개로, 코드와 함께 커밋하고 리뷰할 수 있습니다. - `.lagune/catalog/.md` 경로에 저장되는 전문 지식. [내장 전문 지식](https://lagune.ai/ko-KR/docs/catalog)과 같은 형식입니다. - `.lagune/configs.json` 파일의 항목. 프로젝트는 이 파일에서 직접 만든 전문 지식의 인덱스를 관리하고, 카탈로그는 이를 내장 전문 지식과 합칩니다. 그런 다음 카탈로그를 나열해 새 항목이 들어갔는지 확인합니다. 직접 만든 전문 지식은 카테고리와 관계없이 항상 카탈로그에 포함됩니다. 명령어를 추가하거나 패키지를 수정할 필요는 전혀 없습니다. 새 전문 분야는 프로젝트에 기록되는 지식 파일 하나와 인덱스 항목 하나가 전부입니다. ## 덮어쓰지 않고 다듬기 `regex` 같은 내장 전문 지식이든 이전에 직접 만든 전문 지식이든, 이미 있는 이름으로 전문 지식을 만들면 현재 파일을 교체하지 않고 **현재 상태와 대조해 갱신**합니다. 기존 내용을 읽고 새 지식을 반영하며, 여전히 유효한 내용은 유지하고 바뀐 내용은 다시 씁니다. 확인하지 않은 채 버려지는 내용은 없습니다. 직접 만든 전문 지식은 이름이 같은 내장 전문 지식을 가리므로, 내장 전문 지식을 잃지 않고도 프로젝트에 맞게 다듬을 수 있습니다. **팁** - 새 전문 지식은 내장 전문 지식과 똑같이 불러옵니다. detect 단계와 verify 단계가 필요할 때 불러오며, `npx lagune read catalog ` 명령어로 직접 불러와 작업을 맡길 수도 있습니다. - 자료의 출처(글, 저자, 링크, 표준)를 알 수 있으면 전문 지식에 그 출처를 밝힙니다. 주제만 제공한 경우에는 출처가 붙지 않습니다. **참고** **직접 호출할 때만 실행됩니다**: 에이전트가 스스로 시작하는 일은 없습니다. ## 자주 묻는 질문 ### 보안 전문 지식을 직접 만들어 추가하려면 어떻게 하나요? 자료나 주제와 함께 /lagune-specialize 명령어를 실행하세요. 그 핵심을 정리해 방어 전용 전문 지식으로 만들고, .lagune/catalog/.md 파일에 작성한 뒤 .lagune/configs.json 파일에 항목을 추가합니다. ### Lagune이 익스플로잇 분석 글로 학습할 수 있나요? 네. 다만 자료로 쓸 뿐, 결과물로 내놓지는 않습니다. 공격은 자료가 될 수 있어도 결과물이 되지는 않습니다. specialize 명령어는 공격 입력이나 익스플로잇을 작성하지 않습니다. ### specialize 명령어가 내장 전문 지식을 덮어쓰나요? 아니요. 덮어쓰지 않고 다듬습니다. --- # /lagune-prove: 방어 전용 개념 증명(PoC) > 탐지한 발견 사항마다 실행할 수 있는 방어 전용 개념 증명(PoC)과 책임 있는 공개를 위한 보안 권고를 만듭니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/prove 언어: ko-KR 원문: https://lagune.ai/docs/commands/prove 마지막 업데이트: 2026-11-03 🧪 탐지한 발견 사항 하나하나를 책임 있는 공개에 쓸 수 있는, 실행 가능한 방어 전용 증거로 만드세요. 탐지 맵에 있는 발견 사항마다 단독으로 읽을 수 있는 보안 권고와 **안전한 경로**를 검증하는 테스트를 작성합니다. 그래서 테스트는 문제가 남아 있는 동안 실패하고, 코드를 수정하면 통과합니다. **팁** **Lagune**의 테스트는 프로젝트 자체 테스트 스위트와 분리되어 `.lagune/` 폴더 아래에 따로 보관됩니다. ## 사용법 **모든 발견 사항** ```prompt /lagune-prove ``` **이름을 지정한 발견 사항** 이미 추적 중인 발견 사항의 이름을 확인하세요. ```prompt npx lagune read list --findings # Findings # ... # • 사용자 조회의 SQL 인젝션 # ... ``` ```prompt # 그다음 그중 하나를 증명하세요 /lagune-prove 사용자 조회의 SQL 인젝션 ``` ## 작동 방식 각 발견 사항이 가리키는 소스 코드를 읽고, 증명한 발견 사항마다 `.lagune/proofs/` 폴더 아래에 디렉터리를 하나씩 만듭니다. 각 디렉터리에는 파일이 정확히 2개 들어갑니다. | 파일 | 설명 | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `report.test.mjs` (또는 `.cjs`) | 테스트 파일입니다. 프로젝트에서 이미 Poku를 사용하고 있으면 Poku로, 그렇지 않으면 Node.js 기본 테스트 러너로 실행되므로 따로 설치할 것이 없습니다. | | `report.md` | 심각도, 영향, 재현 방법, 실행 명령어를 모두 담아 단독으로 읽을 수 있는 보안 권고입니다. | 증명은 항상 JavaScript로 작성되므로, 프로젝트가 어떤 언어로 작성되었든 그대로 옮겨 쓸 수 있습니다. 인덱스 역할을 하는 `README.md` 파일은 모든 증명을 링크하고, 전체를 한 번에 실행하는 명령어 하나를 제공합니다. **팁** - **선택 사항이자 독립적인 명령어**입니다. 다섯 단계 중 하나가 아니며, 추적 체인에도 속하지 않습니다. - `.lagune/proofs/` 폴더에만 쓰며, 단계 산출물과 코드는 읽기만 할 뿐 절대 수정하지 않습니다. - 테스트로 문제가 재현되지 않는 발견 사항은 증명을 만들지 않고, 해당 위치에 [`/lagune-detect`](https://lagune.ai/ko-KR/docs/commands/detect) 명령어를 실행해 현재 상태와 대조해 갱신하라고 안내합니다. - 다시 실행하면 증명을 현재 상태와 대조해 갱신합니다. 사라졌거나 더 이상 재현되지 않는 발견 사항은 해당 디렉터리를 삭제합니다. **참고** **직접 호출할 때만 실행됩니다**: 에이전트가 스스로 시작하는 일은 없습니다. **detect 단계 결과를 바탕으로 동작** prove 명령어는 [`/lagune-detect`](https://lagune.ai/ko-KR/docs/commands/detect) 명령어가 만든 탐지 맵을 읽으므로, detect 단계를 먼저 실행하세요. ## 방어 전용, 권한이 있을 때만 무엇이든 생성하기 전에 대상을 테스트할 권한이 있는지 확인하며, 실제로 작동하는 익스플로잇, 공격 페이로드, 탐지 회피 기법을 요청하면 모두 거절합니다. 증명은 안전한 동작을 보여 줄 뿐, 공격 입력은 절대 만들지 않습니다. ## 증명에서 공개까지 취약점을 보고할 때는 증명한 발견 사항의 두 파일을 하나의 **비공개 GitHub Gist**에 함께 올리세요. 두 파일은 아직 공개되지 않은 채 남아 있는 문제의 증거이므로, `.gitignore` 파일이 `.lagune/proofs/` 폴더 안에서 이 파일들을 모든 커밋에서 제외합니다. 메인테이너가 문제를 해결할 때까지는 그 Gist를 통해서만 공유하세요. **Lagune** 체인에서 발견 사항을 종결하는 일은 여전히 [`/lagune-harden`](https://lagune.ai/ko-KR/docs/commands/harden) 명령어와 [`/lagune-verify`](https://lagune.ai/ko-KR/docs/commands/verify) 명령어가 맡습니다. prove 명령어는 증거를 만들 뿐, 아무것도 종결하지 않습니다. ## 자주 묻는 질문 ### Lagune이 익스플로잇을 생성하나요? 아니요. /lagune-prove 명령어는 방어 전용 증거를 작성합니다. 안전한 경로를 검증해 문제가 남아 있는 동안 실패하고 코드를 수정하면 통과하는 테스트, 그리고 책임 있는 공개를 위한 보안 권고입니다. ### prove 명령어는 무엇을 출력하나요? 발견 사항마다 파일 2개를 출력합니다. 테스트(report.test.mjs 또는 .cjs)와 보안 권고(report.md)입니다. ### Lagune이 찾은 버그를 책임 있게 공개하려면 어떻게 해야 하나요? prove 명령어는 단독으로 읽을 수 있는 보안 권고를 작성합니다. 책임 있는 공개 원칙에 따라 비공개 GitHub Gist 같은 비공개 채널로 공유할 수 있습니다. --- # agent 훅: 상한 없는 에이전트 루프 탐지하기 > 명령줄에서 코드베이스를 스캔해 스텝 수나 시간에 상한이 없는 에이전트나 LLM 호출을 찾거나, 호출 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/agent 언어: ko-KR 원문: https://lagune.ai/docs/hooks/agent 마지막 업데이트: 2026-11-03 `agent` 훅은 **턴 수, 예산, 시간 중 어느 것에도 상한을 두지 않고 반복 실행되는 에이전트 런타임**을 잡아냅니다. 자율 실행이 폭주할 수 있는 이 허점 때문에, 조작된 입력 하나가 끝없는 비용 증가나 프롬프트 인젝션 피해 확대로 이어집니다. **언어를 인식하며**, 두 에이전트 프레임워크 생태계를 다룹니다: **JavaScript**(**Claude** 에이전트 SDK의 `query` 런타임)와 **Python**(**LangChain**, **LangGraph**, **CrewAI**, **OpenAI Agents**)입니다. 또한 [`llm` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 직접 실행할 수도 있습니다. ## 실행하기 **코드베이스 스캔** ```bash npx lagune read agent # scans the whole project npx lagune read agent --dir src/ai # scans a directory npx lagune read agent --file chat.ts # scans a single file ``` **호출 검사** ```bash npx lagune read agent --lang javascript --pattern 'query({ prompt })' # => uncapped npx lagune read agent --lang javascript --pattern 'query({ prompt, options: { maxTurns: 5 } })' # => safe npx lagune read agent --lang python --pattern 'AgentExecutor(agent=a, max_iterations=None)' # => uncapped ``` **Uncapped agent loops found** 아래의 각 줄은 에이전트 SDK를 임포트하는 파일에서 찾은 다음 둘 중 하나입니다: 턴 수, 예산, 시간 상한 없이 호출한 Claude 에이전트 SDK의 `query` 런타임(JavaScript, 기본적으로 상한 없음), 또는 `max_iterations=None` / `max_turns=None` 설정처럼 프레임워크의 기본 상한을 명시적으로 없앤 코드(Python, 기본적으로 상한 있음)입니다. 어느 쪽이든 0이 아닌 종료 코드를 반환합니다. Vercel AI SDK의 `generateText`/`streamText` 함수는 기본적으로 한 스텝만 실행하므로(`stopWhen: stepCountIs(1)` 설정) 옵션 없이 호출해도 반복되지 않아 잡아내지 않으며, 평범한 `db.query(...)` 호출을 에이전트 호출로 오인하는 일도 없습니다. 아무것도 발견되지 않으면 `no uncapped agent loops found` 메시지를 출력합니다. ## 판정 해석하기 | 판정 | 의미 | | ---------- | ----------------------------------------------------------------------------------------- | | `uncapped` | 상한이 없는 `query` 런타임 호출(JS), 또는 명시적인 상한 제거(`=None`, Py) | | `safe` | 상한을 설정한 `query` 호출, 한 스텝짜리 생성, 또는 기본적으로 상한이 있는 프레임워크 호출 | | `invalid` | 판정할 수 있는 에이전트 호출이 없는 코드 조각 | ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | --------- | --------------------------------------------------------------------------- | | `--pattern` | 코드 조각 | 호출 하나 검사. 반복해 지정하면 여러 호출을 검사해 한 줄에 판정 하나씩 출력 | | `--lang` | 언어 | `--pattern` 옵션 사용 시 필수: `javascript` 또는 `python` | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션에는 `--lang` 옵션이 필요하며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. **전수 검사가 아닌 최선의 탐지** 직접 구현한 에이전트 루프는 어떤 언어로 작성했든 정적 스캔으로 잡아낼 수 없습니다. 완전한 목록이 아니라 든든한 최소 기준으로 활용하세요. **팁** 훅이 판단하는 것은 상한뿐입니다: 기능 범위 제한, 신뢰 수준 혼재, 인가처럼 판단이 필요한 부분은 여전히 [`llm` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다룹니다. ## 자주 묻는 질문 ### 에이전트 루프에 왜 상한을 둬야 하나요? 상한이 없는 에이전트는 끝없는 재귀, 비용 증가, 프롬프트 인젝션 피해 확대로 내몰릴 수 있습니다. maxTurns/maxBudgetUsd/stopWhen/signal을 설정하면 실행에 한계가 생기며, agent 훅은 이 중 아무것도 설정하지 않은 query 런타임 호출을 잡아냅니다. --- # cors 훅: CORS 오리진 점검하기 > 명령줄에서 소스 코드를 스캔해 우회할 수 있는 CORS 오리진 허용 목록을 찾거나, 오리진 값 하나가 지나치게 넓은 접근을 허용하는지 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/cors 언어: ko-KR 원문: https://lagune.ai/docs/hooks/cors 마지막 업데이트: 2026-11-03 `cors` 훅은 [`http-request` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, 직접 실행할 수도 있습니다. 명령어 하나로 두 가지 모드를 쓸 수 있습니다: **scan** 모드는 소스 코드를 스캔해 **우회할 수 있는 오리진 허용 목록**(공격자 호스트가 빠져나갈 수 있는 호스트 검증 정규식)을 찾고, **score** 모드는 **CORS 오리진** 값 하나에 점수를 매겨 `wildcard`, `null`, `safe` 중 하나로 판정합니다. ## 코드베이스 스캔 플래그를 지정하지 않으면 프로젝트 전체를 스캔합니다. **프로젝트 전체** ```bash npx lagune read cors ``` **특정 디렉터리** ```bash npx lagune read cors --dir src/server ``` **단일 파일** ```bash npx lagune read cors --file internal/auth/origin.go ``` 우회할 수 있는 허용 목록을 파일별로 묶어 헤더 하나 아래에 나열합니다. 신뢰하는 호스트 접미사 앞의 authority 부분에 `.+`/`.*` 패턴이 있는 호스트 검증(`^https?://.+\.trusted\.com`)은 `your-site.com.attacker.com` 같은 공격자 호스트를 그대로 통과시킵니다. ```text Origin-allowlist patterns with a greedy wildcard (bypassable, review): internal/auth/origin.go ^https?://.+\.trusted\.com ``` 이는 확정된 발견 사항이 아니라 검토할 단서입니다: 정규식이 실제 신뢰 판단을 좌우하는지는 텍스트만으로 판단할 수 없으므로, 스캔 결과는 종료 코드를 바꾸지 않습니다. 항목마다 직접 읽고 허용 목록이 완전 일치로 비교하는지 확인하세요. 아무것도 발견되지 않으면 한 줄만 출력합니다. ```bash npx lagune read cors --dir src/clean # => no bypassable origin allowlist found ``` ## 오리진 점수 매기기 각 오리진을 `--origin` 옵션으로 전달하세요. 훅은 오리진마다 단어 하나를 출력하며, `wildcard` 또는 `null` 판정이 하나라도 있으면 0이 아닌 종료 코드를 반환합니다. **오리진 하나** ```bash npx lagune read cors --origin '*' # => wildcard npx lagune read cors --origin 'null' # => null npx lagune read cors --origin 'https://app.example.com' # => safe ``` **여러 오리진** `--origin` 옵션을 반복해 지정하면 허용 목록 전체에 한 번에 점수를 매길 수 있으며, 판정은 입력 순서대로 한 줄에 하나씩 출력됩니다. ```bash npx lagune read cors \ --origin 'https://app.example.com' \ --origin '*' \ --origin 'null' # => safe # => wildcard # => null ``` | 판정 | 의미 | | ---------- | --------------------------------------------------------------------------------------------------- | | `safe` | `*`, `null`, `*` 글롭 중 어느 것도 아닌 값. 다만 오리진 형식이 올바르다는 보장은 아님 | | `wildcard` | `*`, 또는 서브도메인, 호스트, 포트 글롭: 모든 사이트(또는 넓은 범위의 사이트)가 응답을 읽을 수 있음 | | `null` | 샌드박스 처리된 iframe이나 리디렉션이 위조할 수 있는 `null` 오리진 | 허용으로 볼 수 있는 판정은 `safe` 판정뿐이며, `--origin` 옵션은 값을 판정하는 오라클입니다: 핸들러가 아니라 값만 판정하므로, 핸들러는 `http-request` 전문 지식으로 확인하세요. ### CLI 옵션 | 옵션 | 값 | 설명 | | ---------- | -------- | --------------------------------------------------------------------------------------- | | `--origin` | 오리진 | 오리진 값 하나에 점수 매기기. 반복해 지정하면 여러 값에 점수를 매겨 한 줄에 하나씩 출력 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--origin` 옵션은 score 모드이며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. **다루지 않는 범위** 스캔이 읽는 것은 **우회할 수 있는 정규식** 형태이고, `--origin` 옵션이 점수를 매기는 것은 오리진 **값**입니다. 소스 코드 수준의 두 가지 패턴은 다루지 못합니다: 요청의 `Origin` 헤더 반사(서버가 받은 `Origin` 헤더를 그대로 돌려주거나, 자격 증명 허용과 함께 돌려주는 경우)와, `endsWith` 또는 부분 문자열로 비교하는 느슨한 허용 목록입니다. 이런 패턴은 코드에서 직접 알아보고, [`http-request` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)에 설명된 대로 처리하세요. ## 자주 묻는 질문 ### CORS의 null 오리진은 왜 위험한가요? 샌드박스 처리된 iframe과 일부 리디렉션은 Origin: null을 보내므로, null을 신뢰하는 허용 목록은 그런 컨텍스트에 읽기 권한을 주게 됩니다. cors 훅은 와일드카드와 함께 이것도 잡아냅니다. ### 우회할 수 있는 CORS 오리진 허용 목록은 어떻게 찾아내나요? 코드베이스를 대상으로 npx lagune read cors 명령어를 실행하세요. 신뢰하는 접미사 앞에 탐욕적 와일드카드가 있는 호스트 검증 정규식을 잡아내며, 이런 정규식은 your-site.com.attacker.com 같은 공격자 호스트를 그대로 통과시킵니다. --- # crypto 훅: 취약한 암호화 탐지하기 > 명령줄에서 코드베이스를 스캔해 취약한 암호 알고리즘을 찾거나, 코드 조각 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/crypto 언어: ko-KR 원문: https://lagune.ai/docs/hooks/crypto 마지막 업데이트: 2026-11-03 `crypto` 훅은 **취약한 암호 알고리즘**을 호출 지점에서 잡아냅니다: 지원 중단된 암호 방식, 안전하지 않은 모드, 깨진 해시 함수가 그 대상입니다. **언어를 인식해** 파일마다 그 언어의 규칙으로 읽으므로 Rust 파일에서 Python 구문을 잡아내는 일은 없습니다. 또한 [`crypto` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 직접 실행할 수도 있습니다. ## 실행하기 **코드베이스 스캔** ```bash npx lagune read crypto # scans the whole project npx lagune read crypto --dir src # scans a directory npx lagune read crypto --file hash.ts # scans a single file ``` **코드 조각 검사** ```bash npx lagune read crypto --lang javascript --pattern 'createCipher("aes-256-cbc", k)' # => weak npx lagune read crypto --lang python --pattern 'hashlib.md5(data)' # => review npx lagune read crypto --lang go --pattern 'sha256.Sum256(data)' # => safe ``` 스캔 결과는 최대 두 개의 섹션으로 출력됩니다. **Weak cryptography found** 섹션은 발견 사항 목록(DES/3DES/RC4/Blowfish/RC2, ECB 모드)입니다: 모두 깨진 암호 알고리즘이므로 훅은 0이 아닌 종료 코드를 반환합니다. **Cryptography to review manually** 섹션은 훅 혼자서는 판단할 수 없는 단서 목록입니다: MD5/SHA-1 해시(보안 용도로는 깨졌지만 단순 체크섬으로는 문제가 없어 용도에 따라 판단이 갈림), 보안 용도로 쓰인 비암호학적 난수 생성기, 타이밍 공격에 취약한 비교가 여기에 해당합니다. 아무것도 발견되지 않으면 `no weak cryptography found` 메시지를 출력합니다. ## 판정 해석하기 | 판정 | 의미 | | --------- | -------------------------------------------------------------------------------------------------- | | `weak` | 깨진 암호 알고리즘(DES/3DES, RC4, Blowfish, RC2, 또는 ECB 모드)을 사용하는 코드 조각 | | `review` | 용도에 따라 판단이 달라지는 알고리즘: MD5/SHA-1 해시, 또는 보안 용도로 쓰인 비암호학적 난수 생성기 | | `safe` | 암호화를 사용하지만 취약한 알고리즘은 발견되지 않은 코드 조각 | | `invalid` | 판정할 수 있는 암호 구문이 없는 코드 조각 | ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------ | | `--pattern` | 코드 조각 | 코드 조각 하나 검사. 반복해 지정하면 여러 코드 조각을 검사해 한 줄에 판정 하나씩 출력 | | `--lang` | 언어 | `--pattern` 옵션 사용 시 필수: javascript, python, go, java, kotlin, php, ruby, rust, csharp, c, cpp 중 하나 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션에는 `--lang` 옵션이 필요하며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. ### 지원 언어 스캔은 파일 확장자로 다음 언어를 구분해 읽고, 언어마다 해당 언어의 암호 API를 기준으로 검사합니다. | 언어 | 취약한 암호 방식(발견 사항), 해시와 난수 생성기(검토) | | --------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **JavaScript / TypeScript** | `createCipher`, `CryptoJS.DES/RC4`, 따옴표로 감싼 `*-ecb`; MD5/SHA-1용 `createHash`/`subtle.digest`; `Math.random()` | | **Python** | pycryptodome의 `DES/ARC4/Blowfish.new`, `algorithms.TripleDES`, `MODE_ECB`; `hashlib.md5/sha1`; `random.*` | | **Go** | `des.NewCipher`, `rc4.NewCipher`, `blowfish.NewCipher`, `NewECBEncrypter`; `md5/sha1.Sum`; `math/rand` | | **Java / Kotlin** | `Cipher.getInstance("DES"/…/ECB")`; `MessageDigest.getInstance("MD5")`, `HmacMD5`; `java.util.Random` | | **PHP** | `openssl_encrypt("des-…"/"…-ecb")`, `mcrypt_*`; `md5()`/`sha1()`, `hash("md5", …)`; `rand()`/`mt_rand()` | | **Ruby** | `OpenSSL::Cipher.new("des-…")`, `:ECB`; `Digest::MD5/SHA1`; `rand()`/`Random` | | **Rust** | `Rc4::`, `Blowfish::`, `des::`, `ecb::`; `Md5::`, `Sha1::`, `Hmac`; `SmallRng`/`XorShiftRng` | | **C#** | `DES/TripleDES/RC2.Create`, `CipherMode.ECB`; `MD5/SHA1.Create`, `HMACMD5`; `new Random()` | | **C / C++** | OpenSSL의 `DES_*`/`RC4`/`EVP_des_*`, `EVP_*_ecb`; `MD5()`/`SHA1()`, `EVP_md5`; `rand()`/`random()` | **전수 검사가 아닌 최선의 탐지** 소스 코드를 텍스트로 읽으므로, 런타임에 조합되거나 별칭 뒤에 숨겨졌거나 인식하지 못하는 형태로 작성된 알고리즘은 놓칠 수 있습니다. 이 표를 완전한 목록이 아니라 든든한 출발점으로 활용하세요. **팁** 훅이 보장하는 것은 최소 기준(이런 구문이 존재한다는 사실)입니다: 키 관리, IV 재사용, RSA 패딩처럼 판단이 필요한 부분은 여전히 [`crypto` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다룹니다. ## 자주 묻는 질문 ### 코드베이스에서 취약한 암호화를 찾으려면 어떻게 스캔하나요? 플래그 없이 crypto 훅을 실행하세요. 깨진 암호 방식과 ECB 모드는 발견 사항으로 분류되어 0이 아닌 종료 코드를 반환합니다. MD5/SHA-1 해시는 보안 용도로는 깨졌지만 단순 체크섬으로는 문제가 없으므로 검토할 단서로 분류합니다. ### crypto 훅은 Math.random() 호출도 잡아내나요? 보안 용도로 쓰인 경우에만 검토할 단서로 잡아내며, 자동으로 발견 사항이 되지는 않습니다. 지터나 UI 정렬 순서에 난수를 쓰는 것은 문제없는 용도이기 때문입니다. --- # cvss 훅: CVSS v4.0 벡터 점수 매기기 > 명령줄에서 CVSS v4.0 벡터 하나 또는 여러 개에 FIRST 계산기와 같은 계산 방식으로 점수를 매기고, 각 벡터를 쉬운 말로 풀어 볼 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/cvss 언어: ko-KR 원문: https://lagune.ai/docs/hooks/cvss 마지막 업데이트: 2026-11-03 `cvss` 훅은 **CVSS v4.0 벡터**에 점수를 매기고 점수와 심각도 등급을 출력합니다. [`/lagune-plan`](https://lagune.ai/ko-KR/docs/commands/plan) 명령어가 각 수정에, [`/lagune-prove`](https://lagune.ai/ko-KR/docs/commands/prove) 명령어가 각 보안 권고에 기록하는 평가가 바로 이것입니다. 훅은 이 평가를 뒷받침하는 결정론적 엔진으로 [FIRST 계산기](https://www.first.org/cvss/calculator/4.0)와 같은 계산 방식을 사용하며, 직접 실행할 수도 있습니다. ## 실행하기 각 벡터를 `--vector` 옵션으로 전달하세요. 훅은 벡터마다 점수와 등급을 한 줄로 출력합니다. **벡터 하나** ```bash npx lagune read cvss --vector 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N' # => 9.3, Critical ``` **여러 벡터** `--vector` 옵션을 반복해 지정하면 여러 벡터에 한 번에 점수를 매기며, 입력 순서대로 한 줄씩 출력합니다. ```bash npx lagune read cvss \ --vector 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N' \ --vector 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/MAV:A' # => 9.3, Critical # => 8.7, High ``` **쉬운 말로** `--explain` 옵션을 추가하면 각 지표를 쉬운 말로 풀어 보여 줍니다. Threat 지표나 Environmental 지표가 점수를 바꾸면, Base 지표만으로 매긴 점수가 먼저 나옵니다. ```bash npx lagune read cvss --explain --vector 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/MAV:A' # => 8.7, High # => Base metrics alone: 9.3, Critical # => Attack Vector: Network, modified to Adjacent # => Attack Complexity: Low # => ... ``` ## 결과 해석하기 | 등급 | 점수 | | ---------- | -------- | | `None` | 0.0 | | `Low` | 0.1~3.9 | | `Medium` | 4.0~6.9 | | `High` | 7.0~8.9 | | `Critical` | 9.0~10.0 | Base 지표만 있는 벡터는 최악의 상황, 즉 모든 보안 요구 사항이 High이고 결함이 실제로 공격에 악용되고 있는 상황을 가정해 결함 자체에 점수를 매깁니다. Environmental 지표(`MAV` 등의 수정 지표와 `CR`, `IR`, `AR` 지표)는 특정 배포 환경에 맞춰, Threat 지표(`E`)는 악용에 관해 알려진 정보에 맞춰 점수를 확정합니다. 잘못된 벡터를 넣으면 `invalid vector:` 메시지와 함께 무엇이 잘못됐는지 출력하고, 훅은 0이 아닌 종료 코드를 반환합니다. ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | --------------- | -------------------------------------------------------------------------------------------------- | | `--vector` | `CVSS:4.0` 벡터 | 벡터 하나에 점수 매기기. 반복해 지정하면 여러 벡터에 점수를 매겨 입력 순서대로 벡터당 한 줄씩 출력 | | `--explain` | | 모든 평가 줄 아래에 각 지표를 쉬운 말로 덧붙여 출력 | `--vector` 옵션은 하나 이상 필요합니다. 벡터는 절대 단독 위치 인수로 받지 않으므로 플래그로 오인될 일이 없습니다. **플래그 값으로 전달하는 이유** 각 벡터는 명령어에 끼워 넣지 않고 항상 플래그 값으로 전달합니다. 따옴표나 백틱이 든 값도 아무 효과 없이 그대로 남아 셸에 인젝션될 수 없습니다. 셸이 먼저 값을 확장하지 않도록 항상 작은따옴표로 감싸세요. **다루지 않는 범위** CVSS v4.0만 지원합니다: **Lagune**은 모든 발견 사항을 v4.0으로 평가하므로, v2.0, v3.0, v3.1 벡터는 점수를 매기지 않고 거부합니다. **팁** plan 단계의 검증은 모든 CVSS 줄에 이와 같은 계산을 다시 실행하므로, 벡터와 어긋난 점수는 계획이 승인되기 전에 잡힙니다. ## 자주 묻는 질문 ### Lagune은 CVSS 점수를 어떻게 계산하나요? cvss 훅은 FIRST의 CVSS v4.0 참조 계산기를 그대로 따르므로, 벡터 점수는 FIRST 사이트에서 계산한 결과와 정확히 같습니다. ### 이 훅으로 CVSS v3.1 벡터에도 점수를 매길 수 있나요? 아니요. Lagune은 모든 발견 사항을 CVSS v4.0으로 평가하며, 훅은 다른 버전의 벡터에는 점수를 매기지 않고 거부합니다. ### --explain 플래그는 어떤 역할을 하나요? 각 지표를 쉬운 말로 풀어 주고, 전체 점수 옆에 Base 점수를 함께 보여 줍니다. 그래서 누구나 벡터가 무엇을 뜻하는지, 프로젝트 컨텍스트가 점수를 어떻게 바꿨는지 확인할 수 있습니다. --- # infra 훅: IaC 설정 오류 탐지하기 > 명령줄에서 Terraform, Dockerfile, GitHub Actions를 스캔해 설정 오류를 찾거나, 코드 조각 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/infra 언어: ko-KR 원문: https://lagune.ai/docs/hooks/infra 마지막 업데이트: 2026-11-03 `infra` 훅은 파일만 보고 판단할 수 있는 **코드형 인프라(IaC) 설정 오류**를 잡아냅니다: 전 세계에 열린 네트워크, 와일드카드 권한, 매니페스트 안의 시크릿, root로 실행되는 컨테이너, CI 셸에 들어가는 신뢰할 수 없는 값이 여기에 해당합니다. 읽는 파일은 IaC 파일(`.tf`/`.tf.json`/`.hcl`, `Dockerfile*`, `.github/workflows/**`)뿐입니다. 또한 [`infra` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 동작합니다. ## 실행하기 **코드베이스 스캔** ```bash npx lagune read infra # scans every IaC file npx lagune read infra --dir infra # scans a directory npx lagune read infra --file Dockerfile # scans a single file ``` **코드 조각 검사** 코드 조각은 `--pattern` 옵션으로, 그 종류는 `--kind` 옵션(`terraform`, `dockerfile`, `github-actions` 중 하나)으로 전달하세요. ```bash npx lagune read infra --kind terraform --pattern 'actions = ["*"]' # => iam-wildcard npx lagune read infra --kind dockerfile --pattern 'FROM node:20' # => mutable-tag ``` 스캔 결과는 최대 두 개의 섹션으로 출력됩니다. **Infrastructure risks found** 섹션에는 판단할 수 있는 결함(민감한 포트에 `0.0.0.0/0` 인바운드를 허용하는 규칙, 와일드카드 IAM 구문, 매니페스트 안의 시크릿, `encrypted = false` 설정, 버전이 고정되지 않은 git 모듈, 명시적으로 root로 실행되는 이미지, `curl | sh` 실행, CI 스크립트 인젝션, `permissions: write-all` 설정)이 담기며, 이 섹션이 나오면 0이 아닌 종료 코드를 반환합니다. **Infrastructure hardening advisories** 섹션은 종료 코드를 바꾸지 않습니다(내용이 바뀔 수 있는 베이스 이미지 태그, 태그로만 고정한 액션). 아무것도 발견되지 않으면 `no infrastructure risks found` 메시지를 출력합니다. ## 판정 해석하기 check 모드는 일치한 태그 중 심각도가 가장 높은 태그(예: `public-ingress`, `iam-wildcard`, `root-user`, `curl-pipe`, `script-injection`, `write-all`), 권고 태그(`mutable-tag`, `unpinned-action`), 또는 `safe` 판정을 출력합니다. 0이 아닌 종료 코드를 반환하는 것은 발견 사항 수준의 태그뿐입니다. ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | `--pattern` | 코드 조각 | 코드 조각 하나 검사. `--kind` 옵션 필요. 반복해 지정하면 여러 개 검사 | | `--kind` | `terraform` \| `dockerfile` \| `github-actions` | 코드 조각을 어떤 종류로 판정할지 지정 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트의 모든 IaC 파일을 스캔합니다. `--pattern` 옵션은 `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. **팁** 훅은 명백하고 판단할 수 있는 경우만 잡아냅니다: 암호화 누락, `pull_request_target` 노출, 적절한 IAM 범위처럼 판단이 필요한 부분은 여전히 [`infra` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다룹니다. ## 자주 묻는 질문 ### infra 훅은 어떤 인프라 파일을 읽나요? Terraform/HCL(.tf, .tf.json, .hcl), Dockerfile, 그리고 .github/ 아래에 있는 GitHub Actions 워크플로와 액션 YAML 파일을 읽습니다. 소스 코드 스캐너는 이런 파일을 건너뛰지만, infra 훅은 이 파일까지 읽습니다. --- # interpreter 훅: 동적 코드 실행 싱크 잡아내기 > 명령줄에서 코드베이스를 스캔해 여러 언어의 동적 코드 실행 싱크를 찾거나, 코드 조각 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/interpreter 언어: ko-KR 원문: https://lagune.ai/docs/hooks/interpreter 마지막 업데이트: 2026-11-03 `interpreter` 훅은 데이터를 실행되는 코드로 바꾸거나 셸에 넘기는 구문, 즉 **동적 코드 실행 싱크**를 잡아냅니다. `eval` 호출부터 네이티브 역직렬화까지 모두 여기에 해당합니다. 언어를 인식해 파일마다 그 언어의 규칙으로 읽습니다. 또한 [`interpreter` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 직접 실행할 수도 있습니다. ## 실행하기 **코드베이스 스캔** ```bash npx lagune read interpreter # scans the whole project npx lagune read interpreter --dir src # scans a directory npx lagune read interpreter --file app.py # scans a single file ``` **코드 조각 검사** ```bash npx lagune read interpreter --lang javascript --pattern 'eval(x)' # => careful npx lagune read interpreter --lang python --pattern 'json.loads(x)' # => safe ``` 이런 싱크는 정상적인 용도로도, 위험한 용도로도 쓰일 수 있습니다. 공격자가 영향을 줄 수 있는 입력이 싱크에 도달하는지는 정적 스캔으로 판단할 수 없으므로, 일치하는 항목은 모두 확정된 발견 사항이 아니라 **검토할 주의 사항**입니다. 스캔은 파일별로 묶은 **Dynamic-execution sinks to review** 섹션 하나를 출력합니다. 아무것도 발견되지 않으면 `no dynamic-execution sinks found` 메시지를 출력합니다. **잡아낸 코드는 읽기만 하고, 절대 실행하지 마세요!** 신뢰할 수 없는 입력이 각 싱크에 도달하는지 추적하며 **정적으로** 분석하세요. 어떻게 동작하는지 "테스트"하겠다고 잡아낸 코드를 실행하거나 `eval` 함수에 넘기는 일은 절대 하지 마세요. 그 코드가 불러오는 원격 코드나 런타임에 가져오는 코드도 마찬가지입니다. ## 판정 해석하기 | 판정 | 의미 | | --------- | --------------------------------------------------------------------------- | | `careful` | 해당 언어의 동적 실행 싱크가 들어 있는 코드 조각. 실행하지 말고 읽어서 검토 | | `safe` | 지정한 언어의 동적 실행 싱크가 발견되지 않음 | ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------ | | `--pattern` | 코드 조각 | 코드 조각 하나 검사. 반복해 지정하면 여러 코드 조각을 검사해 한 줄에 판정 하나씩 출력 | | `--lang` | 언어 | `--pattern` 옵션 사용 시 필수: javascript, python, php, ruby, java, kotlin, go, rust, c, cpp, csharp 중 하나 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션에는 `--lang` 옵션이 필요하며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. ### 지원 언어 스캔은 파일 확장자로 다음 언어를 구분해 읽고, 언어마다 고유한 동적 실행 싱크 목록과 대조해 검사합니다. | # | 언어 | 확장자 | 잡아내는 싱크 | | --- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **JavaScript / TypeScript** | `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.astro`, `.vue`, `.svelte`, `.marko`, `.riot` | `eval()`, Function 생성자, 문자열 본문을 받는 `setTimeout`/`setInterval`, `vm` 모듈, `child_process` exec, 동적 `require()`, 동적 `import()` | | 2 | **Python** | `.py`, `.pyi` | `eval`/`exec`, `__import__()`, `os.system`/`os.popen`, `subprocess` `shell=True`, `pickle.load`/`loads`, `yaml.load`(안전하지 않은 사용) | | 3 | **Ruby** | `.rb` | eval 계열(`instance_eval`/`class_eval`/`module_eval`/`eval`), `system`/`exec`, 백틱 또는 `%x`, `Kernel#open` / `IO.popen`/`read`/`binread` / `Open3`, `Process.spawn`, `Marshal.load` | | 4 | **Go** | `.go` | `exec.Command`/`exec.CommandContext`, `plugin.Open` | | 5 | **PHP** | `.php` | `eval()`, 문자열을 넘긴 `assert()`, `create_function()`, 셸 실행(`system`/`exec`/`shell_exec`/`passthru`/`popen`/`proc_open`), `call_user_func`/`call_user_func_array`, 런타임 경로를 쓰는 `include`/`require` | | 6 | **Rust** | `.rs` | `Command::new`, `process::Command` | | 7 | **Java** | `.java` | `Runtime.exec`, `ProcessBuilder`, `ScriptEngine`, `ObjectInputStream.readObject` | | 8 | **Kotlin** | `.kt`, `.kts` | JVM 싱크: `Runtime.exec`, `ProcessBuilder`, `ScriptEngine`, `ObjectInputStream.readObject` | | 9 | **C#** | `.cs` | `Process.Start` / `new Process`, `BinaryFormatter`, `Assembly.Load` | | 10 | **C** | `.c`, `.h` | `system()`, `popen()`, `exec*` 계열(`execl`, `execve`, `execvp`, …) | | 11 | **C++** | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx` | `system()`, `popen()`, `exec*` 계열(`execl`, `execve`, `execvp`, …) | **전수 검사가 아닌 최선의 탐지** 소스 코드를 텍스트로 읽으므로, 런타임에 조합되거나 별칭 뒤에 숨겨졌거나 인식하지 못하는 형태로 작성된 싱크는 놓칠 수 있습니다. 이 표를 완전한 목록이 아니라 든든한 출발점으로 활용하세요. **팁** 훅이 보장하는 것은 최소 기준(이런 싱크가 존재한다는 사실과 그 위치)입니다. 신뢰할 수 없는 값이 실제로 싱크에 도달하는지는 [`interpreter` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다루는 판단입니다. ## 자주 묻는 질문 ### interpreter 훅으로 취약점을 확정할 수 있나요? 아니요. 동적 실행 싱크를 확정된 발견 사항이 아니라 검토할 주의 사항으로 잡아냅니다. 공격자가 영향을 줄 수 있는 입력이 싱크에 도달하는지는 정적 스캔으로 판단할 수 없기 때문입니다. ### interpreter 훅은 어떤 언어를 지원하나요? 지원 언어 표에 있는 언어를 파일 확장자로 구분해 읽고, 언어마다 고유한 싱크 목록과 대조해 검사합니다. 그 밖의 언어에서는 싱크를 보고하지 않습니다. --- # jwt 훅: 알고리즘을 고정하지 않은 JWT 검증 탐지하기 > 명령줄에서 코드베이스를 스캔해 알고리즘을 고정하지 않은 JWT 검증을 찾거나, 호출 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/jwt 언어: ko-KR 원문: https://lagune.ai/docs/hooks/jwt 마지막 업데이트: 2026-11-03 `jwt` 훅은 **알고리즘을 고정하지 않은 JWT 검증**과 **아예 꺼 버린 검증**을 잡아냅니다. 알고리즘을 고정하지 않은 검증은 검증하는 쪽이 토큰에 적힌 `alg` 헤더를 그대로 믿게 되는 알고리즘 혼동 허점입니다. **언어를 인식해** 파일마다 그 파일이 쓰는 JWT 라이브러리에 맞춰 읽습니다. 또한 [`federation` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 직접 실행할 수도 있습니다. ## 실행하기 **코드베이스 스캔** ```bash npx lagune read jwt # scans the whole project npx lagune read jwt --dir src # scans a directory npx lagune read jwt --file auth.ts # scans a single file ``` **호출 검사** ```bash npx lagune read jwt --lang javascript --pattern 'jwt.verify(token, secret)' # => unpinned npx lagune read jwt --lang python --pattern 'jwt.decode(t, k, options={"verify_signature": False})' # => unpinned npx lagune read jwt --lang python --pattern 'jwt.decode(t, k, algorithms=["HS256"])' # => safe ``` **Unpinned JWT verification found** 섹션 아래의 각 줄은 `algorithms` 허용 목록을 지정하지 않았거나(라이브러리가 요구하는 경우), 안전하지 않은 허용 목록(`none`, 또는 비대칭 알고리즘과 HMAC의 혼용)을 받아들이거나, 서명 검사를 아예 꺼 버려서 토큰에 적힌 `alg` 값을 믿게 되는 검증 호출입니다. 확정된 노출이므로 훅은 0이 아닌 종료 코드를 반환합니다. 아무것도 발견되지 않으면 `no unpinned JWT verification found` 메시지를 출력합니다. ## 판정 해석하기 | 판정 | 의미 | | ---------- | -------------------------------------------------------------------------------------------- | | `unpinned` | 알고리즘 허용 목록이 없거나(필요한 경우), 허용 목록이 안전하지 않거나, 검증이 꺼진 검증 호출 | | `safe` | 안전한 알고리즘 허용 목록을 고정했거나, 라이브러리가 암묵적으로 고정하는 검증 호출 | | `invalid` | 판정할 수 있는 검증 호출이 없는 코드 조각 | ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | --------- | ---------------------------------------------------------------------------------------------------- | | `--pattern` | 코드 조각 | 호출 하나 검사. 반복해 지정하면 여러 호출을 검사해 한 줄에 판정 하나씩 출력 | | `--lang` | 언어 | `--pattern` 옵션 사용 시 필수: javascript, python, go, java, kotlin, php, ruby, rust, csharp 중 하나 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션에는 `--lang` 옵션이 필요하며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. ### 지원 언어 스캔은 파일 확장자로 다음 라이브러리를 구분해 읽습니다. 일부 라이브러리는 알고리즘을 암묵적으로 고정해 명시적인 목록이 없어도 안전하므로, "허용 목록 없음 ⇒ unpinned" 규칙은 라이브러리가 명시적인 목록을 기대하는 경우에만 적용됩니다. 그래서 올바르게 설정된 호출을 잡아내는 일은 없습니다. | 언어 | 라이브러리 | 허용 목록이 없을 때 unpinned 판정 여부 | 항상 잡아내는 것 | | --------------------------- | ----------------------- | ---------------------------------------------------------- | ----------------------------------------------- | | **JavaScript / TypeScript** | jsonwebtoken, jose | 예 | `none`, 비대칭 알고리즘과 HMAC의 혼용 | | **Python** | PyJWT, python-jose | 예(PyJWT는 필수, python-jose는 기본값이 `algorithms=None`) | `none`, `verify_signature: False` | | **Go** | golang-jwt | 예(`WithValidMethods` 옵션이 없는 경우) | `none`, `ParseUnverified` | | **Ruby** | ruby-jwt | 예 | `none`, `verify = false` | | **Java / Kotlin** | jjwt, nimbus | 아니요(키에서 도출) | `none`, 서명 없는/`unsecured` 파서 | | **PHP** | firebase/php-jwt | 아니요(`Key` 객체가 알고리즘을 담음) | `none` | | **Rust** | jsonwebtoken | 아니요(`Validation` 구조체가 알고리즘 지정을 요구) | `none`, `insecure_disable_signature_validation` | | **C#** | Microsoft.IdentityModel | 아니요(매개변수가 여러 줄에 걸침) | `none`, `RequireSignedTokens = false` | **팁** 훅이 판단하는 것은 알고리즘 고정뿐입니다. 클레임, 키, 흐름 검사처럼 판단이 필요한 부분은 여전히 [`federation` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다룹니다. ## 자주 묻는 질문 ### JWT 알고리즘 혼동이란 무엇인가요? 검증 코드가 토큰 헤더에서 알고리즘을 읽으면, 공격자가 RS256을 HS256으로 바꿔치기하고 공개 키로 서명할 수 있습니다. 안전한 알고리즘 허용 목록을 코드에 고정하면 이를 막을 수 있으며, jwt 훅은 허용 목록을 지정하지 않았거나 안전하지 않은 허용 목록을 쓰는 검증 호출을 잡아냅니다. --- # network 훅: SSRF 관점에서 URL 점수 매기기 > 명령줄에서 바로 요청 대상 하나 또는 여러 개에 SSRF 관점의 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/network 언어: ko-KR 원문: https://lagune.ai/docs/hooks/network 마지막 업데이트: 2026-11-03 `network` 훅은 서버 측 요청 대상이 **SSRF**(내부 서비스나 클라우드 메타데이터, 사설 호스트를 겨냥할 수 있는 요청)로부터 안전한지 판단합니다. [`network` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, 직접 실행할 수도 있습니다. ## 실행하기 각 요청 대상을 `--url` 옵션으로 전달하세요. 훅은 요청 대상마다 단어 하나를 출력하며, 그 의미는 아래 표에서 확인할 수 있습니다. **요청 대상 하나** ```bash npx lagune read network --url 'http://example.com/' # => safe npx lagune read network --url 'http://0x7f000001/' # => private-target ``` **여러 요청 대상** `--url` 옵션을 반복해 지정하면 허용 목록이나 차단 목록 전체에 한 번에 점수를 매길 수 있으며, 판정은 입력 순서대로 한 줄에 하나씩 출력됩니다. ```bash npx lagune read network \ --url 'http://example.com/' \ --url 'http://[::1]/' \ --url 'http://allowed.com@evil.example/' # => safe # => private-target # => parser-divergent ``` 호스트를 네트워크가 해석하는 방식 그대로 해석하므로, 내부 주소를 인코딩한 형태도 빠져나가지 못합니다. 16진수, 8진수, 점 없는 10진수, 축약형, IPv6, IPv4 매핑 주소는 모두 `private-target` 판정이 나옵니다. 그리고 허술한 검증기와 실제로 요청을 보내는 쪽이 서로 다른 호스트를 읽게 되는 경우에는 `parser-divergent` 판정이 나옵니다. ## 판정 해석하기 | 판정 | 의미 | | ------------------ | ---------------------------------------------------------------------------------------- | | `safe` | 공개 호스트에 연결되며, 허술한 검증기도 같은 호스트로 읽는 요청 대상 | | `private-target` | 사설, 루프백, 링크 로컬, 미지정, 클라우드 메타데이터 주소로 해석되는 호스트 | | `parser-divergent` | 허술한 텍스트 검증기가 읽는 실제 호스트가 요청을 보내는 쪽이 연결하는 호스트와 다른 경우 | | `invalid url` | URL로 파싱되지 않아 요청할 대상이 없는 문자열 | 허용으로 볼 수 있는 판정은 `safe` 판정뿐입니다. `private-target`, `parser-divergent`, `invalid url` 판정은 모두 차단으로 처리하세요. ### CLI 옵션 | 옵션 | 값 | 설명 | | ------- | --------------- | ------------------------------------------------------------------------------------- | | `--url` | URL 또는 호스트 | 요청 대상 하나 검사. 반복해 지정하면 여러 요청 대상을 검사해 한 줄에 판정 하나씩 출력 | `--url` 옵션은 하나 이상 필요합니다. 요청 대상은 절대 단독 위치 인수로 받지 않으므로 플래그로 오인될 일이 없습니다. **플래그 값으로 전달하는 이유** 각 요청 대상은 명령어에 끼워 넣지 않고 항상 플래그 값으로 전달합니다. 따옴표나 백틱이 든 값도 아무 효과 없이 그대로 남아 셸에 인젝션될 수 없습니다. 셸이 먼저 값을 확장하지 않도록 항상 작은따옴표로 감싸세요. **다루지 않는 범위** 훅은 순수 함수처럼 동작하며 DNS를 조회하지 않으므로, 런타임에 생기는 두 가지 허점은 범위 밖입니다. 바로 **DNS 리바인딩**(검사할 때는 공개 주소로, 요청할 때는 내부 주소로 해석되는 이름)과 **리디렉션 체인**(첫 요청은 통과한 뒤 내부로 리디렉션하는 경우)입니다. 이 허점은 이름을 한 번만 해석해 검증된 주소로 연결하고, 리디렉션을 거부해서 막으세요. 예약된 루프백 이름(`localhost` 및 `.localhost` 계열)은 조회 없이 내부 주소로 간주하지만, 그 밖의 DNS 이름은 모두 `safe` 판정이 나옵니다. 내부로 해석된다고 단정하려면 실제로 이름을 해석해야 하기 때문입니다. 이런 이름은 허용 목록이 막아 주며, 이 검사기가 검증하는 대상도 바로 그 허용 목록입니다. **팁** [`network` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 요청 대상 필터가 실제로 효과가 있는지 증명할 때 실행하는 것과 같은 검사입니다. ## 자주 묻는 질문 ### URL에 SSRF 위험이 있는지 어떻게 테스트하나요? network 훅을 실행하세요. 요청 대상에 점수를 매겨 safe, private-target, parser-divergent, invalid url 중 하나를 반환합니다. 허용으로 볼 수 있는 판정은 safe 판정뿐입니다. ### parser-divergent URL이란 무엇인가요? 파서마다 다르게 읽는 URL로, 대표적인 SSRF 우회 수법입니다. network 훅은 이런 URL을 허용하지 않고 잡아냅니다. --- # regex 훅: ReDoS 패턴 탐지하기 > 명령줄에서 코드베이스를 스캔해 ReDoS에 취약한 정규식을 찾거나, 패턴 하나에 점수를 매길 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/regex 언어: ko-KR 원문: https://lagune.ai/docs/hooks/regex 마지막 업데이트: 2026-11-03 `regex` 훅은 [`regex` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 실행하는 결정론적 정규식 안전성 엔진이며, 직접 실행할 수도 있습니다. 명령어 하나로 두 가지 모드를 쓸 수 있습니다: **scan** 모드는 **ReDoS**에 취약한 패턴과 런타임에 만들어지는 패턴이 있는지 코드베이스를 스캔하고, **check** 모드는 건네받은 패턴 하나에 점수를 매깁니다. ## 코드베이스 스캔 플래그를 지정하지 않으면 프로젝트 전체를 스캔합니다. `--dir` 옵션은 스캔 범위를 디렉터리로, `--file` 옵션은 파일 하나로 좁힙니다. 두 옵션 모두 여러 번 지정해 하나의 보고서로 합칠 수 있으며, 여러 대상에 걸치는 파일도 한 번만 표시됩니다. **프로젝트 전체** ```bash npx lagune read regex ``` **특정 디렉터리** ```bash npx lagune read regex --dir src/services ``` **단일 파일** ```bash npx lagune read regex --file bin/import.pl ``` **여러 대상** ```bash npx lagune read regex --dir core --dir workers --file Sources/App/Router.swift ``` **한도 지정** `--limit` 옵션은 스캔의 ReDoS 임곗값(기본값 25)을 정하며, check 모드에서 쓰는 한도와 같습니다. 한도가 낮을수록 더 엄격합니다. ```bash npx lagune read regex --dir src/services --limit 15 ``` 출력은 가공하지 않은 텍스트이며, 각 섹션의 헤더가 그 섹션을 읽는 법을 알려 줍니다. 섹션은 발견 사항이 있을 때만 표시됩니다. ```text Vulnerable regular expressions found: cmd/server/main.go ([a-z]+)+$ (exponential, search) Dynamically built regular expressions (review manually by simulating a constructed regex): app/payments.php crates/parser/lexer.rs lib/validate.py Static regex wrapped in a constructor (use a literal instead): config/token.rb ``` 아무것도 발견되지 않으면 한 줄만 출력합니다. ```bash npx lagune read regex --dir src/clean # => no unsafe patterns found ``` ### 섹션 해석하기 | 섹션 | 의미 | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Vulnerable regular expressions found` | ReDoS에 취약한 패턴. 파일별로 묶어 각 패턴을 그 아래에 들여 쓰고, 괄호 안에 안전하지 않은 이유와 (해당하는 경우) 범위 및 플래그를 표시. 모든 줄이 안전하지 않은 패턴이므로 판정은 따로 표시하지 않음 | | `Regular expressions the analysis could not settle (review manually)` | 분석이 작업 한도 안에서 결론을 내지 못한 패턴. 같은 방식으로 나열 | | `Dynamically built regular expressions (review manually by simulating a constructed regex)` | 변수, 문자열 연결, 보간으로 정규식을 만드는 파일 | | `Static regex wrapped in a constructor (use a literal instead)` | 정규식 리터럴이 더 간단하고 런타임 컴파일도 생략할 수 있는데, 일반 문자열 리터럴을 정규식 생성자에 넘기는 파일 | 첫 번째 섹션은 보안 발견 사항입니다. 두 번째와 세 번째 섹션은 그 자체로는 발견 사항이 아니며, 정적 검사로 결론을 낼 수 없는 코드를 가리키므로 사람이 직접 읽어 봐야 합니다. 네 번째 섹션은 보안 발견 사항이 아니라 코드를 더 명확하게 만들기 위한 힌트입니다. ### CLI 옵션 | 옵션 | 값 | 설명 | | ----------- | ------------- | ------------------------------------------------------------------------------------------ | | `--pattern` | 정규식 소스 | 패턴 하나 검사. 반복해 지정하면 여러 패턴을 검사해 입력 순서대로 패턴마다 판정 하나씩 출력 | | `--flags` | 정규식 플래그 | 모든 `--pattern` 패턴을 `im` 같은 플래그로 검사. check 모드에만 적용 | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | | `--limit` | 0 이상의 정수 | ReDoS 반복 한도 설정(기본값 25). 두 모드 모두에 적용. 한도가 낮을수록 더 엄격 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션은 check 모드이며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다. ### 지원 언어 스캔은 파일 확장자로 다음 언어를 구분하고 언어마다 고유한 규칙으로 읽으므로, 한 언어의 패턴을 다른 언어의 규칙으로 검사하는 일은 없습니다. 그 밖의 파일은 잘못된 규칙으로 스캔하지 않고 건너뜁니다. | # | 언어 | 확장자 | | --- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | 1 | **JavaScript / TypeScript** | `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.astro`, `.vue`, `.svelte`, `.marko`, `.riot` | | 2 | **Python** | `.py`, `.pyi` | | 3 | **Ruby** | `.rb` | | 4 | **Go** | `.go` | | 5 | **PHP** | `.php` | | 6 | **Rust** | `.rs` | | 7 | **Java** | `.java` | | 8 | **C#** | `.cs` | | 9 | **C** | `.c`, `.h` | | 10 | **C++** | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx` | | 11 | **Kotlin** | `.kt`, `.kts` | | 12 | **Swift** | `.swift` | | 13 | **Scala** | `.scala`, `.sc` | | 14 | **Dart** | `.dart` | | 15 | **PowerShell** | `.ps1`, `.psm1`, `.psd1` | | 16 | **Elixir** | `.ex`, `.exs` | | 17 | **Objective-C** | `.m`, `.mm` | | 18 | **R** | `.r` | | 19 | **Julia** | `.jl` | | 20 | **Clojure** | `.clj`, `.cljs`, `.cljc`, `.edn` | | 21 | **Crystal** | `.cr` | | 22 | **Nim** | `.nim`, `.nims` | | 23 | **V** | `.v` | | 24 | **D** | `.d` | | 25 | **Perl** | `.pl`, `.pm` | **전수 검사가 아닌 최선의 탐지** 소스 코드를 텍스트로 읽으므로 런타임에 조합되는 패턴은 판단할 수 없고, 여러 줄에 걸쳐 있거나 별칭 뒤에 숨겨졌거나 인식하지 못하는 형태로 작성된 패턴은 놓칠 수 있습니다. 출력된 섹션을 완전한 목록이 아니라 든든한 출발점으로 활용하고, 섹션이 닿지 못하는 부분은 계속 코드를 읽어 확인하세요. ## 단일 패턴 검사 `--pattern` 옵션에 패턴 소스를 넘기면 점수를 매깁니다. 훅은 `safe`, `unsafe`, `undetermined`(분석이 결론을 내기 전에 작업 한도에 도달한 경우), `invalid regex` 중 한 단어를 출력합니다. `--pattern` 옵션을 반복해 지정하면 여러 패턴에 한 번에 점수를 매길 수 있으며, 판정은 입력 순서대로 패턴마다 하나씩 출력됩니다. **패턴 하나** ```bash npx lagune read regex --pattern '(a+)+$' # => unsafe npx lagune read regex --pattern '^[a-z0-9_]{3,20}$' # => safe ``` **여러 패턴** ```bash npx lagune read regex --pattern '(a+)+$' --pattern '^[a-z]+$' # => unsafe # => safe ``` **플래그 지정** `--flags` 옵션을 쓰면 호출에 포함된 모든 `--pattern` 패턴을 실제로 실행될 때의 플래그로 검사합니다. 플래그에 따라 패턴이 일치하는 문자가 달라지기 때문입니다. ```bash npx lagune read regex --pattern '^(?:a|A)+$' # => safe npx lagune read regex --pattern '^(?:a|A)+$' --flags 'i' # => unsafe ``` **한도 지정** `--limit` 옵션은 반복 한도(기본값 25)를 정하며, 호출에 포함된 모든 `--pattern` 패턴에 적용됩니다. 한도가 낮을수록 더 엄격합니다. ```bash npx lagune read regex --pattern 'a?a?a?' --limit 2 # => unsafe ``` **인수를 따옴표로 감싸는 이유** 각 패턴은 명령어에 끼워 넣지 않고 항상 플래그 값으로 전달합니다. 따옴표나 백틱이 든 값도 아무 효과 없이 그대로 남아 셸에 인젝션될 수 없습니다. 셸이 먼저 패턴을 확장하지 않도록 항상 작은따옴표로 감싸세요. **팁** [`regex` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 실행하는 것과 같은 엔진입니다. scan 모드로 ReDoS 점검을 시작하고, check 모드로 스캔에서 드러난 패턴을 확인합니다. ## 자주 묻는 질문 ### CLI에서 정규식의 ReDoS 취약점을 어떻게 검사하나요? npx lagune read regex --pattern '' 명령어를 실행하세요. safe, unsafe, undetermined, invalid regex 중 하나를 반환합니다. ### 프로젝트 전체에서 안전하지 않은 정규식을 어떻게 스캔하나요? regex 훅을 scan 모드로 코드베이스 전체에 실행하세요. 지원하는 25개 언어에서 ReDoS에 취약한 패턴을 보고합니다. --- # secrets 훅: 하드코딩된 시크릿 탐지하기 > 명령줄에서 코드베이스를 스캔해 하드코딩된 자격 증명을 찾을 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/hooks/secrets 언어: ko-KR 원문: https://lagune.ai/docs/hooks/secrets 마지막 업데이트: 2026-11-03 `secrets` 훅은 환경 변수에서 읽지 않고 **소스 코드에 박혀 있는 자격 증명**을 잡아냅니다. 값의 내용이 아니라 **출처**(리터럴인지, 환경 변수 조회인지)를 기준으로 판단하므로, 서비스 제공자별 접두사를 빠짐없이 모은 목록이 필요 없고 오탐도 거의 없습니다. [`secrets` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진입니다. 제공자 형식 시그니처, 연결 문자열에 든 자격 증명, 시크릿을 뜻하는 이름의 식별자에 할당된 리터럴은 **언어와 무관**합니다. 같은 문자열은 어떤 파일에서든 똑같이 읽히기 때문입니다. 반면 문법에 의존하는 두 휴리스틱, 즉 하드코딩된 기본값이 있는 환경 변수 조회와 로그 싱크로 흘러가는 시크릿은 **언어를 인식**합니다. 그래서 JavaScript의 `console.log` 호출을 Rust 파일에서 찾는 일이 없고, Python의 `os.getenv("X", "default")` 호출은 Python 고유의 형태로 따로 인식합니다. ## 실행하기 ```bash npx lagune read secrets # scans the whole project npx lagune read secrets --dir src # scans a directory npx lagune read secrets --file config.ts # scans a single file ``` 스캔 결과는 최대 두 개의 섹션으로 출력됩니다. **Hardcoded secrets found** 섹션은 발견 사항 목록(시크릿을 뜻하는 이름의 환경 변수에 하드코딩된 기본값, 연결 문자열에 포함된 자격 증명, 엄선한 제공자 형식과 일치하는 값)이므로 훅은 0이 아닌 종료 코드를 반환합니다. **Secret handling to review manually** 섹션은 단서 목록입니다. 시크릿을 뜻하는 이름의 식별자에 할당된 일반 리터럴(출처는 판단할 수 있어도 값이 실제 시크릿인지는 판단할 수 없는 경우)과, 로그나 응답 싱크로 흘러가는 시크릿 이름의 값이 여기에 해당합니다. 아무것도 발견되지 않으면 `no hardcoded secrets found` 메시지를 출력합니다. ### CLI 옵션 | 옵션 | 값 | 설명 | | -------- | -------- | --------------------------------------------------------------------------- | | `--dir` | 디렉터리 | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 | | `--file` | 파일 | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 | 옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. ### 언어별 지원 범위 환경 변수 기본값 발견 사항과 로그 싱크 단서는 언어별로 정해진 형태를 읽으므로, 아래 언어에만 적용되고 그 밖의 언어에서는 아무것도 보고하지 않습니다. 나머지 세 신호는 **모든** 파일에서 동작합니다. | 신호 | 언어 | | ---------------- | ------------------------------------------------------------------------------- | | 환경 변수 기본값 | JavaScript/TypeScript, Python, Ruby, PHP, Kotlin, Java, Go (`cmp.Or`), Rust, C# | | 로그 / 응답 싱크 | JavaScript/TypeScript, Python, Ruby, PHP, Java, Kotlin, Go, Rust, C, C++, C# | **정책상 문제가 되나요?** 아니요. 시크릿이 커밋되었다고 경고하려고 그 형식을 탐지하는 것은 표준적인 방어 도구가 하는 일로, gitleaks, trufflehog, GitHub push-protection이 수행하는 것과 같은 작업입니다. 이 훅에는 실제로 쓰이는 시크릿이 아니라 탐지 시그니처(공개된 토큰 **형식**)만 들어 있으며, 시크릿을 외부로 유출하지 않고 점검하고 설명할 뿐입니다. ## 자주 묻는 질문 ### secrets 훅은 오탐을 어떻게 피하나요? 값의 내용이 아니라 출처를 기준으로 판단합니다. 신뢰도가 높은 형식(제공자 토큰, 환경 변수 기본값, 연결 문자열)은 발견 사항으로 분류되어 0이 아닌 종료 코드를 반환합니다. 시크릿을 뜻하는 이름의 식별자에 할당된 일반 리터럴은 검토할 단서로 분류해 직접 확인하도록 하며, 같은 식별자를 process.env에서 읽으면 아예 잡아내지 않습니다. --- # Lagune 프롬프트 예시: Blue Team 흐름 자동화 > 바로 복사해 쓸 수 있는 Lagune 프롬프트 모음입니다. 읽기 전용 스캔, 전체 Blue Team 흐름, 제로 트러스트 감사는 물론, 커밋, 브랜치나 PR의 diff, 실제 보안 사고로 범위를 좁힌 탐지까지 담았습니다. 표준 URL: https://lagune.ai/ko-KR/docs/examples/prompts 언어: ko-KR 원문: https://lagune.ai/docs/examples/prompts 마지막 업데이트: 2026-11-03 AI 에이전트에 그대로 붙여 넣어 바로 쓸 수 있는 Lagune 프롬프트입니다. ## 💧 간단 스캔 Blue Team 흐름을 실행하거나 Lagune의 추적에 기록하지 않고, 에이전트가 스스로 코드를 읽어 모든 결함을 수정 방법과 함께 보고하는 읽기 전용 스캔입니다. **팁** 계획 모드에서, 보안 원칙(`/lagune-charter`)을 정해 둔 상태로 사용하면 더 잘 작동합니다. **🪼 기본** | 항목 | 장단점 | 수준 | | --------------- | ----------------------------------------------------------------- | ------------------- | | **작업량** | 에이전트 하나가 스캔과 보고를 맡음. 서브에이전트 없음. | 1/5 | | **소요 시간** | 짧음. 읽기 전용으로 한 번 훑을 뿐, 아무것도 적용하지 않음. | 2/5 | | **토큰 사용량** | 보통 수준, 컨텍스트 공유. 스캔 전체가 하나의 컨텍스트에서 실행됨. | 2/5 | ```md /lagune 너는 방어 보안에 깊은 전문성을 갖춘 사이버 보안 연구자이고, Lagune을 활용해 지식과 정확도를 높이고 있어. 워크스페이스를 스스로 스캔하고, 찾은 결함마다 구체적인 수정 방법을 함께 제시해 줘. 이건 Blue Team 흐름이 아니라 독립적인 스캔이니까, detect, plan, harden, verify는 실행하지 말고 Lagune의 추적에도 아무것도 기록하지 마. 마지막으로, 찾은 결함을 빠짐없이 나열하고 각각 심각도와 구체적인 수정 방법을 붙여 줘. ``` **🐬 멀티 에이전트** | 항목 | 장단점 | 수준 | | --------------- | --------------------------------------------------------------- | ------------------- | | **작업량** | 파일마다 서브에이전트 하나. 코드베이스 크기에 맞춰 규모를 조정. | 2/5 | | **소요 시간** | 파일별로 병렬 처리한 뒤 보고서 하나로 병합. 여전히 읽기 전용. | 3/5 | | **토큰 사용량** | 더 많지만 격리됨. 서브에이전트마다 각자의 컨텍스트에서 스캔. | 3/5 | ````md /lagune 너는 Lagune을 활용해 경로를 나열하고, 경로마다 서브에이전트를 하나씩 실행하고, 그 보고서를 병합하는 사이버 보안 오케스트레이터야(모든 내용은 서브에이전트가 읽어). 현재 프로젝트 크기에 맞춰 작업을 서브에이전트에게 나눠 맡겨야 해. 코드베이스가 클수록 더 많은 서브에이전트를 모두 병렬로 실행하고, 각각에게 아래 프롬프트를 전달해 줘: ```prompt /lagune 너는 방어 보안에 깊은 전문성을 갖춘 사이버 보안 연구자이고, Lagune을 활용해 지식과 정확도를 높이고 있어. 경로를 스스로 스캔하고, 찾은 결함마다 구체적인 수정 방법을 함께 제시해 줘. 이건 Blue Team 흐름이 아니라 독립적인 스캔이니까, detect, plan, harden, verify는 실행하지 말고 Lagune의 추적에도 아무것도 기록하지 마. 마지막으로, 경로에서 찾은 결함을 빠짐없이 나열하고 각각 심각도와 구체적인 수정 방법을 붙여 줘. ``` 마지막으로, 모든 서브에이전트의 보고서를 결함과 수정 방법을 우선순위대로 정리한 목록 하나로 병합해 줘. ```` **경고** 간단 스캔은 범위를 좁히지 않은 광범위한 프롬프트 하나로 이루어지므로, 에이전트에 따라 거부하거나 중간에 멈출 가능성이 더 높습니다. 사용하는 에이전트가 응하지 않으면 대신 아래의 전체 **Blue Team 흐름**을 실행하세요. 범위를 좁혀 한 단계씩 진행하므로 차단될 가능성이 훨씬 낮습니다. --- ## 🌊 자동 Blue Team 감사 흐름 입력을 기다리며 멈추는 일 없이 [전체 명령어 흐름](https://lagune.ai/ko-KR/docs/get-started/commands)을 처음부터 끝까지 실행합니다. **🪼 기본** | 항목 | 장단점 | 수준 | | --------------- | -------------------------------------------------------------------------- | ------------------- | | **작업량** | 코드베이스 크기와 관계없이 에이전트 하나. 서브에이전트 없음. | 3/5 | | **소요 시간** | 보통이지만 큰 코드베이스에서는 덜 꼼꼼함. 각 명령어를 차례로 한 번씩 실행. | 4/5 | | **토큰 사용량** | 더 적지만 격리 수준은 낮음. 모든 명령어가 같은 컨텍스트를 공유. | 4/5 | ```md 다음 명령어를 하나씩 차례로 실행해 줘: `/lagune-charter`, `/lagune-detect`, `/lagune-plan`, `/lagune-harden`, `/lagune-verify`. ## 반복 `/lagune-verify` 명령어가 수정을 하나라도 거부하면, 모든 발견 사항이 제대로 해결될 때까지 `/lagune-harden` 명령어와 `/lagune-verify` 명령어를 차례로 반복해 줘. ## 중요 - 중간에 멈추거나 묻지 마. 애매할 때는 전부 "full" 모드로 진행해 줘. ``` **🐋 멀티 에이전트(심층 스캔)** | 항목 | 장단점 | 수준 | | --------------- | ------------------------------------------------------------------------------------------------ | ------------------- | | **작업량** | 서브에이전트 수를 코드베이스 크기에 맞춰 조정. | 5/5 | | **소요 시간** | 더 길지만 더 꼼꼼함. 여러 서브에이전트를 실행해 발견 사항의 탐지, 계획, 보안 강화를 병렬로 진행. | 5/5 | | **토큰 사용량** | 더 많지만 더 안전함. 서브에이전트마다 편향 없는 독립된 컨텍스트를 가짐. | 5/5 | ````md 다음 명령어를 각각 서브에이전트 하나에 맡겨, 한 번에 하나씩 실행해 줘(백틱 없이 명령어만 전달해): 서브에이전트 1 프롬프트: `/lagune-charter` 서브에이전트 2 프롬프트: `/lagune-detect` 서브에이전트 3 프롬프트: `/lagune-plan` 서브에이전트 4 프롬프트: `/lagune-harden` 서브에이전트 5 프롬프트: `/lagune-verify` `/lagune-detect`, `/lagune-plan`, `/lagune-harden`, `/lagune-verify` 명령어에서는 현재 프로젝트 크기에 맞춰 작업을 서브에이전트에게 나눠 맡겨야 해. 코드베이스가 클수록 더 많은 서브에이전트를 실행해야 해. 예를 들면: ```prompt /lagune-detect ``` ```prompt /lagune-plan ``` ```prompt /lagune-harden ``` ```prompt /lagune-verify ``` - 같은 명령어를 맡은 여러 에이전트는 병렬로 실행해 줘. - 모든 `/lagune-detect` 서브에이전트가 끝나면 다음을 실행해 줘: ```prompt /lagune-detect 서로 같은 발견 사항을 하나로 합쳐 줘. 새 발견 사항을 찾거나 코드베이스를 다시 스캔하지는 마. ``` ## 반복 `/lagune-verify` 명령어가 수정을 하나라도 거부하면, 모든 발견 사항이 제대로 해결될 때까지 `/lagune-harden` 명령어와 `/lagune-verify` 명령어를 차례로 반복해 줘. ## 중요 - 중간에 멈추거나 묻지 마. 애매할 때는 전부 "full" 모드로 진행해 줘. ```` --- ## 🪄 범위를 지정한 탐지 프로젝트 전체 대신 일부에만 [`/lagune-detect`](https://lagune.ai/ko-KR/docs/commands/detect) 명령어를 실행하세요. 커밋이든 풀 리퀘스트든 실제 상황이든, 범위를 평소 말하듯 설명하면 그 안에서 보안과 관련된 발견 사항만 파악합니다. **팁** 여기서 탐지한 결과는 모두 일반 발견 사항이므로, 해당 항목으로만 범위를 한정해 `/lagune-plan`, `/lagune-harden`, `/lagune-verify` 명령어로 바로 이어 갈 수 있습니다. **📌 특정 커밋 이후** 새로 쌓인 커밋만 따로 보안 점검을 하되, 범위는 그 커밋들이 변경한 부분으로 한정하세요. 예를 들면 다음과 같습니다: ```prompt /lagune-detect 커밋 `a1b2c3d` 이후로 바뀐 모든 부분으로 탐지 범위를 한정해 줘. ``` **🔀 브랜치 또는 PR diff** 풀 리퀘스트를 병합하기 전에, 그 diff로만 범위를 좁혀 보안 관점에서 검토하세요. 예를 들면 다음과 같습니다: ```prompt /lagune-detect 이 브랜치가 `main` 브랜치와 비교해 새로 들여온 변경 사항으로 탐지 범위를 한정해 줘. ``` **⛑️ 보안 사고 이후** 무슨 일이 있었는지 직접 설명하세요. Lagune은 플래그가 아니라 상황 자체를 읽고, 이를 목표가 분명한 탐색으로 바꿉니다. 예를 들면 다음과 같습니다: ```prompt /lagune-detect 몇 주 전에 우리 사이트에서 데이터 유출이 있었어. 정확히 어떻게 일어났는지는 모르겠고, 데이터가 다시 샐 수 있는 구멍이 아직 남아 있을까 봐 걱정돼. 코드를 꼼꼼히 살펴보고, 민감한 데이터를 읽거나 저장하거나 노출하는 곳이라면 어디든 집중해서, 아직 데이터가 빠져나갈 통로가 될 만한 건 전부 파악해 줘. 훈련이 아니라 실제 사고로 다뤄 줘. ``` --- ## 🚨 제로 트러스트 감사 워크스페이스 전체와 모든 의존성을 적대적인 것으로 간주합니다. 인터프리터, 네트워크 호출, 인코딩된 페이로드, 그리고 스캐너를 피하려고 예상치 못한 곳에 숨겨 둔 코드를 찾아낸 뒤, 프로젝트를 안전하게 사용할 수 있는지 go/no-go 판정을 내립니다. 프롬프트는 프로젝트의 카테고리와 관계없이 이 감사에 필요한 전문 지식을 직접 불러옵니다. 그 밖에 `/lagune` 명령어가 카탈로그에서 찾아 쓰는 전문 지식까지 활용하려면, 프로젝트가 **OWASP**, **AI/LLM**, 그리고 스택에 해당하는 카테고리(예: **JavaScript**, **Python** 등)를 사용하도록 하세요: ```bash npx lagune write add --categories owasp ai javascript ``` **위험** 신뢰할 수 없는 출처의 프로젝트를 로컬 환경에서 실행할 때는 주의하세요. 악성 코드가 시스템에 영향을 주지 않도록 **샌드박스**(권장)나 **VM** 같은 격리된 환경을 사용하세요. **🪼 기본** | 항목 | 장단점 | 수준 | | --------------- | ---------------------------------------------------------------------------------- | ------------------- | | **작업량** | 에이전트 하나가 워크스페이스 전체를 스캔. 서브에이전트 없음. | 2/5 | | **소요 시간** | 보통. 에이전트 하나가 코드와 의존성을 차례로 살펴봄. | 3/5 | | **토큰 사용량** | 보통이지만 컨텍스트 공유. 전문 지식, 코드, 의존성이 모두 하나의 컨텍스트에 로드됨. | 3/5 | ```md /lagune 너는 제로 트러스트 방어 보안에 깊은 전문성을 갖춘 사이버 보안 연구자이고, Lagune을 활용해 지식과 정확도를 높이고 있어. 워크스페이스 전체를 신뢰할 수 없는 출처이자 악의적일 수 있는 범위로 보고 파악해 줘. 인터프리터, fetch, base64 같은 것은 하나도 빠짐없이 잠재적 위협으로 다뤄야 해. 분석 범위를 의존성과 하위 의존성까지 넓혀 줘. 프로젝트가 스캐너를 피하려고 예상치 못한 곳에 악성 코드를 숨기려 할 수도 있어. 필수 전문 지식(`npx lagune read catalog ` 명령어로 하나씩 불러와 줘): - interpreter - secrets - llm - path 분명히 말해 둘게: 파악한 취약점은 예외 없이 모두 잠재적 위협으로 다뤄야 해. 마지막으로, 이 프로젝트를 내가 써도 안전하고 믿을 만한지 판정해 줘. ``` **🐋 멀티 에이전트(심층 스캔)** | 항목 | 장단점 | 수준 | | --------------- | -------------------------------------------------------------------------------------- | ------------------- | | **작업량** | 파일마다 서브에이전트 하나. 코드베이스 크기에 맞춰 규모를 조정. | 5/5 | | **소요 시간** | 더 길지만 더 꼼꼼함. 파일을 병렬로 스캔한 뒤 하나의 판정으로 병합. | 4/5 | | **토큰 사용량** | 가장 많지만 가장 안전함. 서브에이전트마다 각자의 격리된 컨텍스트에서 전문 지식을 읽음. | 5/5 | ````md /lagune 너는 Lagune을 활용해 파일을 나열하고, 파일마다 서브에이전트를 하나씩 실행하고, 보고서를 만드는 사이버 보안 오케스트레이터야(모든 내용은 서브에이전트가 읽어). 파일마다 서브에이전트를 하나씩, 모두 병렬로 실행하고, 각 서브에이전트에게 담당 파일로 범위를 한정한 아래 프롬프트를 전달해 줘: ```prompt /lagune 너는 제로 트러스트 방어 보안에 깊은 전문성을 갖춘 사이버 보안 연구자이고, Lagune을 활용해 지식과 정확도를 높이고 있어. 파일을 신뢰할 수 없는 출처이자 악의적일 수 있는 범위로 다뤄 줘. 인터프리터, fetch, base64 같은 것은 하나도 빠짐없이 잠재적 위협으로 다뤄야 해. 분석 범위를 파일이 임포트하는 모든 것, 즉 의존성과 하위 의존성까지 넓혀 줘. 악성 코드는 스캐너를 피하려고 그런 곳에 숨어 있을 수 있어. 모든 서브에이전트의 필수 전문 지식(`npx lagune read catalog ` 명령어로 하나씩 불러와 줘): - interpreter - secrets - llm - path 분명히 말해 둘게: 파악한 취약점은 예외 없이 모두 잠재적 위협으로 다뤄야 해. 마지막으로, 이 프로젝트를 내가 써도 안전하고 믿을 만한지 판정해 줘. ``` 마지막으로, 모든 서브에이전트의 보고서를 하나의 최종 판정으로 종합해 줘. ```` --- # Security-Driven Hardening: AI 지원 개발 시대를 위한 컨벤션 > Security-Driven Hardening(SDH) 방법론: AI 지원 개발과 바이브 코딩으로 만든 소프트웨어를 점검하고 보안을 강화하는, 컨텍스트를 인식하는 Blue Team 컨벤션입니다. 표준 URL: https://lagune.ai/ko-KR/docs/references/paper 언어: ko-KR 원문: https://lagune.ai/docs/references/paper 마지막 업데이트: 2026-11-03 - **Weslley Araújo** - **방법론 논문, 2026년** --- ## 초록 Security-Driven Hardening(SDH)은 AI 에이전트와 보안 전문가가 아닌 사람들이 소프트웨어를 작성하는 일이 점점 늘어나는 시대를 위한, AI가 주도하는 구조화된 방어 전용 보안 방법론입니다. SDH는 일반적인 체크리스트를 실행하는 대신, 먼저 시스템이 실제로 무엇을 하는지(로그인, 파일 업로드, 결제, 데이터 노출 등) 탐지한 다음 그 컨텍스트에 특화된 보안 작업을 이끌어 갑니다. 기본적으로 안전한 원칙을 따르고, 전적으로 방어를 중심으로 짜여 있으며, 어떤 사용자든 바로 행동에 옮길 수 있도록 쉬운 말로 표현됩니다. 이 문서는 SDH가 하나의 도구가 아니라 그동안 빠져 있던 컨벤션이라고 주장합니다. 보안 지식은 방법론과 필요할 때만 불러오는 전문 지식에 담겨 있으며, 모든 사용자가 그 위에 쌓아 갈 수 있는 기준선이 됩니다. 덕분에 초보자와 전문가를 같은 흐름으로 지원할 수 있습니다. 기존의 명세 우선 접근 방식 `[1]` 대비 SDH를 구별하는 속성은 두 가지입니다. SDH는 **상태 독립적**이어서 빈 디렉터리, 진행 중인 프로젝트, 단일 풀 리퀘스트, 대규모 레거시 코드베이스 어디에든, 어떤 스택에서든 적응합니다. 또한 SDH는 **종결 가능**합니다. 해소가 검증된 위험은 흐름 전체에서 종결되므로, 그 발견 사항은 안정 상태에 이르고 코드가 바뀔 때만 다시 열립니다. SDH는 보안 전문가나 전문적인 Blue Team 도구를 대체하지 않습니다. 개발자 자신의 지식을 확장하며, 개발자가 보안을 깊이 이해할수록 SDH를 더 많이 주도할 수 있습니다. **Lagune**은 참조 구현이며, 이 방법론이 실제로 구축할 수 있고 이식할 수 있다는 것을 증명합니다. 다른 이들도 채택할 수 있는 컨벤션으로 SDH를 제안합니다. > **색인어** > > AI 지원 개발, 소프트웨어 보안, 방어 보안, 명세 주도 개발, 보안 강화, 에이전트 주도 워크플로, 종결 가능성, 컨텍스트를 인식하는 보안, 필요할 때만 불러오는 지식, 에이전트 독립적 도구. --- ## I. 서론: AI 지원 개발이 연 보안 공백 유출된 시크릿, 빠진 인가 검사, 인젝션이 가능한 쿼리처럼 안전하지 않은 패턴을 제대로 알아보지 못하는 사람과 AI 에이전트가 소프트웨어를 배포하는 일이 점점 늘고 있습니다. 이는 특이한 위험이 아닙니다. 실제 사고의 대부분을 차지하는 위험 유형에 속하며, 수년 동안 공개 레퍼런스에 문서화되어 왔습니다 `[6]`, `[7]`. 최근 연구도 AI가 생성한 코드의 상당 부분이 바로 이런 결함을 안은 채 배포된다고 보고합니다 `[8]`. AI 코딩 어시스턴트 덕분에 개발자가 아닌 사람도 실제 소프트웨어를 배포할 수 있게 되면서 이 문제는 더 심각해졌지만, 이 공백은 특정 사용자층에 국한되지 않습니다. 대부분의 프로젝트는 자신이 실제로 하는 일에 맞춘 보안 점검을 한 번도 받지 못합니다. "작동하니까 배포하자"라는 섣부른 결정이 내려질 때마다 생태계는 더 취약해집니다. 일반적인 보안 조언으로는 이 공백을 메울 수 없습니다. 고정된 체크리스트는 시스템이 하는 일에 맞춰져 있지 않으므로, 작은 프로젝트에 관련 없는 항목을 쏟아 내면서도 정작 그 프로젝트에 중요한 위험은 놓칩니다. 문제는 세상에 보안 지식이 부족하다는 것이 아닙니다. 사용자 앞에 실제로 놓인 시스템에 맞는 지식을 연결하는 것, 그것도 무엇을 물어야 할지 모를 수도 있는 사람을 위해 그렇게 하는 것이 문제입니다. SDH는 단 하나의 역전으로 이 문제에 답합니다. 바로 **보안 지식은 명세와 필요할 때만 불러오는 전문 지식에 담겨 있으며, 모든 사용자가 그 위에 쌓아 갈 수 있는 기준선이 된다**는 것입니다. 방법론이 컨텍스트를 탐지하고, 그 컨텍스트가 지닌 위험의 우선순위를 정하고, 수정을 안내하므로, 개발자와 비개발자 모두 같은 흐름으로 지원받습니다. 발견 사항과 권장 사항은 쉬운 말로 남아 있으므로, 읽는 사람의 기술적 깊이와 관계없이 바로 실행에 옮길 수 있습니다. 전문가는 이 방식에 제약받지 않고 오히려 역량이 증폭되며, 이 이중성은 뒤에서 자세히 다룹니다(`§VI`). > **핵심 통찰** > > **핵심 역전**: 보안 지식은 명세와 필요할 때만 불러오는 전문 지식에 담겨 있으며, 모든 사용자가 그 위에 쌓아 갈 수 있는 기준선이 됩니다. 방법론은 시스템이 무엇을 하는지 파악해 그에 맞는 보안 작업을 연결하고, 사용자가 이미 아는 것이 무엇이든 그것을 확장합니다. 어떤 개발자가 AI 어시스턴트에게 "내 앱에서 사용자가 프로필 사진을 올릴 수 있어"라고 말한다고 해 보겠습니다. 보안 점검이 없으면 어시스턴트는 작동은 하지만 클라이언트가 보내는 것, 즉 선언된 파일 형식, 파일 이름, 크기를 아무 의심 없이 믿는 코드를 만들어 냅니다. 업로드 기능은 그대로 배포되고, 이미지로 위장한 파일에 코드가 숨어 들어올 수 있으며, 조작된 이름이 저장 경로를 벗어날 수 있고, 지나치게 큰 파일이 서버 자원을 고갈시킬 수 있습니다. 데모에서는 이 중 어느 것도 보이지 않으므로, 결국 배포됩니다. 같은 코드라도 SDH를 거치면 다르게 다뤄집니다. 시스템이 외부에서 파일을 받는다는 것을 탐지하고(탐지), 업로드가 지닌 위험의 우선순위를 정하고(우선순위 분류), 실제 파일 형식과 크기를 확인하고, 저장할 때 이름을 바꾸고, 코드가 실행될 수 없는 곳에 저장하자고 제안한 뒤(조치), 결과를 읽어 각 통제가 실제로 효과가 있는지 확인합니다(검증). 개발자는 "제한 없는 파일 업로드(unrestricted file upload)"라는 용어를 알 필요가 없었습니다. 방법론이 대신 그것을 챙겼습니다. 이 문서의 기여는 다음과 같습니다. - 특정 구현과 무관한 방법론으로서 SDH의 정확한 정의와 그 설계 원칙(`§III`). - 책임 분리 자체가 기여인 다섯 단계의 방어 수명 주기: 탐지는 지어내지 않고, 계획은 코드를 읽지 않으며, 코드를 바꾸는 단계는 하나뿐이고, 검증은 판단을 완화하지 않습니다(`§IV`). - 방법론적 입장으로서의 **종결 가능성**: 개별 발견 사항에는 끝없는 루프가 아니라 최종 상태가 있습니다(`§V`). - **개발자 지식 확장**의 이중성: 하나의 흐름이 초보자를 보호하고 전문가의 역량을 증폭합니다(`§VI`). - **호출할 수 없는 전문 지식과 프롬프트 온디맨드**: 에이전트가 기본으로 불러오지 않고, 프로젝트의 컨텍스트가 요구할 때만 불러오는 집중된 보안 지식(`§VII`). - **상태 독립성**과 **비강제적 적응성**: SDH는 어떤 개발 상태에도 맞고, 고정된 범위를 강요하지 않고 상황에 적응합니다(`§VIII`). - **예방 모드**: 일상적인 작업을 만드는 동안 같은 방어를 실행해, 코드가 처음부터 기본적으로 안전하게 들어오고 단계가 바로잡을 것이 줄어듭니다(`§IX`). - SDH가 출발했다가 갈라져 나온 계보인 Spec-Driven Development와의 비교(`§X`). - 방법론이 리팩터링을 견디고 어떤 에이전트에도 종속되지 않게 하는 엔지니어링 규율: 이름 기반 식별 추적(`§XI`), 그리고 에이전트 독립적 매개체(`§XII`). --- ## II. 배경과 관련 연구 SDH는 선행 연구를 토대로 합니다. 명세 우선, 에이전트 주도 개발이 검증해 온 구조, 즉 템플릿, 에이전트가 사용하는 슬래시 명령어, 모든 단계를 규율하는 문서, 단계를 실행하는 에이전트를 물려받습니다 `[1]`, `[2]`, `[3]`. 그리고 이 구조를 방어 목적으로 다시 구현합니다. 이 계보는 의도된 것이며, SDH의 작업 원칙 중 하나가 이를 직접 밝힙니다. 검증된 구조로 워크플로를 만든 다음, 그 틀을 보안에 맞추라는 원칙입니다. SDH는 일반적인 권장 사항을 모아 둔 고정된 체크리스트가 아닙니다. 체크리스트는 보안 전반에 대해서는 많이 알지만, 눈앞의 프로젝트에 대해서는 아무것도 모릅니다. SDH는 그 무게중심을 뒤집습니다. 먼저 탐지, 즉 시스템이 무엇을 하는지 파악하는 데 힘을 쏟고, 그다음에야 탐지를 통해 관련성이 드러난 지식을 찾아 씁니다. SDH는 보안 인력이나 전문적인 Blue Team 도구를 대체하지도 않습니다. 개발자의 지식을 확장하는 역할을 합니다(`§VI`). 전담 보안 조직이 있는 팀이라면 그 조직을 유지해야 합니다. SDH는 그런 팀에게는 구조화된 매개체를, 그런 조직이 없는 팀에게는 근거 있는 기준선을 제공합니다. SDH는 결정론적 보안 스캐너(정적 분석, 린터)와도 나란히 자리합니다 `[4]`, `[5]`. 이런 도구는 결정론적이고 반복 가능하다는 바로 그 점 때문에 가치가 있습니다. SDH는 대부분 에이전트의 추론에 의존하며, 엄격한 결정론을 내주는 대신 컨텍스트 인식을 얻습니다. 방법론은 이를 숨기지 않습니다. 결정론이 중요한 곳에서는 추론 안에 결정론적 엔진을 넣습니다(`§VII`). 즉, 입력을 검사할 가치가 있는지는 에이전트가 판단하고, 그 입력이 위험한지는 결정론적 프로그램이 판단합니다. 가장 직접적인 선행 사례는 Spec-Driven Development(SDD)로, 실행 가능한 명세에서 출발해 빌드를 앞으로 밀고 나가는 명세 우선 방법론 계열입니다. 이 문서는 SDD를 하나의 부류로 다룹니다. 실무 방법론으로서 가장 명확하게 정리한 Piskala의 보고서 `[1]`, 가장 눈에 띄는 에이전트 주도 도구 모음인 GitHub의 Spec Kit `[2]`, 같은 계열의 두 번째 도구인 OpenSpec `[3]`, 이 세 가지가 비교의 대표 기준입니다(`§X`). --- ## III. SDH: 정의와 설계 원칙 **Security-Driven Hardening**은 임시방편식 수정이 아니라 에이전트가 실행하는 명세에서 작업을 이끌어 내어, 코드베이스를 더 안전하게 바꾸는 구조화된 AI 주도 보안 방법론입니다. 이름은 보안의 방어자인 **Blue Team**에서 영감을 받았습니다. SDH가 다루는 것은 방어, 보안 강화, 검증이며, 공격은 결코 다루지 않습니다. > **정의** > > **Security-Driven Hardening(SDH)**: 먼저 시스템이 실제로 무엇을 하는지 탐지한 다음 그 컨텍스트에 특화된 보안 작업을 이끌어 가는, AI가 주도하는 구조화된 방어 전용 보안 방법론입니다. 기본적으로 안전한 원칙을 따르고 쉬운 말로 표현됩니다. SDH는 반드시 지켜야 하는 원칙들로 정의됩니다. 각 원칙은 하나의 규칙이며, 각각 사용자에게 구체적인 보장을 제공합니다. | 원칙 | 규칙 | 사용자에게 보장하는 것 | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 기본적으로 안전하게, 쉬운 말로, 모두에게 동등하게 | 모든 기본값, 메시지, 수정은 처음부터 안전하며, 개발자든 아니든 누구나 이해할 수 있습니다. 어떤 사용자층도 특별 대우를 받지 않습니다. | 초보자도 따로 요청하지 않아도 안전한 기준선을 받고, 결과를 자신이 이해하는 말로 읽습니다. | | 일반론보다 컨텍스트 인식 | 모든 단계는 detect 단계에서 탐지한 컨텍스트에서 출발하며, 시스템이 실제로 하는 일에 따라 행동합니다. | 권장 사항이 체크리스트가 아니라 프로젝트에 맞춰집니다. 보안 지식은 명세와 필요할 때만 불러오는 전문 지식에 담겨 있어, 사용자가 가진 지식이 무엇이든 그것을 확장합니다. | | 경직성보다 유연성 | 원칙, 요구 사항, 권장 사항은 출발점입니다. 사용자는 무엇이든 고쳐 쓰고, 빼고, 더하고, 범위를 좁힐 수 있습니다. | 방법론은 프로젝트와 사용자에 맞춰 유연하게 바뀌며, 사용자가 원하는 것보다 더 엄격해지지 않습니다. 유연성이 기본적으로 안전한 기준선을 약화하는 일은 없습니다. | | 덧붙이기만 하지 않고, 현재 상태와 대조해 갱신하기 | 산출물은 로그가 아니라 살아 있는 문서입니다. 실행할 때마다 모든 항목을 다시 확인해, 여전히 유효한 것은 유지하고, 바뀐 것은 다시 쓰고, 더 이상 해당하지 않는 것은 제거합니다. | 기록이 언제나 현재를 반영하므로, 낡은 백로그로 썩어 가지 않습니다. | | 방어 전용 | SDH는 점검하고, 보안을 강화하고, 검증합니다. 공격 도구, 악의적인 용도의 익스플로잇, 피해를 목적으로 한 탐지 회피 기법은 절대 만들지 않습니다. | 방법론을 무기로 바꿀 수 없습니다. 이중 용도의 내용은 명확히 방어적인 맥락에서만 등장합니다. | | 명세 우선, 에이전트 주도, 보안 중심 | 워크플로는 템플릿, 명령어, 모든 단계를 규율하는 보안 원칙, 단계를 실행하는 에이전트로 구성됩니다. | 검증된 개발 구조를, 에이전트가 실질적인 보안 작업을 하도록 용도에 맞게 바꾼 것입니다. | **표 1.** SDH의 설계 원칙과 각 원칙이 사용자에게 제공하는 보장. 이 원칙은 장식이 아닙니다. 아래의 모든 단계가 지켜야 하는 제약이며, 방법론의 한계를 짚을 때 다시 이 원칙으로 돌아옵니다(`§XV`). 이 문서의 나머지 부분에서는 이름을 붙인 아홉 개의 기둥을 전개합니다. 독자가 기억해 두어야 할 부분이자, 다른 팀이 SDH를 한다고 말하려면 다시 구현해야 할 부분입니다. | 기둥 | 제공하는 것 | 절 | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------- | | 컨텍스트를 인식하는 역전 | 보안 지식이 명세와 필요할 때만 불러오는 전문 지식에 담겨 있어, 초보자와 전문가가 하나의 흐름을 공유합니다. | `§I`, `§VI` | | 다섯 단계의 방어 수명 주기 | 책임 분리: 정책, 탐지, 우선순위 분류, 조치, 검증이 각각 한 가지 일만 맡습니다. | `§IV` | | 종결 가능성 | 발견 사항에는 끝없는 루프가 아니라 최종 상태가 있습니다. 해소된 작업은 종결됩니다. | `§V` | | 개발자 지식 확장의 이중성 | 하나의 흐름이 초보자를 보호하고 전문가의 역량을 증폭하며, 어느 쪽도 대체하지 않습니다. | `§VI` | | 프롬프트 온디맨드, 호출할 수 없는 지식 | 관련 보안 지식은 기본으로 불러오지 않고, 프로젝트의 실체에 맞춰 불러옵니다. | `§VII` | | 상태 독립성과 비강제적 적응성 | 어떤 스택의 어떤 개발 상태에도 맞고, 범위를 강요하지 않고 상황에 적응합니다. | `§VIII` | | 예방 모드 | 새 작업을 만드는 동안 같은 방어가 작동하므로, 코드가 처음부터 기본적으로 안전하게 들어옵니다. | `§IX` | | 이름 기반 식별 추적 | 발견 사항은 여러 단계를 거치는 동안 하나의 항목으로 유지되며, 이름 변경으로 연결이 끊기는 곳은 한 곳뿐입니다. | `§XI` | | 에이전트 독립적 매개체 | 보안 가치는 한 번만 작성되며, 어떤 에이전트나 스택에도 의존하지 않습니다. | `§XII` | **표 2.** SDH의 아홉 기둥과 각 기둥을 다루는 절. --- ## IV. 5단계 Blue Team 흐름 SDH는 작업을 다섯 단계의 방어 수명 주기로 구성합니다(그림 1). 각 단계는 방어를 중심으로 짜여 있고 앞 단계 위에 쌓이며, 정책 수립, 탐지, 우선순위 분류, 조치, 검증이라는 실제 Blue Team 활동을 따릅니다. ```mermaid flowchart TB charter["1 · charter (정책)
읽는 것: 프로젝트와, 주어졌다면 사용자의 설명
쓰는 것: 보안 원칙
원칙마다 막는 위험을 쉬운 말로 담음"] detect["2 · detect (탐지)
읽는 것: 사용자의 코드
쓰는 것: 탐지 맵
창작이 아닌 탐지: 코드가 뒷받침하는 것만 기록"] plan["3 · plan (우선순위 분류)
읽는 것: 탐지 맵(코드는 읽지 않음)
쓰는 것: 방어 계획
모든 수정은 detect 단계가 실제로 파악한 대상을 가리킴"] harden["4 · harden (조치)
읽는 것: 방어 계획과, 계획이 손대는 코드
쓰는 것: 코드와 강화 기록
코드를 바꾸는 유일한 단계, 한 번에 수정 하나씩, 효과가 있는 가장 작은 변경"] verify["5 · verify (검증)
읽는 것: 코드와 강화 기록
쓰는 것: 아직 열린 판정 각각을 강화 기록에
코드와 기록의 정적 대조, 판정은 절대 완화하지 않음"] charter --> detect --> plan --> harden --> verify verify -.->|"반려: harden 단계가 다시 맡을 작업,
기록된 이유에 맞춰 다시 적용"| harden verify -.->|"종결: 해소를 증명한 것을
체인 전체에서 종결하고,
이력에 한 줄을 남김"| detect ``` **그림 1.** 다섯 단계의 흐름: 각 단계가 읽는 것, 쓰는 것, 그리고 흐름을 떠받치는 불변 조건. 두 갈래의 되돌림은 모두 verify 단계가 이끕니다. 반려된 통제는 harden 단계를 다시 열고, 해소가 증명된 발견 사항은 체인 전체에서 종결되어 이력에 한 줄로 남습니다. 책임 분리가 곧 이 방법론의 기여입니다. 각 단계가 한 가지 일만 맡으므로 실패 양상은 한 곳에 갇히고, 독자는 각 산출물이 주장하는 내용을 신뢰할 수 있습니다. > **핵심 통찰** > > **Applied는 검증된 것이 아닙니다**: harden 단계는 수정이 적용되었다고 기록합니다. verify 단계는 코드를 그 기록과 대조해 이를 검증하며, 기록에 맞추려고 판정을 완화하는 일은 결코 없습니다. 통제가 코드에 있는데도 여전히 위험에 도달할 수 있는 경우가 있으며, 그때 정직한 판정은 "Risk not closed"입니다. ### charter (정책) charter 단계는 프로젝트의 보안 원칙, 즉 이후의 모든 단계가 지켜야 하는 규칙을 세웁니다. charter는 모든 단계를 규율하는 계층이며, 프로젝트 보안 태세에 대한 일종의 컴파일 타임 검사 역할을 합니다. 각 원칙에는 분명한 이름, 코드와 대조해 확인할 수 있는 타협 불가능한 규칙, 그리고 수정 방법만이 아니라 그 원칙이 막는 위험을 밝히는 `Why:` 줄이 있습니다. charter 단계는 언제나 프로젝트 자체(매니페스트, 구조, 의존성)를 읽습니다. 사용자가 설명을 주면 그 설명은 방향이 되고, 프로젝트를 읽는 범위는 거기서 사용자가 언급한 것 너머로 넓어집니다. 설명이 없으면 프로젝트가 유일한 출처입니다. 둘은 서로 경쟁하지 않고 더해지며, charter 단계가 기록하는 것은 코드의 현재 상태가 아니라 프로젝트가 지켜야 할 정책입니다. 개발자가 아닌 사람도 이를 읽고 규칙과 위험을 모두 이해할 수 있어야 합니다. ### detect (탐지) detect 단계는 코드를 읽고, 시스템이 실제로 하는 일 가운데 보안상 의미가 있는 것을 파악합니다. 이 단계를 이끄는 지침은 "창작이 아닌 탐지"입니다. 코드가 뒷받침하는 것만, 이후 단계에 필요한 근거와 함께 기록합니다. detect 단계는 중립적입니다. 발견 사항을 보안 원칙에 억지로 맞추지 않습니다. 위험을 보안 원칙의 규칙과 맞춰 보는 것은 plan 단계의 일이기 때문입니다. 각 발견 사항은 세 부분으로 이루어집니다. 무엇인지(쉬운 말로 된 설명), 왜 중요한지(사실만이 아니라 위험), 그리고 근거(그 발견 사항이 있는 함수나 라우트)입니다. 근거에는 파일 경로가 들어가지 않습니다. 경로는 추적 맵에만 있습니다(`§XI`). 그래서 본문에는 낡을 수 있는 경로가 결코 들어가지 않습니다. ### plan (우선순위 분류) plan 단계는 각 발견 사항을 수정으로 바꿉니다. 수정에는 위험 유형에 따른 이름을 붙이고(근거가 되는 경우 CWE와 OWASP 같은 확립된 레퍼런스를 인용합니다), 그 수정이 지키는 보안 원칙과 연결합니다. 우선순위(치명적, 높음, 중간, 낮음)는 임의로 고르는 것이 아닙니다. plan 단계는 CVSS v4.0의 Base 및 Environmental 방식으로 각 발견 사항에 점수를 매기므로, 등급은 그 점수를 쉬운 말로 옮긴 것이고, 노출 정도와 피해 규모를 설명하는 쉬운 말 한 줄로 근거를 밝히며, 두 번 실행해도 같은 순서가 나옵니다. 벡터는 전문가를 위한 정밀한 기준점이고, 등급과 그 근거는 누구나 따라갈 수 있는 같은 평가입니다. plan 단계는 탐지 맵만 보고 작업하며 코드를 절대 읽지 않습니다. 이는 한계가 아니라 의도된 제약입니다. 모든 수정이 detect 단계가 실제로 탐지한 대상을 가리키도록 강제하기 때문입니다. 파악된 적 없는 범위가 있으면 plan 단계는 추측하지 않고 멈춘 뒤 사용자를 detect 단계로 돌려보냅니다. ### harden (조치) harden 단계는 코드를 바꾸는 유일한 단계이므로 신중하게 진행합니다. 편집에 사용자의 승인이 필요한지는 에이전트와 에이전트를 실행하는 권한 모드가 결정할 일이므로, harden 단계는 별도의 확인 절차를 두지 않습니다. 의존하는 대상을 먼저, 그다음 우선순위가 높은 것부터 한 번에 수정 하나씩 적용하므로, 각 변경은 작고 검토하기 쉬우며 되돌리기도 쉽습니다. 새 수정을 맞추려고 기존 통제를 약화하지 않으며, 보안 원칙을 어기지도 않습니다. 수정이 원칙과 충돌한다면 harden 단계는 적용하지 않고 멈춘 뒤 그 충돌을 알립니다. 각 블록은 Applied, Partial, Blocked 중 하나로 기록됩니다. 다만 "Applied가 곧 검증되었다는 뜻은 아닙니다". 이 문제는 다음 단계가 다룹니다. ### verify (검증) verify 단계는 코드를 읽고 harden 단계가 기록한 내용과 대조해, 적용된 각 통제를 검증합니다. 검증이란 바로 이 대조, 즉 코드와 기록을 맞대어 보는 일이며, 정적으로 이루어집니다. 통제가 코드에 존재하고 올바르다는 것을 확인할 뿐, 실행 중인 시스템에서 공격을 받아도 통제가 실제로 효과가 있다는 것까지 확인하지는 않습니다. 실제 공격이나 모의 공격을 운영 중인 시스템에 실행하는 런타임 검사는 설계상 범위 밖입니다. verify 단계는 Risk closed, Risk not closed, Cannot tell from the code 세 가지 판정 중 하나를 내립니다. verify 단계는 자체 산출물을 만들지 않습니다. harden 단계와 verify 단계는 강화 기록을 공유하며, 무엇을 했는지는 harden 단계가, 판정과 그 이유는 verify 단계가 맡고, 어느 쪽도 상대의 필드에 쓰지 않습니다. 반려된 통제는 harden 단계가 다시 맡을 작업이 되며, harden 단계는 다음 실행에서 코드를 직접 읽은 결과보다 그 판정을 우선하고, 이유에 적힌 바로 그 빈틈을 겨냥해 수정을 다시 적용합니다. verify 단계는 기록보다 코드를 신뢰합니다. 기록은 코드가 실제로 해내는 것보다 더 많은 것을 주장할 수 있기 때문입니다. 사용자의 코드에 대해서는 읽기만 하며, 기록에 맞추려고 판정을 완화하는 일은 결코 없습니다. 통제가 있어도 다른 경로로 위험에 도달할 수 있다면, 그때 정직한 판정은 "Risk not closed"입니다. 읽는 도중 탐지 맵이 다룬 적 없는 보안 문제를 발견하더라도, 탐지는 detect 단계의 일이므로 verify 단계는 그 문제에 대한 판정을 지어내지 않습니다. 대신 문제를 알리고 사용자를 detect 단계로 돌려보내, 발견 사항이 흐름을 건너뛰지 않고 같은 흐름을 통해 들어오게 합니다. > **이어지는 예시: 파일 업로드**. 발견 사항 하나로 흐름의 뼈대를 처음부터 끝까지 보여 줍니다. > > - **detect** 단계가 이를 찾아냅니다. 시스템은 사용자에게서 파일을 받으며, 업로드 핸들러는 파일의 실제 형식을 확인하지 않고 클라이언트가 보낸 MIME 타입을 그대로 믿습니다. _중요한 이유_: 이미지로 위장한 파일에 악성 코드를 숨길 수 있습니다. > - **plan** 단계가 "모든 입력은 검증되기 전까지 신뢰할 수 없습니다"라는 원칙을 지키는 수정을 정하며, 우선순위는 **치명적**입니다. 파일의 실제 형식과 크기를 확인하고, 저장할 때 이름을 바꾸고, 업로드한 파일은 코드로 실행될 수 없는 곳에 저장합니다. > - **harden** 단계가 이를 적용하고 상태를 **Applied**로 기록합니다. 이제 핸들러는 내용에서 실제 형식을 판별하고, 크기 제한을 적용하고, 예상하지 못한 것은 거부하고, 저장할 때 이름을 바꾸고, 코드가 실행될 수 없는 곳에 저장합니다. > - **verify** 단계가 핸들러를 읽고 기록과 대조한 뒤 **Risk closed** 판정을 내립니다. 코드가 기록이 주장하는 그대로 동작합니다. > > 같은 발견 사항 이름이 탐지 맵, 방어 계획, 강화 기록을 관통하며, verify 단계도 같은 이름으로 그 기록에 작업합니다. 아직 열린 판정은 해당 발견 사항의 블록에 기록되고, 해소가 증명된 발견 사항은 종결됩니다(`§V`). 이 공유된 이름이 곧 발견 사항의 식별자입니다(`§XI`). --- ## V. 종결 가능성: 최종 상태가 있는 발견 사항 대부분의 보안 도구는 사용자에게 늘어나기만 하는 백로그를 남깁니다. SDH는 다른 입장을 취합니다. **발견 사항은 종결할 수 있으므로, 끝없는 백로그에 머무르지 않고 최종 상태에 이릅니다**(그림 2). 이는 현재 상태와 대조해 갱신하는 원칙에서 곧바로 나옵니다. > **정의** > > **종결 가능성**: 해소가 검증된 위험은 흐름 전체에서 종결되므로, 그 발견 사항은 안정 상태에 이르고 코드가 바뀔 때만 다시 열립니다. 보안 활동 자체는 계속되더라도 발견 사항에는 최종 상태가 있습니다. SDH의 산출물은 로그가 아니라 살아 있는 문서입니다. 단계를 다시 실행할 때마다 기존 항목을 하나하나 현재 사실과 대조하고, 세 가지 중 하나를 합니다. 여전히 유효한 것은 유지하고, 바뀐 것은 다시 쓰고, 더 이상 해당하지 않는 것은 제거합니다. 이제 해결되었다는 것이 코드로 드러난 발견 사항은 그냥 제거됩니다. 작업 기록은 과거가 아니라 현재를 반영합니다. 종결은 바로 그 대조와 갱신이 결론에 이른 것입니다. verify 단계가 위험이 해소되었음을 검증하면, 그 발견 사항을 흐름 전체, 즉 탐지 맵, 방어 계획, 강화 기록, 추적 맵에서 종결합니다. verify 단계가 다른 단계의 산출물에 쓰는 유일한 단계인 이유가 여기에 있습니다. 루프를 닫는 단계이기 때문입니다. 발견 사항이 체인을 떠날 때, 종결 과정은 그 핵심을 짧은 항목으로 정리해 이력 기록에 남깁니다. 이 이력은 작업 체인 밖에 있으며 다시 처리되지 않습니다. 사라지는 것과 종결되는 것의 경계가 바로 여기에 있습니다. 더 이상 사실이 아니어서 대조와 갱신 과정에서 제거된 발견 사항은 아무것도 남기지 않지만, 해소가 증명된 발견 사항은 이력에 한 줄을 남깁니다. 종결된 발견 사항은 이후 어떤 작업 산출물에도 나타나지 않으며, 그 부재는 체인이 깨진 것이 아니라 예상된 결과입니다. ```mermaid stateDiagram-v2 direction TB [*] --> OPEN: detect 단계가 탐지 OPEN --> Plan: plan Plan --> Harden: harden Harden --> Verify: verify Verify --> StoodDown: Risk closed StoodDown --> SETTLED SETTLED --> OPEN: 코드 변경으로 발견 사항이 다시 열림 Plan: plan Harden: harden Verify: verify StoodDown: STOOD DOWN · 이력에 한 줄 ``` **그림 2.** 종결 가능성의 상태 기계. 발견 사항은 OPEN(열림) → STOOD DOWN(종결) → SETTLED(안정 상태) 순으로 이동하며, 코드가 바뀔 때만 다시 열립니다. 범위 안의 모든 것이 종결되면 사이클은 안정 상태가 되며, 이 안정 상태에는 구체적인 형태가 있습니다. 마지막 발견 사항이 종결된 산출물은 통째로 제거되므로, 완전히 종결된 체인에는 보안 원칙과 이력, 즉 정책과 증명만 남습니다. 사이클은 코드가 바뀔 때만 다시 열립니다. 방법론은 각 발견 사항에 분명한 끝을 주며, 이것이야말로 끝없는 백로그가 할 수 없는 일입니다. --- ## VI. 개발자 지식 확장의 이중성 SDH는 사람을 대체하지 않으며, 전문적인 Blue Team 도구도 대체하지 않습니다. SDH는 **개발자 자신의 지식을 확장합니다**. 개발자가 보안을 잘 이해할수록 흐름을 더 정밀하게 이끌 수 있고, 더 많은 자율성을 갖습니다. 보안을 잘 모르는 개발자도 자동 모드가 보호해 주므로 여전히 안전한 결과를 얻습니다. 보안 지식이 명세에 담겨 있다는 역전은 양방향으로 작용합니다(`§I`). 초보자에게 이것은 보호입니다. 명세가 먼저 제안하므로 무엇을 물어야 할지 몰라도 됩니다. 전문가에게 이것은 증폭입니다. 같은 명세 덕분에 고정된 체크리스트와 씨름하는 대신 흐름을 정밀하게 겨냥할 수 있습니다. 모든 단계는 자신의 동작 안에 이 이중성을 지니고 있습니다(그림 3). 입력 없이 실행하면 사용자를 대신해 전체 범위에 작업합니다. 방향을 주면 같은 단계가 사용자가 겨냥한 대상으로 정확히 좁혀집니다. ```mermaid flowchart TB inversion["하나의 역전, 두 방향:
보안 지식은 명세에 담겨 있음"] inversion --> auto["자동 모드(입력 없음)
단계가 제안하고 전체 범위에
작업함"] inversion --> directed["지정 모드(입력 있음)
단계가 사용자가 겨냥한
대상으로 정확히 좁혀짐"] auto --> novice["보호받는 초보자:
무엇을 물어야 할지 몰라도
안전한 결과"] directed --> expert["역량이 증폭된 전문가:
고정된 체크리스트가 아니라,
정밀하게 겨냥한 흐름"] novice -.-> phases["같은 다섯 단계가 양쪽 모두를 지원:
charter · detect · plan · harden · verify"] expert -.-> phases ``` **그림 3.** 개발자 지식 확장의 이중성. 하나의 역전이 두 독자층을 지원합니다. 같은 다섯 단계를 거치며 자동 모드는 초보자를 보호하고, 지정 모드는 전문가의 역량을 증폭합니다. 필요할 때만 불러오는 전문 지식은 그 본문에서 이 이중성을 명시적으로 드러냅니다(`§VII`). 각 전문 지식은 에이전트에게 자신의 지식이 "판단을 넓혀 준다"는 점을 알리고, 전문 지식이 제공하는 것 너머까지 계속 추론하라고 말합니다. 지식은 하한이지 상한이 아닙니다. 이것이 이 문서가 의도한 균형 속에서 두 독자층을 모두 지원하는 방식입니다. 개발자 커뮤니티는 실질적인 도구를 얻고, Blue Team 실무자는 자신의 일을 대신해 주는 척하지 않는 구조화된 매개체를 얻습니다. --- ## VII. 호출할 수 없는 전문 지식과 프롬프트 온디맨드 이것이 이 방법론에서 가장 새로운 패턴입니다. SDH는 특정 분야에 집중한 보안 지식을 **필요할 때만** 불러오는 전문 지식으로 담고 있으며, 어떤 전문 지식을 불러올지는 에이전트가 프로젝트의 컨텍스트와 맞춰 보고 직접 정합니다. 이를 **프롬프트 온디맨드**(prompt-on-demand)라고 부릅니다. 모든 검사를 기본으로 실행하는 대신, 에이전트가 자신이 놓인 프로젝트의 범위에 따라 활성화할 지식을 고르는 방식입니다. 전문 지식은 계속 진화하며, 어느 것이든 언제든지 바뀌거나 대체될 수 있습니다. 기여는 전문 지식 자체가 아니라 이 패턴입니다. > **정의** > > **프롬프트 온디맨드**: 에이전트가 눈앞의 프로젝트 범위와 맞춰 보며 활성화할 보안 지식을 고르는 것으로, 모든 검사를 기본으로 실행하는 대신 프로젝트의 실체에 맞는 지식을 끌어옵니다. > **정의** > > **호출할 수 없는 전문 지식**: 파일 업로드나 브라우저에서 실행되는 코드처럼 하나의 컨텍스트에 집중한, 특정 언어에 종속되지 않는 보안 지식 단위입니다. 점검하고 설명할 뿐, 코드를 다시 쓰지 않으며 공격 입력도 만들지 않습니다. 명령어가 아니며, 다루는 컨텍스트가 범위 안에 있거나 프롬프트가 이름으로 요청할 때 불러옵니다. 각 전문 지식은 다루는 위험에 대해 더 안전한 형태를 제시하고, 그 지식을 사용하는 각 단계에서 발견 사항을 어떻게 다룰지 에이전트에게 알려 줍니다. 탐지에서는 어떻게 판단할지, 조치에서는 수정을 어떻게 안전하게 적용할지, 검증에서는 어떻게 증명할지입니다. 결정적인 특징은 전문 지식을 **그 자체로는 호출할 수 없다**는 점입니다. 전문 지식은 명령어가 아니며, 흐름 안에서는 매칭이 전문 지식을 불러옵니다. 탐지 단계는 카탈로그를 한 번 나열하고, 프로젝트의 컨텍스트를 각 항목이 다루는 내용과 맞춰 본 뒤, 컨텍스트가 범위 안에 있는 전문 지식만 불러옵니다. 이후 단계는 다시 나열하지 않고 그 매칭 목록을 재사용하므로 한 번의 매칭이 체인 전체에 쓰이며, 예방 모드도 같은 매칭을 이제 만들 작업에 적용합니다(`§IX`). 컨텍스트가 없는 전문 지식은 건너뛰며, 건너뛴 것도 불러온 것만큼 책임 있게 다룹니다. 카탈로그의 모든 항목이 명시적인 판정을 받습니다. 적용했는지, 아니면 코드에서 읽어 낸 이유와 함께 건너뛰었는지를 밝히므로, 막연히 관련 없어 보인다는 느낌이 부재를 대신하는 일은 없습니다. 적용할 것이 하나도 없다는 결과도 유효합니다. 카탈로그는 데이터이며, 카탈로그를 늘리는 데 필요한 것은 지식 파일 하나와 카탈로그 행 하나뿐이고, 새 명령어는 필요 없습니다. 내장 전문 지식은 OWASP, 특정 언어, AI 통합 같은 카테고리로 묶여 있으며, 프로젝트가 사용하는 카탈로그에는 프로젝트가 고른 카테고리의 내장 전문 지식과 프로젝트 고유의 전문 지식이 담깁니다. 프로젝트는 이 선택을 나머지 상태와 함께 기록하므로, 팀 전체가 같은 카탈로그로 매칭합니다. 이는 단계에 적용되는 것과 같은 컨텍스트 인식 원칙을 지식에 적용한 것입니다. 모든 검사를 기본으로 실행하는 대신, 프로젝트의 실체에 맞는 지식을 끌어옵니다. 같은 속성 덕분에 메인테이너뿐 아니라 사용자도 카탈로그를 키울 수 있습니다. 사용자가 제공한 보안 자료나 주제는 핵심이 정리되어 프로젝트에 속하는 새 전문 지식이 되고, 카테고리와 관계없이 그 카탈로그에 합류하며, 내장 전문 지식과 똑같이 불러와지고, 같은 이름의 내장 전문 지식을 대체합니다. 전문 지식을 작성하는 일 자체도 방어 전용이며, 전문 지식이 강제하는 것과 같은 경계를 따릅니다. 공격 분석 글이 출처가 될 수는 있지만, 그로부터 만들어진 전문 지식은 점검하고 설명할 뿐, 실제로 작동하는 익스플로잇을 내놓지 않습니다. 그래서 지능이 명세에 담긴다는 역전은 카탈로그 자체로까지 이어집니다(`§I`). 사용자는 코드를 작성하지 않고도 자신의 컨텍스트에 맞게 카탈로그를 더 깊게 만들 수 있습니다. 짧은 예로 프롬프트 온디맨드를 살펴보겠습니다. detect 단계가 브라우저에서 실행되는 코드 폴더를 읽습니다. 카탈로그에서 그 컨텍스트와 매칭되는 전문 지식을 찾아 불러오고, detect 단계의 일반적인 절차를 거쳐 클라이언트 측 발견 사항을 드러냅니다. 이 범위에 컨텍스트가 없는 전문 지식은 매칭되지 않으므로 불러오지 않으며, 각각 건너뛴 것으로 기록됩니다. 어떤 지식이 관련 있는지는 고정된 설정이 아니라 프로젝트가 정했습니다. 결정론은 정확히 필요한 곳에 등장합니다. 전문 지식은 글뿐 아니라 결정론적 검사기도 담을 수 있습니다. 위험 유형에 명확한 판정 절차가 있다면, 작은 프로그램이 주어진 입력에 대해 고정된 판정을 돌려줍니다. 예를 들면 `safe`, `unsafe`, `invalid input` 같은 몇 가지 짧은 단어입니다. 일부 위험 유형은 바로 이런 방식으로 결정론적으로 판정할 수 있으며, 그 판정 절차 뒤에는 선행 연구가 쌓여 있습니다 `[9]`, `[10]`, `[11]`. 검사기는 에이전트가 제공한 후보에 점수를 매기거나 직접 범위를 스캔해 후보를 찾으며, 어느 경우든 판정을 내리는 것은 에이전트가 아니라 검사기입니다. 충분히 범용적인 전문 지식은 카탈로그에서 필수로 표시할 수 있으며, 그러면 항상 적용되고 그 검사기가 전체 범위에 실행됩니다. 이는 컨텍스트 매칭 없이 지식을 불러오는 유일한 경우이며, 에이전트가 그때그때 정하는 것이 아니라 카탈로그 데이터에 선언됩니다. 바로 이 지점에서 SDH는 흐름 전체가 결정론적인 척하지 않으면서도, 에이전트의 추론을 반복 가능한 무언가에 근거하게 합니다. 마지막으로 전문 지식은 **떼어 내어 쓸 수 있습니다**. 지식이 독립적으로 성립하므로, 사용자는 SDH 전체 흐름과 무관한 프롬프트에서도 전문 지식을 바로 실행해 일상적인 개발과 함께 보안을 챙길 수 있습니다. 예를 들어 결정론적 검사기가 있는 전문 지식은 일반 코딩 중에 만들어진 후보를 하나하나 걸러 안전한 것만 남길 수 있습니다. 이 분리 가능성은 SDH가 그토록 다양한 상황에 적응하는 이유 중 하나로, 다음 절의 주제입니다(`§VIII`). 그리고 이 분리 가능성이 가장 온전하게 드러나는 것은 같은 지식이 일상적인 개발을 처음부터 끝까지 지키는 예방 모드입니다(`§IX`). --- ## VIII. 상태 독립성과 비강제적 적응성 두 가지 속성이 SDH를 경직된 명세 방법론과 구별합니다. ### 상태 독립성 > **정의** > > **상태 독립성**: 방법론이 개발 상태에 의존하지 않습니다. 시작점을 직접 읽어 파악하므로, 빈 디렉터리, 진행 중인 프로젝트, 단일 풀 리퀘스트, 대규모 레거시 코드베이스 어디에든, 어떤 스택에서든 맞습니다. 모든 단계는 프로젝트가 완전히 새것이든 이미 존재하든 같은 방식으로 작동합니다. charter 단계는 있는 코드가 무엇이든 거기서 원칙을 추론합니다. detect 단계는 코드가 아주 적더라도 있는 코드를 그대로 파악합니다. 전제된 시작점은 없습니다. ### 비강제적 적응성 > **정의** > > **비강제적 적응성**: 방법론은 사용자가 따라야 할 고정된 범위를 강요하지 않고 상황에 적응합니다. 사용자가 무엇을 말해야 할지 모를 때는 자신이 호출된 환경을 읽고, 컨텍스트를 만들어 내고, 다음 행동을 결정할 질문을 던집니다. 가장 분명한 예는 charter 단계의 제안 모드입니다. SDH는 프로젝트를 분석해 기본적으로 안전한 보안 원칙을 도출하고, 빈틈이 실제로 결과를 바꿀 때만 사용자에게 묻고, 그다음 보안 원칙을 작성해 각 원칙을 그것이 막는 위험과 함께 쉬운 말로 제시합니다. 보안 원칙은 승인 프롬프트 뒤에 묶인 계약이 아니라 사용자가 다시 실행해 고쳐 나가는 살아 있는 문서이므로, 사용자가 무엇을 요청해야 할지 알 필요가 전혀 없습니다. 이 적응성은 입력의 형태에 민감하게 반응하는 모습으로 나타납니다. 같은 단계가 주어진 것을 읽고 모드를 고릅니다(그림 4). 프롬프트에 담긴 파일, 목록의 발견 사항 하나, 걱정거리, 알려진 약점을 겨냥한 집중 임무, 전체를 무차별로 훑는 스캔 요청까지, 흐름이 설계상 비강제적이므로 어느 것이든 사용자의 필요에 맞춰집니다. 이 중 어떤 것도 기본적으로 안전한 기준선을 약화하지 않습니다. 유연성은 기준선을 적용하는 방식을 바꿀 뿐, 기준선을 낮추지는 않습니다. ```mermaid flowchart TB shape["단계가 주어진 것의
형태를 읽음"] shape --> none["입력 없음"] shape --> paths["하나 이상의 경로"] shape --> concern["설명된 우려 사항"] shape --> finding["이름으로 지정한 발견 사항"] shape --> band["우선순위 등급"] none --> auto["자동 모드:
제안하거나, 전체 범위를
스캔"] paths --> focus["해당 파일이나
디렉터리에만 집중"] concern --> scoped["그 우려 사항 하나로
범위를 좁힘"] finding --> item["그 추적 항목
하나에만 작업"] band --> priority["치명적, 높음,
중간, 낮음 중 하나에만 작업"] ``` **그림 4.** 비강제적 적응성. 같은 단계가 입력의 형태를 읽고 모드를 고르므로, 범위는 강요되지 않고 언제나 사용자가 정합니다. --- ## IX. 범용 예방 모드: 작업을 만드는 동안 작동하는 같은 방어 SDH에는 보완적인 모드가 하나 있습니다. 코드를 작성하는 동안 같은 방어를 켜 둔 채 진행하는 일상적인 개발입니다. 사용자는 로그인 페이지, 업로드, 엔드포인트처럼 작업 자체를 요청하고, 방법론은 빌드가 진행되는 동안 이를 지키므로, 결과물은 나중의 보안 강화 작업을 거친 뒤가 아니라 반영되는 순간부터 기본적으로 안전합니다. > **정의** > > **예방 모드**: SDH의 모든 단계를 규율하는 계층과 지식 아래에서 진행하는 일상적인 개발입니다. 보안 원칙이 빌드를 구속하고, 이제 만들 대상과 관련된 전문 지식을 필요할 때만 불러오며, 작업을 완료라고 하기 전에 결과를 사용한 방어 그대로와 대조합니다. 이 모드는 단계들이 이미 갖춘 요소를 하나하나 재사용하되, 아직 존재하지 않는 코드를 향하게 합니다. 컨텍스트 탐지의 대상은 코드에서 의도로 바뀝니다. 에이전트는 이제 만들 것과 그 작업이 넘나드는 경계를 추론하며(로그인이라면 자격 증명, 세션, 외부에서 들어오는 입력이 따릅니다), 지식 카탈로그는 바로 이 추론과 매칭됩니다. 프롬프트 온디맨드는 여기서 일반화됩니다(`§VII`). 컨텍스트는 이미 있는 코드뿐 아니라 코드를 만들 계획에서도 탐지할 수 있습니다. 보안 원칙은 언제나처럼 규율하며, 원칙을 어기게 될 요청은 충돌로 알려지고 결코 구현되지 않습니다. 방어는 각 부분을 작성하는 바로 그 순간 코드 안에서 적용되어, 경계에서 검증하고 처음부터 안전한 구조를 택하므로, 작동은 하지만 안전하지 않아 나중에 고쳐야 할 버전은 아예 생기지 않습니다. 이 모드는 verify 단계가 시작하는 방식으로 끝납니다. 작업을 완료라고 하기 전에, 만든 쪽은 자신의 결과를 사용한 방어와 대조합니다. 통제는 위험의 경로 옆이 아니라 경로 위에 있어야 하고, 빠짐이 없어야 하며, 전문 지식에 결정론적 검사기가 있다면 검사기의 판정이 에이전트 자신의 해석보다 우선합니다. 여기서 발견된 빈틈은 같은 작업의 일부로 메웁니다. 작업을 끝낸다는 것은 안전하게 끝낸다는 뜻이기 때문입니다. 이 모드가 하지 않는 일도 하는 일만큼 의도된 것입니다. 요청받은 것만 만들고 그 주변은 점검하지 않습니다. 이미 있는 것을 점검하는 일은 단계들의 몫입니다. 산출물을 쓰지 않고 발견 사항도 추적하지 않습니다. 발견 사항은 이미 있는 것에서 탐지된 위험이며, 이 모드의 목적은 안전하지 않은 버전이 애초에 들어오지 않게 하는 것이기 때문입니다. 두 방향은 서로를 완성합니다. 단계들은 이미 있는 것을 종결하고(`§V`), 예방 모드는 새 작업이 그것을 다시 열지 않게 합니다. 안정 상태의 체인이 안정 상태로 남는 것은 개발이 멈춰서가 아니라, 안정 상태인 동안 만든 것이 방어를 갖춘 채 만들어지기 때문입니다. --- ## X. Security-Driven Hardening과 Spec-Driven Development 비교 Security-Driven Hardening(SDH)은 Spec-Driven Development(SDD)를 토대로 자라났다가 이후 크게 갈라졌습니다. 구조적 계승은 실제로 있으며, 이를 분명히 인정합니다. 명세 우선, 에이전트 주도, 모든 단계를 규율하는 문서, 에이전트가 실행하는 단계별 명령어 집합이 그것입니다. SDH는 이 구조를 의도적으로 재사용합니다. 달라지는 것은 목적, 강제력 모델, 전제하는 상태, 종료 조건입니다. 이 문서는 SDD를 하나의 부류로 다루며, 다음 세 가지를 기준으로 삼습니다: 방법론의 대표 기술인 Piskala의 보고서 `[1]`, 대표 에이전트 도구 모음인 GitHub의 Spec Kit `[2]`, 같은 계열의 두 번째 도구인 OpenSpec `[3]`. SDD는 명세를 실행 가능하게 만들어 전통적인 개발을 뒤집습니다. 명세가 구현을 안내하는 데 그치지 않고 작동하는 구현을 직접 만들어 냅니다 `[1]`. SDD의 단계 구성(모든 단계를 규율하는 원칙 수립, 무엇을 만들지 명세, 기술 스택 계획, 계획을 작업으로 분할, 구현)은 빌드를 앞으로 밀고 나갑니다 `[2]`. SDD를 규율하는 문서인 원칙의 헌법(constitution)은 에이전트가 처음부터 끝까지 따라야 하는 토대입니다. 바로 여기에 차이의 핵심이 있습니다. SDD에서 강제력은 명세에서 빌드로 흐르며, 구현은 명세를 따를 것으로 기대됩니다. SDH는 그 계약의 거의 모든 축을 뒤집습니다(표 3). > **핵심 통찰** > > **핵심 차이**: SDD에서 강제력은 명세에서 빌드로 흐르며, 구현은 명세를 따를 것으로 기대됩니다. SDH는 비강제적이며 반대 방향으로, 즉 시스템에서 탐지한 컨텍스트에서 안쪽으로 흘러 이미 있는 것의 보안을 강화합니다. | 축 | SDD | SDH | | ------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 목표 | 기능을 제공합니다. 명세가 작동하는 구현이 됩니다. | 이미 있거나 만들어지고 있는 것의 보안을 강화합니다. 모든 단계가 방어를 위해 짜여 있습니다. | | 강제력 모델 | 강제적입니다. 명세와 헌법이 빌드를 반드시 따라야 할 범위 안에 가둡니다. | 비강제적입니다. SDH가 상황에 적응하며, 사용자는 고쳐 쓰고, 빼고, 범위를 좁힐 수 있습니다. | | 상태 전제 | 명세에서 출발해 앞으로 나아가는 빌드입니다. | 상태 독립적입니다. 빈 디렉터리, 진행 중인 프로젝트, 단일 PR, 레거시 어디서든 작동합니다. | | 종료 조건 | 기능이 완성되면 끝납니다. | 종결 가능합니다. 발견 사항은 안정 상태에 이르며, 코드가 바뀔 때만 다시 열립니다. | | 규율 문서 | 에이전트가 반드시 따라야 하는 원칙의 헌법입니다. | 위험을 중심으로 짠 보안 원칙(각 원칙에 `Why:` 줄이 있음)으로, 명시적으로 고정된 계약이 아닙니다. | | 지식을 늘리는 방법 | 명령어를 추가합니다(또는 단계 구성을 확장합니다). | 에이전트가 필요할 때만 불러오는, 호출할 수 없는 전문 지식을 추가합니다. 파일 하나와 카탈로그 행 하나면 되고, 새 명령어는 필요 없습니다. | | 지원 대상 | 기능을 앞으로 밀고 나가는 개발자입니다. | 개발자든 아니든 모든 사용자를 같은 흐름으로 지원합니다. | | 코드를 바꾸는 주체 | 구현 단계가 빌드를 만들어 냅니다. | harden 단계만 코드를 바꾸며, 한 번에 수정 하나씩 적용합니다. | **표 3.** 여덟 가지 축으로 본 SDD와 SDH. 구조는 빌려 오고, 계약은 뒤집었습니다. 계보를 공정하게 평가하자면, SDD는 검증된 선행 사례이며 SDH가 돌아가는 구조는 SDD에서 빌려 온 것입니다. 이 갈라짐은 SDD에 대한 비판이 아닙니다. SDD는 다른 문제(앞으로 만들어 나가는 일)를 잘 해결합니다. SDH는 같은 검증된 장치를 가져와 방어, 적응성, 종결로 향하게 합니다. 변경 제안, 작업 목록, 변경별 명세를 중심으로 구성된 OpenSpec `[3]` 역시 이 패턴을 확인해 줍니다. 이 계열은 명세에서 출발해 빌드를 앞으로 밀고 나가는 반면, SDH는 탐지한 컨텍스트에서 안쪽으로 시스템의 보안을 강화합니다. 예방 모드는 SDH가 앞으로 나아가는 빌드에 동행하는 유일한 곳이지만(`§IX`), 여기서도 뒤집힌 계약은 유지됩니다. 작업을 어떻게 만들지를 규율할 뿐, 무엇을 만들지는 결코 정하지 않습니다. --- ## XI. 엔지니어링의 엄밀함: 추적 규율 덧붙이지 않고 대조해 갱신하는 규율에는 리팩터링을 견디는 기반이 필요합니다(`§V`). 발견 사항은 자신을 다루는 모든 단계에서 하나의 항목으로 유지되어야 하며, 파일 이름이 바뀌거나 파일이 옮겨져도 체인이 끊겨서는 안 됩니다. SDH는 **이름 기반 식별**과 **추적에만 보관하는 경로**로 이 문제를 해결합니다. > **정의** > > **이름 기반 식별**: 발견 사항의 식별자는 모든 산출물에 똑같이 적히는 그 이름입니다. 본문에는 이름만 담기고 경로는 담기지 않습니다. 파일 경로는 추적 맵에만 있으므로, 파일 이름이 바뀌거나 파일이 옮겨져도 연결이 끊기는 곳은 정확히 한 곳뿐입니다. detect 단계의 각 발견 사항은 하나의 추적 항목입니다. 그 식별자는 **이름**, 즉 절 제목이며, 탐지 맵, 방어 계획, 강화 기록에 똑같이 적힙니다. 이후 단계는 같은 항목에 작업할 때 그 이름을 글자 그대로 재사용하며, verify 단계는 같은 이름 아래 강화 기록에 판정을 씁니다. 추적 맵에는 추적 정보 외에는 아무것도 담기지 않으며, 항목마다 엔트리가 하나씩 있습니다. ```json { "name": "File uploads", "paths": ["src/routes/upload.ts"] } ``` 맵에는 본문도, 주석도, 별도의 식별자도, 단계도 기록되지 않습니다. 문구는 본문 산출물이 담고, 맵은 식별자와 경로만 담습니다. 파일 경로는 유일하게 자주 바뀌는 정보이며, 오직 여기에만 있습니다. 파일 이름이 바뀌거나 파일이 옮겨지면 연결이 끊길 수 있는 곳은 정확히 한 곳뿐이며, 서로 어긋나는 두 사본에서 끊기는 일은 없습니다. ```mermaid flowchart TB detect["탐지 맵"] --> name plan["방어 계획"] --> name harden["강화 기록
verify 단계가 여기에 판정을 씀"] --> name name["name = "File uploads"
본문에는 경로 없이 이름만 담김"] name -.-> tracking tracking["추적 맵
{ name: "File uploads",
paths: ["src/routes/upload.ts"] }
경로는 여기에만 있으므로 이름이 바뀌면 이 엔트리만 고침"] ``` **그림 5.** 식별자 컨베이어. 하나의 발견 사항 이름이 모든 산출물을 거쳐 흐르는 반면 경로는 추적 맵에만 있으므로, 이름 변경은 한 곳에서 바로잡힙니다. 일반적인 흐름에서는 두 가지 동작이 맵을 관리하고, 세 번째 동작은 유지 보수용으로 따로 있습니다. **Track**은 추가 전용 등록입니다. 단계가 자신이 쓴 발견 사항을 보고하면, 엔진은 새 발견 사항을 기록하고 나머지는 바뀐 경로를 따라가며, 각각을 새 항목, 이동, 변경 없음으로 분류합니다. 단계가 보고하지 않은 것은 절대 제거하지 않습니다. **Untrack**은 verify 단계가 해소를 확인한 발견 사항을 종결합니다. 한 번의 결정론적 처리로 각 발견 사항의 핵심을 이력 항목으로 정리하고, 산출물에서 해당 절 전체를 제거하고, 마지막 발견 사항이 사라진 산출물을 삭제하고, 추적 엔트리를 지우므로, 에이전트는 이 중 어느 것도 직접 하지 않습니다. 종결된 이름이 다른 발견 사항의 본문에 아직 인용되어 있는 경우처럼 결정론적 처리가 안전하게 진행할 수 없는 곳에서는, 편집을 추측하지 않고 그 지점을 잡아내 에이전트에게 알립니다. 이 두 가지가 단계들이 실행 중에 호출하는 동작입니다. **Repair**는 유지 보수 동작입니다. 단계는 자체 대조 과정에서 추적 정보가 일관되지 않음(기록된 경로가 더 이상 존재하지 않음)을 발견하면 자동으로 Repair에 작업을 넘기며, 그 밖의 경우에는 필요할 때 실행합니다. Repair는 모든 산출물과 현재 코드를 읽고 각 항목의 경로를 바로잡아 맵 전체를 한 번에 다시 맞추며, 혼자 결정할 수 없는 것, 즉 고아 항목(더 이상 어떤 산출물도 이름을 언급하지 않는 추적 항목)이나 이름 변경 후보(경로가 보고된 다른 이름과 일치하는 항목)를 드러냅니다. Repair는 여섯 번째 단계가 아니라 유지 보수입니다. 사용자의 코드도, 본문 산출물도 건드리지 않고 추적 정보만 다룹니다. 사용자의 소스를 읽는 이유는 이름이 바뀐 파일의 새 경로를 알아내는 것 하나뿐이며, 보안 내용을 직접 작성하지 않습니다. 엔진이 추측하기를 거부하는 단 하나의 판단, 즉 사라진 항목이 해결된 것인지 이름만 바뀐 것인지에 대해서는 사람이 최종 결정권자입니다. 잘못 지운 항목은 체인을 끊으므로, 추측하기보다는 물어보는 편이 낫습니다. 방법론은 자신의 방어 규율을 스스로에게도 적용합니다. 결정론적 엔진은 명령줄 프로그램으로 호출되며, 각 입력을 독립된 프로세스 인수로 전달해 단순한 데이터로만 취급되게 하므로, 따옴표나 백틱이 들어간 값이 명령에 주입될 수 없습니다. 알 수 없는 검사는 답을 내놓는 대신 실패하므로, 철자가 틀린 검사가 문제없는 결과로 읽히는 일은 없습니다. SDH는 자신의 내부 구조도 기본적으로 안전한 원칙에서 예외로 두지 않습니다. --- ## XII. 매개체: 이식성을 증명하는 에이전트 독립적 아키텍처 SDH가 다른 이들이 채택하는 컨벤션이 되려면 특정 에이전트나 스택에 묶여서는 안 되므로, SDH의 매개체는 세 가지 관심사를 분리합니다(그림 6). Lagune은 이것이 가능하다는 것을 증명합니다. **보안 가치**는 한 번만 작성되며 어떤 에이전트가 자신을 실행하는지 전혀 알지 못합니다. 단계 지침과 그 지침이 채우는 템플릿, 지식 카탈로그, 결정론적 엔진이 여기에 속합니다. **배포**는 얇습니다. 유일한 역할은 그 가치를 각 에이전트에게 그 에이전트가 기대하는 형태와 위치로 전달하는 것이며, 자체적인 보안 로직은 전혀 없습니다. **프로젝트의 상태**는 프로젝트의 것입니다. 보안 원칙, 단계 산출물, 추적 맵, 프로젝트가 고른 카테고리, 프로젝트 고유의 전문 지식이 여기에 속하며, 다른 코드와 마찬가지로 커밋되고 검토할 수 있습니다. ```mermaid flowchart TB value["한 번만 작성되는 보안 가치
단계 지침 · 템플릿 · 지식 카탈로그 · 결정론적 엔진
어떤 에이전트가 실행하는지 모름"] delivery["배포
그 가치를 각 에이전트가 기대하는 형태로 전달
보안 로직 없음"] agent["에이전트
단계를 실행"] project["프로젝트의 상태
코드와 함께 커밋됨
보안 원칙 · 단계 산출물 · 추적 · 카테고리 · 고유 전문 지식"] value --> delivery --> agent agent -->|"읽고 씀"| project ``` **그림 6.** 에이전트 독립적 매개체. 보안 가치는 한 번만 작성되고, 얇은 배포 계층이 이를 각 에이전트에 전달하며, 상태는 프로젝트의 것으로 남습니다. 배포에는 보안 로직이 없으므로, 배포를 어떻게 구축하든 SDH는 달라지지 않습니다. 매개체는 배포를 직접 구축할 수도 있고, 참조 구현처럼 이미 에이전트 스킬을 배포하는 생태계에 맡길 수도 있으며, 어느 쪽이든 단계와 그 산출물, 그 보장은 그대로입니다. 또한 이 중 어느 것도 특정 언어나 런타임에 국한되지 않습니다. 참조 구현은 우연히 하나의 스택으로 작성되었을 뿐, 방법론은 이 관심사들 사이의 경계이지 그것을 만드는 툴체인이 아닙니다. 같은 설계를 완전히 다른 언어로 다시 구현해도 SDH의 본질은 바뀌지 않습니다. --- ## XIII. 적용 사례: SDH 전 과정 > **적용 사례** > > **업로드 및 관리자 공격 표면의 방어적 보안 강화**. > **컨텍스트**: 사용자가 올린 파일을 받아 관리자 페이지에 목록으로 보여 주는 작은 앱. > **패턴**: charter → detect(컨텍스트에 따라 필요할 때만 불러오는 지식 활성화) → plan → harden → verify, 그리고 종결 한 건과 실제 실패 한 건. > **결과(역량)**: 해소가 검증되어 체인 전체에서 종결된 위험 하나, 그리고 *해소되지 않았다*고 검증되어 harden 단계로 돌려보낸 통제 하나. 판정은 기록이 아니라 코드를 반영합니다. _이 예시는 방법론의 작동 방식을 보여 주기 위한 설명용 사례로, 현장에서 측정한 연구가 아니며 효과 지표도 보고하지 않습니다._ 하나로 이어지는 시연은 방법론의 부분만이 아니라 방법론이 실제로 작동하는 모습을 보여 줍니다. 여기서는 파일 업로드 예시(`§IV`)를 확장해 필요할 때만 불러오는 지식의 활성화와 종결을 더하고, 실제 실패도 하나 포함합니다. 1. **charter** 단계가 "모든 입력은 검증되기 전까지 신뢰할 수 없습니다"라는 원칙을 제안하고, 그 위험을 쉬운 말로 덧붙입니다. 확인하지 않은 입력은 시스템이 뚫리는 가장 흔한 경로입니다. 2. **detect** 단계가 업로드 라우트와, 업로드된 파일 목록을 보여 주는 작은 관리자 페이지를 스캔합니다. 업로드 발견 사항(핸들러가 클라이언트의 MIME 타입을 그대로 믿음)을 탐지합니다. 관리자 페이지는 브라우저에서 실행되며, 프롬프트 온디맨드는 이 컨텍스트를 인식합니다(`§VII`). 그래서 detect 단계는 그 컨텍스트에 맞는 전문 지식을 불러와 두 번째 발견 사항을 드러냅니다. 파일 이름이 텍스트가 아니라 마크업으로 페이지에 쓰여, 조작된 이름이 방문자의 브라우저에서 스크립트로 실행될 수 있는 지점입니다. 이 범위에 컨텍스트가 없는 전문 지식은 불러오지 않으며, 건너뛸 때마다 코드에서 확인한 부재와 함께 기록됩니다. 3. **plan** 단계는 업로드 수정에 치명적 등급의 우선순위를 매기고 원칙과 연결합니다. 파일의 실제 형식과 크기를 확인하고, 저장할 때 이름을 바꾸고, 코드가 실행될 수 없는 곳에 저장하는 수정입니다. 두 번째 수정에는 높음 등급의 우선순위를 매깁니다. 파일 이름을 마크업이 아니라 텍스트로 렌더링하는 수정입니다. 4. **harden** 단계는 업로드 수정을 먼저(우선순위가 가장 높으므로) 적용해 Applied로 기록하고, 이어서 두 번째 수정도 적용해 Applied로 기록합니다. 5. **verify** 단계는 각 지점을 읽고 코드와 기록을 대조합니다. 업로드 통제는 실제로 효과가 있습니다. 핸들러가 내용에서 실제 형식을 판별하고, 크기 제한을 적용하고, 나머지는 거부합니다. 판정: Risk closed. verify 단계는 업로드 발견 사항을 체인 전체에서 종결하며, 핵심을 정리한 요약이 이력에 남습니다. 이제 실제 실패입니다. harden 단계의 두 번째 수정이 텍스트를 안전하게 렌더링하는 헬퍼를 추가했지만, 마크업을 쓰는 예전 호출이 다른 코드 경로에서 여전히 도달 가능한 상태로 남았다고 가정해 보겠습니다. verify 단계는 페이지를 읽고 안전한 헬퍼를 확인하지만, 안전하지 않은 경로가 아직 살아 있다는 것도 확인합니다. 통제는 있지만 위험은 해소되지 않았습니다. verify 단계는 기록에 맞추려고 판정을 완화하기를 거부합니다. "Risk not closed" 판정을 내리고, 빈틈을 기록하고, harden 단계로 돌려보냅니다. 위험을 완전히 해결하지 못한 통제는 통과가 아닙니다. 이 예시 하나에 방법론의 성격이 담겨 있습니다. 컨텍스트를 인식하는 탐지, 원칙과 연결되고 우선순위가 정해진 수정, 신중한 적용, 그리고 기록과 관계없이 코드의 실제 상태를 보고하는 검증입니다. --- ## XIV. SDH를 써야 할 때와 그 한계 SDH는 상태 독립적이고 종결 가능하므로, 무거운 프로세스처럼 과해지는 일이 드뭅니다. 파일 하나, 우려 사항 하나로까지 규모를 줄일 수 있고, 계속 남는 부담을 남기지 않고 안정 상태에 이릅니다. SDH의 경계는 프로젝트 규모가 아니라 **보증의 깊이**입니다. ```mermaid flowchart TB q1{"코드가 보안과 관련된 일을 하나요?
(입력, 인증, 데이터, 시크릿, 외부 호출)"} q1 -->|아니요| little["여기서는 SDH의 효과가 적습니다."] q1 -->|예| q2{"SDH를 실행하세요. 컴플라이언스 기준이나
전담 보안 조직이 있나요?"} q2 -->|아니요| baseline["SDH가 근거 있는 기준선이 됩니다."] q2 -->|예| carrier["SDH는 구조화된 매개체입니다.
전문가 검토와 감사를 뒷받침하며,
그것을 대체하지 않습니다."] ``` **그림 7.** SDH를 써야 할 때. 분기 기준은 먼저 보안 관련성, 그다음 보증의 깊이이며, 프로젝트 규모는 기준이 아닙니다. SDH가 경계에 닿는 곳은 다음과 같습니다. 시스템이 실행될 때만 드러나는 동작(verify 단계는 코드를 읽을 뿐 시스템을 실행하지 않습니다), 에이전트가 읽을 수 없는 설정이나 환경에 좌우되는 위험, 그리고 어떤 경우든 전문가 검토가 필요한 위험도가 높은 상황입니다. 이 모든 경우에도 SDH는 구조화된 1차 점검으로서 여전히 가치를 더하지만, 그것은 하한이지 상한이 아닙니다. > **핵심 통찰** > > **경계**: SDH의 한계는 프로젝트 규모가 아니라 보증의 깊이입니다. 거의 어디서든 근거 있는 기준선 역할을 할 수 있고, 위험이 큰 곳에서는 전문가 검토를 뒷받침하지만, 실행 중인 시스템에 대한 테스트나 보안 전문가의 판단을 대체하지는 않습니다. --- ## XV. 논의: 위치 설정, 한계, SDH가 주장하지 않는 것 SDH는 자신의 경계를 정확히 밝힙니다. ### 대체가 아닌 확장 SDH는 보안 전문가나 전문적인 Blue Team 도구를 대체하지 않습니다. 개발자의 지식을 확장합니다(`§VI`). 신중한 주장이 옳은 주장입니다. 잘 적용하면 SDH는 실제 위험을 효과적으로 해소**할 수 있습니다**. 그렇지 않으면 보안 점검을 전혀 받지 못했을 프로젝트라면 더욱 그렇습니다. 그렇다고 보장은 아니며, 위험이 커서 전문가 검토가 필요한 곳에서 그것을 대신하지도 않습니다. ### 설계상 방어 전용 SDH는 점검하고, 보안을 강화하고, 검증합니다. 공격 도구, 익스플로잇, 피해를 목적으로 한 탐지 회피 기법은 결코 만들지 않습니다. 이중 용도의 보안 내용은 명확히 방어적이고 승인된 맥락에서만 허용됩니다. 이것은 선호가 아니라 절대적인 경계입니다. ### 보여 주기식이 아닌 실질적인 검증 verify 단계는 시스템을 실행하는 것이 아니라 코드를 읽고 기록과 대조해 검증합니다. 이것은 정적 검증입니다. 통제가 코드에 존재하고 올바르다는 것을 확인할 뿐, 런타임에 공격을 받아도 통제가 실제로 효과가 있다는 것을 증명하지는 않습니다. 따라서 "Cannot tell from the code"는 통과 결과 뒤에 숨긴 실패가 아니라 정당한 판정입니다. 근거가 코드에 없을 때(설정이나 에이전트가 읽을 수 없는 경로에 좌우될 때) SDH는 추측하지 않고 그렇다고 말합니다. ### 범위가 정해지고 명시된 결정론 SDH의 대부분은 에이전트의 추론에 의존하며, 바로 이것이 컨텍스트 인식을 가능하게 합니다. 결정론은 결정론적 엔진에만 쓰입니다. 전문 지식에 담길 수 있는 검사기(`§VII`), 그리고 추적 엔진(`§XI`)입니다. 이 문서는 이 경계를 흐리지 않습니다. 결정론적인 결과는 프로그램이 낸 결과입니다. 추론한 결과는 에이전트가 코드를 읽은 해석이며, 최종 결정권자는 사용자입니다. ### 비용과 규모 전체 스캔은 토큰을 많이 사용합니다. 수동 모드가 있는 이유 중 하나는 비용을 우려 사항의 크기에 비례하게 유지하기 위해서입니다(`§VI`, `§VIII`). ### 최종 결정권자는 사용자 SDH는 이름이 바뀐 것인지 해결된 것인지를 사람이 결정하도록 요청하며, 코드 편집의 승인은 사용자가 이미 에이전트를 관리하는 곳, 즉 에이전트를 실행하는 권한 모드에 그대로 남습니다. 방법론은 제안하고 검증할 뿐, 사람의 결정을 뒤집지 않습니다. ### 반론과 답변 공정한 회의론자라면 몇 가지 반론을 제기할 것입니다. 그중 실질적인 반론은 그들의 말 그대로 제기해 볼 만합니다. **"정적 분석기에 LLM을 덧붙인 것에 불과하지 않나요?"** 아닙니다. 정적 분석기는 가진 규칙을 기본적으로 전부 실행합니다. SDH는 먼저 시스템이 무엇인지 탐지한 다음 관련 지식을 찾아 씁니다(`§II`, `§VII`). 그리고 위험 유형에 명확한 판정 절차가 있는 곳에서만 결정론적 검사기를 *내장*합니다. 추론은 컨텍스트가 먼저이고, 결정론은 필요한 곳을 겨냥해 쓰입니다. **"그냥 보안 체크리스트 아닌가요?"** 아닙니다. SDH는 체크리스트를 뒤집습니다. 탐지가 먼저 오고, 지식은 프로젝트가 실제로 하는 일에 맞춰 끌어옵니다(`§II`, `§VII`). **"보안용으로 이름만 바꾼 SDD 아닌가요?"** 아닙니다. SDH는 SDD의 구조를 빌려 오되 그 계약을 뒤집습니다. 강제력, 상태 전제, 종료 조건, 지원 대상이 모두 다릅니다(`§X`). 같은 장치, 반대 방향입니다. **"AI가 추론하는 방법은 결국 발견 사항을 환각으로 지어내지 않나요?"** 이 설계는 모델이 올바르게 행동하리라 믿는 대신 지어내기 자체를 제약합니다. detect 단계는 코드가 뒷받침하는 것만 기록합니다("창작이 아닌 탐지", `§IV`). verify 단계는 코드와 기록을 대조하며 "Cannot tell from the code"라고 답할 수 있습니다(`§XV`). 결정론적 검사기는 판정할 수 있는 경우에 근거를 제공합니다(`§VII`). 그리고 최종 결정권자는 사용자입니다. 이것이 에이전트를 오류 없는 존재로 만들지는 않지만, 에이전트의 주장을 확인할 수 있게 만듭니다. 위치 설정에 대해 덧붙입니다. 이 문서는 SDH를 참조 구현과 독립적으로 정의합니다. 다섯 단계, 위험을 중심으로 짠 보안 원칙, 덧붙이지 않고 대조해 갱신하는 원칙과 그에 따른 종결 가능성, 프롬프트 온디맨드 지식, 예방 모드, 이름 기반 식별 추적, 방어 전용이라는 경계, 이것이 방법론입니다. 다른 팀이 다른 스택과 다른 에이전트 생태계에서 이를 구현하더라도 결과는 여전히 SDH입니다. Lagune은 SDH의 정의가 아니라 증명입니다. --- ## XVI. 함정, 그리고 SDH가 구조적으로 이를 피하는 방법 이 계열의 방법론은 잘 알려진 실패 양상을 공유합니다. SDH는 그 대부분에 구조로 답합니다. 규율에 맡기지 않고 흐름 자체에 녹여 넣었습니다. | 함정 | 실패 | SDH의 구조적 답 | | ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | 명세 부패, 낡은 백로그 | 아무도 믿지 않는 죽은 항목이 산출물에 쌓임 | 덧붙이지 않고 대조해 갱신하기(`§V`): 실행할 때마다 모든 항목을 다시 확인하고 해결된 것은 제거 | | 잘못된 확신, 통과 결과 | 통제가 있으면 위험이 해소되었다고 가정함 | verify 단계가 코드와 기록을 대조하므로 "Risk not closed"와 "Cannot tell"도 정식 판정이 됨(`§IV`, `§XV`) | | 체크리스트 범람 | 일반적인 항목이 정작 중요한 위험을 가림 | 일반론보다 컨텍스트 인식, 그리고 범위에 필요한 것만 불러오는 프롬프트 온디맨드(`§VII`) | | 도구 종속 | 방법이 하나의 벤더나 에이전트에 단단히 묶임 | 에이전트 독립적 매개체: 보안 가치는 한 번만 작성되고, 각 에이전트로의 배포에는 보안 로직이 없음(`§XII`) | | 끝없는 루프 | 백로그가 결코 닫히지 않고, 작업이 끝나지 않음 | 종결 가능성과 안정 상태(`§V`) | **표 4.** 이 방법론 계열의 알려진 함정과 각각에 대한 SDH의 구조적 답. 핵심은 함정의 이름을 붙이고 그것을 막는 장치를 가리키는 데 있습니다. 이것은 조심하라는 경고가 아니라 흐름 자체의 속성입니다. --- ## XVII. 향후 과제 방법론과 참조 구현에는 분명한 다음 단계가 있습니다. - **지식 카탈로그 키우기**: 무엇을 추가하든 지식 파일 하나와 카탈로그 행 하나라는, 새 명령어 없는 형태를 유지합니다(`§VII`). 사용자 쪽 경로는 그곳에 이미 마련되어 있습니다. 사용자는 필요할 때 자신만의 전문 지식의 핵심을 정리해 만듭니다. 각각 하나의 카테고리에 속하는 더 많은 내장 언어, 런타임, 위험 유형은 메인테이너 쪽의 방향이며, 전문 지식은 계속 진화할 것으로 예상됩니다. - **더 많은 결정론적 검사기**: 위험 유형에 명확한 판정 절차가 있다면, 전문 지식은 에이전트의 추론을 반복 가능한 판정에 근거하게 하는 결정론적 검사기를 담을 수 있습니다. 이를 더 많은 위험 유형으로 넓히는 것이 자연스러운 방향입니다. - **실증 평가**: 가장 큰 미해결 질문은 측정된 효과, 즉 실제 코드베이스 전반에서의 종결 품질과 잘못된 판정의 비율입니다. SDH의 보안 성과에 대한 연구는 향후 과제이며, 이 문서의 주장은 그에 맞게 범위를 한정합니다. --- ## XVIII. 결론 AI 지원 개발은 일반적인 체크리스트로는 메울 수 없는 보안 공백을 열었습니다. 중요한 위험은 시스템이 실제로 하는 일에 따라 달라지고, 그것을 배포하는 사람은 무엇을 물어야 할지 모를 수 있기 때문입니다. SDH는 컨텍스트를 인식하고, 방어 전용이며, 종결 가능한 흐름으로 이 공백을 메웁니다. 이 흐름에서 보안 지식은 방법론과 필요할 때만 불러오는 전문 지식에 담겨 있으며, 모든 사용자가 그 위에 쌓아 갈 수 있는 기준선이 됩니다. SDH는 시스템의 실제 컨텍스트를 탐지하고, 그 컨텍스트가 지닌 위험의 우선순위를 정하고, 수정을 신중하게 적용하고, 각 수정을 검증한 다음, 해소한 것을 종결해 각 발견 사항이 최종 상태에 이르게 합니다. 새 작업을 만드는 동안에도 같은 방어가 예방적으로 작동하므로, 흐름이 종결한 것은 종결된 상태로 남습니다. SDH는 어떤 스택의 어떤 개발 상태에도 적응하며, 이미 그 일을 하는 사람과 도구를 대체하는 대신 개발자의 지식을 확장합니다. Lagune은 증명이지만, 기여는 컨벤션입니다. 다른 이들이 채택하고, 다듬고, 각자의 스택에서 구현할 수 있도록 SDH를 AI와 함께하는 개발 시대의 필수 보안 흐름으로 제안합니다. --- ## 참고 문헌 **[1]** D. B. Piskala, "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants," arXiv preprint arXiv:2602.00180v1 [cs.SE], Jan. 2026. (Submitted to AIWare 2026.) [Online]. Available: https://arxiv.org/abs/2602.00180 **[2]** GitHub, "Spec Kit: Toolkit for Spec-Driven Development." [Online]. Available: https://github.com/github/spec-kit. Accessed: 2026. **[3]** Fission AI, "OpenSpec: Spec-Driven Development for AI Coding Assistants." [Online]. Available: https://github.com/Fission-AI/OpenSpec. Accessed: 2026. **[4]** B. Chess and G. McGraw, "Static Analysis for Security," IEEE Security & Privacy, vol. 2, no. 6, pp. 76-79, 2004, doi: 10.1109/MSP.2004.111. **[5]** OWASP Foundation, "Source Code Analysis Tools." [Online]. Available: https://owasp.org/www-community/Source_Code_Analysis_Tools. Accessed: 2026. **[6]** OWASP Foundation, "OWASP Top 10:2021." [Online]. Available: https://owasp.org/Top10/. Accessed: 2026. **[7]** MITRE, "Common Weakness Enumeration (CWE)." [Online]. Available: https://cwe.mitre.org/. Accessed: 2026. **[8]** N. Perry, M. Srivastava, D. Kumar, and D. Boneh, "Do Users Write More Insecure Code with AI Assistants?," in Proc. ACM SIGSAC Conf. on Computer and Communications Security (CCS '23), 2023, pp. 2785-2799, doi: 10.1145/3576915.3623157. [Online]. Available: https://arxiv.org/abs/2211.03622 **[9]** J. Davis and contributors, "safe-regex: Detect Possibly Catastrophic, Exponential-Time Regular Expressions." [Online]. Available: https://github.com/davisjam/safe-regex. Accessed: 2026. **[10]** D. Soshnikov, "regexp-tree: Regular Expressions Processor in JavaScript." [Online]. Available: https://github.com/DmitrySoshnikov/regexp-tree. Accessed: 2026. **[11]** T. Jenkinson, "redos-detector: A CLI and Library to Score How Vulnerable a Regex Pattern Is to ReDoS Attacks." [Online]. Available: https://github.com/tjenkinson/redos-detector. Accessed: 2026. --- ## 부록 A: 원칙 전문 1. **기본적으로 안전하게, 쉬운 말로, 모두에게 동등하게**: 모든 기본값, 메시지, 수정은 처음부터 안전해야 하며, 개발자든 아니든 어떤 사용자도 이해할 수 있어야 합니다. 어떤 사용자층도 다른 사용자층보다 우대받지 않습니다. 2. **일반론보다 컨텍스트 인식**: 모든 단계는 detect 단계에서 탐지한 컨텍스트에서 출발해 시스템이 실제로 하는 일에 따라 행동해야 합니다. 일반적인 체크리스트보다 그 컨텍스트에 특화된 권장 사항을 우선합니다. 보안 지식은 명세와 필요할 때만 불러오는 전문 지식에 담겨 있으며, 사용자가 가진 지식이 무엇이든 그것을 확장합니다. 3. **경직성보다 유연성**: SDH는 프로젝트와 사용자에 맞춰 유연하게 바뀝니다. 원칙, 요구 사항, 권장 사항은 고정된 계약이 아니라 출발점입니다. 사용자가 무엇이든 고쳐 쓰고, 빼고, 더하고, 범위를 좁힐 수 있게 합니다. 유연성은 기본적으로 안전한 기준선을 결코 약화하지 않으며, 사용자가 그 기준선을 적용하는 방식을 다듬을 수 있게 할 뿐입니다. 4. **덧붙이기만 하지 않고, 현재 상태와 대조해 갱신하기**: 산출물은 로그가 아니라 살아 있는 문서입니다. 단계를 다시 실행할 때는 기존 항목을 하나하나 현재 사실과 대조해 갱신합니다. 여전히 유효한 것은 유지하고, 바뀐 것은 다시 쓰고, 더 이상 해당하지 않는 것은 제거합니다. 종결은 바로 이 대조와 갱신이 결론에 이른 것입니다. 5. **방어 전용**: SDH는 점검하고, 보안을 강화하고, 검증합니다. 공격 도구, 악의적인 용도의 익스플로잇, 피해를 목적으로 한 탐지 회피 기법은 결코 만들지 않습니다. 이중 용도의 보안 내용은 명확히 방어적이고 승인된 맥락에서만 허용됩니다. 6. **명세 우선, 에이전트 주도, 보안 중심**: 검증된 구조, 즉 템플릿, 명령어, 모든 단계를 규율하는 보안 원칙, 단계를 실행하는 에이전트로 워크플로를 만듭니다. 그 구조를 방어 목적으로 다시 구현합니다. --- # Lagune 용어집: SDH, Charter, 발견 사항, 보안 통제 > Lagune과 Security-Driven Hardening의 모든 용어를 쉬운 말로 정의합니다. SDH, charter, detect, 발견 사항, 보안 통제, harden, verify, 종결, 종결 가능성, 전문 지식, 카테고리, 카탈로그를 다룹니다. 표준 URL: https://lagune.ai/ko-KR/docs/references/glossary 언어: ko-KR 원문: https://lagune.ai/docs/references/glossary 마지막 업데이트: 2026-11-03 Lagune과 Security-Driven Hardening 방법론을 이해하는 데 꼭 필요한 용어를 한곳에서 쉬운 말로 정의합니다. ### Security-Driven Hardening (SDH) Lagune이 구현하는 방법론으로, 컨텍스트를 인식하는 Blue Team 컨벤션입니다. 시스템의 컨텍스트를 탐지하고, 그 컨텍스트에 따르는 위험의 우선순위를 정하며, 수정을 안내합니다. 보안 지식은 명세와, 필요할 때만 불러오는 전문 지식에 담겨 있으므로 개발자든 아니든 같은 흐름으로 도움을 받습니다. ### Lagune SDH의 참조 구현입니다. AI 에이전트가 코드베이스의 보안을 강화하려고 실행하는 에이전트 명령어 9개로 이루어지며, 각 명령어에는 채워 넣을 템플릿이 함께 있습니다. 각 에이전트는 자체 플러그인 설치 도구나 [**skills.sh**](https://www.skills.sh/wellwelwel/lagune)를 통해 명령어를 설치하며([설치 페이지](https://lagune.ai/ko-KR/docs) 참고), 명령어는 모든 결정론적 단계에서 Lagune의 엔진을 실행합니다. ### Charter(보안 원칙) Lagune에서 모든 단계를 규율하는 계층으로, 이후의 모든 단계가 따라야 하는 보안 우선 원칙의 모음입니다. 프로젝트 보안 태세에 대한 컴파일 타임 검사라고 생각하면 됩니다. `.lagune/memory/charter.md` 파일에 저장됩니다. ### 개발 흐름 작업하는 바로 그 순간에 보안을 강화하는 범용 `/lagune` 명령어입니다. 어느 단계에서든 어떤 프롬프트든 받아 요청한 것을 만들고, 돌려주기 전에 안전한 기본값으로 보안을 강화합니다. 보안 원칙이 있으면 그에 따릅니다. Lagune의 추적에는 아무것도 기록하지 않으므로, 결과물은 보안이 강화된 코드뿐입니다. 앞서 정하는 보안 원칙, 뒤이어 실행하는 Blue Team 흐름과 함께, 개발하는 동안 Lagune이 프로젝트를 보호하는 방법입니다. ### Blue Team 흐름 Lagune의 핵심인 5단계 감사로, charter, detect, plan, harden, verify로 이루어집니다. 각 단계는 이전 단계의 결과를 바탕으로 진행됩니다. "Blue Team"은 공격하는 Red Team과 달리 방어하는 쪽의 보안 전통을 가리킵니다. ### 발견 사항(Finding) 탐지된 위험 하나를 가리킵니다. 각 발견 사항에는 무엇인지, 왜 중요한지, 코드에 있는 근거가 담깁니다. 발견 사항은 plan, harden, verify 단계가 이어받아 처리하는 하나의 추적 단위이며, 모든 산출물에서 이름으로 식별됩니다. ### 보안 통제(Control) 위험을 해소하려고 적용하는 보안 조치입니다. harden 단계는 보안 통제를 적용하고, verify 단계는 그 통제가 실제로 효과가 있는지 증명합니다. Lagune은 프롬프트에 맞추려고 보안 통제를 약화하는 일이 절대 없습니다. ### Detect 코드를 읽고 시스템이 무엇을 하는지, 위험이 어디에 있는지 파악하는 단계입니다. 핵심 규칙은 지어내지 않고 탐지하는 것으로, 코드가 뒷받침하는 내용만 기록합니다. ### Harden 코드를 직접 수정하는 유일한 단계입니다. plan 단계의 수정을 하나씩 적용하고, 각각을 Applied, Partial, Blocked 중 하나로 기록합니다. Applied라고 해서 증명까지 끝난 것은 아닙니다. ### Verify 코드를 읽고 harden 단계가 기록한 내용과 대조해, 적용한 각 수정이 실제로 효과가 있는지 증명하는 단계입니다. 판정은 Risk closed, Risk not closed, Cannot tell from the code 세 가지 중 하나입니다. ### 종결(Stand down) verify 단계에서 위험이 해소되었음을 증명하면 해당 발견 사항을 종결합니다. 확인을 거쳐 체인 전체에서 제거하므로, 더 이상 다시 처리되지 않습니다. ### 종결 가능성(Closability) 보안 작업에 끝이 있다는 성질입니다. 해소가 증명된 발견 사항은 종결되므로 흐름이 안정 상태에 이를 수 있고, 코드가 바뀔 때만 다시 열립니다. SDH는 끝없는 루프가 아니라 종결할 수 있는 과정입니다. ### 엔진 **npm**에 있는 `lagune` 패키지로, 명령어는 모든 결정론적 단계(훅, 카탈로그, 카테고리)에서 `npx` 명령어를 통해 이 패키지를 실행합니다. ### 전문 지식(Specialization) 특정 주제에 집중한, 프로그래밍 언어와 무관한 보안 지식 모듈로, 기본으로는 불러오지 않고 필요할 때만 불러옵니다. 전문 지식은 명령어가 아닙니다. 엔진의 `read catalog ` 명령어로 어떤 프롬프트에든 불러올 수 있습니다(예: `npx lagune read catalog regex`). ### 카테고리 이름이 붙은 내장 전문 지식의 묶음으로, `owasp` 카테고리부터 `javascript`, `python`, `go`, `rust` 같은 언어별 카테고리까지 있습니다. 프로젝트가 사용하는 카테고리는 `.lagune/configs.json` 파일에 기록되며, 어떤 내장 전문 지식이 카탈로그에 들어갈지 결정합니다. 기록된 카테고리가 없으면 프로젝트는 `owasp` 카테고리만 사용합니다. ### 카탈로그 프로젝트가 사용하는 전문 지식의 모음으로, 프로젝트 카테고리의 내장 전문 지식에 `/lagune-specialize` 명령어로 직접 작성한 전문 지식을 더한 것입니다. 엔진의 `read catalog` 명령어가 카탈로그 목록을 보여 주고, 각 단계는 카탈로그를 코드와 대조합니다. ### 필요할 때만 불러오는 프롬프트(Prompt-on-demand) 모든 검사를 기본으로 실행하는 대신, 프로젝트의 실제 모습에 맞는 보안 지식만 불러온다는 원칙입니다. ### 이름 기반 식별(Identity-by-name) Lagune의 추적 모델입니다. 각 발견 사항의 이름은 모든 산출물에서 똑같은 섹션 제목으로 쓰이며, 체인 전체에서 그 발견 사항을 식별하는 기준이 됩니다. 추적 맵(`.lagune/tracking.json`)은 추적 정보만 담고, 설명 글은 절대 담지 않습니다. ## 자주 묻는 질문 ### Security-Driven Hardening(SDH)이란 무엇인가요? SDH는 컨텍스트를 인식하는 Blue Team 보안 방법론입니다. 시스템의 컨텍스트를 탐지하고, 그 컨텍스트에 따르는 위험의 우선순위를 정하며, 모든 발견 사항을 쉬운 말로 전달하면서 수정을 안내합니다. Lagune은 그 참조 구현입니다. ### Lagune의 charter란 무엇인가요? charter는 Lagune에서 모든 단계를 규율하는 계층으로, 이후의 모든 단계가 따라야 하는 보안 우선 원칙의 모음입니다. .lagune/memory/charter.md 파일에 저장됩니다. ### 발견 사항을 종결한다는 것은 무슨 뜻인가요? verify 단계에서 위험이 해소되었음을 증명하면 해당 발견 사항을 종결합니다. 확인을 거쳐 체인 전체에서 제거하므로, 더 이상 다시 처리되지 않습니다. --- # 설정 스키마 > Lagune 프로젝트 설정 파일의 JSON Schema입니다. 에디터에서 자동 완성과 유효성 검사를 제공하며, 최신 Lagune을 따르게 하거나 특정 버전에 고정할 수 있습니다. 표준 URL: https://lagune.ai/ko-KR/docs/references/configs-schema 언어: ko-KR 원문: https://lagune.ai/docs/references/configs-schema 마지막 업데이트: 2026-11-03 `.lagune/configs.json` 파일은 프로젝트가 사용하는 [**카테고리**](https://lagune.ai/ko-KR/docs/categories)를 기록하고, 프로젝트가 직접 만든 [**전문 지식**](https://lagune.ai/ko-KR/docs/catalog)의 색인을 담습니다. 이 파일의 JSON Schema를 사용하면 파일을 편집하는 동안 에디터가 각 필드를 자동 완성하고, 오타나 알 수 없는 카테고리를 잡아냅니다. ## 최신 스키마 **Lagune**은 이 파일을 기록할 때 `$schema` 필드가 없으면, 파일이 최신 스키마를 가리키도록 설정합니다: ```json { "$schema": "https://lagune.ai/schemas/configs.json", "categories": ["owasp", "javascript"] } ``` 이 주소는 항상 최신 **Lagune**을 따릅니다. **Lagune** 0.16.0 이전에 작성된 파일은 다음에 변경될 때 이 주소를 받으며, 그전까지는 모든 단계가 이를 알려 줍니다. ## 버전 고정하기 0.16.0부터 나온 모든 **Lagune** 릴리스에는 그 버전 당시의 스키마가 들어 있으며, 이 스키마는 **npm**에 게시되고 **jsDelivr**를 통해 제공됩니다. 버전을 고정하려면 `lagune@` 뒤에 원하는 버전을 적어 `$schema` 주소를 지정하세요: ```json { "$schema": "https://cdn.jsdelivr.net/npm/lagune@0.16.0/schemas/configs.json" } ``` 버전에는 어떤 semver 범위든 쓸 수 있습니다: | 버전 | 스키마 | | -------------------- | ------------------------- | | `0.16.0` | 0.16.0 버전의 스키마 | | `0.16.x` 또는 `0.16` | 최신 0.16 릴리스의 스키마 | | `0.x` 또는 `0` | 최신 0.x 릴리스의 스키마 | | `latest` | 최신 릴리스의 스키마 | ## 자주 묻는 질문 ### Lagune을 쓰려면 스키마가 꼭 필요한가요? 아니요. 스키마는 에디터를 돕기 위한 것일 뿐이며, Lagune은 $schema 필드가 있든 없든 파일을 똑같이 읽습니다. ### 고정해 둔 스키마를 Lagune이 덮어쓰나요? 아니요. Lagune은 파일에 $schema 필드가 없을 때만 기록하며, 직접 설정한 주소는 그대로 유지합니다. ### 언제 버전을 고정해야 하나요? 프로젝트에서 특정 버전의 Lagune을 사용할 때입니다. 그러면 에디터가 해당 버전이 허용하는 내용을 기준으로 파일을 검증합니다. --- # Lagune vs. Deepsec: AI 기반 보안 접근 방식 두 가지 비교 > Lagune과 Vercel의 Deepsec을 작동 방식, 수명 주기, 탐지, 비용, 발견 사항, 종결 관점에서 비교한 참고 문서입니다. 표준 URL: https://lagune.ai/ko-KR/docs/references/deepsec 언어: ko-KR 원문: https://lagune.ai/docs/references/deepsec 마지막 업데이트: 2026-11-03 [Lagune](https://github.com/wellwelwel/lagune)과 [Deepsec](https://github.com/vercel-labs/deepsec)(`v2.2.1`)은 AI를 활용한 개발 시대의 보안이라는 같은 문제에 대한 두 가지 방어적 해답입니다. 메커니즘이 겹치는 부분이 있더라도, 두 프로젝트는 전제도, 처음과 중간과 끝도, 사용자에게 드러나는 모습도 의도적으로 다르게 설계되었습니다. **팁** Lagune은 Deepsec에서 영감을 받았나요? 아니요. Lagune은 처음부터 새로 작성한 프로젝트이며, Spec-Driven Development와 Security Hardening에서 영감을 받았습니다. 두 프로젝트는 서로 독립적으로 개발되었고, 이 비교는 사용자가 둘의 차이를 이해하도록 돕기 위한 것입니다. ## 한눈에 보기 | 항목 | Lagune | Deepsec | | -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | 유형 | 참조 구현을 갖춘 방법론(SDH) | 제품: 에이전트 기반 취약점 스캐너 | | 중심축 | 결정론적 훅을 토대로, 보안 원칙과 필요할 때만 불러오는 지식이 에이전트를 이끄는 구조 | 넓게 친 정규식 그물이 필수 AI 조사로 이어지는 구조 | | 결과물 | 보안이 강화된 코드, 증명, 추적되는 발견 사항 체인 | 심각도순으로 정렬하고 트리아지를 거친 발견 사항 보고서 | | 코드 수정 여부 | 예: `harden` 단계가 코드를 수정 | 아니요: 정적 분석만 하며, 발견 사항과 권장 사항 텍스트를 출력 | | 실행 환경 | 이미 쓰고 있는 에이전트와 모델에서 실행, 모델 등급 제한 없음 | 자체 모델 파이프라인에서 실행, 기본값은 프런티어급 모델 | | 시작 방법 | 플러그인 한 번 설치 또는 `npx skills add` 실행 후 일상 언어로 지시, 새로 구축할 도구 없음 | `.deepsec/` 워크스페이스 구성, 의존성 설치, 모델 키 추가 | ## 작동 방식 Lagune은 에이전트 우선 방식으로, 에이전트가 작업을 이끌고, 코드의 성격에 맞는 지식을 필요할 때만 불러오며, 판정할 수 있는 부분은 결정론적 훅에 맡깁니다. Deepsec은 결정론적 처리 우선 방식으로, 넓은 범위의 스캔이 후보를 잡아내면 그 후보가 반드시 거쳐야 하는 모델에게 무엇을 조사하고 판단할지 알려 줍니다. | 항목 | Lagune | Deepsec | | -------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | 순서 | 보안 원칙과 코드에 맞는 지식이 에이전트를 이끌고, 에이전트는 일부를 훅에 맡긴 뒤 나머지를 직접 판단 | 매처(matcher)가 후보를 잡아내고, 모델이 후보마다 조사해 판단 | | 결정론적 처리의 역할 | 판정을 돌려주거나 에이전트가 살필 곳을 짚어 주는 다국어 훅, 카테고리 지식과 함께 사용 | 필수 모델이 판단할 후보를 잡아내는 매처 | | 개발 흐름 | 코드를 작성하는 동안 `/lagune` 명령어가 그 자리에서 안전하게 구축 | 코드를 검토할 뿐, 작성하지는 않음 | | 감사 흐름 | `charter` → `detect` → `plan` → `harden` → `verify` | `scan` → `process` → `triage` → `revalidate` → `report` | | AI의 역할 | 지식을 바탕으로 추론하고, 수정을 적용하고, 그 수정이 실제로 효과가 있는지 증명 | 모든 후보를 조사하고 발견 사항을 보고 | ## 수명 주기 Lagune은 코드를 작성하기 전에도, 작성하는 중에도, 작성한 후에도 작동합니다. Deepsec은 코드가 생긴 뒤에 저장소를 검토합니다. | 시점 | Lagune | Deepsec | | -------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- | | 코드가 없을 때 | `charter` 단계가 밝힌 의도를 바탕으로 보안 정책 수립 | 기존 코드에서 시작: `init` 명령어에 디렉터리 필요 | | 개발 중 | `/lagune` 명령어가 그 자리에서 기본적으로 안전하게 구축, 남는 산출물 없음 | 개발 중이 아닌 개발 후에 검토 | | 기존 코드 | `detect` → `plan` → `harden` → `verify` | 핵심 흐름인 `scan` → `process` | | 지속적인 검토 | 범위별로 단계를 다시 실행, 기본 제공 CI 게이트 없음 | 증분 재스캔, CI 종료 게이트 역할을 하는 `process --diff` | ## 탐지 계층 두 프로젝트의 결정론적 계층은 성격이 정반대여서, 한쪽은 판정하고 다른 한쪽은 후보를 잡아냅니다. | 항목 | Lagune | Deepsec | | --------- | ------------------------------------------------------------------ | ------------------------------------------------------- | | 묶는 방식 | 카테고리별로 묶은 훅과 전문 지식 | 패턴이나 프레임워크별 매처 | | 출력 | 명시적인 판정(finding / review / advisory)과 분류(classify) 레이블 | 판정 없는 후보(slug, 줄, 코드 조각, 일치한 패턴) | | 튜닝 | 정밀도 중심: 주석 인식, 플레이스홀더 가드와 윈도 가드 | 재현율 중심: 넓은 그물, 오탐은 나중에 AI가 걸러 냄 | | 깊이 | 두 프로젝트가 공통으로 다루는 유형에서 더 깊음 | 더 넓지만, 공통으로 다루는 유형에서는 덜 깊음 | | 오탐 | 발생 지점에서 낮게 억제한 뒤 컨텍스트 안에서 판단 | 의도적으로 많이 만들어 낸 뒤 `revalidate` 과정에서 줄임 | ## 지식과 판단 두 프로젝트 모두 정규식으로는 담을 수 없는 보안 지식을 갖추고 있습니다. 차이는 그 지식이 어디에 있고 누가 다듬을 수 있는지에 있습니다. | 항목 | Lagune | Deepsec | | --------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- | | 형태 | 편집할 수 있는 Markdown 모듈, 그중 여러 개는 결정론적 훅이 뒷받침 | 짧은 프롬프트와 기술별 요점, 모델 자체의 지식에 의존 | | 선택 방식 | 코드에 맞는 모듈만 골라, 해당 컨텍스트가 있을 때만 불러옴 | 모든 AI 배치에 주입, 탐지된 기술의 요점도 추가 | | 작성 주체 | 사용자가 모듈을 편집하고, `specialize` 명령어로 새 모듈 추가 | 프롬프트는 메인테이너가 관리하고, 사용자는 `INFO.md` 파일 작성 | | 판단 주체 | 훅이 자신이 맡은 최소 기준을 판정하고, 나머지는 에이전트가 지식을 바탕으로 판단 | 중앙 집중형: 하나의 AI 프로세서가 모든 후보를 판단 | | 재사용 | 하나의 모듈이 `detect` 단계와 `verify` 단계를 모두 안내 | 하나의 프롬프트가 단 하나뿐인 `process` 단계를 구동 | ## 발견 사항과 종결 두 프로젝트가 가장 크게 갈리는 지점은 해결된 발견 사항이 이후 어떻게 되느냐입니다. | 항목 | Lagune | Deepsec | | ------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | 심각도 | 노출 정도와 사안의 중대성에 맞춰 조정한 CVSS v4.0 점수 | AI가 매긴 심각도와, 악용 가능성과 영향도에 따른 P0 / P1 / P2 트리아지 | | 판정 | Risk closed, Risk not closed, Cannot tell from the code 중 하나 | true-positive, false-positive, fixed, uncertain, accepted-risk, duplicate | | 보존 방식 | 작업 중인 체인은 현재 상태와 대조해 갱신하고, 종결된 발견 사항은 핵심만 정리해 이력으로 남김 | 파일별 추가 전용 기록, 아무것도 삭제하지 않음 | | 최종 상태 | 종결 가능: 증명된 발견 사항은 종결되고, 체인은 안정 상태가 될 수 있음 | 모든 발견 사항을 영구 보관하고, 해결되면 화면에서 숨김 | | 이력의 상세도 | 어떤 위험이었는지에 대한 간결한 요약 | 어떻게 수정했는지까지 담은 판정 기록 전체 | ## 비용 | 항목 | Lagune | Deepsec | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 결정론적 최소 기준 | 무료: 훅은 AI도 키도 없이 실행되며, 그 단계에서 이미 판정을 내림 | 무료: `scan` 명령어는 AI 없이 실행되지만, 그 자체로는 판정을 내리지 않음 | | 일반적인 비용 | 이미 쓰고 있는 에이전트 비용에 포함: 로컬 모델이면 $0, 이미 이용 중인 요금제라면 그 요금 그대로, API 기반 사용이라면 반복마다 과금 | [파일 100개에서 2,000개 기준 1회 실행에 약 $25에서 $1,200, 규모가 커지면 그 이상](https://github.com/vercel-labs/deepsec/blob/f75a16803ec5250938bacfe41571d929e8564f45/docs/getting-started.md#run-the-ai-investigation) | | 가장 저렴한 방법 | 무료 로컬 모델을 포함해 어떤 모델로든 사이클을 마무리 | 더 저렴한 유료 등급도 있지만, 발견 사항을 얻으려면 유료 AI 단계가 필요 | ## 확장성과 거버넌스 각자 상대가 닫아 둔 계층을 열어 둡니다. | 항목 | Lagune | Deepsec | | --------------- | ----------------------------------------------------- | ------------------------------------------- | | 확장 대상 | 모듈을 편집하거나, `specialize` 명령어로 새 모듈 추가 | 매처, 에이전트, 알림 기능, 소유자 정보 추가 | | 정책 계층 | 보안 원칙이 모든 단계를 규율하며, 버전 관리됨 | 설정은 운영용(매처, 모델, 경로) | | 이름으로 재정의 | 다듬은 모듈이 같은 이름의 내장 모듈을 가림 | 매처 slug가 겹치면 사용자의 매처가 우선 | ## 인터페이스 Deepsec은 보안 조직에 전달할 결과물을 만들어 냅니다. Lagune은 실행하는 사람을 위해 실시간 뷰를 보여 줍니다. | 항목 | Lagune | Deepsec | | ---------------- | ------------------------------------------------------------- | ------------------------------------------------------ | | 사람이 보는 화면 | 체인 전체를 쉬운 말로 보여 주는 로컬 실시간 대시보드 | 보고서, 내보내기, 지표, PR 코멘트 파일과 문서 사이트 | | 책임 소재 | 관련 파일과 적용된 전문 지식을 드러냄 | 추천 담당자 지정: 온콜 담당자, 매니저, 커미터 | | 재현 가능한 증명 | `prove` 명령어가 실행 가능한 테스트와 공개용 보안 권고를 작성 | 설계상 정적 분석에 머물며, 대상을 실행하지 않음 | | 도구 자체 방어 | 대시보드의 로컬 쓰기 API 보안 강화 | 신뢰할 수 없는 대상 코드에 맞서 자체 AI 실행 보안 강화 | ## 규모와 배포 | 항목 | Lagune | Deepsec | | ----------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- | | 설치 | 에이전트의 플러그인이나 **skills** CLI로 받는 명령어 9개, 미리 생성되는 파일 없음 | 자체 패키지와 의존성을 갖춘 `.deepsec/` 워크스페이스 | | 규모의 방향 | 컨텍스트 하나, 파일 하나부터 프로젝트 전체까지 어떤 범위로든 좁힐 수 있음 | 저장소 전체를 스캔하며, 대규모 모노레포까지 지원 | | 분산 실행 | 로컬 전용, 유일한 서버는 루프백에 바인딩 | 선택적으로 Vercel Sandbox 워커 VM에 분산 | ## 사용자 경험 각 도구가 실행하는 사람을 맞이하는 방식, 즉 첫 실행에 필요한 것과 실행하는 사람이 작업 대상을 겨누는 방법입니다. ### 온보딩 Lagune은 이미 열려 있는 에이전트를 통해 실행됩니다. Deepsec은 먼저 자체 워크스페이스와 모델 접근 권한을 준비합니다. | 항목 | Lagune | Deepsec | | ----------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | 첫 명령어 | 플러그인 설치 또는 `npx skills add wellwelwel/lagune`, 이후 에이전트에서 `/lagune-*` 실행 | `npx deepsec init` 실행 후 `cd .deepsec`, `pnpm install`, `scan`, `process` | | 실행에 필요한 자격 증명 | 별도 키 없음, 지금 쓰는 에이전트를 그대로 사용 | 모델 키(예: AI Gateway, 유효 시간 12시간인 Vercel OIDC 토큰, Anthropic 토큰) | ### 지시하기 두 도구 모두 지시를 받습니다. Lagune은 단계마다 입력의 형태를 읽어 냅니다. Deepsec은 같은 조사를 실행할 파일 범위를 좁힙니다. | 항목 | Lagune | Deepsec | | ------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- | | 프로젝트 전체 | 입력 없이 실행한 단계는 범위 전체를 스캔 | `scan` 명령어와 `process` 명령어가 저장소 전체를 스캔 | | 일부 범위 | 어떤 단계든 지정한 파일이나 디렉터리로 범위를 좁힘 | `--files`, `--files-from`, `--diff` 옵션으로 실행 범위를 좁힘 | | 우려 사항 | 단계의 범위를 사용자가 설명한 우려 사항으로 좁힘 | 조사 프롬프트는 고정 | | 우선순위 구간 | `harden` 단계와 `verify` 단계의 범위를 치명적, 높음, 중간, 낮음 중 하나로 좁힘 | 발견 사항 레이블은 실행 후에 붙음 | | 단일 값 | 훅이 코드 조각, 패턴, URL 하나에 직접 점수를 매김(`--pattern`, `--url`) | 작업 단위는 파일 | ## 자주 묻는 질문 ### Lagune은 Deepsec과 무엇이 다른가요? Lagune은 에이전트 우선 방식으로, 코드를 작성하기 전에도, 작성하는 중에도, 작성한 후에도 작동합니다. 코드를 쓰기 전에는 정책을 정하고, 개발하는 동안에는 그 자리에서 보안을 강화하며, 이미 작성된 코드는 점검하고, 보안을 강화하고, 검증합니다. Deepsec은 결정론적 처리 우선 방식으로, 넓은 범위의 정규식 스캔 결과가 반드시 거치는 프런티어 모델의 조사로 이어지며, 이 조사는 기존 코드를 검토해 발견 사항을 보고할 뿐 코드를 변경하지는 않습니다. ### 둘 중 어느 쪽이든 무료로 실행할 수 있나요? Lagune은 무료 로컬 모델로 전체 흐름을 $0에 실행할 수 있고, 결정론적 훅은 AI 없이도 판정을 내립니다. Deepsec의 스캔은 무료지만 판정을 내리지 않으므로, 발견 사항을 얻으려면 반드시 유료 AI 단계를 거쳐야 합니다. ### 둘 중 코드를 수정하는 도구가 있나요? Lagune은 harden 단계에서 코드에 수정을 적용합니다. 반면 Deepsec은 정적 분석만 하므로 코드를 수정하지 않으며, 사람이나 에이전트가 따로 적용해야 하는 발견 사항과 권장 사항 텍스트를 출력합니다. --- # OWASP 출처 > 내장 OWASP 전문 지식의 출처를 OWASP 공식 공격 페이지와 Cheat Sheet 페이지에 대응시켜 정리했습니다. 표준 URL: https://lagune.ai/ko-KR/docs/references/owasp-sources 언어: ko-KR 원문: https://lagune.ai/docs/references/owasp-sources 마지막 업데이트: 2026-11-03 이 문서는 OWASP의 모든 **공격**(`www-community`)과 **Cheat Sheet**(`CheatSheetSeries`) 항목을 보안 카테고리에 대응시키고, 각 항목을 공식 공개 페이지에 연결합니다. 한 카테고리 안에서 같은 위험을 다루는 공격과 Cheat Sheet는 체크리스트 한 줄에 쉼표로 구분해 함께 나열합니다. 직접 대응하는 짝이 없는 항목은 한 줄을 단독으로 차지합니다. - 이 자료의 공로는 OWASP에 있습니다. 공격 페이지는 `https://owasp.org/www-community/attacks/` 주소에, Cheat Sheet는 `https://cheatsheetseries.owasp.org/cheatsheets/.html` 주소에 있습니다. --- ## 1. 인젝션(일반) - [x] [Code Injection](https://owasp.org/www-community/attacks/Code_Injection), [Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html), [Injection Prevention in Java](https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_in_Java_Cheat_Sheet.html) (interpreter) - [x] [Direct Dynamic Code Evaluation (Eval Injection)](https://owasp.org/www-community/attacks/Direct_Dynamic_Code_Evaluation_Eval_Injection) (interpreter) - [x] [Function Injection](https://owasp.org/www-community/attacks/Function_Injection) (interpreter) - [x] [Resource Injection](https://owasp.org/www-community/attacks/Resource_Injection) (network) - [x] [Special Element Injection](https://owasp.org/www-community/attacks/Special_Element_Injection) (interpreter) - [x] [Custom Special Character Injection](https://owasp.org/www-community/attacks/Custom_Special_Character_Injection) (interpreter) - [x] [Comment Injection Attack](https://owasp.org/www-community/attacks/Comment_Injection_Attack) (interpreter) - [x] [Parameter Delimiter](https://owasp.org/www-community/attacks/Parameter_Delimiter) (interpreter) - [x] [Server-Side Includes (SSI) Injection](https://owasp.org/www-community/attacks/Server-Side_Includes_%28SSI%29_Injection) (interpreter) - [x] [Input Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html), [Bean Validation](https://cheatsheetseries.owasp.org/cheatsheets/Bean_Validation_Cheat_Sheet.html) (interpreter) --- ## 2. SQL / 데이터베이스 인젝션 - [x] [SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection), [SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html), [Query Parameterization](https://cheatsheetseries.owasp.org/cheatsheets/Query_Parameterization_Cheat_Sheet.html) (sql) - [x] [Blind SQL Injection](https://owasp.org/www-community/attacks/Blind_SQL_Injection) (sql) - [x] [SQL Injection Bypassing WAF](https://owasp.org/www-community/attacks/SQL_Injection_Bypassing_WAF) (sql) - [x] [RSQL Injection](https://owasp.org/www-community/attacks/RSQL_Injection) (interpreter) - [x] [Database Security](https://cheatsheetseries.owasp.org/cheatsheets/Database_Security_Cheat_Sheet.html) (sql) - [x] [NoSQL Security](https://cheatsheetseries.owasp.org/cheatsheets/NoSQL_Security_Cheat_Sheet.html) (interpreter) --- ## 3. OS / 명령어 인젝션 - [x] [Command Injection](https://owasp.org/www-community/attacks/Command_Injection), [OS Command Injection Defense](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html) (interpreter) --- ## 4. LDAP / XPath / XML 인젝션 - [x] [LDAP Injection](https://owasp.org/www-community/attacks/LDAP_Injection), [LDAP Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/LDAP_Injection_Prevention_Cheat_Sheet.html) (interpreter) - [x] [XPATH Injection](https://owasp.org/www-community/attacks/XPATH_Injection) (interpreter) - [x] [Blind XPath Injection](https://owasp.org/www-community/attacks/Blind_XPath_Injection) (interpreter) - [x] [XML External Entity (XXE) Prevention](https://cheatsheetseries.owasp.org/cheatsheets/XML_External_Entity_Prevention_Cheat_Sheet.html), [XML Security](https://cheatsheetseries.owasp.org/cheatsheets/XML_Security_Cheat_Sheet.html) (xml) --- ## 5. 크로스 사이트 스크립팅(XSS) - [x] [Cross Site Scripting (XSS)](https://owasp.org/www-community/attacks/Cross-site-Scripting-%28XSS%29), [Cross Site Scripting Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html), [XSS Filter Evasion](https://cheatsheetseries.owasp.org/cheatsheets/XSS_Filter_Evasion_Cheat_Sheet.html) (browser) - [x] [DOM Based XSS](https://owasp.org/www-community/attacks/DOM_Based_XSS), [DOM based XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html), [DOM Clobbering Prevention](https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html) (browser) - [x] [Reflected DOM Injection](https://owasp.org/www-community/attacks/Reflected_DOM_Injection) (browser) - [x] [XSS in Converting File Content to Text](https://owasp.org/www-community/attacks/XSS_in_Converting_File_Content_to_Text) (browser) - [x] [XSS in subtitle](https://owasp.org/www-community/attacks/Xss_in_subtitle) (browser) - [x] [Cross Frame Scripting](https://owasp.org/www-community/attacks/Cross_Frame_Scripting) (browser) - [x] [Cross Site Tracing](https://owasp.org/www-community/attacks/Cross_Site_Tracing) (browser) - [x] [Content Security Policy](https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html) (browser) --- ## 6. 크로스 사이트 요청 위조(CSRF)와 클릭재킹 - [x] [Cross Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/cross-site-request-forgery), [XSRF](https://owasp.org/www-community/attacks/XSRF), [Cross-Site Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) (http-request) - [x] [Clickjacking](https://owasp.org/www-community/attacks/Clickjacking), [Clickjacking Defense](https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html) (browser) - [x] [Cross Site History Manipulation (XSHM)](https://owasp.org/www-community/attacks/Cross_Site_History_Manipulation_%28XSHM%29) (browser) - [x] [Form action hijacking](https://owasp.org/www-community/attacks/Form_action_hijacking) (network) - [x] [Reverse Tabnabbing](https://owasp.org/www-community/attacks/Reverse_Tabnabbing) (browser) --- ## 7. 리다이렉트와 포워드 - [x] [Open Redirect](https://owasp.org/www-community/attacks/open_redirect), [Unvalidated Redirects and Forwards](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) (network) - [x] [Execution After Redirect (EAR)](https://owasp.org/www-community/attacks/Execution_After_Redirect_%28EAR%29) (browser) --- ## 8. 접근 통제와 인가 - [x] [Insecure Direct Object Reference (IDOR)](https://owasp.org/www-community/attacks/insecure_direct_object_reference), [Insecure Direct Object Reference Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html) (access-control) - [x] [Forced browsing](https://owasp.org/www-community/attacks/Forced_browsing) (access-control) - [x] [Web Parameter Tampering](https://owasp.org/www-community/attacks/Web_Parameter_Tampering) (access-control) - [x] [Setting Manipulation](https://owasp.org/www-community/attacks/Setting_Manipulation) (access-control) - [x] [Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) (access-control) - [x] [Transaction Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html) (access-control) - [x] [Mass Assignment](https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html) (access-control) - [x] [Multi-Tenant Application Security](https://cheatsheetseries.owasp.org/cheatsheets/Multi_Tenant_Security_Cheat_Sheet.html) (access-control) --- ## 9. 인증과 자격 증명 - [x] [Brute Force Attack](https://owasp.org/www-community/attacks/Brute_force_attack), [Password Spraying Attack](https://owasp.org/www-community/attacks/Password_Spraying_Attack), [Bot Management and Anti-Automation](https://cheatsheetseries.owasp.org/cheatsheets/Bot_Management_and_Anti-Automation_Cheat_Sheet.html) (credential-endpoint) - [x] [Credential stuffing](https://owasp.org/www-community/attacks/Credential_stuffing), [Credential Stuffing Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Credential_Stuffing_Prevention_Cheat_Sheet.html) (credential-endpoint) - [x] [Qrljacking](https://owasp.org/www-community/attacks/Qrljacking) (federation) - [x] [Authentication](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html), [Multifactor Authentication](https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html) (access-control) - [x] [Password Storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) (access-control) - [x] [Forgot Password](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html), [Choosing and Using Security Questions](https://cheatsheetseries.owasp.org/cheatsheets/Choosing_and_Using_Security_Questions_Cheat_Sheet.html) (access-control) - [x] [Email Validation and Verification in Identity Systems](https://cheatsheetseries.owasp.org/cheatsheets/Email_Validation_and_Verification_Cheat_Sheet.html) (access-control) --- ## 10. 세션 관리 - [x] [Session fixation](https://owasp.org/www-community/attacks/Session_fixation), [Session hijacking attack](https://owasp.org/www-community/attacks/Session_hijacking_attack), [Session Prediction](https://owasp.org/www-community/attacks/Session_Prediction), [Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) (access-control) - [x] [Cookie Theft Mitigation](https://cheatsheetseries.owasp.org/cheatsheets/Cookie_Theft_Mitigation_Cheat_Sheet.html) (access-control) --- ## 11. ID 페더레이션(OAuth / SAML / JWT) - [x] [OAuth 2.0 Protocol](https://cheatsheetseries.owasp.org/cheatsheets/OAuth2_Cheat_Sheet.html) (federation) - [x] [SAML Security](https://cheatsheetseries.owasp.org/cheatsheets/SAML_Security_Cheat_Sheet.html) (federation) - [x] [JSON Web Token for Java](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html) (federation) --- ## 12. 암호 기술과 전송 보안 - [x] [Cryptanalysis](https://owasp.org/www-community/attacks/Cryptanalysis), [Cryptographic Storage](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html), [Key Management](https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html) (crypto) - [x] [Manipulator-in-the-Middle (MITM)](https://owasp.org/www-community/attacks/Man-in-the-middle_attack), [Transport Layer Security](https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Security_Cheat_Sheet.html) (transport) - [x] [HTTP Strict Transport Security](https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Strict_Transport_Security_Cheat_Sheet.html) (transport) - [x] [Pinning](https://cheatsheetseries.owasp.org/cheatsheets/Pinning_Cheat_Sheet.html) (transport) --- ## 13. 서버 측 요청 위조(SSRF) - [x] [Server Side Request Forgery](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery), [Server-Side Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html) (network) --- ## 14. 경로 탐색(path traversal)과 파일 처리 - [x] [Path Traversal](https://owasp.org/www-community/attacks/Path_Traversal) (path) - [x] [Binary Planting](https://owasp.org/www-community/attacks/Binary_planting) (path) - [x] [Windows ::DATA Alternate Data Stream](https://owasp.org/www-community/attacks/Windows_DATA_alternate_data_stream) (path) - [x] [Embedding Null Code](https://owasp.org/www-community/attacks/Embedding_Null_Code) (path) - [x] [File Upload](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) (upload) --- ## 15. HTTP 프로토콜 악용(헤더, 캐싱, 분할) - [x] [HTTP Response Splitting](https://owasp.org/www-community/attacks/HTTP_Response_Splitting), [Cross-User Defacement](https://owasp.org/www-community/attacks/Cross-User_Defacement) (interpreter) - [x] [HTTP Security Response Headers](https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html) (browser, transport, http-request, access-control로 나눔) - [x] [Cache Poisoning](https://owasp.org/www-community/attacks/Cache_Poisoning) (interpreter) - [x] [IP Spoofing via HTTP Headers](https://owasp.org/www-community/attacks/ip_spoofing_via_http_headers) (http-request) --- ## 16. 인코딩과 콘텐츠 스푸핑 - [x] [Unicode Encoding](https://owasp.org/www-community/attacks/Unicode_Encoding) (interpreter) - [x] [Double Encoding](https://owasp.org/www-community/Double_Encoding) (interpreter) - [x] [Content Spoofing](https://owasp.org/www-community/attacks/Content_Spoofing) (browser) --- ## 17. CSV / 스프레드시트 인젝션 - [x] [CSV Injection](https://owasp.org/www-community/attacks/CSV_Injection) (csv) --- ## 18. CORS(교차 출처 리소스 공유) - [x] [CORS OriginHeaderScrutiny](https://owasp.org/www-community/attacks/CORS_OriginHeaderScrutiny) (http-request) - [x] [CORS RequestPreflightScrutiny](https://owasp.org/www-community/attacks/CORS_RequestPreflightScrutiny) (http-request) --- ## 19. 서비스 거부 - [x] [Regular expression Denial of Service (ReDoS)](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS) (regex) --- ## 20. 메모리 안전성과 네이티브 코드 - [x] [Buffer Overflow Attack](https://owasp.org/www-community/attacks/Buffer_overflow_attack), [Buffer Overflow via Environment Variables](https://owasp.org/www-community/attacks/Buffer_Overflow_via_Environment_Variables) (c-cpp) - [x] [Format string attack](https://owasp.org/www-community/attacks/Format_string_attack) (c-cpp) --- ## 21. 모바일 코드와 신뢰할 수 없는 코드 실행 - [x] [Mobile code invoking untrusted mobile code](https://owasp.org/www-community/attacks/Mobile_code_invoking_untrusted_mobile_code) (interpreter) - [x] [Mobile code non-final public field](https://owasp.org/www-community/attacks/Mobile_code_non-final_public_field) (java) - [x] [Mobile code object hijack](https://owasp.org/www-community/attacks/Mobile_code_object_hijack) (java) --- ## 22. 역직렬화 - [x] [Deserialization](https://cheatsheetseries.owasp.org/cheatsheets/Deserialization_Cheat_Sheet.html) (python, ruby, php, java, dotnet으로 나눔) --- ## 23. 악성 코드와 클라이언트 측 위협 - [x] [Man-in-the-browser attack](https://owasp.org/www-community/attacks/Man-in-the-browser_attack), [Browser Extension Security Vulnerabilities](https://cheatsheetseries.owasp.org/cheatsheets/Browser_Extension_Vulnerabilities_Cheat_Sheet.html) (browser) - [x] [Third Party JavaScript Management](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html) (browser) --- ## 24. 로깅, 부인(repudiation), 오류 처리 - [x] [Log Injection](https://owasp.org/www-community/attacks/Log_Injection), [Logging](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html), [Application Logging Vocabulary](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Vocabulary_Cheat_Sheet.html) (interpreter) - [x] [Repudiation Attack](https://owasp.org/www-community/attacks/Repudiation_Attack) (interpreter) --- ## 25. 비즈니스 로직과 기능 악용 비즈니스 로직과 기능 악용은 코드상의 공격 표면 하나로 좁혀지지 않으므로, 공격 표면별로 방어하는 전문 지식의 대상이 아닙니다. 방어는 애플리케이션에 맞춘 설계에 달려 있으며, 이는 프로젝트의 위협 모델링이 이끄는 것과 같은 추론입니다. "범위 밖"으로 옮겼습니다. --- ## 26. AI / LLM / 에이전트 보안 - [x] [Prompt Injection](https://owasp.org/www-community/attacks/prompt-injection), [LLM Prompt Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html) (llm) - [x] [MCP Tool Poisoning](https://owasp.org/www-community/attacks/MCP_Tool_Poisoning), [MCP (Model Context Protocol) Security](https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html) (llm) - [x] [HITL Dialog Forging (Lies-in-the-Loop)](https://owasp.org/www-community/attacks/lies-in-the-loop) (llm) - [x] [AI Agent Security](https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html), [Secure Coding with AI](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) (llm) - [x] [Retrieval-Augmented Generation (RAG) Security](https://cheatsheetseries.owasp.org/cheatsheets/RAG_Security_Cheat_Sheet.html) (llm) - [x] [Secure AI/ML Model Ops](https://cheatsheetseries.owasp.org/cheatsheets/Secure_AI_Model_Ops_Cheat_Sheet.html) (llm) - [x] [AML and Sanctions Compliance for AI Agent Payments](https://cheatsheetseries.owasp.org/cheatsheets/AML_Sanctions_AI_Agent_Payments_Cheat_Sheet.html) (llm) --- ## 27. 프로토타입 오염과 크로스 사이트 리크 - [x] [Prototype Pollution Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Prototype_Pollution_Prevention_Cheat_Sheet.html) (javascript) - [x] [Cross-site leaks (XS-Leaks)](https://cheatsheetseries.owasp.org/cheatsheets/XS_Leaks_Cheat_Sheet.html) (browser) --- ## 28. 프레임워크와 언어 플랫폼 - [x] [Django Security](https://cheatsheetseries.owasp.org/cheatsheets/Django_Security_Cheat_Sheet.html), [Django REST Framework](https://cheatsheetseries.owasp.org/cheatsheets/Django_REST_Framework_Cheat_Sheet.html) (python) - [x] [Ruby on Rails](https://cheatsheetseries.owasp.org/cheatsheets/Ruby_on_Rails_Cheat_Sheet.html) (ruby) - [x] [Laravel](https://cheatsheetseries.owasp.org/cheatsheets/Laravel_Cheat_Sheet.html) (php) - [x] [Symfony](https://cheatsheetseries.owasp.org/cheatsheets/Symfony_Cheat_Sheet.html) (php) - [x] [Java Security](https://cheatsheetseries.owasp.org/cheatsheets/Java_Security_Cheat_Sheet.html) (java) - [x] [DotNet Security](https://cheatsheetseries.owasp.org/cheatsheets/DotNet_Security_Cheat_Sheet.html) (dotnet) - [x] [NodeJS Security](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html) (javascript) - [x] [PHP Configuration](https://cheatsheetseries.owasp.org/cheatsheets/PHP_Configuration_Cheat_Sheet.html) (php) --- ## 29. 웹 프런트엔드와 브라우저 - [x] [HTML5 Security](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html) (browser) - [x] [AJAX Security](https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html) (browser) - [x] [Securing Cascading Style Sheets](https://cheatsheetseries.owasp.org/cheatsheets/Securing_Cascading_Style_Sheets_Cheat_Sheet.html) (access-control, browser로 나눔) --- ## 30. API와 서비스 - [x] [GraphQL](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html) (api-endpoint) - [x] [gRPC Security](https://cheatsheetseries.owasp.org/cheatsheets/gRPC_Security_Cheat_Sheet.html) (api-endpoint) - [x] [WebSocket Security](https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html) (api-endpoint) --- ## 31. 클라우드, 컨테이너, 인프라 컨테이너와 워크로드 설정은 개발자가 앱과 함께 배포하는, 코드로 관리하는 설정(`Dockerfile`, Compose, Pod의 `securityContext`)입니다. `harden` 단계가 수정하고 `verify` 단계가 증명하는 실제 공격 표면이므로 범위 안에 포함합니다. 클러스터 관리(RBAC, etcd, API 서버, 어드미션 제어, 네트워크 분할)는 운영자의 영역이므로 범위 밖에 둡니다. - [x] [Docker Security](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html), [Node.js Docker](https://cheatsheetseries.owasp.org/cheatsheets/NodeJS_Docker_Cheat_Sheet.html) (container) - [x] [Kubernetes Security](https://cheatsheetseries.owasp.org/cheatsheets/Kubernetes_Security_Cheat_Sheet.html) (container: 워크로드와 Pod 부분. 클러스터 관리는 범위 밖) - [x] [Serverless / FaaS Security](https://cheatsheetseries.owasp.org/cheatsheets/Serverless_FaaS_Security_Cheat_Sheet.html) (serverless) --- ## 32. 공급망과 CI/CD - [x] [NPM Security](https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html) (interpreter) - [x] [Dependency Graph & SBOM Best Practices](https://cheatsheetseries.owasp.org/cheatsheets/Dependency_Graph_SBOM_Cheat_Sheet.html), [Vulnerable Dependency Management](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html) (interpreter) --- ## 33. 시크릿과 설정 시크릿 관리는 볼트(vault), CI/CD, 클라우드 설정, 주기적 교체처럼 운영의 영역입니다. 코드 수준의 유일한 측면(소스 코드에 하드코딩된 시크릿)은 결정론적 스캔이 맡을 일이지, 위험을 다루는 전문 지식의 대상이 아닙니다. "범위 밖"으로 옮겼습니다. --- ## 34. 프로세스, 설계, 거버넌스 사용자 개인정보 보호는 정책과 설계의 문제(데이터 최소화, 투명성, 보존 기간)이며, 전문 지식이 방어하는 코드상의 공격 표면이 아닙니다. "범위 밖"으로 옮겼습니다. --- ## 35. 결제와 규정 준수 - [x] [Secure Integration of Third-Party Payment Gateways](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Payment_Gateway_Integration_Cheat_Sheet.html) (payment) --- ## 36. 임베디드 / IoT / 특수 분야 자동차와 드론 보안은 임베디드 시스템 영역(CAN 버스, OTA 펌웨어, 센서와 무선 신호의 무결성, 물리적 접근)으로, Lagune이 점검하는 웹이나 API 애플리케이션 소스 코드가 아닙니다. "범위 밖"으로 옮겼습니다. --- ## 범위 밖(코드상의 공격 표면 없음) 아래 항목은 전문 지식이 다루는 영역이 아니므로 체크박스가 없습니다. 거버넌스, 프로세스, 운영 측면의 보안 강화, 또는 프레임워크 사용법에 해당하며, 코드상의 공격 표면 하나로 좁혀지지 않아 공격 표면별로 방어하는 전문 지식의 대상이 되지 않습니다. 보안상의 가치는 분명하지만, 그 가치는 이 카탈로그가 제공하는 방어가 아니라 프로세스와 아키텍처(프레임워크라면 해당 언어 전용 스킬)에 있습니다. 작업 대상이 아니라 참고용으로 나열합니다. - [Authorization Regression Testing](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Regression_Testing_Cheat_Sheet.html), [Authorization Testing Automation](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Testing_Automation_Cheat_Sheet.html) - [JAAS](https://cheatsheetseries.owasp.org/cheatsheets/JAAS_Cheat_Sheet.html) - [Denial of Service](https://owasp.org/www-community/attacks/Denial_of_Service), [Denial of Service](https://cheatsheetseries.owasp.org/cheatsheets/Denial_of_Service_Cheat_Sheet.html) - [HTTP/2 Reset Attack](https://owasp.org/www-community/attacks/HTTP2_Reset_Attack) - [Traffic flood](https://owasp.org/www-community/attacks/Traffic_flood) - [Web Service Amplification Attack](https://owasp.org/www-community/attacks/web_service_amplificaiton) (SOAP/WS-Addressing 증폭 공격으로, 코드상의 공격 표면이 없는 운영 측면의 DoS 변형) - [Cash Overflow](https://owasp.org/www-community/attacks/Cash_Overflow) - [Spyware](https://owasp.org/www-community/attacks/Spyware), [Trojan Horse](https://owasp.org/www-community/attacks/Trojan_Horse) (최종 사용자를 노리는 악성 코드로, 감사 대상 프로젝트의 코드상의 공격 표면이 아님. 브라우저 안에서 전달되는 측면은 `browser` 전문 지식에서 다룸) - [REST Security](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html), [REST Assessment](https://cheatsheetseries.owasp.org/cheatsheets/REST_Assessment_Cheat_Sheet.html) - [Web Service Security](https://cheatsheetseries.owasp.org/cheatsheets/Web_Service_Security_Cheat_Sheet.html) - [Cloud Architecture Security](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Cloud_Architecture_Cheat_Sheet.html) (설계와 트레이드오프: IAM과 서명된 URL 중 선택, 퍼블릭 VPC와 프라이빗 VPC, 신뢰 경계, 공동 책임 모델. `container` 전문 지식과 달리, 전문 지식이 점검할 구체적인 설정이 없음) - [Infrastructure as Code Security](https://cheatsheetseries.owasp.org/cheatsheets/Infrastructure_as_Code_Security_Cheat_Sheet.html) (이름과 달리, IaC를 _관리하기_ 위한 SDLC 프로세스와 도구를 다룸: IDE 플러그인, 정적 분석, 이미지 스캔, CI/CD, 서명. Terraform이나 CloudFormation 파일에서 안전하지 않은 패턴을 안전한 형태로 바꾸는 방법은 제시하지 않음) - [Kubernetes Security](https://cheatsheetseries.owasp.org/cheatsheets/Kubernetes_Security_Cheat_Sheet.html) (_클러스터 관리 부분만 해당_: RBAC, etcd, API 서버, 어드미션 제어. 워크로드와 Pod 부분은 `container` 전문 지식에서 범위 안으로 다룸) - [Network Segmentation](https://cheatsheetseries.owasp.org/cheatsheets/Network_Segmentation_Cheat_Sheet.html) (네트워크 아키텍처와 방화벽 정책) - [Subdomain Takeover Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Subdomain_Takeover_Prevention_Cheat_Sheet.html) (DNS 수명 주기와 모니터링의 문제로, 코드가 아님) - [Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) (볼트, CI/CD, 주기적 교체. 하드코딩된 시크릿 측면은 결정론적 스캔이 맡을 일로, 위험을 다루는 전문 지식의 대상이 아님) - [C-Based Toolchain Hardening](https://cheatsheetseries.owasp.org/cheatsheets/C-Based_Toolchain_Hardening_Cheat_Sheet.html) (컴파일러, 링커, 빌드 플래그의 문제로, 소스 코드상의 싱크가 없음) - [Microservices Security](https://cheatsheetseries.owasp.org/cheatsheets/Microservices_Security_Cheat_Sheet.html), [Microservices based Security Arch Doc](https://cheatsheetseries.owasp.org/cheatsheets/Microservices_based_Security_Arch_Doc_Cheat_Sheet.html) - [Zero Trust Architecture](https://cheatsheetseries.owasp.org/cheatsheets/Zero_Trust_Architecture_Cheat_Sheet.html) - [CI/CD Security](https://cheatsheetseries.owasp.org/cheatsheets/CI_CD_Security_Cheat_Sheet.html), [GitHub Actions Security](https://cheatsheetseries.owasp.org/cheatsheets/GitHub_Actions_Security_Cheat_Sheet.html) - [Software Supply Chain Security](https://cheatsheetseries.owasp.org/cheatsheets/Software_Supply_Chain_Security_Cheat_Sheet.html) - [Error Handling](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html), [Full Path Disclosure](https://owasp.org/www-community/attacks/Full_Path_Disclosure) (기술 스택별 전역 오류 핸들러 설정. 이 유출은 오류 처리가 이미 다루는 정보 노출과 같은 문제) - [Abuse of Functionality](https://owasp.org/www-community/attacks/Abuse_of_Functionality), [Business Logic Security](https://cheatsheetseries.owasp.org/cheatsheets/Business_Logic_Security_Cheat_Sheet.html), [Abuse Case (_과거 문서_)](https://cheatsheetseries.owasp.org/cheatsheets/Abuse_Case_Cheat_Sheet.html) (애플리케이션에 맞춘 설계의 문제로, 단일한 코드상의 싱크가 없음) - [User Privacy Protection](https://cheatsheetseries.owasp.org/cheatsheets/User_Privacy_Protection_Cheat_Sheet.html) (데이터 최소화, 투명성, 보존 정책) - [Top 10 Automotive Security Vulnerabilities](https://cheatsheetseries.owasp.org/cheatsheets/Automotive_Security_Cheat_Sheet.html), [Drone Security](https://cheatsheetseries.owasp.org/cheatsheets/Drone_Security_Cheat_Sheet.html) (임베디드 시스템 영역: CAN 버스, OTA 펌웨어, 센서와 무선 신호의 무결성으로, 웹이나 API 소스 코드가 아님) - [Mobile Application Security](https://cheatsheetseries.owasp.org/cheatsheets/Mobile_Application_Security_Cheat_Sheet.html) (Android와 iOS 플랫폼 보안 강화: 스토리지, 생체 인증, 피닝, 개인 식별 정보(PII). 단일한 코드상의 공격 표면이 없으며, 신뢰할 수 없는 코드를 불러오는 측면은 `interpreter` 전문 지식으로 옮김) - [Threat Modeling](https://cheatsheetseries.owasp.org/cheatsheets/Threat_Modeling_Cheat_Sheet.html), [Threat Modeling (_커뮤니티 페이지_)](https://owasp.org/www-community/Threat_Modeling) - [Attack Surface Analysis](https://cheatsheetseries.owasp.org/cheatsheets/Attack_Surface_Analysis_Cheat_Sheet.html) - [Secure Product Design](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Product_Design_Cheat_Sheet.html) - [Secure Code Review](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Code_Review_Cheat_Sheet.html) - [Virtual Patching](https://cheatsheetseries.owasp.org/cheatsheets/Virtual_Patching_Cheat_Sheet.html) - [Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - [Legacy Application Management](https://cheatsheetseries.owasp.org/cheatsheets/Legacy_Application_Management_Cheat_Sheet.html) - [Security Terminology](https://cheatsheetseries.owasp.org/cheatsheets/Security_Terminology_Cheat_Sheet.html) --- # /lagune-repair: 깨진 발견 사항 추적 복구하기 > 파일 이름이 바뀌거나 파일이 이동해 Lagune의 추적이 꼬였을 때 체인을 복구합니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/repair 언어: ko-KR 원문: https://lagune.ai/docs/commands/repair 마지막 업데이트: 2026-11-03 🧰 파일 이름이 바뀌거나 파일이 이동해 체인이 꼬였을 때 복구합니다. **보안 단계가 아닌 내부 유지 관리** repair는 순서대로 진행되는 흐름의 여섯 번째 단계가 아닙니다. repair의 역할은 추적의 일관성을 유지하는 것입니다. ```prompt # 입력은 받지 않으며, 항상 체인 전체를 복구합니다 /lagune-repair ``` ## 작동 방식 detect 단계의 각 발견 사항은 하나의 추적 항목이며, plan, harden, verify 단계가 이를 이어받아 각자 처리하고 이름으로 다시 보고합니다. 이 이름은 모든 산출물에서 똑같은 섹션 제목으로 쓰이며, 처음부터 끝까지 그 항목의 식별자 역할을 합니다. 추적이 저장하는 정보 중 바뀔 수 있는 것은 항목이 가리키는 파일 경로뿐입니다. 이 경로는 다른 곳에는 저장되지 않으므로, 파일 이름이 바뀌거나 파일이 이동해도 연결이 끊기는 곳은 이곳 하나뿐이며, 서로 어긋난 두 사본이 생기는 일은 없습니다. 그런 일이 생기면 repair가 추적 맵(`.lagune/tracking.json`)을 바로잡아, 이름이 바뀌어도 항목의 식별자가 유지되게 합니다. repair는 산출물과 추적 맵을 읽고, 소스 코드는 이름이 바뀐 파일의 새 경로를 알아낼 때만 읽으며, 보안 관련 내용을 직접 작성하는 일은 없습니다. 같은 실행에서 모든 기록 산출물을 각 템플릿과 대조해 어긋난 부분을 보고하고, 각 부분을 바로잡을 단계를 알려 줍니다. **팁** - 코드도, 글로 된 산출물도 건드리지 않고 추적만 다룹니다. - 직접 실행할 일은 거의 없습니다. 체인이 일관되지 않다는 것을 알아챈 단계가 대신 repair를 실행하고 작업을 이어 갑니다. - repair가 관리하는 추적은 `.lagune/tracking.json` 파일에 있으며, 직접 편집할 일이 없는 내부 상태입니다. --- # Migrate: 매니페스트 기반 Lagune 프로젝트를 스킬과 플러그인으로 옮기기 > 매니페스트 기반 Lagune 프로젝트를 보안 원칙, 산출물, 추적, 직접 만든 전문 지식을 그대로 유지한 채 스킬 기반 Lagune으로 옮깁니다. 표준 URL: https://lagune.ai/ko-KR/docs/commands/migrate 언어: ko-KR 원문: https://lagune.ai/docs/commands/migrate 마지막 업데이트: 2026-11-03 🔀 매니페스트 기반 **Lagune** 프로젝트를 작성한 내용을 모두 유지한 채 스킬 기반 **Lagune**으로 옮깁니다. **지원 중단 안내** 매니페스트가 있는 프로젝트는 `v1.x` 버전까지 지금처럼 작동합니다. `npx lagune` 명령어가 `init`, `pull`, `update`, `add`, `remove`, `list` 명령어와 대시보드를 매니페스트 기반의 마지막 버전인 `lagune@0.15.0` 버전에 넘기기 때문입니다. ## 옮기기 1. 현재 작업이 커밋되어 있는지 확인한 뒤, 프로젝트 루트에서 migrate 명령어를 실행하세요. ```bash npx lagune migrate ``` 2. migrate 명령어가 바꾼 내용만 커밋해, 이번 이동을 검토하기 쉬운 하나의 변경으로 남기세요. 3. [설치 페이지](https://lagune.ai/ko-KR/docs)의 안내에 따라 사용하는 에이전트에 맞는 명령어를 설치하세요. 4. 프로젝트에 이미 detect, plan, harden 산출물이 있다면, [`/lagune-repair`](https://lagune.ai/ko-KR/docs/commands/repair) 명령어에 산출물과 직접 만든 전문 지식에 남아 있는 예전 참조를 현재 상태와 대조해 갱신해 달라고 요청하세요. ```prompt /lagune-repair `.lagune/memory/` 폴더 아래 산출물(`detect.md`, `plan.md`, `harden.md`)에 있는 적용된 전문 지식(예전 이름은 sub-skills)을 새 카탈로그에 나오는 이름과 대조해서 갱신해 줘. 그리고 `.lagune/catalog/` 폴더에 있는 내 전문 지식이 `.lagune/hooks/` 폴더의 예전 훅을 호출하는 부분을 모두 `lagune_read` 또는 `lagune_write` 도구 호출로 바꿔 줘. ``` ## 바뀌는 내용 | 이전 | 이후 | | -------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `.lagune/templates/`, `.lagune/hooks/`, `.lagune/specializations.md` | 삭제: 템플릿은 각 스킬에 들어 있고 훅은 엔진이 실행함 | | `.lagune/skills/` 폴더에 있는 내장 전문 지식 사본 | 삭제: 내장 전문 지식은 엔진이 제공함 | | `.lagune/skills/` 폴더에 있는 직접 만든 전문 지식 | `.lagune/catalog/` 폴더로 이동 | | `.lagune/skills.json` 파일(직접 만든 전문 지식의 색인) | `.lagune/configs.json` 파일에 병합 | | 매니페스트의 카테고리 | `.lagune/configs.json` 파일에 기록 | | `/lagune.detect` 같은 예전 에이전트 명령어 | 삭제: [**Lagune**을 설치하면](https://lagune.ai/ko-KR/docs) `/lagune-detect` 같은 새 명령어가 생김 | | `.gitignore` 파일의 **Lagune** 블록 | 삭제, 다른 내용이 없었다면 파일도 함께 삭제 | | 그 블록이 무시하던 `.lagune/proofs/` 폴더 | 자체 `.gitignore` 파일로 커밋에서 제외 | | `.lagune/manifest.json` | 마지막으로 삭제 | 보안 작업은 그대로 유지됩니다. 보안 원칙, 각 단계가 만든 산출물, 각 발견 사항이 가리키는 경로를 담은 추적 맵이 모두 남습니다. ## 자주 묻는 질문 ### 꼭 마이그레이션해야 하나요? 네. 매니페스트 기반 프로젝트는 지원 중단되었고 v1.x 버전까지만 작동하므로, npx lagune migrate 명령어를 실행해 옮기세요. ### migrate 명령어는 무엇을 유지하나요? 보안 원칙, 모든 단계의 산출물, 추적 맵, 카테고리, 직접 만든 전문 지식을 유지합니다. 전문 지식은 .lagune/catalog/ 폴더로 옮겨지고, 그 색인은 카테고리와 함께 .lagune/configs.json 파일에 들어갑니다. ### 새 명령어는 언제 설치하나요? migrate 명령어를 실행한 뒤, 설치 페이지에서 사용하는 에이전트에 맞는 방법으로 설치하세요. migrate 명령어는 새 /lagune 명령어를 남겨 두므로 먼저 설치해도 됩니다. ### 팀원이 이미 마이그레이션했다면 무엇을 실행해야 하나요? 마이그레이션된 변경 사항을 pull한 뒤 npx lagune migrate 명령어를 한 번 실행하세요. 매니페스트 기반 Lagune이 로컬 클론에 남긴 것(버전 관리에는 한 번도 포함되지 않았던 것)을 지우고, 증명 파일이 커밋되지 않게 합니다.