🛡️ Sentinel: [MEDIUM] 원자적 파일 교체(Atomic Move) 및 폴백 처리 적용

.jules/sentinel.md

@@ -63,23 +63,28 @@
 **Learning:** 큐에 넣기 전(`listFiles`)에 한 번 검사했다고 해서, 큐에서 빼내어 처리(`process_dir`)하는 시점에도 파일 시스템 상태가 동일할 것이라고 가정(Implicit Trust)하면 안 됩니다.
 **Prevention:** 큐에 넣는 시점(`Time-of-Check`)에 파일의 고유 식별자(`BasicFileAttributes.fileKey()`)를 캡처해두고, 큐에서 꺼내어 실제로 처리하는 시점(`Time-of-Use`)에 현재 파일의 `fileKey()`를 다시 읽어 두 값이 일치하는지 재검증(Re-verify)해야 합니다.
 
-## 2024-05-25 - Information Exposure via Default Inclusion and Referrer
-**Vulnerability:** Common sensitive files (like `.aws`, `.kube`, `.npmrc`) could be accidentally indexed if present in the tree. Furthermore, clicking on external links (if any were added) could leak the directory structure via the HTTP Referer header.
-**Learning:** Default exclude lists must encompass modern toolchains and cloud credentials, as users often run directory indexers in their home or project root directories. HTML templates need explicit policies to prevent accidental data leakage via headers.
-**Prevention:** Maintain an extensive default deny-list for known sensitive files and enforce `no-referrer` globally on generated index pages.
+## 2024-05-25 - 기본 포함 및 Referrer를 통한 정보 노출 (Information Exposure)
+**Vulnerability:** `.aws`, `.kube`, `.npmrc` 같은 민감한 파일들이 트리에 존재할 경우 실수로 인덱싱될 수 있었습니다. 더불어 추가된 외부 링크를 클릭할 때 HTTP Referer 헤더를 통해 디렉토리 구조가 유출될 위험이 있었습니다.
+**Learning:** 사용자들이 종종 홈 디렉토리나 프로젝트 루트에서 디렉토리 인덱서를 실행하므로, 최신 도구 체인 및 클라우드 자격 증명을 포괄하는 기본 제외 목록이 필수적입니다. HTML 템플릿에는 헤더를 통한 우발적 데이터 유출을 방지하기 위한 명시적 정책이 필요합니다.
+**Prevention:** 널리 알려진 민감한 파일들에 대한 광범위한 기본 거부(deny-list) 목록을 유지하고, 생성된 인덱스 페이지에서 전역적으로 `no-referrer`를 강제하십시오.
 
-## 2024-07-07 - [Sensitive Data Exposure in Directory Indexing]
-**Vulnerability:** The application was traversing and listing hidden files and directories (those starting with `.`), potentially exposing sensitive information like `.git` histories or `.env` configuration files in the generated HTML index.
-**Learning:** This existed because the traversal and filtering logic did not explicitly account for standard conventions regarding hidden files, defaulting to listing everything not explicitly ignored.
-**Prevention:** Always implement explicit filters for hidden files and directories (e.g., `!file.name.startsWith(".")`) in applications that generate static files or expose directory structures to the public.
+## 2024-07-07 - [디렉토리 인덱싱 중 민감한 데이터 노출]
+**Vulnerability:** 애플리케이션이 숨김 파일 및 디렉토리(`. `로 시작하는 항목)를 순회하고 나열하여, 생성된 HTML 인덱스에서 `.git` 히스토리나 `.env` 구성 파일 같은 민감한 정보를 노출할 잠재적 위험이 있었습니다.
+**Learning:** 명시적으로 무시되지 않은 모든 것을 나열하는 기본 동작 때문에, 순회 및 필터링 로직이 숨김 파일에 대한 일반적인 규칙을 제대로 고려하지 않아 발생한 문제입니다.
+**Prevention:** 정적 파일을 생성하거나 디렉토리 구조를 대중에게 노출하는 애플리케이션에서는 항상 숨김 파일 및 디렉토리에 대한 명시적인 필터(예: `!file.name.startsWith(".")`)를 구현하십시오.
 
 
-## 2024-05-18 - Prevent Sensitive Information Disclosure
-**Vulnerability:** The application lists all files in a directory, including hidden files (those starting with `.`), which could inadvertently expose sensitive information like `.env`, `.git`, or `.ssh` directories.
-**Learning:** Default directory listing implementations without hidden file filtering can lead to information disclosure vulnerabilities when serving directories containing configuration or sensitive files.
-**Prevention:** Automatically exclude hidden files (files starting with `.`) from the generated directory listing by default.
+## 2024-05-18 - 민감한 정보 노출 방지
+**Vulnerability:** 애플리케이션이 디렉토리 내의 모든 파일(숨김 파일 포함)을 나열하여 `.env`, `.git` 또는 `.ssh` 디렉토리와 같은 민감한 정보를 실수로 노출할 수 있었습니다.
+**Learning:** 숨김 파일 필터링이 없는 기본 디렉토리 나열 구현은, 구성 파일이나 민감한 파일이 포함된 디렉토리를 서비스할 때 정보 노출 취약점으로 이어질 수 있습니다.
+**Prevention:** 생성된 디렉토리 목록에서 숨김 파일(`. `로 시작하는 파일)을 기본적으로 자동 제외하십시오.
 
 ## 2024-07-13 - [MEDIUM] 정적 리소스용 CSP 생성 방식(Nonce 대신 해시) 관련 보안 강화
 **Vulnerability:** 정적 HTML 생성 도구에서 매번 다른 Nonce를 동적으로 생성하여 CSP에 적용하는 것은, 캐싱 효율을 저하시킬 뿐만 아니라 정적 배포 환경(예: GitHub Pages 등)에서 올바른 보안 정책 수립을 방해할 수 있는 안티 패턴입니다.
 **Learning:** 정적으로 고정된 인라인 스타일이나 스크립트에는 난수화된 Nonce보다 콘텐츠 자체의 해시(SHA-256 등)를 사용하는 것이 안전하고 일관된 방식임을 배웠습니다.
 **Prevention:** 자동 생성되는 정적 HTML의 콘텐츠 보안 정책(CSP)에는 `style-src 'sha256-<HASH>'` 방식을 적용하고, `<style>` 태그에서 불필요한 `nonce` 속성을 제거하여 브라우저의 무결성 검증 기능을 적극 활용하십시오.
