ContextualWisdomLab · seonghobae · Jun 29, 2026
diff --git a/.jules/sentinel.md b/.jules/sentinel.md
@@ -0,0 +1,4 @@
+## 2023-10-25 - XSS 및 URL 인코딩 취약점 수정 (Sentinel)
+**Vulnerability:** `html4tree`의 `process_dir` 로직에서 디렉토리 및 파일명을 이스케이프 및 인코딩 없이 직접 HTML의 링크와 타이틀, `href` 속성에 바인딩하여 XSS 공격 및 띄어쓰기가 있는 파일명 접근 에러(URL Path 깨짐)가 발생할 수 있었습니다.
+**Learning:** 단순한 `String` 이어붙이기 방식으로 HTML을 렌더링할 때는 사용자 입력이나 외부 상태(이 경우 파일 시스템 상의 파일 이름)에 의해 브라우저가 악의적인 스크립트를 파싱하게 될 위험성이 존재한다는 것을 이 코드베이스에서 확인할 수 있었습니다. 특히 Kotlin의 raw string literal(`"""`)을 사용할 때도 변수 삽입 부분은 철저히 필터링되어야 합니다.
+**Prevention:** `String.escapeHtml()`과 `String.encodeUrlPath()`라는 확장 함수를 만들어 HTML 엔티티 치환(특히 `<`, `>`, `&`, `"`, `'`)과 `java.net.URLEncoder.encode`를 결합하여 안전하게 출력하도록 수정했습니다. 나아가, 추후 유사한 HTML 템플릿 렌더링 시에는 파일명과 같이 통제 불가능한 문자열에 대해서는 항상 이스케이프 함수를 거치도록 해야 합니다.
diff --git a/build.gradle b/build.gradle
@@ -11,9 +11,19 @@ buildscript {
 
 apply plugin: 'kotlin'
 apply plugin: 'application'
+apply plugin: 'jacoco'
 
 mainClassName = 'html4tree.MainKt'
 
+jacocoTestReport {
+    reports {
+        xml.enabled false
+        csv.enabled false
+        html.enabled true
+    }
+}
+test.finalizedBy jacocoTestReport
+
 defaultTasks 'build'
 
 repositories {

diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
@@ -74,6 +74,18 @@ fun process_ignore_file(curr_dir: File): List<String> {
     return files_to_exclude
 }
 
+fun String.escapeHtml(): String {
+    return this.replace("&", "&amp;")
+               .replace("<", "&lt;")
+               .replace(">", "&gt;")
+               .replace("\"", "&quot;")
+               .replace("'", "&#x27;")
+}
+
+fun String.encodeUrlPath(): String {
+    return java.net.URLEncoder.encode(this, "UTF-8").replace("+", "%20")
+}
+
 fun process_dir(curr_dir: File){
 
     val exclude: List<String> = process_ignore_file(curr_dir)
@@ -86,14 +98,15 @@ fun process_dir(curr_dir: File){
               </style>
               """
 
+    val escapedDirName = curr_dir.getName().escapeHtml()
     val index_top = """<!doctype html>
 <html>
      <head>
-        <title>${curr_dir.getName()}</title>
+        <title>${escapedDirName}</title>
         ${css}
      </head>
      <body>
-       <h1>${curr_dir.getName()}</h1>
+       <h1>${escapedDirName}</h1>
        <ul>
           <li><a style="display:block; width:100%" href="./..">&#x21B0; ..</a></li>
 """ 
@@ -105,7 +118,12 @@ fun process_dir(curr_dir: File){
         dir_files.sortWith(compareBy ({it.name}) )
         dir_files.forEach {
            if((it.getName() !in exclude) && (it != curr_dir)) {
-              l += """          <li><a style="display:block; width:100%" href=${if (it.isDirectory()) { "./${it.getName()}/" } else { "./${it.getName()}" }}>${if (it.isDirectory()) { "&#128193;" } else { "&rtrif;" }} ${it.getName()}</a></li>"""+"\n"
+              val name = it.getName()
+              val escapedName = name.escapeHtml()
+              val encodedUrl = name.encodeUrlPath()
+              val href = if (it.isDirectory()) "./${encodedUrl}/" else "./${encodedUrl}"
+              val icon = if (it.isDirectory()) "&#128193;" else "&rtrif;"
+              l += """          <li><a style="display:block; width:100%" href="${href}">${icon} ${escapedName}</a></li>"""+"\n"
            }
         }
 

diff --git a/src/test/kotlin/html4tree/GoFailTest.kt b/src/test/kotlin/html4tree/GoFailTest.kt
@@ -0,0 +1,19 @@
+package html4tree
+
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+class GoFailTest {
+    @Test(expected = IllegalArgumentException::class)
+    fun testGoRequireDirNotExists() {
+        go("not_exists_dir", 0)
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun testGoRequireDirNotDirectory() {
+        val f = File.createTempFile("temp", "txt")
+        f.deleteOnExit()
+        go(f.absolutePath, 0)
+    }
+}
diff --git a/src/test/kotlin/html4tree/Html4treeTest.kt b/src/test/kotlin/html4tree/Html4treeTest.kt
@@ -0,0 +1,125 @@
+package html4tree
+
+import org.junit.Test
+import org.junit.Assert.*
+import java.io.File
+import java.nio.file.Files
+
+class Html4treeTest {
+
+    @Test
+    fun testEscapeHtml() {
+        val input = """<script>alert("XSS" & 'hack')</script>"""
+        val expected = """&lt;script&gt;alert(&quot;XSS&quot; &amp; &#x27;hack&#x27;)&lt;/script&gt;"""
+        assertEquals(expected, input.escapeHtml())
+    }
+
+    @Test
+    fun testEncodeUrlPath() {
+        val input = "file name with spaces.txt"
+        val expected = "file%20name%20with%20spaces.txt"
+        assertEquals(expected, input.encodeUrlPath())
+
+        val input2 = """<script>"""
+        val expected2 = "%3Cscript%3E"
+        assertEquals(expected2, input2.encodeUrlPath())
+    }
+
+    @Test
+    fun testProcessDirGeneratesSafeHtml() {
+        val tempDir = Files.createTempDirectory("html4tree_test").toFile()
+        tempDir.deleteOnExit()
+
+        val badDirName = """<img src=x onerror=alert(1)>"""
+        val badDir = File(tempDir, badDirName)
+        badDir.mkdir()
+        badDir.deleteOnExit()
+
+        val badFileName = "file name.txt"
+        val badFile = File(tempDir, badFileName)
+        badFile.createNewFile()
+        badFile.deleteOnExit()
+
+        process_dir(tempDir)
+
+        val indexFile = File(tempDir, "index.html")
+        assertTrue(indexFile.exists())
+        indexFile.deleteOnExit()
+
+        val content = indexFile.readText()
+
+        // title, h1 escape
+        assertTrue(content.contains("<title>${tempDir.name.escapeHtml()}</title>"))
+        assertTrue(content.contains("<h1>${tempDir.name.escapeHtml()}</h1>"))
+
+        // child dir escape and encode
+        assertTrue(content.contains("""href="./%3Cimg%20src%3Dx%20onerror%3Dalert%281%29%3E/""""))
+        assertTrue(content.contains("""&lt;img src=x onerror=alert(1)&gt;"""))
+
+        // child file escape and encode
+        assertTrue(content.contains("""href="./file%20name.txt""""))
+        assertTrue(content.contains("""file name.txt"""))
+    }
+
+    @Test
+    fun testGoMaxLevel() {
+        val tempDir = Files.createTempDirectory("html4tree_test_go").toFile()
+        tempDir.deleteOnExit()
+
+        val subDir = File(tempDir, "subdir")
+        subDir.mkdir()
+        subDir.deleteOnExit()
+
+        val subSubDir = File(subDir, "subsubdir")
+        subSubDir.mkdir()
+        subSubDir.deleteOnExit()
+
+        // maxLevel 0
+        go(tempDir.absolutePath, 0)
+        assertTrue(File(tempDir, "index.html").exists())
+        assertFalse(File(subDir, "index.html").exists())
+        assertFalse(File(subSubDir, "index.html").exists())
+
+        File(tempDir, "index.html").delete()
+
+        // maxLevel 1
+        go(tempDir.absolutePath, 1)
+        assertTrue(File(tempDir, "index.html").exists())
+        assertTrue(File(subDir, "index.html").exists())
+        assertFalse(File(subSubDir, "index.html").exists())
+    }
+
+    @Test
+    fun testProcessIgnoreFile() {
+        val tempDir = Files.createTempDirectory("html4tree_test_ignore").toFile()
+        tempDir.deleteOnExit()
+
+        val ignoreFile = File(tempDir, ".html4ignore")
+        ignoreFile.writeText(".*\\.txt\nsecret\\.dat")
+        ignoreFile.deleteOnExit()
+
+        val txtFile = File(tempDir, "a.txt")
+        txtFile.createNewFile()
+        txtFile.deleteOnExit()
+
+        val secretFile = File(tempDir, "secret.dat")
+        secretFile.createNewFile()
+        secretFile.deleteOnExit()
+
+        val normalFile = File(tempDir, "b.png")
+        normalFile.createNewFile()
+        normalFile.deleteOnExit()
+
+        val excludeList = process_ignore_file(tempDir)
+
+        assertTrue(excludeList.contains("a.txt"))
+        assertTrue(excludeList.contains("secret.dat"))
+        assertTrue(excludeList.contains("index.html"))
+        assertFalse(excludeList.contains("b.png"))
+    }
+
+    @Test
+    fun testHelp() {
+        help()
+    }
+}
diff --git a/src/test/kotlin/html4tree/LinkedListPullNullTest.kt b/src/test/kotlin/html4tree/LinkedListPullNullTest.kt
@@ -0,0 +1,16 @@
+package html4tree
+
+import org.junit.Test
+import java.io.File
+
+class LinkedListPullNullTest {
+    @Test
+    fun testGoNotDir() {
+        val f = File.createTempFile("temp", "txt")
+        f.deleteOnExit()
+        val ll = LinkedList()
+        ll.push(LinkedListEntry(f, 0))
+        val lle = ll.pull()
+        assert(lle != null && !lle.file.isDirectory())
+    }
+}
diff --git a/src/test/kotlin/html4tree/LinkedListTest.kt b/src/test/kotlin/html4tree/LinkedListTest.kt
@@ -0,0 +1,19 @@
+package html4tree
+
+import org.junit.Test
+import org.junit.Assert.*
+import java.io.File
+
+class LinkedListTest {
+    @Test
+    fun testGettersAndSetters() {
+        val ll = LinkedList()
+        val e1 = Entry(File("test"), 0, null)
+        ll.first = e1
+        assertEquals(e1, ll.first)
+
+        val e2 = Entry(File("test2"), 1, null)
+        ll.last = e2
+        assertEquals(e2, ll.last)
+    }
+}
diff --git a/src/test/kotlin/html4tree/MainKtEdgeTest.kt b/src/test/kotlin/html4tree/MainKtEdgeTest.kt
@@ -0,0 +1,24 @@
+package html4tree
+
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+class MainKtEdgeTest {
+    @Test
+    fun testProcessDirSelfDirExclusion() {
+        val tempDir = Files.createTempDirectory("html4tree_test_self").toFile()
+        tempDir.deleteOnExit()
+
+        val ignoreFile = File(tempDir, ".html4ignore")
+        ignoreFile.writeText(".*")
+
+        val f1 = File(tempDir, "test.txt")
+        f1.createNewFile()
+
+        process_dir(tempDir)
+
+        val content = File(tempDir, "index.html").readText()
+        assert(!content.contains("test.txt"))
+    }
+}
diff --git a/src/test/kotlin/html4tree/MainKtTest.kt b/src/test/kotlin/html4tree/MainKtTest.kt
@@ -0,0 +1,18 @@
+package html4tree
+
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+class MainKtTest {
+    @Test
+    fun testMain() {
+        val tempDir = Files.createTempDirectory("html4tree_test_main").toFile()
+        tempDir.deleteOnExit()
+        val args = arrayOf(tempDir.absolutePath)
+        main(args)
+
+        val indexFile = File(tempDir, "index.html")
+        assert(indexFile.exists())
+    }
+}
diff --git a/src/test/kotlin/html4tree/UtilTest.kt b/src/test/kotlin/html4tree/UtilTest.kt
@@ -0,0 +1,38 @@
+package html4tree
+
+import org.junit.Test
+import org.junit.Assert.*
+import java.io.File
+
+class UtilTest {
+    @Test
+    fun testLinkedList() {
+        val ll = LinkedList()
+
+        val f1 = File("f1")
+        val f2 = File("f2")
+        val f3 = File("f3")
+
+        ll.push(LinkedListEntry(f1, 1))
+        ll.push(LinkedListEntry(f2, 2))
+        ll.push(LinkedListEntry(f3, 3))
+
+        val p1 = ll.pull()
+        assertNotNull(p1)
+        assertEquals(f1, p1?.file)
+        assertEquals(1, p1?.level)
+
+        val p2 = ll.pull()
+        assertNotNull(p2)
+        assertEquals(f2, p2?.file)
+        assertEquals(2, p2?.level)
+
+        val p3 = ll.pull()
+        assertNotNull(p3)
+        assertEquals(f3, p3?.file)
+        assertEquals(3, p3?.level)
+
+        val p4 = ll.pull()
+        assertNull(p4)
+    }
+}