# SpotBugs와 Find Security Bugs로 Java 보안 점검 게이트 만들기

> Maven 컨테이너에서 SpotBugs 플러그인에 Find Security Bugs를 붙여 SQL 문자열 결합, MD5, 하드코딩 비밀번호, 경로 조작이 심어진 연습용 코드를 점검합니다. XML과 HTML 보고서를 읽고, 코드를 고쳐 결과를 0건으로 만들고, threshold 설정과 이유를 남기는 제외 필터까지 mvn verify 빌드 게이트로 묶습니다.

- 주소: https://copyandrun.com/blog/java-spotbugs-findsecbugs-gate/
- 분야: 시큐어코딩
- 발행일: 2026-11-02
- 태그: SpotBugs, Find Security Bugs, Maven, Java, 정적 분석

Java 코드의 보안 결함을 빌드 단계에서 잡으려면 SpotBugs에 Find Security Bugs 플러그인을 붙이고 `mvn verify`에서 실패하게 만들면 됩니다. 이 글은 일부러 취약하게 만든 연습용 코드 네 개 클래스를 점검하고, 보고서를 읽고, 고친 뒤 게이트를 통과하는 과정을 다룹니다.

Windows Git Bash에서 Docker Desktop으로 실행했습니다. 컨테이너 안에서만 빌드하므로 호스트에 Java나 Maven을 설치하지 않으며, 포트도 열지 않습니다. 취약한 코드는 직접 만든 연습용이니 실제 서비스에 쓰지 않습니다. 비밀번호 값도 연습용 문자열입니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| 이미지 | `maven:3.9-eclipse-temurin-21` (Maven 3.9.16, OpenJDK 21.0.12 Temurin) |
| spotbugs-maven-plugin | 4.10.5 뒤에 `.0`이 붙은 버전 (SpotBugs 4.10.5, Maven Central 최신 릴리스) |
| Find Security Bugs | `com.h3xstream.findsecbugs:findsecbugs-plugin` 1.14.0 |
| 캐시 | 의존성은 볼륨 `cr-j28-m2`에 보관(`/root/.m2`) |

작업 폴더는 아래와 같습니다. 파일 내용은 글 끝의 `## 전체 코드`에 모두 있고, 내려받은 `UserRepo.fixed.java` 같은 파일은 `fixed/UserRepo.java`로 이름을 바꿔 둡니다.

```
pom.xml
spotbugs-exclude.xml
empty-filter.xml
summary.sh
src/main/java/lab/UserRepo.java
src/main/java/lab/PasswordUtil.java
src/main/java/lab/FileService.java
src/main/java/lab/BadgeColor.java
fixed/UserRepo.java
fixed/PasswordUtil.java
fixed/FileService.java
```

## 1. 컨테이너 준비

<!-- files: pom.xml, empty-filter.xml, spotbugs-exclude.xml, summary.sh -->

작업 폴더에서 컨테이너를 띄우고 파일을 `/work`로 복사합니다. 이 글의 모든 명령은 `docker exec`로 컨테이너 안의 Maven을 실행합니다. `docker exec -w`에는 절대 경로를 써야 합니다(`-w work`는 `Cwd must be an absolute path` 오류가 났습니다).

```bash
docker run -d --name cr-j28-mvn -v cr-j28-m2:/root/.m2 maven:3.9-eclipse-temurin-21 sleep 3600 | cut -c1-12
docker exec cr-j28-mvn mkdir /work && docker cp . cr-j28-mvn:/work/
docker exec cr-j28-mvn mvn -v | head -3
docker exec -w /work cr-j28-mvn find . -type f
```

