개발자를 위한 보안 문서를 쓰고 검토하기

## 개발자가 바로 쓸 수 있는 조언을 보안 주제에 맞춰 쓰기 보안 전문가가 아니라 개발자를 위해 작성한다. 지침은 정확하고 실용적이며 간결해야 하고 분명한 입장을 제시해야 한다. 이론적으로는 최선이지만 따르기에는 너무 복잡한 조언보다 개발자가 적용할 수 있는 좋은 조언을 우선한다. 모든 권고 사항을 문서의 보안 위협 모델 범위 안에 둔다. 일반적인 코드 품질, 성능, 아키텍처 조언은 보안 위험을 직접 통제하는 경우가 아니라면 다른 곳에서 다룬다. 모든 작성 도구가 기여 규칙을 필수로 따르게 한다. 저장소의 공식적인 사람 중심 절차와 작성 지침을 보존하고, 더 짧은 에이전트 지침은 운영 요약으로만 사용한다. ## 인용한 출처를 모두 읽고 주장을 뒷받침하는지 확인하기 인용하는 모든 출처를 가져와 읽은 뒤, 해당 출처가 정확한 주장을 뒷받침하는지 확인한다. URL을 만들거나 추측해서는 안 되고, 관련 없는 방문 페이지로 이동되는 페이지를 인용해서도 안 되며, 학습 과정의 기억이나 요약에 의존해서도 안 된다. 근거가 담긴 구체적인 페이지나 절로 연결한다. 내부 교차 링크는 사용하기 전에 검증한다. 존재하지 않는 문서나 앵커를 가리켜서는 안 된다. 인용 밀도 검증이 적용되면 새 H2 절마다 인라인 HTTPS 인용을 적어도 하나 포함한다. 새롭거나, 뜻밖이거나, 특정 매개변수에 관한 것이거나, 이견이 있을 수 있는 주장에는 각각 별도의 근거를 제시한다. 이미 확립된 일반적인 관행은 모든 문장에 인용을 붙일 필요가 없다. 출처는 본문에 직접 넣거나 참고문헌 절에 모을 수 있다. 표준, 정부 또는 업계의 보안 지침, 프로젝트와 공급업체의 공식 문서, 잘 관리되는 플랫폼 참고 자료, 기준이 되는 소스 저장소, 동료 심사를 거친 연구를 우선한다. 검색 노출만을 노린 마케팅 콘텐츠 농장은 피한다. 인용 검증은 최저 기준일 뿐이며 내용의 정확성을 증명하지 않는다. ## 위협마다 대책을 쓰고 막지 못하는 것도 밝히기 인용은 필요하지만 그것만으로 충분하지 않다. 모든 위협에 구체적인 대응책을 연결하고, 그 통제 수단이 무엇을 방어하고 무엇을 방어하지 못하는지 명시한다. 명확한 단서 없이 명시된 위협 모델 밖의 공격을 도입해서는 안 된다. 한 계층을 위한 통제 수단을 다른 계층의 침해까지 방어하는 수단으로 제시해서는 안 된다. 실제로 보안 통제 또는 보안 위험에 해당하는 지침만 추가한다. 정확성, 개발자 관점의 실용성, 주제 관련성을 각각 독립적으로 검토한다. 인용이 충분하더라도 잘못된 권고 사항은 반드시 거부해야 한다. ## 변경은 작게 유지하고 같은 내용은 복사 대신 링크하기 한 번의 변경은 단일 지침 문서 또는 작고 명확하게 조율된 문서 집합으로 제한한다. 저장소가 해당 한도를 명시한 경우, 승인된 추적 이슈가 없다면 콘텐츠 문서 3개 또는 순증 1,500줄을 초과해서는 안 된다. 종속성, 자동화, 오타만 수정하는 변경에는 각각의 범위 규칙을 적용한다. 기본 브랜치를 바탕으로 한 깨끗한 브랜치에서 시작하고, 브랜치 하나당 주제 하나만 다룬다. 관련 없는 변경 사항이 서로 섞일 수 있으므로 동일한 브랜치에서 변경 요청 두 건을 열어서는 안 된다. 새 지침 문서나 대폭 다시 작성한 지침 문서를 제안하기 전에 승인된 이슈를 필수로 요구한다. 곁다리 서식 변경, 대량 편집, 관련 없는 수정 사항을 함께 묶지 않는다. 절을 추가하기 전에 현재 문서, 관련 문서, 저장소 색인을 검색한다. 기존 지침을 되풀이하지 말고 링크로 연결한다. 의도적으로 구성된 허브 앤드 스포크형 문서 묶음을 유지한다. 조율된 교차 링크는 유효하지만 다른 문서의 지침을 복사하는 것은 유효하지 않다. 내용이 다른 주제에 속한다면 현재 범위를 억지로 늘리지 말고 적절한 기존 문서나 새 문서로 옮긴다. ## 설계를 먼저 설명하고 코드는 주제에 필요할 때만 쓰기 일반적인 주제에서는 언어별 코드보다 아키텍처 패턴, 설계 원칙, 보안 의사 결정을 우선한다. 코드는 빠르게 낡으며, 원래 맥락 없이 복사된 개별 코드 조각은 안전하지 않을 수 있다. 주제가 본질적으로 특정 언어, 인젝션, 매개변수화 또는 구체적인 강화 조치에 관한 것이라면 코드를 충분히 사용한다. 실행 가능한 세부 내용 자체가 보안 지침이고 부수적인 상용구 코드가 아니라면 코드 비중이 높아도 적절하다. 예시 코드는 짧게 유지하고, 가능하면 울타리형 코드 블록에 언어를 표시한다. 해당 기준에 따라 설계하고 검토하지 않은 예시를 운영 환경에 바로 사용할 수 있는 것으로 제시해서는 안 된다. ## 내용 없는 서두를 빼고 한 가지 방법을 분명히 권하기 일반적인 서문, 반복되는 배경 설명, 모든 선택지를 나열한 목록, 유행을 따르지만 내용은 빈약한 도입부는 덜어낸다. 구체적인 접근법을 권고하고, 개발자가 이를 안전하게 적용하는 데 필요한 맥락만 설명한다. 미국식 영어를 사용하고, 맞춤법과 용어 검사를 실행하며, 비원어민 독자도 이해할 수 있는 문장을 쓴다. 명확하지 않은 두문자어는 처음 사용할 때 정의하되, 작성 지침이 허용한다면 누구나 아는 프로토콜 및 로케이터 약어는 설명하지 않아도 된다. 일반적인 자동 생성 문장처럼 보이는 부분은 다시 작성하거나 제외한다. 간결하게 만들더라도 제약, 예외, 위협 경계 또는 어떤 권고가 더 안전한 이유를 없애서는 안 된다. ## 저장소의 Markdown과 이미지 규칙 따르기 Markdown을 사용하고, `details`와 `summary`처럼 명시적으로 허용된 요소를 제외한 원시 HTML은 피한다. 하이픈 글머리 기호, Markdown 굵은 글씨, 인용 블록을 일관되게 사용한다. 모든 제목 뒤에 빈 줄을 둔다. 일반적인 문서는 H1 하나와 소개로 시작하고, 초점이 분명한 H2 절로 이어지며, 참고문헌으로 끝날 수 있다. H2 절 3~6개는 유용한 기본값이지 엄격한 최대 한도가 아니다. 게시 도구가 목차를 생성한다면 수동 목차를 추가하지 않는다. 저장소의 파일 이름 규약을 따른다. 문자, 숫자, 하이픈, 밑줄만 사용하고 `_Cheat_Sheet.md`와 같은 필수 접미사는 유지한다. 새 문서는 승인된 서식에서 시작한다. 자산을 지정된 자산 디렉터리에 저장한다. 승인된 이미지 형식을 사용하고, 의미 있는 대체 텍스트를 제공하며, 올바른 상대 경로로 자산을 참조한다. 링크는 내용을 설명하는 레이블과 함께 인라인으로 작성하고 가능한 경우 HTTPS를 사용한다. ## 검토를 요청하기 전에 린트와 링크 검사 실행하기 변경을 제안하기 전에 저장소에서 정한 Markdown 린트, 용어 검사, 링크 검사기를 실행한다. 변경한 콘텐츠에 적용되는 범위, 인용 밀도, 기타 정책 검증도 실행한다. 로컬 또는 지속적 통합 검사 실패는 검증을 우회할 이유가 아니라 조사해야 할 결함으로 취급한다. 생성되거나 자동화된 변경이 관련 없는 편집을 숨기지 않도록 최종 차이를 검토한다. 자동화의 한계를 이해한다. 기계적 검사는 잘못된 Markdown, 허용되지 않은 용어, 끊어진 링크, 과도한 범위, 누락된 인용 패턴을 감지할 수 있지만 출처가 주장을 뒷받침하는지, 조언이 정확한지, 주제가 문서에 속하는지, 내용이 기존 지침과 중복되는지는 판단할 수 없다. ## AI 사용 사실을 밝히고 여러 관점에서 검토하기 변경 요청 설명에 실질적인 AI 지원 사용을 공개한다. 저장소에서 지정한 공개 절에 도구 이름, 알려진 버전, 입력 지시문을 기록한다. 이 요구 사항은 모든 AI 도구에 적용되며, 공개하지 않으면 기여가 무효가 될 수 있다. 보안 지침을 서로 다른 차원에서 검토한다. 보안 정확성, 개발자 관점의 실용성, 출처와 링크의 품질, 중복과 배치, 언어 품질을 각각 살핀다. 전문 검토자는 독립적으로 작업할 수 있지만, 각자의 발견 사항은 근거에 기반한 하나의 판정으로 통합해야 한다. 수락, 변경 요청, 종료처럼 명시적인 결과를 사용한다. 승인을 막는 발견 사항에는 구체적인 근거를 인용하고, 기계적 실패와 판단 실패를 구분하며, 인용이나 자동 검사가 있다는 이유만으로 승인해서는 안 된다.