
OWASP Java Encoder는 Java 1.5+에서 사용할 수 있는, 사용하기 쉬운 드롭인 고성능 인코더 클래스로, 의존성이 없고 부담이 적습니다. 이 프로젝트는 Java 웹 개발자가 크로스 사이트 스크립팅(XSS)으로부터 시스템을 방어할 수 있도록 도와줍니다!
Java 8+를 위한 컨텍스트 기반 출력 인코딩. 신뢰할 수 없는 텍스트를 수신하는 파서 컨텍스트(HTML, JavaScript, CSS, XML 또는 URL 구성 요소)에 맞는 인코더를 선택하십시오. 코어에는 런타임 의존성이 없으며, 선택적인 JSP 및 Jakarta 어댑터가 뷰 계층 바인딩을 제공합니다. 인코딩은 안전한 템플릿, URL 검증 및 기타 애플리케이션 제어와 함께 [XSS 방지][xss]의 한 부분입니다.
1.6.0은 Maven Central에서 사용할 수 있습니다. 이 마이너 릴리스는 신뢰할 수 있는 프래그먼트 전반에서 인식된 HTML 토큰 보호를 유지하면서 불필요한 JavaScript 문자 이스케이프를 줄입니다. 인코딩된 바이트와 스트리밍 동작이 변경됩니다. 릴리스 노트 및 게시 검증을 참조하십시오.
1.5.0에서 도입된 파서 경계 보안 수정 사항은 여전히 유효하며, 1.4.1까지의 버전에는 해당 수정 사항이 포함되어 있지 않습니다. 보안 권고 및 VERIFYING.md를 참조하십시오.
필요한 의존성을 선택하십시오.
지원되는 세 가지 아티팩트는 그룹 ID org.owasp.encoder를 사용합니다:
| 아티팩트 ID | 용도 및 런타임 의존성 |
|---|---|
encoder | 코어 String/Writer API; 런타임 의존성 없음 |
encoder-jsp | 레거시 javax JSP 태그/EL 함수; 코어 및 컨테이너 제공 JSP API |
encoder-jakarta-jsp | Jakarta JSP 태그/EL 함수; 코어 및 컨테이너 제공 Jakarta JSP API |
<dependency>
<groupId>org.owasp.encoder</groupId>
<artifactId>encoder</artifactId>
<version>1.6.0</version>
</dependency>
필요한 경우 encoder를 태그 어댑터 아티팩트 ID 중 하나로 교체하세요. 각 어댑터는 core를 함께 가져옵니다. 별도로 관리되는 core/어댑터 버전을 일치된 상태로 유지하세요. javax 또는 Jakarta taglib JAR 중 하나만 사용하세요. 이들은 org.owasp.encoder.tag를 공유하므로 동일한 클래스패스나 모듈 경로에 함께 존재해서는 안 됩니다. 런타임 매트릭스와 의존성/라이선스 인벤토리를 참조하세요.
encoder-esapi는 1.4.1 이후 폐기되었으며 1.5.x 또는 1.6.0에는 포함되거나 지원되지 않습니다. 이를 사용하는 애플리케이션은 어댑터에서 마이그레이션해야 합니다.
게시된 1.6.0 API 문서(호스팅 인덱싱은 게시 시점보다 늦을 수 있음): core, javax JSP 및 Jakarta JSP.
import org.owasp.encoder.Encode;
out.write("<p>");
Encode.forHtmlContent(out, userText); // Writer overload; no intermediate String
out.write("</p>");
동등한 String 호출은 Encode.forHtmlContent(userText)입니다. 호출자는 신뢰할 수 있는 주변 구문과 속성 따옴표를 제공합니다. 원시 데이터는 출력 경계에서 한 번만 인코딩하세요. 템플릿 엔진이 이미 수행하는 이스케이프도 고려해야 합니다.
| 대상 | API 및 제한 사항 |
|---|---|
| textarea 콘텐츠를 포함한 HTML 텍스트 | forHtmlContent; forHtml은 따옴표로 묶인 일반 텍스트 속성도 처리합니다 |
| 따옴표로 묶인 HTML 텍스트 속성 | forHtmlAttribute; 이벤트 핸들러 표현식이나 URL 검증기가 아닙니다 |
| 하나의 원시 URL 구성 요소 | forUriComponent; 신뢰할 수 있는 구분자로 조립하고, URL을 검증한 다음, 이를 감싸는 HTML 속성에 맞게 인코딩하세요 |
| JavaScript 문자열 | forJavaScript; 작은따옴표/큰따옴표를 제공하세요. 태그가 없는 일반 템플릿 리터럴 텍스트에는 1.5가 필요합니다. 태그가 있는 템플릿, 표현식 본문, JSON 또는 스크립트 URL에는 절대 사용하지 마세요 |
| JSON 문자열 콘텐츠 | forJson (1.5); 큰따옴표를 제공하세요. 완전한 문서에는 직렬화기를 사용하는 것이 좋습니다 |
따옴표로 묶인 CSS 문자열 / CSS url(...) 값 | forCssString / forCssUrl; URL을 검증하고 해당 메서드의 주변 컨텍스트 규칙을 준수하세요 |
| XML 1.0 텍스트 / 따옴표로 묶인 속성 | forXmlContent / forXmlAttribute; forXml은 둘 다 처리합니다 |
| XML 1.1 텍스트 / 따옴표로 묶인 속성 | forXml11Content / forXml11Attribute (코어 1.4+); XML 1.1 문서/파서가 필요하며 HTML이 아닙니다 |
| XML CDATA / 주석 | forCDATA / forXmlComment; HTML 주석이 아닙니다 |
| Java 소스 문자열 리터럴 | forJava; 호출자가 따옴표를 제공합니다. 짝이 없는 서로게이트는 컴파일되지 않을 수 있습니다 |
나열된 모든 facade 메서드에는 String 및 Writer 오버로드가 있습니다. 컨텍스트 가이드는 중첩, null/Unicode 동작, JavaScript 변형, 템플릿 경계, JSON 및 안전하지 않은 컨텍스트를 설명합니다. Java/JSP 예제는 완전한 주변 구문을 보여줍니다.
인코딩은 HTML을 정화하거나, 입력/URL을 검증하거나, JSON 문서를 직렬화하거나, SQL 매개변수화를 수행하거나, 데이터를 디코딩/정규화하지 않습니다. 마크업을 허용해야 할 때는 HTML 정화기를 사용하고, SQL에는 매개변수화된 쿼리를 사용하세요. 이러한 서로 다른 역할에 대해서는 [OWASP Java 보안 라이브러리 가이드][java-libraries]를 참조하세요.
Taglib URI는 브라우저에서 열려야 하는 URL이 아닌 식별자입니다:
| 어댑터 | 기본 식별자 | 고급 식별자 |
|---|---|---|
| Jakarta | owasp.encoder.jakarta | owasp.encoder.jakarta.advanced |
| javax JSP | https://www.owasp.org/index.php/OWASP_Java_Encoder_Project | 동일한 식별자에 #advanced를 추가 |
<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="e" uri="owasp.encoder.jakarta" %>
<p>${e:forHtmlContent(param.message)}</p>
javax 컨테이너에는 javax 식별자를 사용하십시오. 태그는 빈 본문과 필수 value 속성을 사용합니다. 예: <e:forHtmlContent value="${param.message}" />. 기본 방식과 고급 방식, 그리고 버전에 민감한 배포 설정은 바인딩 및 EL 평가를 참조하십시오. 1.5에서는 고급 taglib이 forJava를 제외한 모든 Encode.forX(String) 컨텍스트를 노출합니다. Java 소스 생성은 JSP 컨텍스트가 아닙니다. XML 1.1 바인딩은 1.5에서 새로 추가되었습니다.
Encode.forUri는 릴리스된 API에서 사용 중단(deprecated)되었습니다. 버전 1.5.0은 이 사용 중단을 Encoders.URI, 두 ForUriTag 클래스, 그리고 forUri 태그/함수 문서로 확장합니다. 이 모든 진입점은 1.x 전반에 걸쳐 유지됩니다. 전체 URI를 인코딩한다고 해서 URI가 검증되지는 않습니다. forUri("javascript:alert(1)")는 이를 변경 없이 반환합니다. 기존 % 기호는 다시 인코딩됩니다. 하나의 원시 파라미터 이름/값, 경로 세그먼트 또는 프래그먼트에는 forUriComponent를 사용하십시오. 완전한 URL은 별도로 검증한 다음, 인용된 HTML 속성에 배치할 때는 forHtmlAttribute를 사용하십시오. java.net.URI만으로 파싱하는 것은 안전성을 보장하지 않습니다. URL 예제를 참조하십시오.
사용 중단된 core/tag API를 제거하려면 별도로 검토되는 향후 메이저 버전 결정이 필요합니다. 사용 중단은 제거 일정이 아닙니다. 별도의 역사적 ESAPI 어댑터는 1.5.0으로 이어지지 않고 폐기됩니다.
공개된 모듈 이름 및 OSGi 범위와 실행 가능한 JPMS 예제를 사용하십시오. 명시적 다중 릴리스 모듈 이름은 의도적으로 과거의 자동 이름과 다릅니다. 자동 모듈에 사용되는 의존성 JAR의 이름을 변경하지 마십시오. CI는 Java 8/11/17/21/25, 클래스패스, JPMS 및 Felix R6/R8에서 원본 패키징된 JAR을 실행합니다. 이는 모든 컨테이너나 다운스트림 의존성 조합을 인증하는 것은 아닙니다.
JDK 17과 커밋된 래퍼(Maven 3.10.1)로 빌드하십시오. Windows에서는 mvnw.cmd를 사용하십시오:
./mvnw clean verify
./mvnw clean verify -PtestJakarta # optional locally; requires Docker
일반 verify에는 Docker가 필요 없는 JSP 엔진이 포함됩니다. 브라우저/WAR 제품군은 CI에서 여전히 필수입니다. 스타일/커버리지 정책은 BUILDING.md를, 리뷰 및 진단 명령은 CONTRIBUTING.md를, 별도의 릴리스 게이트는 RELEASING.md를 참조하세요. 벤치마크나 Maven Site 게시 프로필은 없습니다.
지원되는 1.x 아티팩트는 Java 8 라이브러리 API/바이트코드와 게시된 API/모듈 식별자 및 의존성 범위를 보존합니다. 정확한 인코딩 출력 또한 관찰 가능한 동작입니다. 이스케이프를 추가하는 것이 자동으로 패치 호환되는 것은 아닙니다. 변경에는 컨텍스트/파서 테스트, 출력 변경 노트, 필요한 경우 마이그레이션 안내가 필요합니다. 보안 수정은 명시적 권고와 함께 패치에서 안전하지 않은 동작을 바로잡을 수 있지만, 그 외의 호환성 파괴는 단순한 버전 레이블이 아니라 향후 메이저 버전 결정이 필요합니다. 유지되는 1.x 계약과 향후 제안의 처리 방침은 호환성 및 범위 결정을 참조하세요.
리더: Jim Manico 및 Jeremy Long; 원저자: Jeff Ichnowski. MAINTAINERS.md와 [OWASP 프로젝트 페이지][project]를 참조하세요. 별도의 OWASP 웹사이트는 이 저장소의 릴리스 상태보다 뒤처질 수 있습니다.