![컨테이너가 Maven 3.9.16과 Java 21.0.12로 올라오고 pom.xml, 소스 네 개, 고친 소스 세 개, 필터 두 개가 /work에 복사된 것을 확인합니다.](https://copyandrun.com/img/java-spotbugs-findsecbugs-gate/01-container-and-files.png)

`pom.xml`의 핵심은 네 가지입니다. 플러그인 버전은 `spotbugs.base` 속성(4.10.5)에 `.0`을 붙여 지정했습니다. 플러그인의 `<dependencies>`에 `findsecbugs-plugin`을 넣는 방식은 SpotBugs Maven 플러그인 문서와 같습니다. 그리고 `check` 목표를 `verify` 단계에 묶어서 `mvn verify`가 결과를 판정하게 했습니다. `threshold`와 제외 필터 파일은 `gate.threshold`, `gate.exclude` 속성으로 빼 두어 명령행에서 바꿀 수 있습니다.

## 2. 첫 점검: 게이트가 실패한다

<!-- files: empty-filter.xml, pom.xml -->

`empty-filter.xml`은 제외 항목이 없는 필터입니다. 이것으로 심어 둔 결함이 전부 잡히는지 봅니다. 둘째 명령은 `threshold`를 `High`로 올려 같은 코드를 다시 점검합니다.

```bash
docker exec -w /work cr-j28-mvn mvn -B verify -Dgate.exclude=empty-filter.xml | grep -E 'Total bugs|BUILD'; echo "종료 코드: ${PIPESTATUS[0]}"
docker exec -w /work cr-j28-mvn mvn -B verify -Dgate.exclude=empty-filter.xml -Dgate.threshold=High | grep -E 'Total bugs|BUILD'; echo "종료 코드: ${PIPESTATUS[0]}"
```

![threshold Medium에서는 7건, High에서는 3건이 나오고 두 번 모두 BUILD FAILURE와 종료 코드 1로 끝나는 것을 확인합니다.](https://copyandrun.com/img/java-spotbugs-findsecbugs-gate/02-gate-fails.png)

`threshold`는 보고할 최소 심각도입니다. 이 실행에서 `Medium`은 High와 Medium을, `High`는 High만 보고했습니다. 공식 Goals 문서에는 허용 값 목록이 없어서, 이 글은 `Medium`과 `High`를 이 버전에서 실행해 동작을 확인한 값으로만 씁니다. `Low`는 실행하지 않았습니다. `effort`는 `Max`로만 실행했고 `Default`와 비교하지 않았습니다.

## 3. XML 보고서 읽기

<!-- files: summary.sh -->

결과는 `target/spotbugsXml.xml`에 있습니다. 한 줄로 이어진 XML이라 `summary.sh`가 심각도, 패턴 이름, 위치만 뽑아 줍니다. `priority=1`이 High, `priority=2`가 Medium입니다. 먼저 2단계의 Medium 실행을 다시 돌려 보고서를 만든 뒤 실행했습니다.

```bash
docker exec -w /work cr-j28-mvn sh summary.sh target/spotbugsXml.xml
```

![High 3건(MD5, HARD_CODE_PASSWORD, SQL_NONCONSTANT_STRING_PASSED_TO_EXECUTE)과 Medium 4건이 파일과 줄 번호와 함께 나열된 것을 확인합니다.](https://copyandrun.com/img/java-spotbugs-findsecbugs-gate/03-xml-summary.png)

일곱 건은 이렇게 읽습니다.

| 패턴 | 위치 | 의미 |
|---|---|---|
| `SQL_NONCONSTANT_STRING_PASSED_TO_EXECUTE`, `SQL_INJECTION_JDBC` | UserRepo 22행 | 입력을 문자열로 이어 붙인 SQL. 같은 줄을 두 규칙이 각각 보고 |
| `HARD_CODE_PASSWORD`, `DMI_CONSTANT_DB_PASSWORD` | UserRepo 20행 | 소스에 적힌 DB 비밀번호 |
| `WEAK_MESSAGE_DIGEST_MD5` | PasswordUtil 10행 | 비밀번호 해시에 MD5 사용 |
| `PATH_TRAVERSAL_IN` | FileService 17행 | 사용자 입력이 파일 경로로 가는 호출 |
| `PREDICTABLE_RANDOM` | BadgeColor 8행 | `java.util.Random` 사용 |

표의 마지막 줄 `PREDICTABLE_RANDOM`은 화면 배지 색을 고르는 코드라 보안 결함이 아닙니다. 5단계에서 이유를 남기고 제외합니다.

## 4. HTML 보고서 보기

HTML 보고서는 `target/reports/spotbugs.html`에 만들어졌습니다. 컨테이너에서 꺼내 브라우저로 엽니다.

```bash
docker cp cr-j28-mvn:/work/target/reports/spotbugs.html ./spotbugs.html
```

![프로젝트 정보와 심각도별 건수 표 아래에 Security Warnings 목록이 코드별로 나열된 보고서를 확인합니다.](https://copyandrun.com/img/java-spotbugs-findsecbugs-gate/04-html-report.png)

위쪽 표는 High 3건, Medium 4건, 합계 7건입니다. 아래쪽 Details에는 패턴마다 설명과 취약한 예, 권장 대체 방법, CWE 링크가 들어 있어 어떻게 고칠지 찾을 때 씁니다.

## 5. 코드 고치기와 제외 필터

<!-- files: UserRepo.fixed.java, PasswordUtil.fixed.java, FileService.fixed.java, spotbugs-exclude.xml -->

고친 코드는 `fixed/` 폴더에 있습니다. `UserRepo`는 `PreparedStatement`로 입력을 값으로 넘기고 비밀번호를 환경 변수 `DB_PASSWORD`에서 읽습니다. `PasswordUtil`은 MD5 대신 JDK의 PBKDF2(HMAC-SHA256)와 무작위 솔트를 씁니다. 반복 횟수는 OWASP Password Storage Cheat Sheet(`https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html`)가 PBKDF2-HMAC-SHA256에 권고하는 600,000회로 했습니다. 이 값은 이후 권고가 바뀔 수 있으므로 적용할 때 다시 확인합니다. `FileService`는 기준 폴더 밖으로 나가는 경로를 `normalize()`와 `startsWith()`로 거절합니다.

고친 파일을 소스 자리로 복사하고 점검합니다. 첫 점검은 제외 필터를 비우고, 둘째는 기본 설정(`spotbugs-exclude.xml`)으로 합니다.

```bash
docker exec -w /work cr-j28-mvn sh -c 'for f in UserRepo PasswordUtil FileService; do cp fixed/$f.java src/main/java/lab/$f.java; done'
docker exec -w /work cr-j28-mvn mvn -B verify -Dgate.exclude=empty-filter.xml | grep -oE 'Total bugs.*|PREDICTABLE_RANDOM|BUILD.*'; echo "종료 코드: ${PIPESTATUS[0]}"
docker exec -w /work cr-j28-mvn mvn -B verify | grep -E 'BugInstance size|BUILD'; echo "종료 코드: ${PIPESTATUS[0]}"
```

![제외 필터 없이는 PREDICTABLE_RANDOM 한 건 때문에 실패하고, spotbugs-exclude.xml을 적용하면 BugInstance size is 0과 BUILD SUCCESS, 종료 코드 0이 되는 것을 확인합니다.](https://copyandrun.com/img/java-spotbugs-findsecbugs-gate/05-fixed-gate-passes.png)

남은 한 건이 오탐입니다. `spotbugs-exclude.xml`은 클래스 하나와 패턴 하나만 지정하고, 주석에 이유와 검토 날짜를 남깁니다. 범위를 좁게 잡아야 다른 곳에 같은 패턴이 생겼을 때 다시 걸립니다. 패턴 전체를 끄거나 `Match`에 아무 조건도 두지 않으면 이후의 진짜 결함까지 가려집니다.

## 결과 정리

- `check` 목표를 `verify`에 묶으면 결함이 있을 때 종료 코드 1로 빌드가 멈춥니다. CI에서는 이 종료 코드가 곧 게이트입니다.
- 보고서는 XML을 자동 처리에, HTML을 사람이 읽는 데 씁니다.
- 고친 뒤에는 같은 명령을 다시 돌려 0건을 확인합니다. 0건은 이 규칙이 찾는 범위 안에서 그렇다는 뜻이며 안전하다는 증명은 아닙니다.
- 오탐은 코드 옆이 아니라 필터 파일에 이유와 함께 한 건씩 적어 제외합니다.

## 전체 코드

작업 폴더 구조는 위 `## 준비물`과 같습니다. `*.fixed.java`는 `fixed/` 폴더에 원래 이름으로 둡니다.

### pom.xml

```html
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>lab</groupId>
  <artifactId>spotbugs-lab</artifactId>
  <version>1.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spotbugs.base>4.10.5</spotbugs.base>
    <gate.threshold>Medium</gate.threshold>
    <gate.exclude>spotbugs-exclude.xml</gate.exclude>
  </properties>

  <build>
    <plugins>
      <plugin>
        <groupId>com.github.spotbugs</groupId>
        <artifactId>spotbugs-maven-plugin</artifactId>
        <version>${spotbugs.base}.0</version>
        <configuration>
          <effort>Max</effort>
          <threshold>${gate.threshold}</threshold>
          <xmlOutput>true</xmlOutput>
          <htmlOutput>true</htmlOutput>
          <excludeFilterFile>${gate.exclude}</excludeFilterFile>
          <failOnError>true</failOnError>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>com.h3xstream.findsecbugs</groupId>
            <artifactId>findsecbugs-plugin</artifactId>
            <version>1.14.0</version>
          </dependency>
        </dependencies>
        <executions>
          <execution>
            <id>security-gate</id>
            <phase>verify</phase>
            <goals>
              <goal>check</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
```

### spotbugs-exclude.xml

```html
<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
  <!--
    제외 이유: BadgeColor 의 Random 은 화면 배지 색을 고르는 용도이며 비밀값이나
    토큰 생성에 쓰이지 않습니다. 검토일 2026-11-02, 검토자 기록은 이슈 번호로 남깁니다.
    다른 클래스에 같은 패턴이 생기면 다시 걸리도록 클래스 하나와 패턴 하나만 지정합니다.
  -->
  <Match>
    <Class name="lab.BadgeColor"/>
    <Bug pattern="PREDICTABLE_RANDOM"/>
  </Match>
</FindBugsFilter>
```

### empty-filter.xml

```html
<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
</FindBugsFilter>
```

### summary.sh

```bash
#!/bin/sh
# SpotBugs XML 보고서에서 결과를 한 줄씩 요약합니다. 사용법: sh summary.sh target/spotbugsXml.xml
grep -oE "priority='[0-9]' type='[A-Z0-9_]+'|<Message>At [A-Za-z]+\.java:\[line [0-9]+\]" "$1" \
  | sed -E "s/priority='([0-9])' type='([A-Z0-9_]+)'/\1 \2/; s/<Message>At //" \
  | awk 'function out() { if (t != "") printf "priority=%s  %-42s %s\n", p, t, loc }
         /^[0-9] / { out(); p = $1; t = $2; loc = ""; next }
         loc == "" { loc = $0 }
         END { out() }'
```

### UserRepo.java

```java
package lab;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

/** 연습용 코드입니다. 일부러 취약하게 만들었으므로 실제 서비스에 쓰지 않습니다. */
public class UserRepo {
    private static final String DB_PASSWORD = "Lab-Pass-2026";

    private final String url;

    public UserRepo(String url) {
        this.url = url;
    }

    public String findEmail(String name) throws SQLException {
        try (Connection conn = DriverManager.getConnection(url, "app", DB_PASSWORD);
             Statement st = conn.createStatement();
             ResultSet rs = st.executeQuery("SELECT email FROM users WHERE name = '" + name + "'")) {
            return rs.next() ? rs.getString(1) : null;
        }
    }
}
```

### PasswordUtil.java

```java
package lab;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

/** 연습용 코드입니다. 일부러 취약하게 만들었으므로 실제 서비스에 쓰지 않습니다. */
public class PasswordUtil {
    public static String hash(String password) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] out = md.digest(password.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : out) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}
```

### FileService.java

```java
package lab;

import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;

/** 연습용 코드입니다. 일부러 취약하게 만들었으므로 실제 서비스에 쓰지 않습니다. */
public class FileService {
    private final String base;

    public FileService(String base) {
        this.base = base;
    }

    public String read(String fileName) throws IOException {
        File f = new File(base, fileName);
        return new String(Files.readAllBytes(f.toPath()), StandardCharsets.UTF_8);
    }
}
```

### BadgeColor.java

```java
package lab;

import java.util.Random;

/** 화면 배지 색만 고르는 코드입니다. 보안 값 생성에는 쓰지 않습니다. */
public class BadgeColor {
    private static final String[] COLORS = {"blue", "green", "orange", "gray"};
    private static final Random RANDOM = new Random();

    public static String pick() {
        return COLORS[RANDOM.nextInt(COLORS.length)];
    }
}
```

### UserRepo.fixed.java

```java
package lab;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class UserRepo {
    private final String url;

    public UserRepo(String url) {
        this.url = url;
    }

    public String findEmail(String name) throws SQLException {
        String password = System.getenv("DB_PASSWORD");
        if (password == null) {
            throw new IllegalStateException("DB_PASSWORD 환경 변수가 필요합니다");
        }
        try (Connection conn = DriverManager.getConnection(url, "app", password);
             PreparedStatement st = conn.prepareStatement("SELECT email FROM users WHERE name = ?")) {
            st.setString(1, name);
            try (ResultSet rs = st.executeQuery()) {
                return rs.next() ? rs.getString(1) : null;
            }
        }
    }
}
```

### PasswordUtil.fixed.java

```java
package lab;

import java.security.GeneralSecurityException;
import java.security.SecureRandom;
import java.util.Base64;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;

public class PasswordUtil {
    private static final int ITERATIONS = 600_000;
    private static final SecureRandom RANDOM = new SecureRandom();

    public static String hash(String password) throws GeneralSecurityException {
        byte[] salt = new byte[16];
        RANDOM.nextBytes(salt);
        PBEKeySpec spec = new PBEKeySpec(password.toCharArray(), salt, ITERATIONS, 256);
        byte[] out = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256").generateSecret(spec).getEncoded();
        Base64.Encoder b64 = Base64.getEncoder();
        return ITERATIONS + "$" + b64.encodeToString(salt) + "$" + b64.encodeToString(out);
    }
}
```

### FileService.fixed.java

```java
package lab;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class FileService {
    private final Path base;

    public FileService(String base) {
        this.base = Path.of(base).toAbsolutePath().normalize();
    }

    public String read(String fileName) throws IOException {
        Path target = base.resolve(fileName).normalize();
        if (!target.startsWith(base)) {
            throw new IOException("허용된 폴더 밖의 경로입니다");
        }
        return new String(Files.readAllBytes(target), StandardCharsets.UTF_8);
    }
}
```

## 자주 막히는 곳

- **`docker exec -w work`가 `Cwd must be an absolute path`로 실패합니다.** `-w /work`처럼 절대 경로를 씁니다. Git Bash에서는 `export MSYS_NO_PATHCONV=1`을 먼저 실행합니다.
- **비밀번호 상수를 만들었는데 `HARD_CODE_PASSWORD`가 나오지 않습니다.** 처음에는 비밀번호를 `private static final String`으로만 두고 어디에도 쓰지 않았더니 보고되지 않았습니다. `DriverManager.getConnection(url, "app", DB_PASSWORD)`처럼 인증 API에 넘기는 코드로 바꾸자 두 건이 나왔습니다.
- **`Random`이 `PREDICTABLE_RANDOM` 대신 `DMI_RANDOM_USED_ONLY_ONCE`로 나옵니다.** 호출마다 `new Random()`을 만들면 다른 패턴이 걸려 제외 필터의 패턴 이름과 맞지 않습니다. 이 글에서는 정적 필드로 한 번만 만들었습니다.
- **보안과 무관한 경고가 섞입니다.** 처음에 `Connection`을 필드로 받고 `Statement`를 닫지 않는 코드로 시험했더니 `EI_EXPOSE_REP2`, `ODR_OPEN_DATABASE_RESOURCE`, `OBL_UNSATISFIED_OBLIGATION`이 Medium으로 나왔습니다. Find Security Bugs 항목만 보려면 코드를 먼저 정리하거나 필터로 범주를 좁힙니다.
- **절대 경로 상수에 경고가 붙습니다.** 기준 폴더를 `"/srv/uploads"` 상수로 두었더니 `DMI_HARDCODED_ABSOLUTE_FILENAME`이 나왔습니다. 생성자로 받도록 바꿨습니다.
- **`docker cp`에 Git Bash의 `/tmp/...` 경로를 넘기면 파일을 못 찾습니다.** `cygpath -m`으로 바꾼 Windows 경로를 씁니다.

## 확인 범위

- **확인한 것:** 위 명령과 출력은 모두 `maven:3.9-eclipse-temurin-21` 컨테이너에서 실제로 실행한 결과입니다. 좌표와 버전은 Maven Central의 maven-metadata.xml(최신 릴리스는 spotbugs-maven-plugin 4.10.5 계열의 `.0` 버전, findsecbugs-plugin 1.14.0)로 확인했고, 플러그인 설정 방식은 `https://spotbugs.github.io/spotbugs-maven-plugin/usage.html`, 매개변수 기본값은 `https://spotbugs.github.io/spotbugs-maven-plugin/spotbugs-mojo.html`과 `check-mojo.html`, Find Security Bugs 좌표는 `https://find-sec-bugs.github.io/download.htm`에서 확인했습니다. `check` 목표의 기본 단계는 `verify`입니다.
- **공식 문서와 다른 점:** check 목표 문서에는 `threshold`가 없고 `failThreshold`만 있습니다. 이 글에서는 `spotbugs` 목표 문서의 `threshold`, `effort`, `excludeFilterFile`을 `check`의 `<configuration>`에 넣었고 실행에서 적용된 것을 확인했습니다. 두 문서 모두 `threshold`와 `effort`의 허용 값을 적어 두지 않아서, 이 글의 `Medium`과 `High`는 문서에서 찾은 값이 아니라 이 버전에서 동작을 확인한 값입니다.
- **하지 못한 것:** `threshold` Low, `effort` Default, `failThreshold` 사용, GitHub Actions 같은 CI 연동은 실행하지 않았습니다. Gradle 플러그인과 SpotBugs 어노테이션(`@SuppressFBWarnings`)도 다루지 않았습니다. Find Security Bugs가 찾는 패턴 전체 목록과 이번 연습 코드 밖의 탐지율은 확인하지 않았습니다.
- **범위의 한계:** 정적 분석은 규칙이 아는 패턴만 보고합니다. 0건은 코드 검토와 시험을 대신하지 못합니다. 고친 `FileService`가 경고에서 빠진 것은 확인했지만 경로 조작에 안전한지는 시험하지 않았습니다.