+
+## 2024-07-14 - [MEDIUM] 원자적 파일 교체(Atomic Move) 폴백 구현
+**Vulnerability:** 정적 HTML 인덱스를 생성하고 기존 파일을 교체(`Files.move`)하는 과정에서 `ATOMIC_MOVE` 옵션 부재로 인해, 동시 읽기나 시스템 문제 발생 시 Race Condition 또는 불완전한 파일 쓰기가 발생할 수 있었습니다.
+**Learning:** 파일 시스템 조작 시 강력한 원자성(Atomicity)을 보장하기 위해서는 `StandardCopyOption.ATOMIC_MOVE`를 사용해야 하지만, 일부 파일 시스템이나 환경에서는 이 옵션을 지원하지 않아 `AtomicMoveNotSupportedException`을 발생시킵니다.
+**Prevention:** `Files.move`를 사용할 때 `ATOMIC_MOVE` 옵션을 우선 시도하되, `AtomicMoveNotSupportedException`이 발생할 경우 `StandardCopyOption.REPLACE_EXISTING`으로 정상적으로 Fallback(우아한 실패) 할 수 있도록 방어적인 예외 처리를 구현하십시오.

src/main/kotlin/html4tree/main.kt

@@ -229,12 +229,20 @@ fun process_ignore_file(curr_dir: File, dirFilesNames: Array<String>? = null): S
     return files_to_exclude
 }
 
-fun write_index_file(curr_dir: File, content: String) {
+fun write_index_file(
+    curr_dir: File,
+    content: String,
+    moveFile: (java.nio.file.Path, java.nio.file.Path, Array<out java.nio.file.CopyOption>) -> java.nio.file.Path = Files::move
+) {
     val indexPath = curr_dir.toPath().resolve("index.html")
     val tempPath = Files.createTempFile(curr_dir.toPath(), ".index-", ".html")
     try {
         Files.write(tempPath, content.toByteArray(Charsets.UTF_8))
-        Files.move(tempPath, indexPath, StandardCopyOption.REPLACE_EXISTING)
+        try {
+            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING))
+        } catch (e: java.nio.file.AtomicMoveNotSupportedException) {
+            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.REPLACE_EXISTING))
+        }
     } finally {
         Files.deleteIfExists(tempPath)
     }

src/test/kotlin/html4tree/MainTest.kt

@@ -29,6 +29,22 @@ class MainTest {
         }
     }
 
+    @Test
+    fun testWriteIndexFileAtomicMoveFallback() {
+        var fallbackCalled = false
+        write_index_file(tempDir, "content") { source, target, options ->
+            if (options.contains(java.nio.file.StandardCopyOption.ATOMIC_MOVE)) {
+                throw java.nio.file.AtomicMoveNotSupportedException(source.toString(), target.toString(), "Mocked exception")
+            }
+            fallbackCalled = true
+            java.nio.file.Files.move(source, target, *options)
+        }
+        assertTrue(fallbackCalled, "Fallback to REPLACE_EXISTING should be called")
+        val indexFile = File(tempDir, "index.html")
+        assertTrue(indexFile.exists())
+        assertEquals("content", indexFile.readText())
+    }
+
     @Test
     fun testEscapeHtml() {
         assertEquals("&", "&".escapeHtml())